| 1 | . ///////////////////////////////////////////////////////////////////////////// |
| 2 | . This is the primary source of the Exim Manual. It is an xfpt document that is |
| 3 | . converted into DocBook XML for subsequent conversion into printing and online |
| 4 | . formats. The markup used herein is "standard" xfpt markup, with some extras. |
| 5 | . The markup is summarized in a file called Markup.txt. |
| 6 | . |
| 7 | . WARNING: When you use the .new macro, make sure it appears *before* any |
| 8 | . adjacent index items; otherwise you get an empty "paragraph" which causes |
| 9 | . unwanted vertical space. |
| 10 | . ///////////////////////////////////////////////////////////////////////////// |
| 11 | |
| 12 | .include stdflags |
| 13 | .include stdmacs |
| 14 | |
| 15 | . ///////////////////////////////////////////////////////////////////////////// |
| 16 | . This outputs the standard DocBook boilerplate. |
| 17 | . ///////////////////////////////////////////////////////////////////////////// |
| 18 | |
| 19 | .docbook |
| 20 | |
| 21 | . ///////////////////////////////////////////////////////////////////////////// |
| 22 | . These lines are processing instructions for the Simple DocBook Processor that |
| 23 | . Philip Hazel has developed as a less cumbersome way of making PostScript and |
| 24 | . PDFs than using xmlto and fop. They will be ignored by all other XML |
| 25 | . processors. |
| 26 | . ///////////////////////////////////////////////////////////////////////////// |
| 27 | |
| 28 | .literal xml |
| 29 | <?sdop |
| 30 | foot_right_recto="&chaptertitle; (&chapternumber;)" |
| 31 | foot_right_verso="&chaptertitle; (&chapternumber;)" |
| 32 | toc_chapter_blanks="yes,yes" |
| 33 | table_warn_overflow="overprint" |
| 34 | ?> |
| 35 | .literal off |
| 36 | |
| 37 | . ///////////////////////////////////////////////////////////////////////////// |
| 38 | . This generate the outermost <book> element that wraps then entire document. |
| 39 | . ///////////////////////////////////////////////////////////////////////////// |
| 40 | |
| 41 | .book |
| 42 | |
| 43 | . ///////////////////////////////////////////////////////////////////////////// |
| 44 | . These definitions set some parameters and save some typing. |
| 45 | . Update the Copyright year (only) when changing content. |
| 46 | . ///////////////////////////////////////////////////////////////////////////// |
| 47 | |
| 48 | .set previousversion "4.80" |
| 49 | .include ./local_params |
| 50 | |
| 51 | .set ACL "access control lists (ACLs)" |
| 52 | .set I " " |
| 53 | |
| 54 | .macro copyyear |
| 55 | 2014 |
| 56 | .endmacro |
| 57 | |
| 58 | . ///////////////////////////////////////////////////////////////////////////// |
| 59 | . Additional xfpt markup used by this document, over and above the default |
| 60 | . provided in the xfpt library. |
| 61 | . ///////////////////////////////////////////////////////////////////////////// |
| 62 | |
| 63 | . --- Override the &$ flag to automatically insert a $ with the variable name |
| 64 | |
| 65 | .flag &$ $& "<varname>$" "</varname>" |
| 66 | |
| 67 | . --- Short flags for daggers in option headings. They will always be inside |
| 68 | . --- an italic string, but we want the daggers to be roman. |
| 69 | |
| 70 | .flag &!! "</emphasis>†<emphasis>" |
| 71 | .flag &!? "</emphasis>‡<emphasis>" |
| 72 | |
| 73 | . --- A macro for an Exim option definition heading, generating a one-line |
| 74 | . --- table with four columns. For cases when the option name is given with |
| 75 | . --- a space, so that it can be split, a fifth argument is used for the |
| 76 | . --- index entry. |
| 77 | |
| 78 | .macro option |
| 79 | .arg 5 |
| 80 | .oindex "&%$5%&" |
| 81 | .endarg |
| 82 | .arg -5 |
| 83 | .oindex "&%$1%&" |
| 84 | .endarg |
| 85 | .itable all 0 0 4 8* left 6* center 6* center 6* right |
| 86 | .row "&%$1%&" "Use: &'$2'&" "Type: &'$3'&" "Default: &'$4'&" |
| 87 | .endtable |
| 88 | .endmacro |
| 89 | |
| 90 | . --- A macro for the common 2-column tables. The width of the first column |
| 91 | . --- is suitable for the many tables at the start of the main options chapter; |
| 92 | . --- the small number of other 2-column tables override it. |
| 93 | |
| 94 | .macro table2 196pt 254pt |
| 95 | .itable none 0 0 2 $1 left $2 left |
| 96 | .endmacro |
| 97 | |
| 98 | . --- A macro that generates .row, but puts &I; at the start of the first |
| 99 | . --- argument, thus indenting it. Assume a minimum of two arguments, and |
| 100 | . --- allow up to four arguments, which is as many as we'll ever need. |
| 101 | |
| 102 | .macro irow |
| 103 | .arg 4 |
| 104 | .row "&I;$1" "$2" "$3" "$4" |
| 105 | .endarg |
| 106 | .arg -4 |
| 107 | .arg 3 |
| 108 | .row "&I;$1" "$2" "$3" |
| 109 | .endarg |
| 110 | .arg -3 |
| 111 | .row "&I;$1" "$2" |
| 112 | .endarg |
| 113 | .endarg |
| 114 | .endmacro |
| 115 | |
| 116 | . --- Macros for option, variable, and concept index entries. For a "range" |
| 117 | . --- style of entry, use .scindex for the start and .ecindex for the end. The |
| 118 | . --- first argument of .scindex and the only argument of .ecindex must be the |
| 119 | . --- ID that ties them together. |
| 120 | |
| 121 | .macro cindex |
| 122 | &<indexterm role="concept">& |
| 123 | &<primary>&$1&</primary>& |
| 124 | .arg 2 |
| 125 | &<secondary>&$2&</secondary>& |
| 126 | .endarg |
| 127 | &</indexterm>& |
| 128 | .endmacro |
| 129 | |
| 130 | .macro scindex |
| 131 | &<indexterm role="concept" id="$1" class="startofrange">& |
| 132 | &<primary>&$2&</primary>& |
| 133 | .arg 3 |
| 134 | &<secondary>&$3&</secondary>& |
| 135 | .endarg |
| 136 | &</indexterm>& |
| 137 | .endmacro |
| 138 | |
| 139 | .macro ecindex |
| 140 | &<indexterm role="concept" startref="$1" class="endofrange"/>& |
| 141 | .endmacro |
| 142 | |
| 143 | .macro oindex |
| 144 | &<indexterm role="option">& |
| 145 | &<primary>&$1&</primary>& |
| 146 | .arg 2 |
| 147 | &<secondary>&$2&</secondary>& |
| 148 | .endarg |
| 149 | &</indexterm>& |
| 150 | .endmacro |
| 151 | |
| 152 | .macro vindex |
| 153 | &<indexterm role="variable">& |
| 154 | &<primary>&$1&</primary>& |
| 155 | .arg 2 |
| 156 | &<secondary>&$2&</secondary>& |
| 157 | .endarg |
| 158 | &</indexterm>& |
| 159 | .endmacro |
| 160 | |
| 161 | .macro index |
| 162 | .echo "** Don't use .index; use .cindex or .oindex or .vindex" |
| 163 | .endmacro |
| 164 | . //////////////////////////////////////////////////////////////////////////// |
| 165 | |
| 166 | |
| 167 | . //////////////////////////////////////////////////////////////////////////// |
| 168 | . The <bookinfo> element is removed from the XML before processing for Ascii |
| 169 | . output formats. |
| 170 | . //////////////////////////////////////////////////////////////////////////// |
| 171 | |
| 172 | .literal xml |
| 173 | <bookinfo> |
| 174 | <title>Specification of the Exim Mail Transfer Agent</title> |
| 175 | <titleabbrev>The Exim MTA</titleabbrev> |
| 176 | <date> |
| 177 | .fulldate |
| 178 | </date> |
| 179 | <author><firstname>Exim</firstname><surname>Maintainers</surname></author> |
| 180 | <authorinitials>EM</authorinitials> |
| 181 | <revhistory><revision> |
| 182 | .versiondatexml |
| 183 | <authorinitials>EM</authorinitials> |
| 184 | </revision></revhistory> |
| 185 | <copyright><year> |
| 186 | .copyyear |
| 187 | </year><holder>University of Cambridge</holder></copyright> |
| 188 | </bookinfo> |
| 189 | .literal off |
| 190 | |
| 191 | |
| 192 | . ///////////////////////////////////////////////////////////////////////////// |
| 193 | . This chunk of literal XML implements index entries of the form "x, see y" and |
| 194 | . "x, see also y". However, the DocBook DTD doesn't allow <indexterm> entries |
| 195 | . at the top level, so we have to put the .chapter directive first. |
| 196 | . ///////////////////////////////////////////////////////////////////////////// |
| 197 | |
| 198 | .chapter "Introduction" "CHID1" |
| 199 | .literal xml |
| 200 | |
| 201 | <indexterm role="variable"> |
| 202 | <primary>$1, $2, etc.</primary> |
| 203 | <see><emphasis>numerical variables</emphasis></see> |
| 204 | </indexterm> |
| 205 | <indexterm role="concept"> |
| 206 | <primary>address</primary> |
| 207 | <secondary>rewriting</secondary> |
| 208 | <see><emphasis>rewriting</emphasis></see> |
| 209 | </indexterm> |
| 210 | <indexterm role="concept"> |
| 211 | <primary>Bounce Address Tag Validation</primary> |
| 212 | <see><emphasis>BATV</emphasis></see> |
| 213 | </indexterm> |
| 214 | <indexterm role="concept"> |
| 215 | <primary>Client SMTP Authorization</primary> |
| 216 | <see><emphasis>CSA</emphasis></see> |
| 217 | </indexterm> |
| 218 | <indexterm role="concept"> |
| 219 | <primary>CR character</primary> |
| 220 | <see><emphasis>carriage return</emphasis></see> |
| 221 | </indexterm> |
| 222 | <indexterm role="concept"> |
| 223 | <primary>CRL</primary> |
| 224 | <see><emphasis>certificate revocation list</emphasis></see> |
| 225 | </indexterm> |
| 226 | <indexterm role="concept"> |
| 227 | <primary>delivery</primary> |
| 228 | <secondary>failure report</secondary> |
| 229 | <see><emphasis>bounce message</emphasis></see> |
| 230 | </indexterm> |
| 231 | <indexterm role="concept"> |
| 232 | <primary>dialup</primary> |
| 233 | <see><emphasis>intermittently connected hosts</emphasis></see> |
| 234 | </indexterm> |
| 235 | <indexterm role="concept"> |
| 236 | <primary>exiscan</primary> |
| 237 | <see><emphasis>content scanning</emphasis></see> |
| 238 | </indexterm> |
| 239 | <indexterm role="concept"> |
| 240 | <primary>failover</primary> |
| 241 | <see><emphasis>fallback</emphasis></see> |
| 242 | </indexterm> |
| 243 | <indexterm role="concept"> |
| 244 | <primary>fallover</primary> |
| 245 | <see><emphasis>fallback</emphasis></see> |
| 246 | </indexterm> |
| 247 | <indexterm role="concept"> |
| 248 | <primary>filter</primary> |
| 249 | <secondary>Sieve</secondary> |
| 250 | <see><emphasis>Sieve filter</emphasis></see> |
| 251 | </indexterm> |
| 252 | <indexterm role="concept"> |
| 253 | <primary>ident</primary> |
| 254 | <see><emphasis>RFC 1413</emphasis></see> |
| 255 | </indexterm> |
| 256 | <indexterm role="concept"> |
| 257 | <primary>LF character</primary> |
| 258 | <see><emphasis>linefeed</emphasis></see> |
| 259 | </indexterm> |
| 260 | <indexterm role="concept"> |
| 261 | <primary>maximum</primary> |
| 262 | <seealso><emphasis>limit</emphasis></seealso> |
| 263 | </indexterm> |
| 264 | <indexterm role="concept"> |
| 265 | <primary>monitor</primary> |
| 266 | <see><emphasis>Exim monitor</emphasis></see> |
| 267 | </indexterm> |
| 268 | <indexterm role="concept"> |
| 269 | <primary>no_<emphasis>xxx</emphasis></primary> |
| 270 | <see>entry for xxx</see> |
| 271 | </indexterm> |
| 272 | <indexterm role="concept"> |
| 273 | <primary>NUL</primary> |
| 274 | <see><emphasis>binary zero</emphasis></see> |
| 275 | </indexterm> |
| 276 | <indexterm role="concept"> |
| 277 | <primary>passwd file</primary> |
| 278 | <see><emphasis>/etc/passwd</emphasis></see> |
| 279 | </indexterm> |
| 280 | <indexterm role="concept"> |
| 281 | <primary>process id</primary> |
| 282 | <see><emphasis>pid</emphasis></see> |
| 283 | </indexterm> |
| 284 | <indexterm role="concept"> |
| 285 | <primary>RBL</primary> |
| 286 | <see><emphasis>DNS list</emphasis></see> |
| 287 | </indexterm> |
| 288 | <indexterm role="concept"> |
| 289 | <primary>redirection</primary> |
| 290 | <see><emphasis>address redirection</emphasis></see> |
| 291 | </indexterm> |
| 292 | <indexterm role="concept"> |
| 293 | <primary>return path</primary> |
| 294 | <seealso><emphasis>envelope sender</emphasis></seealso> |
| 295 | </indexterm> |
| 296 | <indexterm role="concept"> |
| 297 | <primary>scanning</primary> |
| 298 | <see><emphasis>content scanning</emphasis></see> |
| 299 | </indexterm> |
| 300 | <indexterm role="concept"> |
| 301 | <primary>SSL</primary> |
| 302 | <see><emphasis>TLS</emphasis></see> |
| 303 | </indexterm> |
| 304 | <indexterm role="concept"> |
| 305 | <primary>string</primary> |
| 306 | <secondary>expansion</secondary> |
| 307 | <see><emphasis>expansion</emphasis></see> |
| 308 | </indexterm> |
| 309 | <indexterm role="concept"> |
| 310 | <primary>top bit</primary> |
| 311 | <see><emphasis>8-bit characters</emphasis></see> |
| 312 | </indexterm> |
| 313 | <indexterm role="concept"> |
| 314 | <primary>variables</primary> |
| 315 | <see><emphasis>expansion, variables</emphasis></see> |
| 316 | </indexterm> |
| 317 | <indexterm role="concept"> |
| 318 | <primary>zero, binary</primary> |
| 319 | <see><emphasis>binary zero</emphasis></see> |
| 320 | </indexterm> |
| 321 | |
| 322 | .literal off |
| 323 | |
| 324 | |
| 325 | . ///////////////////////////////////////////////////////////////////////////// |
| 326 | . This is the real start of the first chapter. See the comment above as to why |
| 327 | . we can't have the .chapter line here. |
| 328 | . chapter "Introduction" |
| 329 | . ///////////////////////////////////////////////////////////////////////////// |
| 330 | |
| 331 | Exim is a mail transfer agent (MTA) for hosts that are running Unix or |
| 332 | Unix-like operating systems. It was designed on the assumption that it would be |
| 333 | run on hosts that are permanently connected to the Internet. However, it can be |
| 334 | used on intermittently connected hosts with suitable configuration adjustments. |
| 335 | |
| 336 | Configuration files currently exist for the following operating systems: AIX, |
| 337 | BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, Dragonfly, FreeBSD, GNU/Hurd, |
| 338 | GNU/Linux, HI-OSF (Hitachi), HI-UX, HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, |
| 339 | OpenUNIX, QNX, SCO, SCO SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4, |
| 340 | Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware. |
| 341 | Some of these operating systems are no longer current and cannot easily be |
| 342 | tested, so the configuration files may no longer work in practice. |
| 343 | |
| 344 | There are also configuration files for compiling Exim in the Cygwin environment |
| 345 | that can be installed on systems running Windows. However, this document does |
| 346 | not contain any information about running Exim in the Cygwin environment. |
| 347 | |
| 348 | The terms and conditions for the use and distribution of Exim are contained in |
| 349 | the file &_NOTICE_&. Exim is distributed under the terms of the GNU General |
| 350 | Public Licence, a copy of which may be found in the file &_LICENCE_&. |
| 351 | |
| 352 | The use, supply or promotion of Exim for the purpose of sending bulk, |
| 353 | unsolicited electronic mail is incompatible with the basic aims of the program, |
| 354 | which revolve around the free provision of a service that enhances the quality |
| 355 | of personal communications. The author of Exim regards indiscriminate |
| 356 | mass-mailing as an antisocial, irresponsible abuse of the Internet. |
| 357 | |
| 358 | Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the |
| 359 | experience of running and working on the Smail 3 code, I could never have |
| 360 | contemplated starting to write a new MTA. Many of the ideas and user interfaces |
| 361 | were originally taken from Smail 3, though the actual code of Exim is entirely |
| 362 | new, and has developed far beyond the initial concept. |
| 363 | |
| 364 | Many people, both in Cambridge and around the world, have contributed to the |
| 365 | development and the testing of Exim, and to porting it to various operating |
| 366 | systems. I am grateful to them all. The distribution now contains a file called |
| 367 | &_ACKNOWLEDGMENTS_&, in which I have started recording the names of |
| 368 | contributors. |
| 369 | |
| 370 | |
| 371 | .section "Exim documentation" "SECID1" |
| 372 | . Keep this example change bar when updating the documentation! |
| 373 | |
| 374 | .new |
| 375 | .cindex "documentation" |
| 376 | This edition of the Exim specification applies to version &version() of Exim. |
| 377 | Substantive changes from the &previousversion; edition are marked in some |
| 378 | renditions of the document; this paragraph is so marked if the rendition is |
| 379 | capable of showing a change indicator. |
| 380 | .wen |
| 381 | |
| 382 | This document is very much a reference manual; it is not a tutorial. The reader |
| 383 | is expected to have some familiarity with the SMTP mail transfer protocol and |
| 384 | with general Unix system administration. Although there are some discussions |
| 385 | and examples in places, the information is mostly organized in a way that makes |
| 386 | it easy to look up, rather than in a natural order for sequential reading. |
| 387 | Furthermore, the manual aims to cover every aspect of Exim in detail, including |
| 388 | a number of rarely-used, special-purpose features that are unlikely to be of |
| 389 | very wide interest. |
| 390 | |
| 391 | .cindex "books about Exim" |
| 392 | An &"easier"& discussion of Exim which provides more in-depth explanatory, |
| 393 | introductory, and tutorial material can be found in a book entitled &'The Exim |
| 394 | SMTP Mail Server'& (second edition, 2007), published by UIT Cambridge |
| 395 | (&url(http://www.uit.co.uk/exim-book/)). |
| 396 | |
| 397 | This book also contains a chapter that gives a general introduction to SMTP and |
| 398 | Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date |
| 399 | with the latest release of Exim. (Note that the earlier book about Exim, |
| 400 | published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.) |
| 401 | |
| 402 | .cindex "Debian" "information sources" |
| 403 | If you are using a Debian distribution of Exim, you will find information about |
| 404 | Debian-specific features in the file |
| 405 | &_/usr/share/doc/exim4-base/README.Debian_&. |
| 406 | The command &(man update-exim.conf)& is another source of Debian-specific |
| 407 | information. |
| 408 | |
| 409 | .cindex "&_doc/NewStuff_&" |
| 410 | .cindex "&_doc/ChangeLog_&" |
| 411 | .cindex "change log" |
| 412 | As the program develops, there may be features in newer versions that have not |
| 413 | yet made it into this document, which is updated only when the most significant |
| 414 | digit of the fractional part of the version number changes. Specifications of |
| 415 | new features that are not yet in this manual are placed in the file |
| 416 | &_doc/NewStuff_& in the Exim distribution. |
| 417 | |
| 418 | Some features may be classified as &"experimental"&. These may change |
| 419 | incompatibly while they are developing, or even be withdrawn. For this reason, |
| 420 | they are not documented in this manual. Information about experimental features |
| 421 | can be found in the file &_doc/experimental.txt_&. |
| 422 | |
| 423 | All changes to the program (whether new features, bug fixes, or other kinds of |
| 424 | change) are noted briefly in the file called &_doc/ChangeLog_&. |
| 425 | |
| 426 | .cindex "&_doc/spec.txt_&" |
| 427 | This specification itself is available as an ASCII file in &_doc/spec.txt_& so |
| 428 | that it can easily be searched with a text editor. Other files in the &_doc_& |
| 429 | directory are: |
| 430 | |
| 431 | .table2 100pt |
| 432 | .row &_OptionLists.txt_& "list of all options in alphabetical order" |
| 433 | .row &_dbm.discuss.txt_& "discussion about DBM libraries" |
| 434 | .row &_exim.8_& "a man page of Exim's command line options" |
| 435 | .row &_experimental.txt_& "documentation of experimental features" |
| 436 | .row &_filter.txt_& "specification of the filter language" |
| 437 | .row &_Exim3.upgrade_& "upgrade notes from release 2 to release 3" |
| 438 | .row &_Exim4.upgrade_& "upgrade notes from release 3 to release 4" |
| 439 | .endtable |
| 440 | |
| 441 | The main specification and the specification of the filtering language are also |
| 442 | available in other formats (HTML, PostScript, PDF, and Texinfo). Section |
| 443 | &<<SECTavail>>& below tells you how to get hold of these. |
| 444 | |
| 445 | |
| 446 | |
| 447 | .section "FTP and web sites" "SECID2" |
| 448 | .cindex "web site" |
| 449 | .cindex "FTP site" |
| 450 | The primary site for Exim source distributions is currently the University of |
| 451 | Cambridge's FTP site, whose contents are described in &'Where to find the Exim |
| 452 | distribution'& below. In addition, there is a web site and an FTP site at |
| 453 | &%exim.org%&. These are now also hosted at the University of Cambridge. The |
| 454 | &%exim.org%& site was previously hosted for a number of years by Energis |
| 455 | Squared, formerly Planet Online Ltd, whose support I gratefully acknowledge. |
| 456 | |
| 457 | .cindex "wiki" |
| 458 | .cindex "FAQ" |
| 459 | As well as Exim distribution tar files, the Exim web site contains a number of |
| 460 | differently formatted versions of the documentation. A recent addition to the |
| 461 | online information is the Exim wiki (&url(http://wiki.exim.org)), |
| 462 | which contains what used to be a separate FAQ, as well as various other |
| 463 | examples, tips, and know-how that have been contributed by Exim users. |
| 464 | |
| 465 | .cindex Bugzilla |
| 466 | An Exim Bugzilla exists at &url(http://bugs.exim.org). You can use |
| 467 | this to report bugs, and also to add items to the wish list. Please search |
| 468 | first to check that you are not duplicating a previous entry. |
| 469 | |
| 470 | |
| 471 | |
| 472 | .section "Mailing lists" "SECID3" |
| 473 | .cindex "mailing lists" "for Exim users" |
| 474 | The following Exim mailing lists exist: |
| 475 | |
| 476 | .table2 140pt |
| 477 | .row &'exim-announce@exim.org'& "Moderated, low volume announcements list" |
| 478 | .row &'exim-users@exim.org'& "General discussion list" |
| 479 | .row &'exim-dev@exim.org'& "Discussion of bugs, enhancements, etc." |
| 480 | .row &'exim-cvs@exim.org'& "Automated commit messages from the VCS" |
| 481 | .endtable |
| 482 | |
| 483 | You can subscribe to these lists, change your existing subscriptions, and view |
| 484 | or search the archives via the mailing lists link on the Exim home page. |
| 485 | .cindex "Debian" "mailing list for" |
| 486 | If you are using a Debian distribution of Exim, you may wish to subscribe to |
| 487 | the Debian-specific mailing list &'pkg-exim4-users@lists.alioth.debian.org'& |
| 488 | via this web page: |
| 489 | .display |
| 490 | &url(http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-users) |
| 491 | .endd |
| 492 | Please ask Debian-specific questions on this list and not on the general Exim |
| 493 | lists. |
| 494 | |
| 495 | .section "Exim training" "SECID4" |
| 496 | .cindex "training courses" |
| 497 | Training courses in Cambridge (UK) used to be run annually by the author of |
| 498 | Exim, before he retired. At the time of writing, there are no plans to run |
| 499 | further Exim courses in Cambridge. However, if that changes, relevant |
| 500 | information will be posted at &url(http://www-tus.csx.cam.ac.uk/courses/exim/). |
| 501 | |
| 502 | .section "Bug reports" "SECID5" |
| 503 | .cindex "bug reports" |
| 504 | .cindex "reporting bugs" |
| 505 | Reports of obvious bugs can be emailed to &'bugs@exim.org'& or reported |
| 506 | via the Bugzilla (&url(http://bugs.exim.org)). However, if you are unsure |
| 507 | whether some behaviour is a bug or not, the best thing to do is to post a |
| 508 | message to the &'exim-dev'& mailing list and have it discussed. |
| 509 | |
| 510 | |
| 511 | |
| 512 | .section "Where to find the Exim distribution" "SECTavail" |
| 513 | .cindex "FTP site" |
| 514 | .cindex "distribution" "ftp site" |
| 515 | The master ftp site for the Exim distribution is |
| 516 | .display |
| 517 | &*ftp://ftp.csx.cam.ac.uk/pub/software/email/exim*& |
| 518 | .endd |
| 519 | This is mirrored by |
| 520 | .display |
| 521 | &*ftp://ftp.exim.org/pub/exim*& |
| 522 | .endd |
| 523 | The file references that follow are relative to the &_exim_& directories at |
| 524 | these sites. There are now quite a number of independent mirror sites around |
| 525 | the world. Those that I know about are listed in the file called &_Mirrors_&. |
| 526 | |
| 527 | Within the &_exim_& directory there are subdirectories called &_exim3_& (for |
| 528 | previous Exim 3 distributions), &_exim4_& (for the latest Exim 4 |
| 529 | distributions), and &_Testing_& for testing versions. In the &_exim4_& |
| 530 | subdirectory, the current release can always be found in files called |
| 531 | .display |
| 532 | &_exim-n.nn.tar.gz_& |
| 533 | &_exim-n.nn.tar.bz2_& |
| 534 | .endd |
| 535 | where &'n.nn'& is the highest such version number in the directory. The two |
| 536 | files contain identical data; the only difference is the type of compression. |
| 537 | The &_.bz2_& file is usually a lot smaller than the &_.gz_& file. |
| 538 | |
| 539 | .cindex "distribution" "signing details" |
| 540 | .cindex "distribution" "public key" |
| 541 | .cindex "public key for signed distribution" |
| 542 | The distributions will be PGP signed by an individual key of the Release |
| 543 | Coordinator. This key will have a uid containing an email address in the |
| 544 | &'exim.org'& domain and will have signatures from other people, including |
| 545 | other Exim maintainers. We expect that the key will be in the "strong set" of |
| 546 | PGP keys. There should be a trust path to that key from Nigel Metheringham's |
| 547 | PGP key, a version of which can be found in the release directory in the file |
| 548 | &_nigel-pubkey.asc_&. All keys used will be available in public keyserver pools, |
| 549 | such as &'pool.sks-keyservers.net'&. |
| 550 | |
| 551 | At time of last update, releases were being made by Phil Pennock and signed with |
| 552 | key &'0x403043153903637F'&, although that key is expected to be replaced in 2013. |
| 553 | A trust path from Nigel's key to Phil's can be observed at |
| 554 | &url(https://www.security.spodhuis.org/exim-trustpath). |
| 555 | |
| 556 | Releases have also been authorized to be performed by Todd Lyons who signs with |
| 557 | key &'0xC4F4F94804D29EBA'&. A direct trust path exists between previous RE Phil |
| 558 | Pennock and Todd Lyons through a common associate. |
| 559 | |
| 560 | The signatures for the tar bundles are in: |
| 561 | .display |
| 562 | &_exim-n.nn.tar.gz.asc_& |
| 563 | &_exim-n.nn.tar.bz2.asc_& |
| 564 | .endd |
| 565 | For each released version, the log of changes is made separately available in a |
| 566 | separate file in the directory &_ChangeLogs_& so that it is possible to |
| 567 | find out what has changed without having to download the entire distribution. |
| 568 | |
| 569 | .cindex "documentation" "available formats" |
| 570 | The main distribution contains ASCII versions of this specification and other |
| 571 | documentation; other formats of the documents are available in separate files |
| 572 | inside the &_exim4_& directory of the FTP site: |
| 573 | .display |
| 574 | &_exim-html-n.nn.tar.gz_& |
| 575 | &_exim-pdf-n.nn.tar.gz_& |
| 576 | &_exim-postscript-n.nn.tar.gz_& |
| 577 | &_exim-texinfo-n.nn.tar.gz_& |
| 578 | .endd |
| 579 | These tar files contain only the &_doc_& directory, not the complete |
| 580 | distribution, and are also available in &_.bz2_& as well as &_.gz_& forms. |
| 581 | |
| 582 | |
| 583 | .section "Limitations" "SECID6" |
| 584 | .ilist |
| 585 | .cindex "limitations of Exim" |
| 586 | .cindex "bang paths" "not handled by Exim" |
| 587 | Exim is designed for use as an Internet MTA, and therefore handles addresses in |
| 588 | RFC 2822 domain format only. It cannot handle UUCP &"bang paths"&, though |
| 589 | simple two-component bang paths can be converted by a straightforward rewriting |
| 590 | configuration. This restriction does not prevent Exim from being interfaced to |
| 591 | UUCP as a transport mechanism, provided that domain addresses are used. |
| 592 | .next |
| 593 | .cindex "domainless addresses" |
| 594 | .cindex "address" "without domain" |
| 595 | Exim insists that every address it handles has a domain attached. For incoming |
| 596 | local messages, domainless addresses are automatically qualified with a |
| 597 | configured domain value. Configuration options specify from which remote |
| 598 | systems unqualified addresses are acceptable. These are then qualified on |
| 599 | arrival. |
| 600 | .next |
| 601 | .cindex "transport" "external" |
| 602 | .cindex "external transports" |
| 603 | The only external transport mechanisms that are currently implemented are SMTP |
| 604 | and LMTP over a TCP/IP network (including support for IPv6). However, a pipe |
| 605 | transport is available, and there are facilities for writing messages to files |
| 606 | and pipes, optionally in &'batched SMTP'& format; these facilities can be used |
| 607 | to send messages to other transport mechanisms such as UUCP, provided they can |
| 608 | handle domain-style addresses. Batched SMTP input is also catered for. |
| 609 | .next |
| 610 | Exim is not designed for storing mail for dial-in hosts. When the volumes of |
| 611 | such mail are large, it is better to get the messages &"delivered"& into files |
| 612 | (that is, off Exim's queue) and subsequently passed on to the dial-in hosts by |
| 613 | other means. |
| 614 | .next |
| 615 | Although Exim does have basic facilities for scanning incoming messages, these |
| 616 | are not comprehensive enough to do full virus or spam scanning. Such operations |
| 617 | are best carried out using additional specialized software packages. If you |
| 618 | compile Exim with the content-scanning extension, straightforward interfaces to |
| 619 | a number of common scanners are provided. |
| 620 | .endlist |
| 621 | |
| 622 | |
| 623 | .section "Run time configuration" "SECID7" |
| 624 | Exim's run time configuration is held in a single text file that is divided |
| 625 | into a number of sections. The entries in this file consist of keywords and |
| 626 | values, in the style of Smail 3 configuration files. A default configuration |
| 627 | file which is suitable for simple online installations is provided in the |
| 628 | distribution, and is described in chapter &<<CHAPdefconfil>>& below. |
| 629 | |
| 630 | |
| 631 | .section "Calling interface" "SECID8" |
| 632 | .cindex "Sendmail compatibility" "command line interface" |
| 633 | Like many MTAs, Exim has adopted the Sendmail command line interface so that it |
| 634 | can be a straight replacement for &_/usr/lib/sendmail_& or |
| 635 | &_/usr/sbin/sendmail_& when sending mail, but you do not need to know anything |
| 636 | about Sendmail in order to run Exim. For actions other than sending messages, |
| 637 | Sendmail-compatible options also exist, but those that produce output (for |
| 638 | example, &%-bp%&, which lists the messages on the queue) do so in Exim's own |
| 639 | format. There are also some additional options that are compatible with Smail |
| 640 | 3, and some further options that are new to Exim. Chapter &<<CHAPcommandline>>& |
| 641 | documents all Exim's command line options. This information is automatically |
| 642 | made into the man page that forms part of the Exim distribution. |
| 643 | |
| 644 | Control of messages on the queue can be done via certain privileged command |
| 645 | line options. There is also an optional monitor program called &'eximon'&, |
| 646 | which displays current information in an X window, and which contains a menu |
| 647 | interface to Exim's command line administration options. |
| 648 | |
| 649 | |
| 650 | |
| 651 | .section "Terminology" "SECID9" |
| 652 | .cindex "terminology definitions" |
| 653 | .cindex "body of message" "definition of" |
| 654 | The &'body'& of a message is the actual data that the sender wants to transmit. |
| 655 | It is the last part of a message, and is separated from the &'header'& (see |
| 656 | below) by a blank line. |
| 657 | |
| 658 | .cindex "bounce message" "definition of" |
| 659 | When a message cannot be delivered, it is normally returned to the sender in a |
| 660 | delivery failure message or a &"non-delivery report"& (NDR). The term |
| 661 | &'bounce'& is commonly used for this action, and the error reports are often |
| 662 | called &'bounce messages'&. This is a convenient shorthand for &"delivery |
| 663 | failure error report"&. Such messages have an empty sender address in the |
| 664 | message's &'envelope'& (see below) to ensure that they cannot themselves give |
| 665 | 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 &'not'& used in that sense here, where it normally refers to |
| 679 | the part of an email address following the @ sign. |
| 680 | |
| 681 | .cindex "envelope, definition of" |
| 682 | .cindex "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 | .cindex "message" "header, definition of" |
| 691 | .cindex "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 | .cindex "local part" "definition of" |
| 699 | .cindex "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 | .cindex "local delivery" "definition of" |
| 705 | .cindex "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 another host. As far as Exim is concerned, all hosts other than the |
| 709 | host it is running on are &'remote'&. |
| 710 | |
| 711 | .cindex "return path" "definition of" |
| 712 | &'Return path'& is another name that is used for the sender address in a |
| 713 | message's envelope. |
| 714 | |
| 715 | .cindex "queue" "definition of" |
| 716 | The term &'queue'& is used to refer to the set of messages awaiting delivery, |
| 717 | because this term is in widespread use in the context of MTAs. However, in |
| 718 | Exim's case the reality is more like a pool than a queue, because there is |
| 719 | normally no ordering of waiting messages. |
| 720 | |
| 721 | .cindex "queue runner" "definition of" |
| 722 | The term &'queue runner'& is used to describe a process that scans the queue |
| 723 | and attempts to deliver those messages whose retry times have come. This term |
| 724 | is used by other MTAs, and also relates to the command &%runq%&, but in Exim |
| 725 | the waiting messages are normally processed in an unpredictable order. |
| 726 | |
| 727 | .cindex "spool directory" "definition of" |
| 728 | The term &'spool directory'& is used for a directory in which Exim keeps the |
| 729 | messages on its queue &-- that is, those that it is in the process of |
| 730 | delivering. This should not be confused with the directory in which local |
| 731 | mailboxes are stored, which is called a &"spool directory"& by some people. In |
| 732 | the Exim documentation, &"spool"& is always used in the first sense. |
| 733 | |
| 734 | |
| 735 | |
| 736 | |
| 737 | |
| 738 | |
| 739 | . //////////////////////////////////////////////////////////////////////////// |
| 740 | . //////////////////////////////////////////////////////////////////////////// |
| 741 | |
| 742 | .chapter "Incorporated code" "CHID2" |
| 743 | .cindex "incorporated code" |
| 744 | .cindex "regular expressions" "library" |
| 745 | .cindex "PCRE" |
| 746 | .cindex "OpenDMARC" |
| 747 | A number of pieces of external code are included in the Exim distribution. |
| 748 | |
| 749 | .ilist |
| 750 | Regular expressions are supported in the main Exim program and in the |
| 751 | Exim monitor using the freely-distributable PCRE library, copyright |
| 752 | © University of Cambridge. The source to PCRE is no longer shipped with |
| 753 | Exim, so you will need to use the version of PCRE shipped with your system, |
| 754 | or obtain and install the full version of the library from |
| 755 | &url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre). |
| 756 | .next |
| 757 | .cindex "cdb" "acknowledgment" |
| 758 | Support for the cdb (Constant DataBase) lookup method is provided by code |
| 759 | contributed by Nigel Metheringham of (at the time he contributed it) Planet |
| 760 | Online Ltd. The implementation is completely contained within the code of Exim. |
| 761 | It does not link against an external cdb library. The code contains the |
| 762 | following statements: |
| 763 | |
| 764 | .blockquote |
| 765 | Copyright © 1998 Nigel Metheringham, Planet Online Ltd |
| 766 | |
| 767 | This program is free software; you can redistribute it and/or modify it under |
| 768 | the terms of the GNU General Public License as published by the Free Software |
| 769 | Foundation; either version 2 of the License, or (at your option) any later |
| 770 | version. |
| 771 | This code implements Dan Bernstein's Constant DataBase (cdb) spec. Information, |
| 772 | the spec and sample code for cdb can be obtained from |
| 773 | &url(http://www.pobox.com/~djb/cdb.html). This implementation borrows |
| 774 | some code from Dan Bernstein's implementation (which has no license |
| 775 | restrictions applied to it). |
| 776 | .endblockquote |
| 777 | .next |
| 778 | .cindex "SPA authentication" |
| 779 | .cindex "Samba project" |
| 780 | .cindex "Microsoft Secure Password Authentication" |
| 781 | Client support for Microsoft's &'Secure Password Authentication'& is provided |
| 782 | by code contributed by Marc Prud'hommeaux. Server support was contributed by |
| 783 | Tom Kistner. This includes code taken from the Samba project, which is released |
| 784 | under the Gnu GPL. |
| 785 | .next |
| 786 | .cindex "Cyrus" |
| 787 | .cindex "&'pwcheck'& daemon" |
| 788 | .cindex "&'pwauthd'& daemon" |
| 789 | Support for calling the Cyrus &'pwcheck'& and &'saslauthd'& daemons is provided |
| 790 | by code taken from the Cyrus-SASL library and adapted by Alexander S. |
| 791 | Sabourenkov. The permission notice appears below, in accordance with the |
| 792 | conditions expressed therein. |
| 793 | |
| 794 | .blockquote |
| 795 | Copyright © 2001 Carnegie Mellon University. All rights reserved. |
| 796 | |
| 797 | Redistribution and use in source and binary forms, with or without |
| 798 | modification, are permitted provided that the following conditions |
| 799 | are met: |
| 800 | |
| 801 | .olist |
| 802 | Redistributions of source code must retain the above copyright |
| 803 | notice, this list of conditions and the following disclaimer. |
| 804 | .next |
| 805 | Redistributions in binary form must reproduce the above copyright |
| 806 | notice, this list of conditions and the following disclaimer in |
| 807 | the documentation and/or other materials provided with the |
| 808 | distribution. |
| 809 | .next |
| 810 | The name &"Carnegie Mellon University"& must not be used to |
| 811 | endorse or promote products derived from this software without |
| 812 | prior written permission. For permission or any other legal |
| 813 | details, please contact |
| 814 | .display |
| 815 | Office of Technology Transfer |
| 816 | Carnegie Mellon University |
| 817 | 5000 Forbes Avenue |
| 818 | Pittsburgh, PA 15213-3890 |
| 819 | (412) 268-4387, fax: (412) 268-7395 |
| 820 | tech-transfer@andrew.cmu.edu |
| 821 | .endd |
| 822 | .next |
| 823 | Redistributions of any form whatsoever must retain the following |
| 824 | acknowledgment: |
| 825 | |
| 826 | &"This product includes software developed by Computing Services |
| 827 | at Carnegie Mellon University (&url(http://www.cmu.edu/computing/)."& |
| 828 | |
| 829 | CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO |
| 830 | THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY |
| 831 | AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE |
| 832 | FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
| 833 | WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN |
| 834 | AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING |
| 835 | OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
| 836 | .endlist |
| 837 | .endblockquote |
| 838 | |
| 839 | .next |
| 840 | .cindex "Exim monitor" "acknowledgment" |
| 841 | .cindex "X-windows" |
| 842 | .cindex "Athena" |
| 843 | The Exim Monitor program, which is an X-Window application, includes |
| 844 | modified versions of the Athena StripChart and TextPop widgets. |
| 845 | This code is copyright by DEC and MIT, and their permission notice appears |
| 846 | below, in accordance with the conditions expressed therein. |
| 847 | |
| 848 | .blockquote |
| 849 | Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, Massachusetts, |
| 850 | and the Massachusetts Institute of Technology, Cambridge, Massachusetts. |
| 851 | |
| 852 | All Rights Reserved |
| 853 | |
| 854 | Permission to use, copy, modify, and distribute this software and its |
| 855 | documentation for any purpose and without fee is hereby granted, |
| 856 | provided that the above copyright notice appear in all copies and that |
| 857 | both that copyright notice and this permission notice appear in |
| 858 | supporting documentation, and that the names of Digital or MIT not be |
| 859 | used in advertising or publicity pertaining to distribution of the |
| 860 | software without specific, written prior permission. |
| 861 | |
| 862 | DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING |
| 863 | ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL |
| 864 | DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR |
| 865 | ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, |
| 866 | WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, |
| 867 | ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS |
| 868 | SOFTWARE. |
| 869 | .endblockquote |
| 870 | |
| 871 | .next |
| 872 | .cindex "opendmarc" "acknowledgment" |
| 873 | The DMARC implementation uses the OpenDMARC library which is Copyrighted by |
| 874 | The Trusted Domain Project. Portions of Exim source which use OpenDMARC |
| 875 | derived code are indicated in the respective source files. The full OpenDMARC |
| 876 | license is provided in the LICENSE.opendmarc file contained in the distributed |
| 877 | source code. |
| 878 | |
| 879 | .next |
| 880 | Many people have contributed code fragments, some large, some small, that were |
| 881 | not covered by any specific licence requirements. It is assumed that the |
| 882 | contributors are happy to see their code incorporated into Exim under the GPL. |
| 883 | .endlist |
| 884 | |
| 885 | |
| 886 | |
| 887 | |
| 888 | |
| 889 | . //////////////////////////////////////////////////////////////////////////// |
| 890 | . //////////////////////////////////////////////////////////////////////////// |
| 891 | |
| 892 | .chapter "How Exim receives and delivers mail" "CHID11" &&& |
| 893 | "Receiving and delivering mail" |
| 894 | |
| 895 | |
| 896 | .section "Overall philosophy" "SECID10" |
| 897 | .cindex "design philosophy" |
| 898 | Exim is designed to work efficiently on systems that are permanently connected |
| 899 | to the Internet and are handling a general mix of mail. In such circumstances, |
| 900 | most messages can be delivered immediately. Consequently, Exim does not |
| 901 | maintain independent queues of messages for specific domains or hosts, though |
| 902 | it does try to send several messages in a single SMTP connection after a host |
| 903 | has been down, and it also maintains per-host retry information. |
| 904 | |
| 905 | |
| 906 | .section "Policy control" "SECID11" |
| 907 | .cindex "policy control" "overview" |
| 908 | Policy controls are now an important feature of MTAs that are connected to the |
| 909 | Internet. Perhaps their most important job is to stop MTAs being abused as |
| 910 | &"open relays"& by misguided individuals who send out vast amounts of |
| 911 | unsolicited junk, and want to disguise its source. Exim provides flexible |
| 912 | facilities for specifying policy controls on incoming mail: |
| 913 | |
| 914 | .ilist |
| 915 | .cindex "&ACL;" "introduction" |
| 916 | Exim 4 (unlike previous versions of Exim) implements policy controls on |
| 917 | incoming mail by means of &'Access Control Lists'& (ACLs). Each list is a |
| 918 | series of statements that may either grant or deny access. ACLs can be used at |
| 919 | several places in the SMTP dialogue while receiving a message from a remote |
| 920 | host. However, the most common places are after each RCPT command, and at the |
| 921 | very end of the message. The sysadmin can specify conditions for accepting or |
| 922 | rejecting individual recipients or the entire message, respectively, at these |
| 923 | two points (see chapter &<<CHAPACL>>&). Denial of access results in an SMTP |
| 924 | error code. |
| 925 | .next |
| 926 | An ACL is also available for locally generated, non-SMTP messages. In this |
| 927 | case, the only available actions are to accept or deny the entire message. |
| 928 | .next |
| 929 | When Exim is compiled with the content-scanning extension, facilities are |
| 930 | provided in the ACL mechanism for passing the message to external virus and/or |
| 931 | spam scanning software. The result of such a scan is passed back to the ACL, |
| 932 | which can then use it to decide what to do with the message. |
| 933 | .next |
| 934 | When a message has been received, either from a remote host or from the local |
| 935 | host, but before the final acknowledgment has been sent, a locally supplied C |
| 936 | function called &[local_scan()]& can be run to inspect the message and decide |
| 937 | whether to accept it or not (see chapter &<<CHAPlocalscan>>&). If the message |
| 938 | is accepted, the list of recipients can be modified by the function. |
| 939 | .next |
| 940 | Using the &[local_scan()]& mechanism is another way of calling external scanner |
| 941 | software. The &%SA-Exim%& add-on package works this way. It does not require |
| 942 | Exim to be compiled with the content-scanning extension. |
| 943 | .next |
| 944 | After a message has been accepted, a further checking mechanism is available in |
| 945 | the form of the &'system filter'& (see chapter &<<CHAPsystemfilter>>&). This |
| 946 | runs at the start of every delivery process. |
| 947 | .endlist |
| 948 | |
| 949 | |
| 950 | |
| 951 | .section "User filters" "SECID12" |
| 952 | .cindex "filter" "introduction" |
| 953 | .cindex "Sieve filter" |
| 954 | In a conventional Exim configuration, users are able to run private filters by |
| 955 | setting up appropriate &_.forward_& files in their home directories. See |
| 956 | chapter &<<CHAPredirect>>& (about the &(redirect)& router) for the |
| 957 | configuration needed to support this, and the separate document entitled |
| 958 | &'Exim's interfaces to mail filtering'& for user details. Two different kinds |
| 959 | of filtering are available: |
| 960 | |
| 961 | .ilist |
| 962 | Sieve filters are written in the standard filtering language that is defined |
| 963 | by RFC 3028. |
| 964 | .next |
| 965 | Exim filters are written in a syntax that is unique to Exim, but which is more |
| 966 | powerful than Sieve, which it pre-dates. |
| 967 | .endlist |
| 968 | |
| 969 | User filters are run as part of the routing process, described below. |
| 970 | |
| 971 | |
| 972 | |
| 973 | .section "Message identification" "SECTmessiden" |
| 974 | .cindex "message ids" "details of format" |
| 975 | .cindex "format" "of message id" |
| 976 | .cindex "id of message" |
| 977 | .cindex "base62" |
| 978 | .cindex "base36" |
| 979 | .cindex "Darwin" |
| 980 | .cindex "Cygwin" |
| 981 | Every message handled by Exim is given a &'message id'& which is sixteen |
| 982 | characters long. It is divided into three parts, separated by hyphens, for |
| 983 | example &`16VDhn-0001bo-D3`&. Each part is a sequence of letters and digits, |
| 984 | normally encoding numbers in base 62. However, in the Darwin operating |
| 985 | system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36 |
| 986 | (avoiding the use of lower case letters) is used instead, because the message |
| 987 | id is used to construct file names, and the names of files in those systems are |
| 988 | not always case-sensitive. |
| 989 | |
| 990 | .cindex "pid (process id)" "re-use of" |
| 991 | The detail of the contents of the message id have changed as Exim has evolved. |
| 992 | Earlier versions relied on the operating system not re-using a process id (pid) |
| 993 | within one second. On modern operating systems, this assumption can no longer |
| 994 | be made, so the algorithm had to be changed. To retain backward compatibility, |
| 995 | the format of the message id was retained, which is why the following rules are |
| 996 | somewhat eccentric: |
| 997 | |
| 998 | .ilist |
| 999 | The first six characters of the message id are the time at which the message |
| 1000 | started to be received, to a granularity of one second. That is, this field |
| 1001 | contains the number of seconds since the start of the epoch (the normal Unix |
| 1002 | way of representing the date and time of day). |
| 1003 | .next |
| 1004 | After the first hyphen, the next six characters are the id of the process that |
| 1005 | received the message. |
| 1006 | .next |
| 1007 | There are two different possibilities for the final two characters: |
| 1008 | .olist |
| 1009 | .oindex "&%localhost_number%&" |
| 1010 | If &%localhost_number%& is not set, this value is the fractional part of the |
| 1011 | time of reception, normally in units of 1/2000 of a second, but for systems |
| 1012 | that must use base 36 instead of base 62 (because of case-insensitive file |
| 1013 | systems), the units are 1/1000 of a second. |
| 1014 | .next |
| 1015 | If &%localhost_number%& is set, it is multiplied by 200 (100) and added to |
| 1016 | the fractional part of the time, which in this case is in units of 1/200 |
| 1017 | (1/100) of a second. |
| 1018 | .endlist |
| 1019 | .endlist |
| 1020 | |
| 1021 | After a message has been received, Exim waits for the clock to tick at the |
| 1022 | appropriate resolution before proceeding, so that if another message is |
| 1023 | received by the same process, or by another process with the same (re-used) |
| 1024 | pid, it is guaranteed that the time will be different. In most cases, the clock |
| 1025 | will already have ticked while the message was being received. |
| 1026 | |
| 1027 | |
| 1028 | .section "Receiving mail" "SECID13" |
| 1029 | .cindex "receiving mail" |
| 1030 | .cindex "message" "reception" |
| 1031 | The only way Exim can receive mail from another host is using SMTP over |
| 1032 | TCP/IP, in which case the sender and recipient addresses are transferred using |
| 1033 | SMTP commands. However, from a locally running process (such as a user's MUA), |
| 1034 | there are several possibilities: |
| 1035 | |
| 1036 | .ilist |
| 1037 | If the process runs Exim with the &%-bm%& option, the message is read |
| 1038 | non-interactively (usually via a pipe), with the recipients taken from the |
| 1039 | command line, or from the body of the message if &%-t%& is also used. |
| 1040 | .next |
| 1041 | If the process runs Exim with the &%-bS%& option, the message is also read |
| 1042 | non-interactively, but in this case the recipients are listed at the start of |
| 1043 | the message in a series of SMTP RCPT commands, terminated by a DATA |
| 1044 | command. This is so-called &"batch SMTP"& format, |
| 1045 | but it isn't really SMTP. The SMTP commands are just another way of passing |
| 1046 | envelope addresses in a non-interactive submission. |
| 1047 | .next |
| 1048 | If the process runs Exim with the &%-bs%& option, the message is read |
| 1049 | interactively, using the SMTP protocol. A two-way pipe is normally used for |
| 1050 | passing data between the local process and the Exim process. |
| 1051 | This is &"real"& SMTP and is handled in the same way as SMTP over TCP/IP. For |
| 1052 | example, the ACLs for SMTP commands are used for this form of submission. |
| 1053 | .next |
| 1054 | A local process may also make a TCP/IP call to the host's loopback address |
| 1055 | (127.0.0.1) or any other of its IP addresses. When receiving messages, Exim |
| 1056 | does not treat the loopback address specially. It treats all such connections |
| 1057 | in the same way as connections from other hosts. |
| 1058 | .endlist |
| 1059 | |
| 1060 | |
| 1061 | .cindex "message sender, constructed by Exim" |
| 1062 | .cindex "sender" "constructed by Exim" |
| 1063 | In the three cases that do not involve TCP/IP, the sender address is |
| 1064 | constructed from the login name of the user that called Exim and a default |
| 1065 | qualification domain (which can be set by the &%qualify_domain%& configuration |
| 1066 | option). For local or batch SMTP, a sender address that is passed using the |
| 1067 | SMTP MAIL command is ignored. However, the system administrator may allow |
| 1068 | certain users (&"trusted users"&) to specify a different sender address |
| 1069 | unconditionally, or all users to specify certain forms of different sender |
| 1070 | address. The &%-f%& option or the SMTP MAIL command is used to specify these |
| 1071 | different addresses. See section &<<SECTtrustedadmin>>& for details of trusted |
| 1072 | users, and the &%untrusted_set_sender%& option for a way of allowing untrusted |
| 1073 | users to change sender addresses. |
| 1074 | |
| 1075 | Messages received by either of the non-interactive mechanisms are subject to |
| 1076 | checking by the non-SMTP ACL, if one is defined. Messages received using SMTP |
| 1077 | (either over TCP/IP, or interacting with a local process) can be checked by a |
| 1078 | number of ACLs that operate at different times during the SMTP session. Either |
| 1079 | individual recipients, or the entire message, can be rejected if local policy |
| 1080 | requirements are not met. The &[local_scan()]& function (see chapter |
| 1081 | &<<CHAPlocalscan>>&) is run for all incoming messages. |
| 1082 | |
| 1083 | Exim can be configured not to start a delivery process when a message is |
| 1084 | received; this can be unconditional, or depend on the number of incoming SMTP |
| 1085 | connections or the system load. In these situations, new messages wait on the |
| 1086 | queue until a queue runner process picks them up. However, in standard |
| 1087 | configurations under normal conditions, delivery is started as soon as a |
| 1088 | message is received. |
| 1089 | |
| 1090 | |
| 1091 | |
| 1092 | |
| 1093 | |
| 1094 | .section "Handling an incoming message" "SECID14" |
| 1095 | .cindex "spool directory" "files that hold a message" |
| 1096 | .cindex "file" "how a message is held" |
| 1097 | When Exim accepts a message, it writes two files in its spool directory. The |
| 1098 | first contains the envelope information, the current status of the message, and |
| 1099 | the header lines, and the second contains the body of the message. The names of |
| 1100 | the two spool files consist of the message id, followed by &`-H`& for the |
| 1101 | file containing the envelope and header, and &`-D`& for the data file. |
| 1102 | |
| 1103 | .cindex "spool directory" "&_input_& sub-directory" |
| 1104 | By default all these message files are held in a single directory called |
| 1105 | &_input_& inside the general Exim spool directory. Some operating systems do |
| 1106 | not perform very well if the number of files in a directory gets large; to |
| 1107 | improve performance in such cases, the &%split_spool_directory%& option can be |
| 1108 | used. This causes Exim to split up the input files into 62 sub-directories |
| 1109 | whose names are single letters or digits. When this is done, the queue is |
| 1110 | processed one sub-directory at a time instead of all at once, which can improve |
| 1111 | overall performance even when there are not enough files in each directory to |
| 1112 | affect file system performance. |
| 1113 | |
| 1114 | The envelope information consists of the address of the message's sender and |
| 1115 | the addresses of the recipients. This information is entirely separate from |
| 1116 | any addresses contained in the header lines. The status of the message includes |
| 1117 | a list of recipients who have already received the message. The format of the |
| 1118 | first spool file is described in chapter &<<CHAPspool>>&. |
| 1119 | |
| 1120 | .cindex "rewriting" "addresses" |
| 1121 | Address rewriting that is specified in the rewrite section of the configuration |
| 1122 | (see chapter &<<CHAPrewrite>>&) is done once and for all on incoming addresses, |
| 1123 | both in the header lines and the envelope, at the time the message is accepted. |
| 1124 | If during the course of delivery additional addresses are generated (for |
| 1125 | example, via aliasing), these new addresses are rewritten as soon as they are |
| 1126 | generated. At the time a message is actually delivered (transported) further |
| 1127 | rewriting can take place; because this is a transport option, it can be |
| 1128 | different for different forms of delivery. It is also possible to specify the |
| 1129 | addition or removal of certain header lines at the time the message is |
| 1130 | delivered (see chapters &<<CHAProutergeneric>>& and |
| 1131 | &<<CHAPtransportgeneric>>&). |
| 1132 | |
| 1133 | |
| 1134 | |
| 1135 | .section "Life of a message" "SECID15" |
| 1136 | .cindex "message" "life of" |
| 1137 | .cindex "message" "frozen" |
| 1138 | A message remains in the spool directory until it is completely delivered to |
| 1139 | its recipients or to an error address, or until it is deleted by an |
| 1140 | administrator or by the user who originally created it. In cases when delivery |
| 1141 | cannot proceed &-- for example, when a message can neither be delivered to its |
| 1142 | recipients nor returned to its sender, the message is marked &"frozen"& on the |
| 1143 | spool, and no more deliveries are attempted. |
| 1144 | |
| 1145 | .cindex "frozen messages" "thawing" |
| 1146 | .cindex "message" "thawing frozen" |
| 1147 | An administrator can &"thaw"& such messages when the problem has been |
| 1148 | corrected, and can also freeze individual messages by hand if necessary. In |
| 1149 | addition, an administrator can force a delivery error, causing a bounce message |
| 1150 | to be sent. |
| 1151 | |
| 1152 | .oindex "&%timeout_frozen_after%&" |
| 1153 | .oindex "&%ignore_bounce_errors_after%&" |
| 1154 | There are options called &%ignore_bounce_errors_after%& and |
| 1155 | &%timeout_frozen_after%&, which discard frozen messages after a certain time. |
| 1156 | The first applies only to frozen bounces, the second to any frozen messages. |
| 1157 | |
| 1158 | .cindex "message" "log file for" |
| 1159 | .cindex "log" "file for each message" |
| 1160 | While Exim is working on a message, it writes information about each delivery |
| 1161 | attempt to its main log file. This includes successful, unsuccessful, and |
| 1162 | delayed deliveries for each recipient (see chapter &<<CHAPlog>>&). The log |
| 1163 | lines are also written to a separate &'message log'& file for each message. |
| 1164 | These logs are solely for the benefit of the administrator, and are normally |
| 1165 | deleted along with the spool files when processing of a message is complete. |
| 1166 | The use of individual message logs can be disabled by setting |
| 1167 | &%no_message_logs%&; this might give an improvement in performance on very busy |
| 1168 | systems. |
| 1169 | |
| 1170 | .cindex "journal file" |
| 1171 | .cindex "file" "journal" |
| 1172 | All the information Exim itself needs to set up a delivery is kept in the first |
| 1173 | spool file, along with the header lines. When a successful delivery occurs, the |
| 1174 | address is immediately written at the end of a journal file, whose name is the |
| 1175 | message id followed by &`-J`&. At the end of a delivery run, if there are some |
| 1176 | addresses left to be tried again later, the first spool file (the &`-H`& file) |
| 1177 | is updated to indicate which these are, and the journal file is then deleted. |
| 1178 | Updating the spool file is done by writing a new file and renaming it, to |
| 1179 | minimize the possibility of data loss. |
| 1180 | |
| 1181 | Should the system or the program crash after a successful delivery but before |
| 1182 | the spool file has been updated, the journal is left lying around. The next |
| 1183 | time Exim attempts to deliver the message, it reads the journal file and |
| 1184 | updates the spool file before proceeding. This minimizes the chances of double |
| 1185 | deliveries caused by crashes. |
| 1186 | |
| 1187 | |
| 1188 | |
| 1189 | .section "Processing an address for delivery" "SECTprocaddress" |
| 1190 | .cindex "drivers" "definition of" |
| 1191 | .cindex "router" "definition of" |
| 1192 | .cindex "transport" "definition of" |
| 1193 | The main delivery processing elements of Exim are called &'routers'& and |
| 1194 | &'transports'&, and collectively these are known as &'drivers'&. Code for a |
| 1195 | number of them is provided in the source distribution, and compile-time options |
| 1196 | specify which ones are included in the binary. Run time options specify which |
| 1197 | ones are actually used for delivering messages. |
| 1198 | |
| 1199 | .cindex "drivers" "instance definition" |
| 1200 | Each driver that is specified in the run time configuration is an &'instance'& |
| 1201 | of that particular driver type. Multiple instances are allowed; for example, |
| 1202 | you can set up several different &(smtp)& transports, each with different |
| 1203 | option values that might specify different ports or different timeouts. Each |
| 1204 | instance has its own identifying name. In what follows we will normally use the |
| 1205 | instance name when discussing one particular instance (that is, one specific |
| 1206 | configuration of the driver), and the generic driver name when discussing |
| 1207 | the driver's features in general. |
| 1208 | |
| 1209 | A &'router'& is a driver that operates on an address, either determining how |
| 1210 | its delivery should happen, by assigning it to a specific transport, or |
| 1211 | converting the address into one or more new addresses (for example, via an |
| 1212 | alias file). A router may also explicitly choose to fail an address, causing it |
| 1213 | to be bounced. |
| 1214 | |
| 1215 | A &'transport'& is a driver that transmits a copy of the message from Exim's |
| 1216 | spool to some destination. There are two kinds of transport: for a &'local'& |
| 1217 | transport, the destination is a file or a pipe on the local host, whereas for a |
| 1218 | &'remote'& transport the destination is some other host. A message is passed |
| 1219 | to a specific transport as a result of successful routing. If a message has |
| 1220 | several recipients, it may be passed to a number of different transports. |
| 1221 | |
| 1222 | .cindex "preconditions" "definition of" |
| 1223 | An address is processed by passing it to each configured router instance in |
| 1224 | turn, subject to certain preconditions, until a router accepts the address or |
| 1225 | specifies that it should be bounced. We will describe this process in more |
| 1226 | detail shortly. First, as a simple example, we consider how each recipient |
| 1227 | address in a message is processed in a small configuration of three routers. |
| 1228 | |
| 1229 | To make this a more concrete example, it is described in terms of some actual |
| 1230 | routers, but remember, this is only an example. You can configure Exim's |
| 1231 | routers in many different ways, and there may be any number of routers in a |
| 1232 | configuration. |
| 1233 | |
| 1234 | The first router that is specified in a configuration is often one that handles |
| 1235 | addresses in domains that are not recognized specially by the local host. These |
| 1236 | are typically addresses for arbitrary domains on the Internet. A precondition |
| 1237 | is set up which looks for the special domains known to the host (for example, |
| 1238 | its own domain name), and the router is run for addresses that do &'not'& |
| 1239 | match. Typically, this is a router that looks up domains in the DNS in order to |
| 1240 | find the hosts to which this address routes. If it succeeds, the address is |
| 1241 | assigned to a suitable SMTP transport; if it does not succeed, the router is |
| 1242 | configured to fail the address. |
| 1243 | |
| 1244 | The second router is reached only when the domain is recognized as one that |
| 1245 | &"belongs"& to the local host. This router does redirection &-- also known as |
| 1246 | aliasing and forwarding. When it generates one or more new addresses from the |
| 1247 | original, each of them is routed independently from the start. Otherwise, the |
| 1248 | router may cause an address to fail, or it may simply decline to handle the |
| 1249 | address, in which case the address is passed to the next router. |
| 1250 | |
| 1251 | The final router in many configurations is one that checks to see if the |
| 1252 | address belongs to a local mailbox. The precondition may involve a check to |
| 1253 | see if the local part is the name of a login account, or it may look up the |
| 1254 | local part in a file or a database. If its preconditions are not met, or if |
| 1255 | the router declines, we have reached the end of the routers. When this happens, |
| 1256 | the address is bounced. |
| 1257 | |
| 1258 | |
| 1259 | |
| 1260 | .section "Processing an address for verification" "SECID16" |
| 1261 | .cindex "router" "for verification" |
| 1262 | .cindex "verifying address" "overview" |
| 1263 | As well as being used to decide how to deliver to an address, Exim's routers |
| 1264 | are also used for &'address verification'&. Verification can be requested as |
| 1265 | one of the checks to be performed in an ACL for incoming messages, on both |
| 1266 | sender and recipient addresses, and it can be tested using the &%-bv%& and |
| 1267 | &%-bvs%& command line options. |
| 1268 | |
| 1269 | When an address is being verified, the routers are run in &"verify mode"&. This |
| 1270 | does not affect the way the routers work, but it is a state that can be |
| 1271 | detected. By this means, a router can be skipped or made to behave differently |
| 1272 | when verifying. A common example is a configuration in which the first router |
| 1273 | sends all messages to a message-scanning program, unless they have been |
| 1274 | previously scanned. Thus, the first router accepts all addresses without any |
| 1275 | checking, making it useless for verifying. Normally, the &%no_verify%& option |
| 1276 | would be set for such a router, causing it to be skipped in verify mode. |
| 1277 | |
| 1278 | |
| 1279 | |
| 1280 | |
| 1281 | .section "Running an individual router" "SECTrunindrou" |
| 1282 | .cindex "router" "running details" |
| 1283 | .cindex "preconditions" "checking" |
| 1284 | .cindex "router" "result of running" |
| 1285 | As explained in the example above, a number of preconditions are checked before |
| 1286 | running a router. If any are not met, the router is skipped, and the address is |
| 1287 | passed to the next router. When all the preconditions on a router &'are'& met, |
| 1288 | the router is run. What happens next depends on the outcome, which is one of |
| 1289 | the following: |
| 1290 | |
| 1291 | .ilist |
| 1292 | &'accept'&: The router accepts the address, and either assigns it to a |
| 1293 | transport, or generates one or more &"child"& addresses. Processing the |
| 1294 | original address ceases, |
| 1295 | .oindex "&%unseen%&" |
| 1296 | unless the &%unseen%& option is set on the router. This option |
| 1297 | can be used to set up multiple deliveries with different routing (for example, |
| 1298 | for keeping archive copies of messages). When &%unseen%& is set, the address is |
| 1299 | passed to the next router. Normally, however, an &'accept'& return marks the |
| 1300 | end of routing. |
| 1301 | |
| 1302 | Any child addresses generated by the router are processed independently, |
| 1303 | starting with the first router by default. It is possible to change this by |
| 1304 | setting the &%redirect_router%& option to specify which router to start at for |
| 1305 | child addresses. Unlike &%pass_router%& (see below) the router specified by |
| 1306 | &%redirect_router%& may be anywhere in the router configuration. |
| 1307 | .next |
| 1308 | &'pass'&: The router recognizes the address, but cannot handle it itself. It |
| 1309 | requests that the address be passed to another router. By default the address |
| 1310 | is passed to the next router, but this can be changed by setting the |
| 1311 | &%pass_router%& option. However, (unlike &%redirect_router%&) the named router |
| 1312 | must be below the current router (to avoid loops). |
| 1313 | .next |
| 1314 | &'decline'&: The router declines to accept the address because it does not |
| 1315 | recognize it at all. By default, the address is passed to the next router, but |
| 1316 | this can be prevented by setting the &%no_more%& option. When &%no_more%& is |
| 1317 | set, all the remaining routers are skipped. In effect, &%no_more%& converts |
| 1318 | &'decline'& into &'fail'&. |
| 1319 | .next |
| 1320 | &'fail'&: The router determines that the address should fail, and queues it for |
| 1321 | the generation of a bounce message. There is no further processing of the |
| 1322 | original address unless &%unseen%& is set on the router. |
| 1323 | .next |
| 1324 | &'defer'&: The router cannot handle the address at the present time. (A |
| 1325 | database may be offline, or a DNS lookup may have timed out.) No further |
| 1326 | processing of the address happens in this delivery attempt. It is tried again |
| 1327 | next time the message is considered for delivery. |
| 1328 | .next |
| 1329 | &'error'&: There is some error in the router (for example, a syntax error in |
| 1330 | its configuration). The action is as for defer. |
| 1331 | .endlist |
| 1332 | |
| 1333 | If an address reaches the end of the routers without having been accepted by |
| 1334 | any of them, it is bounced as unrouteable. The default error message in this |
| 1335 | situation is &"unrouteable address"&, but you can set your own message by |
| 1336 | making use of the &%cannot_route_message%& option. This can be set for any |
| 1337 | router; the value from the last router that &"saw"& the address is used. |
| 1338 | |
| 1339 | Sometimes while routing you want to fail a delivery when some conditions are |
| 1340 | met but others are not, instead of passing the address on for further routing. |
| 1341 | You can do this by having a second router that explicitly fails the delivery |
| 1342 | when the relevant conditions are met. The &(redirect)& router has a &"fail"& |
| 1343 | facility for this purpose. |
| 1344 | |
| 1345 | |
| 1346 | .section "Duplicate addresses" "SECID17" |
| 1347 | .cindex "case of local parts" |
| 1348 | .cindex "address duplicate, discarding" |
| 1349 | .cindex "duplicate addresses" |
| 1350 | Once routing is complete, Exim scans the addresses that are assigned to local |
| 1351 | and remote transports, and discards any duplicates that it finds. During this |
| 1352 | check, local parts are treated as case-sensitive. This happens only when |
| 1353 | actually delivering a message; when testing routers with &%-bt%&, all the |
| 1354 | routed addresses are shown. |
| 1355 | |
| 1356 | |
| 1357 | |
| 1358 | .section "Router preconditions" "SECTrouprecon" |
| 1359 | .cindex "router" "preconditions, order of processing" |
| 1360 | .cindex "preconditions" "order of processing" |
| 1361 | The preconditions that are tested for each router are listed below, in the |
| 1362 | order in which they are tested. The individual configuration options are |
| 1363 | described in more detail in chapter &<<CHAProutergeneric>>&. |
| 1364 | |
| 1365 | .ilist |
| 1366 | The &%local_part_prefix%& and &%local_part_suffix%& options can specify that |
| 1367 | the local parts handled by the router may or must have certain prefixes and/or |
| 1368 | suffixes. If a mandatory affix (prefix or suffix) is not present, the router is |
| 1369 | skipped. These conditions are tested first. When an affix is present, it is |
| 1370 | removed from the local part before further processing, including the evaluation |
| 1371 | of any other conditions. |
| 1372 | .next |
| 1373 | Routers can be designated for use only when not verifying an address, that is, |
| 1374 | only when routing it for delivery (or testing its delivery routing). If the |
| 1375 | &%verify%& option is set false, the router is skipped when Exim is verifying an |
| 1376 | address. |
| 1377 | Setting the &%verify%& option actually sets two options, &%verify_sender%& and |
| 1378 | &%verify_recipient%&, which independently control the use of the router for |
| 1379 | sender and recipient verification. You can set these options directly if |
| 1380 | you want a router to be used for only one type of verification. |
| 1381 | Note that cutthrough delivery is classed as a recipient verification for this purpose. |
| 1382 | .next |
| 1383 | If the &%address_test%& option is set false, the router is skipped when Exim is |
| 1384 | run with the &%-bt%& option to test an address routing. This can be helpful |
| 1385 | when the first router sends all new messages to a scanner of some sort; it |
| 1386 | makes it possible to use &%-bt%& to test subsequent delivery routing without |
| 1387 | having to simulate the effect of the scanner. |
| 1388 | .next |
| 1389 | Routers can be designated for use only when verifying an address, as |
| 1390 | opposed to routing it for delivery. The &%verify_only%& option controls this. |
| 1391 | Again, cutthrough delivery counts as a verification. |
| 1392 | .next |
| 1393 | Individual routers can be explicitly skipped when running the routers to |
| 1394 | check an address given in the SMTP EXPN command (see the &%expn%& option). |
| 1395 | .next |
| 1396 | If the &%domains%& option is set, the domain of the address must be in the set |
| 1397 | of domains that it defines. |
| 1398 | .next |
| 1399 | .vindex "&$local_part_prefix$&" |
| 1400 | .vindex "&$local_part$&" |
| 1401 | .vindex "&$local_part_suffix$&" |
| 1402 | If the &%local_parts%& option is set, the local part of the address must be in |
| 1403 | the set of local parts that it defines. If &%local_part_prefix%& or |
| 1404 | &%local_part_suffix%& is in use, the prefix or suffix is removed from the local |
| 1405 | part before this check. If you want to do precondition tests on local parts |
| 1406 | that include affixes, you can do so by using a &%condition%& option (see below) |
| 1407 | that uses the variables &$local_part$&, &$local_part_prefix$&, and |
| 1408 | &$local_part_suffix$& as necessary. |
| 1409 | .next |
| 1410 | .vindex "&$local_user_uid$&" |
| 1411 | .vindex "&$local_user_gid$&" |
| 1412 | .vindex "&$home$&" |
| 1413 | If the &%check_local_user%& option is set, the local part must be the name of |
| 1414 | an account on the local host. If this check succeeds, the uid and gid of the |
| 1415 | local user are placed in &$local_user_uid$& and &$local_user_gid$& and the |
| 1416 | user's home directory is placed in &$home$&; these values can be used in the |
| 1417 | remaining preconditions. |
| 1418 | .next |
| 1419 | If the &%router_home_directory%& option is set, it is expanded at this point, |
| 1420 | because it overrides the value of &$home$&. If this expansion were left till |
| 1421 | later, the value of &$home$& as set by &%check_local_user%& would be used in |
| 1422 | subsequent tests. Having two different values of &$home$& in the same router |
| 1423 | could lead to confusion. |
| 1424 | .next |
| 1425 | If the &%senders%& option is set, the envelope sender address must be in the |
| 1426 | set of addresses that it defines. |
| 1427 | .next |
| 1428 | If the &%require_files%& option is set, the existence or non-existence of |
| 1429 | specified files is tested. |
| 1430 | .next |
| 1431 | .cindex "customizing" "precondition" |
| 1432 | If the &%condition%& option is set, it is evaluated and tested. This option |
| 1433 | uses an expanded string to allow you to set up your own custom preconditions. |
| 1434 | Expanded strings are described in chapter &<<CHAPexpand>>&. |
| 1435 | .endlist |
| 1436 | |
| 1437 | |
| 1438 | Note that &%require_files%& comes near the end of the list, so you cannot use |
| 1439 | it to check for the existence of a file in which to lookup up a domain, local |
| 1440 | part, or sender. However, as these options are all expanded, you can use the |
| 1441 | &%exists%& expansion condition to make such tests within each condition. The |
| 1442 | &%require_files%& option is intended for checking files that the router may be |
| 1443 | going to use internally, or which are needed by a specific transport (for |
| 1444 | example, &_.procmailrc_&). |
| 1445 | |
| 1446 | |
| 1447 | |
| 1448 | .section "Delivery in detail" "SECID18" |
| 1449 | .cindex "delivery" "in detail" |
| 1450 | When a message is to be delivered, the sequence of events is as follows: |
| 1451 | |
| 1452 | .ilist |
| 1453 | If a system-wide filter file is specified, the message is passed to it. The |
| 1454 | filter may add recipients to the message, replace the recipients, discard the |
| 1455 | message, cause a new message to be generated, or cause the message delivery to |
| 1456 | fail. The format of the system filter file is the same as for Exim user filter |
| 1457 | files, described in the separate document entitled &'Exim's interfaces to mail |
| 1458 | filtering'&. |
| 1459 | .cindex "Sieve filter" "not available for system filter" |
| 1460 | (&*Note*&: Sieve cannot be used for system filter files.) |
| 1461 | |
| 1462 | Some additional features are available in system filters &-- see chapter |
| 1463 | &<<CHAPsystemfilter>>& for details. Note that a message is passed to the system |
| 1464 | filter only once per delivery attempt, however many recipients it has. However, |
| 1465 | if there are several delivery attempts because one or more addresses could not |
| 1466 | be immediately delivered, the system filter is run each time. The filter |
| 1467 | condition &%first_delivery%& can be used to detect the first run of the system |
| 1468 | filter. |
| 1469 | .next |
| 1470 | Each recipient address is offered to each configured router in turn, subject to |
| 1471 | its preconditions, until one is able to handle it. If no router can handle the |
| 1472 | address, that is, if they all decline, the address is failed. Because routers |
| 1473 | can be targeted at particular domains, several locally handled domains can be |
| 1474 | processed entirely independently of each other. |
| 1475 | .next |
| 1476 | .cindex "routing" "loops in" |
| 1477 | .cindex "loop" "while routing" |
| 1478 | A router that accepts an address may assign it to a local or a remote |
| 1479 | transport. However, the transport is not run at this time. Instead, the address |
| 1480 | is placed on a list for the particular transport, which will be run later. |
| 1481 | Alternatively, the router may generate one or more new addresses (typically |
| 1482 | from alias, forward, or filter files). New addresses are fed back into this |
| 1483 | process from the top, but in order to avoid loops, a router ignores any address |
| 1484 | which has an identically-named ancestor that was processed by itself. |
| 1485 | .next |
| 1486 | When all the routing has been done, addresses that have been successfully |
| 1487 | handled are passed to their assigned transports. When local transports are |
| 1488 | doing real local deliveries, they handle only one address at a time, but if a |
| 1489 | local transport is being used as a pseudo-remote transport (for example, to |
| 1490 | collect batched SMTP messages for transmission by some other means) multiple |
| 1491 | addresses can be handled. Remote transports can always handle more than one |
| 1492 | address at a time, but can be configured not to do so, or to restrict multiple |
| 1493 | addresses to the same domain. |
| 1494 | .next |
| 1495 | Each local delivery to a file or a pipe runs in a separate process under a |
| 1496 | non-privileged uid, and these deliveries are run one at a time. Remote |
| 1497 | deliveries also run in separate processes, normally under a uid that is private |
| 1498 | to Exim (&"the Exim user"&), but in this case, several remote deliveries can be |
| 1499 | run in parallel. The maximum number of simultaneous remote deliveries for any |
| 1500 | one message is set by the &%remote_max_parallel%& option. |
| 1501 | The order in which deliveries are done is not defined, except that all local |
| 1502 | deliveries happen before any remote deliveries. |
| 1503 | .next |
| 1504 | .cindex "queue runner" |
| 1505 | When it encounters a local delivery during a queue run, Exim checks its retry |
| 1506 | database to see if there has been a previous temporary delivery failure for the |
| 1507 | address before running the local transport. If there was a previous failure, |
| 1508 | Exim does not attempt a new delivery until the retry time for the address is |
| 1509 | reached. However, this happens only for delivery attempts that are part of a |
| 1510 | queue run. Local deliveries are always attempted when delivery immediately |
| 1511 | follows message reception, even if retry times are set for them. This makes for |
| 1512 | better behaviour if one particular message is causing problems (for example, |
| 1513 | causing quota overflow, or provoking an error in a filter file). |
| 1514 | .next |
| 1515 | .cindex "delivery" "retry in remote transports" |
| 1516 | Remote transports do their own retry handling, since an address may be |
| 1517 | deliverable to one of a number of hosts, each of which may have a different |
| 1518 | retry time. If there have been previous temporary failures and no host has |
| 1519 | reached its retry time, no delivery is attempted, whether in a queue run or |
| 1520 | not. See chapter &<<CHAPretry>>& for details of retry strategies. |
| 1521 | .next |
| 1522 | If there were any permanent errors, a bounce message is returned to an |
| 1523 | appropriate address (the sender in the common case), with details of the error |
| 1524 | for each failing address. Exim can be configured to send copies of bounce |
| 1525 | messages to other addresses. |
| 1526 | .next |
| 1527 | .cindex "delivery" "deferral" |
| 1528 | If one or more addresses suffered a temporary failure, the message is left on |
| 1529 | the queue, to be tried again later. Delivery of these addresses is said to be |
| 1530 | &'deferred'&. |
| 1531 | .next |
| 1532 | When all the recipient addresses have either been delivered or bounced, |
| 1533 | handling of the message is complete. The spool files and message log are |
| 1534 | deleted, though the message log can optionally be preserved if required. |
| 1535 | .endlist |
| 1536 | |
| 1537 | |
| 1538 | |
| 1539 | |
| 1540 | .section "Retry mechanism" "SECID19" |
| 1541 | .cindex "delivery" "retry mechanism" |
| 1542 | .cindex "retry" "description of mechanism" |
| 1543 | .cindex "queue runner" |
| 1544 | Exim's mechanism for retrying messages that fail to get delivered at the first |
| 1545 | attempt is the queue runner process. You must either run an Exim daemon that |
| 1546 | uses the &%-q%& option with a time interval to start queue runners at regular |
| 1547 | intervals, or use some other means (such as &'cron'&) to start them. If you do |
| 1548 | not arrange for queue runners to be run, messages that fail temporarily at the |
| 1549 | first attempt will remain on your queue for ever. A queue runner process works |
| 1550 | its way through the queue, one message at a time, trying each delivery that has |
| 1551 | passed its retry time. |
| 1552 | You can run several queue runners at once. |
| 1553 | |
| 1554 | Exim uses a set of configured rules to determine when next to retry the failing |
| 1555 | address (see chapter &<<CHAPretry>>&). These rules also specify when Exim |
| 1556 | should give up trying to deliver to the address, at which point it generates a |
| 1557 | bounce message. If no retry rules are set for a particular host, address, and |
| 1558 | error combination, no retries are attempted, and temporary errors are treated |
| 1559 | as permanent. |
| 1560 | |
| 1561 | |
| 1562 | |
| 1563 | .section "Temporary delivery failure" "SECID20" |
| 1564 | .cindex "delivery" "temporary failure" |
| 1565 | There are many reasons why a message may not be immediately deliverable to a |
| 1566 | particular address. Failure to connect to a remote machine (because it, or the |
| 1567 | connection to it, is down) is one of the most common. Temporary failures may be |
| 1568 | detected during routing as well as during the transport stage of delivery. |
| 1569 | Local deliveries may be delayed if NFS files are unavailable, or if a mailbox |
| 1570 | is on a file system where the user is over quota. Exim can be configured to |
| 1571 | impose its own quotas on local mailboxes; where system quotas are set they will |
| 1572 | also apply. |
| 1573 | |
| 1574 | If a host is unreachable for a period of time, a number of messages may be |
| 1575 | waiting for it by the time it recovers, and sending them in a single SMTP |
| 1576 | connection is clearly beneficial. Whenever a delivery to a remote host is |
| 1577 | deferred, |
| 1578 | .cindex "hints database" |
| 1579 | Exim makes a note in its hints database, and whenever a successful |
| 1580 | SMTP delivery has happened, it looks to see if any other messages are waiting |
| 1581 | for the same host. If any are found, they are sent over the same SMTP |
| 1582 | connection, subject to a configuration limit as to the maximum number in any |
| 1583 | one connection. |
| 1584 | |
| 1585 | |
| 1586 | |
| 1587 | .section "Permanent delivery failure" "SECID21" |
| 1588 | .cindex "delivery" "permanent failure" |
| 1589 | .cindex "bounce message" "when generated" |
| 1590 | When a message cannot be delivered to some or all of its intended recipients, a |
| 1591 | bounce message is generated. Temporary delivery failures turn into permanent |
| 1592 | errors when their timeout expires. All the addresses that fail in a given |
| 1593 | delivery attempt are listed in a single message. If the original message has |
| 1594 | many recipients, it is possible for some addresses to fail in one delivery |
| 1595 | attempt and others to fail subsequently, giving rise to more than one bounce |
| 1596 | message. The wording of bounce messages can be customized by the administrator. |
| 1597 | See chapter &<<CHAPemsgcust>>& for details. |
| 1598 | |
| 1599 | .cindex "&'X-Failed-Recipients:'& header line" |
| 1600 | Bounce messages contain an &'X-Failed-Recipients:'& header line that lists the |
| 1601 | failed addresses, for the benefit of programs that try to analyse such messages |
| 1602 | automatically. |
| 1603 | |
| 1604 | .cindex "bounce message" "recipient of" |
| 1605 | A bounce message is normally sent to the sender of the original message, as |
| 1606 | obtained from the message's envelope. For incoming SMTP messages, this is the |
| 1607 | address given in the MAIL command. However, when an address is expanded via a |
| 1608 | forward or alias file, an alternative address can be specified for delivery |
| 1609 | failures of the generated addresses. For a mailing list expansion (see section |
| 1610 | &<<SECTmailinglists>>&) it is common to direct bounce messages to the manager |
| 1611 | of the list. |
| 1612 | |
| 1613 | |
| 1614 | |
| 1615 | .section "Failures to deliver bounce messages" "SECID22" |
| 1616 | .cindex "bounce message" "failure to deliver" |
| 1617 | If a bounce message (either locally generated or received from a remote host) |
| 1618 | itself suffers a permanent delivery failure, the message is left on the queue, |
| 1619 | but it is frozen, awaiting the attention of an administrator. There are options |
| 1620 | that can be used to make Exim discard such failed messages, or to keep them |
| 1621 | for only a short time (see &%timeout_frozen_after%& and |
| 1622 | &%ignore_bounce_errors_after%&). |
| 1623 | |
| 1624 | |
| 1625 | |
| 1626 | |
| 1627 | |
| 1628 | . //////////////////////////////////////////////////////////////////////////// |
| 1629 | . //////////////////////////////////////////////////////////////////////////// |
| 1630 | |
| 1631 | .chapter "Building and installing Exim" "CHID3" |
| 1632 | .scindex IIDbuex "building Exim" |
| 1633 | |
| 1634 | .section "Unpacking" "SECID23" |
| 1635 | Exim is distributed as a gzipped or bzipped tar file which, when unpacked, |
| 1636 | creates a directory with the name of the current release (for example, |
| 1637 | &_exim-&version()_&) into which the following files are placed: |
| 1638 | |
| 1639 | .table2 140pt |
| 1640 | .irow &_ACKNOWLEDGMENTS_& "contains some acknowledgments" |
| 1641 | .irow &_CHANGES_& "contains a reference to where changes are &&& |
| 1642 | documented" |
| 1643 | .irow &_LICENCE_& "the GNU General Public Licence" |
| 1644 | .irow &_Makefile_& "top-level make file" |
| 1645 | .irow &_NOTICE_& "conditions for the use of Exim" |
| 1646 | .irow &_README_& "list of files, directories and simple build &&& |
| 1647 | instructions" |
| 1648 | .endtable |
| 1649 | |
| 1650 | Other files whose names begin with &_README_& may also be present. The |
| 1651 | following subdirectories are created: |
| 1652 | |
| 1653 | .table2 140pt |
| 1654 | .irow &_Local_& "an empty directory for local configuration files" |
| 1655 | .irow &_OS_& "OS-specific files" |
| 1656 | .irow &_doc_& "documentation files" |
| 1657 | .irow &_exim_monitor_& "source files for the Exim monitor" |
| 1658 | .irow &_scripts_& "scripts used in the build process" |
| 1659 | .irow &_src_& "remaining source files" |
| 1660 | .irow &_util_& "independent utilities" |
| 1661 | .endtable |
| 1662 | |
| 1663 | The main utility programs are contained in the &_src_& directory, and are built |
| 1664 | with the Exim binary. The &_util_& directory contains a few optional scripts |
| 1665 | that may be useful to some sites. |
| 1666 | |
| 1667 | |
| 1668 | .section "Multiple machine architectures and operating systems" "SECID24" |
| 1669 | .cindex "building Exim" "multiple OS/architectures" |
| 1670 | The building process for Exim is arranged to make it easy to build binaries for |
| 1671 | a number of different architectures and operating systems from the same set of |
| 1672 | source files. Compilation does not take place in the &_src_& directory. |
| 1673 | Instead, a &'build directory'& is created for each architecture and operating |
| 1674 | system. |
| 1675 | .cindex "symbolic link" "to build directory" |
| 1676 | Symbolic links to the sources are installed in this directory, which is where |
| 1677 | the actual building takes place. In most cases, Exim can discover the machine |
| 1678 | architecture and operating system for itself, but the defaults can be |
| 1679 | overridden if necessary. |
| 1680 | |
| 1681 | |
| 1682 | .section "PCRE library" "SECTpcre" |
| 1683 | .cindex "PCRE library" |
| 1684 | Exim no longer has an embedded PCRE library as the vast majority of |
| 1685 | modern systems include PCRE as a system library, although you may need |
| 1686 | to install the PCRE or PCRE development package for your operating |
| 1687 | system. If your system has a normal PCRE installation the Exim build |
| 1688 | process will need no further configuration. If the library or the |
| 1689 | headers are in an unusual location you will need to either set the PCRE_LIBS |
| 1690 | and INCLUDE directives appropriately, |
| 1691 | or set PCRE_CONFIG=yes to use the installed &(pcre-config)& command. |
| 1692 | If your operating system has no |
| 1693 | PCRE support then you will need to obtain and build the current PCRE |
| 1694 | from &url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/). |
| 1695 | More information on PCRE is available at &url(http://www.pcre.org/). |
| 1696 | |
| 1697 | .section "DBM libraries" "SECTdb" |
| 1698 | .cindex "DBM libraries" "discussion of" |
| 1699 | .cindex "hints database" "DBM files used for" |
| 1700 | Even if you do not use any DBM files in your configuration, Exim still needs a |
| 1701 | DBM library in order to operate, because it uses indexed files for its hints |
| 1702 | databases. Unfortunately, there are a number of DBM libraries in existence, and |
| 1703 | different operating systems often have different ones installed. |
| 1704 | |
| 1705 | .cindex "Solaris" "DBM library for" |
| 1706 | .cindex "IRIX, DBM library for" |
| 1707 | .cindex "BSD, DBM library for" |
| 1708 | .cindex "Linux, DBM library for" |
| 1709 | If you are using Solaris, IRIX, one of the modern BSD systems, or a modern |
| 1710 | Linux distribution, the DBM configuration should happen automatically, and you |
| 1711 | may be able to ignore this section. Otherwise, you may have to learn more than |
| 1712 | you would like about DBM libraries from what follows. |
| 1713 | |
| 1714 | .cindex "&'ndbm'& DBM library" |
| 1715 | Licensed versions of Unix normally contain a library of DBM functions operating |
| 1716 | via the &'ndbm'& interface, and this is what Exim expects by default. Free |
| 1717 | versions of Unix seem to vary in what they contain as standard. In particular, |
| 1718 | some early versions of Linux have no default DBM library, and different |
| 1719 | distributors have chosen to bundle different libraries with their packaged |
| 1720 | versions. However, the more recent releases seem to have standardized on the |
| 1721 | Berkeley DB library. |
| 1722 | |
| 1723 | Different DBM libraries have different conventions for naming the files they |
| 1724 | use. When a program opens a file called &_dbmfile_&, there are several |
| 1725 | possibilities: |
| 1726 | |
| 1727 | .olist |
| 1728 | A traditional &'ndbm'& implementation, such as that supplied as part of |
| 1729 | Solaris, operates on two files called &_dbmfile.dir_& and &_dbmfile.pag_&. |
| 1730 | .next |
| 1731 | .cindex "&'gdbm'& DBM library" |
| 1732 | The GNU library, &'gdbm'&, operates on a single file. If used via its &'ndbm'& |
| 1733 | compatibility interface it makes two different hard links to it with names |
| 1734 | &_dbmfile.dir_& and &_dbmfile.pag_&, but if used via its native interface, the |
| 1735 | file name is used unmodified. |
| 1736 | .next |
| 1737 | .cindex "Berkeley DB library" |
| 1738 | The Berkeley DB package, if called via its &'ndbm'& compatibility interface, |
| 1739 | operates on a single file called &_dbmfile.db_&, but otherwise looks to the |
| 1740 | programmer exactly the same as the traditional &'ndbm'& implementation. |
| 1741 | .next |
| 1742 | If the Berkeley package is used in its native mode, it operates on a single |
| 1743 | file called &_dbmfile_&; the programmer's interface is somewhat different to |
| 1744 | the traditional &'ndbm'& interface. |
| 1745 | .next |
| 1746 | To complicate things further, there are several very different versions of the |
| 1747 | Berkeley DB package. Version 1.85 was stable for a very long time, releases |
| 1748 | 2.&'x'& and 3.&'x'& were current for a while, but the latest versions are now |
| 1749 | numbered 4.&'x'&. Maintenance of some of the earlier releases has ceased. All |
| 1750 | versions of Berkeley DB can be obtained from |
| 1751 | &url(http://www.sleepycat.com/). |
| 1752 | .next |
| 1753 | .cindex "&'tdb'& DBM library" |
| 1754 | Yet another DBM library, called &'tdb'&, is available from |
| 1755 | &url(http://download.sourceforge.net/tdb). It has its own interface, and also |
| 1756 | operates on a single file. |
| 1757 | .endlist |
| 1758 | |
| 1759 | .cindex "USE_DB" |
| 1760 | .cindex "DBM libraries" "configuration for building" |
| 1761 | Exim and its utilities can be compiled to use any of these interfaces. In order |
| 1762 | to use any version of the Berkeley DB package in native mode, you must set |
| 1763 | USE_DB in an appropriate configuration file (typically |
| 1764 | &_Local/Makefile_&). For example: |
| 1765 | .code |
| 1766 | USE_DB=yes |
| 1767 | .endd |
| 1768 | Similarly, for gdbm you set USE_GDBM, and for tdb you set USE_TDB. An |
| 1769 | error is diagnosed if you set more than one of these. |
| 1770 | |
| 1771 | At the lowest level, the build-time configuration sets none of these options, |
| 1772 | thereby assuming an interface of type (1). However, some operating system |
| 1773 | configuration files (for example, those for the BSD operating systems and |
| 1774 | Linux) assume type (4) by setting USE_DB as their default, and the |
| 1775 | configuration files for Cygwin set USE_GDBM. Anything you set in |
| 1776 | &_Local/Makefile_&, however, overrides these system defaults. |
| 1777 | |
| 1778 | As well as setting USE_DB, USE_GDBM, or USE_TDB, it may also be |
| 1779 | necessary to set DBMLIB, to cause inclusion of the appropriate library, as |
| 1780 | in one of these lines: |
| 1781 | .code |
| 1782 | DBMLIB = -ldb |
| 1783 | DBMLIB = -ltdb |
| 1784 | .endd |
| 1785 | Settings like that will work if the DBM library is installed in the standard |
| 1786 | place. Sometimes it is not, and the library's header file may also not be in |
| 1787 | the default path. You may need to set INCLUDE to specify where the header |
| 1788 | file is, and to specify the path to the library more fully in DBMLIB, as in |
| 1789 | this example: |
| 1790 | .code |
| 1791 | INCLUDE=-I/usr/local/include/db-4.1 |
| 1792 | DBMLIB=/usr/local/lib/db-4.1/libdb.a |
| 1793 | .endd |
| 1794 | There is further detailed discussion about the various DBM libraries in the |
| 1795 | file &_doc/dbm.discuss.txt_& in the Exim distribution. |
| 1796 | |
| 1797 | |
| 1798 | |
| 1799 | .section "Pre-building configuration" "SECID25" |
| 1800 | .cindex "building Exim" "pre-building configuration" |
| 1801 | .cindex "configuration for building Exim" |
| 1802 | .cindex "&_Local/Makefile_&" |
| 1803 | .cindex "&_src/EDITME_&" |
| 1804 | Before building Exim, a local configuration file that specifies options |
| 1805 | independent of any operating system has to be created with the name |
| 1806 | &_Local/Makefile_&. A template for this file is supplied as the file |
| 1807 | &_src/EDITME_&, and it contains full descriptions of all the option settings |
| 1808 | therein. These descriptions are therefore not repeated here. If you are |
| 1809 | building Exim for the first time, the simplest thing to do is to copy |
| 1810 | &_src/EDITME_& to &_Local/Makefile_&, then read it and edit it appropriately. |
| 1811 | |
| 1812 | There are three settings that you must supply, because Exim will not build |
| 1813 | without them. They are the location of the run time configuration file |
| 1814 | (CONFIGURE_FILE), the directory in which Exim binaries will be installed |
| 1815 | (BIN_DIRECTORY), and the identity of the Exim user (EXIM_USER and |
| 1816 | maybe EXIM_GROUP as well). The value of CONFIGURE_FILE can in fact be |
| 1817 | a colon-separated list of file names; Exim uses the first of them that exists. |
| 1818 | |
| 1819 | There are a few other parameters that can be specified either at build time or |
| 1820 | at run time, to enable the same binary to be used on a number of different |
| 1821 | machines. However, if the locations of Exim's spool directory and log file |
| 1822 | directory (if not within the spool directory) are fixed, it is recommended that |
| 1823 | you specify them in &_Local/Makefile_& instead of at run time, so that errors |
| 1824 | detected early in Exim's execution (such as a malformed configuration file) can |
| 1825 | be logged. |
| 1826 | |
| 1827 | .cindex "content scanning" "specifying at build time" |
| 1828 | Exim's interfaces for calling virus and spam scanning software directly from |
| 1829 | access control lists are not compiled by default. If you want to include these |
| 1830 | facilities, you need to set |
| 1831 | .code |
| 1832 | WITH_CONTENT_SCAN=yes |
| 1833 | .endd |
| 1834 | in your &_Local/Makefile_&. For details of the facilities themselves, see |
| 1835 | chapter &<<CHAPexiscan>>&. |
| 1836 | |
| 1837 | |
| 1838 | .cindex "&_Local/eximon.conf_&" |
| 1839 | .cindex "&_exim_monitor/EDITME_&" |
| 1840 | If you are going to build the Exim monitor, a similar configuration process is |
| 1841 | required. The file &_exim_monitor/EDITME_& must be edited appropriately for |
| 1842 | your installation and saved under the name &_Local/eximon.conf_&. If you are |
| 1843 | happy with the default settings described in &_exim_monitor/EDITME_&, |
| 1844 | &_Local/eximon.conf_& can be empty, but it must exist. |
| 1845 | |
| 1846 | This is all the configuration that is needed in straightforward cases for known |
| 1847 | operating systems. However, the building process is set up so that it is easy |
| 1848 | to override options that are set by default or by operating-system-specific |
| 1849 | configuration files, for example to change the name of the C compiler, which |
| 1850 | defaults to &%gcc%&. See section &<<SECToverride>>& below for details of how to |
| 1851 | do this. |
| 1852 | |
| 1853 | |
| 1854 | |
| 1855 | .section "Support for iconv()" "SECID26" |
| 1856 | .cindex "&[iconv()]& support" |
| 1857 | .cindex "RFC 2047" |
| 1858 | The contents of header lines in messages may be encoded according to the rules |
| 1859 | described RFC 2047. This makes it possible to transmit characters that are not |
| 1860 | in the ASCII character set, and to label them as being in a particular |
| 1861 | character set. When Exim is inspecting header lines by means of the &%$h_%& |
| 1862 | mechanism, it decodes them, and translates them into a specified character set |
| 1863 | (default ISO-8859-1). The translation is possible only if the operating system |
| 1864 | supports the &[iconv()]& function. |
| 1865 | |
| 1866 | However, some of the operating systems that supply &[iconv()]& do not support |
| 1867 | very many conversions. The GNU &%libiconv%& library (available from |
| 1868 | &url(http://www.gnu.org/software/libiconv/)) can be installed on such |
| 1869 | systems to remedy this deficiency, as well as on systems that do not supply |
| 1870 | &[iconv()]& at all. After installing &%libiconv%&, you should add |
| 1871 | .code |
| 1872 | HAVE_ICONV=yes |
| 1873 | .endd |
| 1874 | to your &_Local/Makefile_& and rebuild Exim. |
| 1875 | |
| 1876 | |
| 1877 | |
| 1878 | .section "Including TLS/SSL encryption support" "SECTinctlsssl" |
| 1879 | .cindex "TLS" "including support for TLS" |
| 1880 | .cindex "encryption" "including support for" |
| 1881 | .cindex "SUPPORT_TLS" |
| 1882 | .cindex "OpenSSL" "building Exim with" |
| 1883 | .cindex "GnuTLS" "building Exim with" |
| 1884 | Exim can be built to support encrypted SMTP connections, using the STARTTLS |
| 1885 | command as per RFC 2487. It can also support legacy clients that expect to |
| 1886 | start a TLS session immediately on connection to a non-standard port (see the |
| 1887 | &%tls_on_connect_ports%& runtime option and the &%-tls-on-connect%& command |
| 1888 | line option). |
| 1889 | |
| 1890 | If you want to build Exim with TLS support, you must first install either the |
| 1891 | OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for |
| 1892 | implementing SSL. |
| 1893 | |
| 1894 | If OpenSSL is installed, you should set |
| 1895 | .code |
| 1896 | SUPPORT_TLS=yes |
| 1897 | TLS_LIBS=-lssl -lcrypto |
| 1898 | .endd |
| 1899 | in &_Local/Makefile_&. You may also need to specify the locations of the |
| 1900 | OpenSSL library and include files. For example: |
| 1901 | .code |
| 1902 | SUPPORT_TLS=yes |
| 1903 | TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto |
| 1904 | TLS_INCLUDE=-I/usr/local/openssl/include/ |
| 1905 | .endd |
| 1906 | .cindex "pkg-config" "OpenSSL" |
| 1907 | If you have &'pkg-config'& available, then instead you can just use: |
| 1908 | .code |
| 1909 | SUPPORT_TLS=yes |
| 1910 | USE_OPENSSL_PC=openssl |
| 1911 | .endd |
| 1912 | .cindex "USE_GNUTLS" |
| 1913 | If GnuTLS is installed, you should set |
| 1914 | .code |
| 1915 | SUPPORT_TLS=yes |
| 1916 | USE_GNUTLS=yes |
| 1917 | TLS_LIBS=-lgnutls -ltasn1 -lgcrypt |
| 1918 | .endd |
| 1919 | in &_Local/Makefile_&, and again you may need to specify the locations of the |
| 1920 | library and include files. For example: |
| 1921 | .code |
| 1922 | SUPPORT_TLS=yes |
| 1923 | USE_GNUTLS=yes |
| 1924 | TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt |
| 1925 | TLS_INCLUDE=-I/usr/gnu/include |
| 1926 | .endd |
| 1927 | .cindex "pkg-config" "GnuTLS" |
| 1928 | If you have &'pkg-config'& available, then instead you can just use: |
| 1929 | .code |
| 1930 | SUPPORT_TLS=yes |
| 1931 | USE_GNUTLS=yes |
| 1932 | USE_GNUTLS_PC=gnutls |
| 1933 | .endd |
| 1934 | |
| 1935 | You do not need to set TLS_INCLUDE if the relevant directory is already |
| 1936 | specified in INCLUDE. Details of how to configure Exim to make use of TLS are |
| 1937 | given in chapter &<<CHAPTLS>>&. |
| 1938 | |
| 1939 | |
| 1940 | |
| 1941 | |
| 1942 | .section "Use of tcpwrappers" "SECID27" |
| 1943 | |
| 1944 | .cindex "tcpwrappers, building Exim to support" |
| 1945 | .cindex "USE_TCP_WRAPPERS" |
| 1946 | .cindex "TCP_WRAPPERS_DAEMON_NAME" |
| 1947 | .cindex "tcp_wrappers_daemon_name" |
| 1948 | Exim can be linked with the &'tcpwrappers'& library in order to check incoming |
| 1949 | SMTP calls using the &'tcpwrappers'& control files. This may be a convenient |
| 1950 | alternative to Exim's own checking facilities for installations that are |
| 1951 | already making use of &'tcpwrappers'& for other purposes. To do this, you |
| 1952 | should set USE_TCP_WRAPPERS in &_Local/Makefile_&, arrange for the file |
| 1953 | &_tcpd.h_& to be available at compile time, and also ensure that the library |
| 1954 | &_libwrap.a_& is available at link time, typically by including &%-lwrap%& in |
| 1955 | EXTRALIBS_EXIM. For example, if &'tcpwrappers'& is installed in &_/usr/local_&, |
| 1956 | you might have |
| 1957 | .code |
| 1958 | USE_TCP_WRAPPERS=yes |
| 1959 | CFLAGS=-O -I/usr/local/include |
| 1960 | EXTRALIBS_EXIM=-L/usr/local/lib -lwrap |
| 1961 | .endd |
| 1962 | in &_Local/Makefile_&. The daemon name to use in the &'tcpwrappers'& control |
| 1963 | files is &"exim"&. For example, the line |
| 1964 | .code |
| 1965 | exim : LOCAL 192.168.1. .friendly.domain.example |
| 1966 | .endd |
| 1967 | in your &_/etc/hosts.allow_& file allows connections from the local host, from |
| 1968 | the subnet 192.168.1.0/24, and from all hosts in &'friendly.domain.example'&. |
| 1969 | All other connections are denied. The daemon name used by &'tcpwrappers'& |
| 1970 | can be changed at build time by setting TCP_WRAPPERS_DAEMON_NAME in |
| 1971 | &_Local/Makefile_&, or by setting tcp_wrappers_daemon_name in the |
| 1972 | configure file. Consult the &'tcpwrappers'& documentation for |
| 1973 | further details. |
| 1974 | |
| 1975 | |
| 1976 | .section "Including support for IPv6" "SECID28" |
| 1977 | .cindex "IPv6" "including support for" |
| 1978 | Exim contains code for use on systems that have IPv6 support. Setting |
| 1979 | &`HAVE_IPV6=YES`& in &_Local/Makefile_& causes the IPv6 code to be included; |
| 1980 | it may also be necessary to set IPV6_INCLUDE and IPV6_LIBS on systems |
| 1981 | where the IPv6 support is not fully integrated into the normal include and |
| 1982 | library files. |
| 1983 | |
| 1984 | Two different types of DNS record for handling IPv6 addresses have been |
| 1985 | defined. AAAA records (analogous to A records for IPv4) are in use, and are |
| 1986 | currently seen as the mainstream. Another record type called A6 was proposed |
| 1987 | as better than AAAA because it had more flexibility. However, it was felt to be |
| 1988 | over-complex, and its status was reduced to &"experimental"&. It is not known |
| 1989 | if anyone is actually using A6 records. Exim has support for A6 records, but |
| 1990 | this is included only if you set &`SUPPORT_A6=YES`& in &_Local/Makefile_&. The |
| 1991 | support has not been tested for some time. |
| 1992 | |
| 1993 | |
| 1994 | |
| 1995 | .section "Dynamically loaded lookup module support" "SECTdynamicmodules" |
| 1996 | .cindex "lookup modules" |
| 1997 | .cindex "dynamic modules" |
| 1998 | .cindex ".so building" |
| 1999 | On some platforms, Exim supports not compiling all lookup types directly into |
| 2000 | the main binary, instead putting some into external modules which can be loaded |
| 2001 | on demand. |
| 2002 | This permits packagers to build Exim with support for lookups with extensive |
| 2003 | library dependencies without requiring all users to install all of those |
| 2004 | dependencies. |
| 2005 | Most, but not all, lookup types can be built this way. |
| 2006 | |
| 2007 | Set &`LOOKUP_MODULE_DIR`& to the directory into which the modules will be |
| 2008 | installed; Exim will only load modules from that directory, as a security |
| 2009 | measure. You will need to set &`CFLAGS_DYNAMIC`& if not already defined |
| 2010 | for your OS; see &_OS/Makefile-Linux_& for an example. |
| 2011 | Some other requirements for adjusting &`EXTRALIBS`& may also be necessary, |
| 2012 | see &_src/EDITME_& for details. |
| 2013 | |
| 2014 | Then, for each module to be loaded dynamically, define the relevant |
| 2015 | &`LOOKUP_`&<&'lookup_type'&> flags to have the value "2" instead of "yes". |
| 2016 | For example, this will build in lsearch but load sqlite and mysql support |
| 2017 | on demand: |
| 2018 | .code |
| 2019 | LOOKUP_LSEARCH=yes |
| 2020 | LOOKUP_SQLITE=2 |
| 2021 | LOOKUP_MYSQL=2 |
| 2022 | .endd |
| 2023 | |
| 2024 | |
| 2025 | .section "The building process" "SECID29" |
| 2026 | .cindex "build directory" |
| 2027 | Once &_Local/Makefile_& (and &_Local/eximon.conf_&, if required) have been |
| 2028 | created, run &'make'& at the top level. It determines the architecture and |
| 2029 | operating system types, and creates a build directory if one does not exist. |
| 2030 | For example, on a Sun system running Solaris 8, the directory |
| 2031 | &_build-SunOS5-5.8-sparc_& is created. |
| 2032 | .cindex "symbolic link" "to source files" |
| 2033 | Symbolic links to relevant source files are installed in the build directory. |
| 2034 | |
| 2035 | &*Warning*&: The &%-j%& (parallel) flag must not be used with &'make'&; the |
| 2036 | building process fails if it is set. |
| 2037 | |
| 2038 | If this is the first time &'make'& has been run, it calls a script that builds |
| 2039 | a make file inside the build directory, using the configuration files from the |
| 2040 | &_Local_& directory. The new make file is then passed to another instance of |
| 2041 | &'make'&. This does the real work, building a number of utility scripts, and |
| 2042 | then compiling and linking the binaries for the Exim monitor (if configured), a |
| 2043 | number of utility programs, and finally Exim itself. The command &`make |
| 2044 | makefile`& can be used to force a rebuild of the make file in the build |
| 2045 | directory, should this ever be necessary. |
| 2046 | |
| 2047 | If you have problems building Exim, check for any comments there may be in the |
| 2048 | &_README_& file concerning your operating system, and also take a look at the |
| 2049 | FAQ, where some common problems are covered. |
| 2050 | |
| 2051 | |
| 2052 | |
| 2053 | .section 'Output from &"make"&' "SECID283" |
| 2054 | The output produced by the &'make'& process for compile lines is often very |
| 2055 | unreadable, because these lines can be very long. For this reason, the normal |
| 2056 | output is suppressed by default, and instead output similar to that which |
| 2057 | appears when compiling the 2.6 Linux kernel is generated: just a short line for |
| 2058 | each module that is being compiled or linked. However, it is still possible to |
| 2059 | get the full output, by calling &'make'& like this: |
| 2060 | .code |
| 2061 | FULLECHO='' make -e |
| 2062 | .endd |
| 2063 | The value of FULLECHO defaults to &"@"&, the flag character that suppresses |
| 2064 | command reflection in &'make'&. When you ask for the full output, it is |
| 2065 | given in addition to the short output. |
| 2066 | |
| 2067 | |
| 2068 | |
| 2069 | .section "Overriding build-time options for Exim" "SECToverride" |
| 2070 | .cindex "build-time options, overriding" |
| 2071 | The main make file that is created at the beginning of the building process |
| 2072 | consists of the concatenation of a number of files which set configuration |
| 2073 | values, followed by a fixed set of &'make'& instructions. If a value is set |
| 2074 | more than once, the last setting overrides any previous ones. This provides a |
| 2075 | convenient way of overriding defaults. The files that are concatenated are, in |
| 2076 | order: |
| 2077 | .display |
| 2078 | &_OS/Makefile-Default_& |
| 2079 | &_OS/Makefile-_&<&'ostype'&> |
| 2080 | &_Local/Makefile_& |
| 2081 | &_Local/Makefile-_&<&'ostype'&> |
| 2082 | &_Local/Makefile-_&<&'archtype'&> |
| 2083 | &_Local/Makefile-_&<&'ostype'&>-<&'archtype'&> |
| 2084 | &_OS/Makefile-Base_& |
| 2085 | .endd |
| 2086 | .cindex "&_Local/Makefile_&" |
| 2087 | .cindex "building Exim" "operating system type" |
| 2088 | .cindex "building Exim" "architecture type" |
| 2089 | where <&'ostype'&> is the operating system type and <&'archtype'&> is the |
| 2090 | architecture type. &_Local/Makefile_& is required to exist, and the building |
| 2091 | process fails if it is absent. The other three &_Local_& files are optional, |
| 2092 | and are often not needed. |
| 2093 | |
| 2094 | The values used for <&'ostype'&> and <&'archtype'&> are obtained from scripts |
| 2095 | called &_scripts/os-type_& and &_scripts/arch-type_& respectively. If either of |
| 2096 | the environment variables EXIM_OSTYPE or EXIM_ARCHTYPE is set, their |
| 2097 | values are used, thereby providing a means of forcing particular settings. |
| 2098 | Otherwise, the scripts try to get values from the &%uname%& command. If this |
| 2099 | fails, the shell variables OSTYPE and ARCHTYPE are inspected. A number |
| 2100 | of &'ad hoc'& transformations are then applied, to produce the standard names |
| 2101 | that Exim expects. You can run these scripts directly from the shell in order |
| 2102 | to find out what values are being used on your system. |
| 2103 | |
| 2104 | |
| 2105 | &_OS/Makefile-Default_& contains comments about the variables that are set |
| 2106 | therein. Some (but not all) are mentioned below. If there is something that |
| 2107 | needs changing, review the contents of this file and the contents of the make |
| 2108 | file for your operating system (&_OS/Makefile-<ostype>_&) to see what the |
| 2109 | default values are. |
| 2110 | |
| 2111 | |
| 2112 | .cindex "building Exim" "overriding default settings" |
| 2113 | If you need to change any of the values that are set in &_OS/Makefile-Default_& |
| 2114 | or in &_OS/Makefile-<ostype>_&, or to add any new definitions, you do not |
| 2115 | need to change the original files. Instead, you should make the changes by |
| 2116 | putting the new values in an appropriate &_Local_& file. For example, |
| 2117 | .cindex "Tru64-Unix build-time settings" |
| 2118 | when building Exim in many releases of the Tru64-Unix (formerly Digital UNIX, |
| 2119 | formerly DEC-OSF1) operating system, it is necessary to specify that the C |
| 2120 | compiler is called &'cc'& rather than &'gcc'&. Also, the compiler must be |
| 2121 | called with the option &%-std1%&, to make it recognize some of the features of |
| 2122 | Standard C that Exim uses. (Most other compilers recognize Standard C by |
| 2123 | default.) To do this, you should create a file called &_Local/Makefile-OSF1_& |
| 2124 | containing the lines |
| 2125 | .code |
| 2126 | CC=cc |
| 2127 | CFLAGS=-std1 |
| 2128 | .endd |
| 2129 | If you are compiling for just one operating system, it may be easier to put |
| 2130 | these lines directly into &_Local/Makefile_&. |
| 2131 | |
| 2132 | Keeping all your local configuration settings separate from the distributed |
| 2133 | files makes it easy to transfer them to new versions of Exim simply by copying |
| 2134 | the contents of the &_Local_& directory. |
| 2135 | |
| 2136 | |
| 2137 | .cindex "NIS lookup type" "including support for" |
| 2138 | .cindex "NIS+ lookup type" "including support for" |
| 2139 | .cindex "LDAP" "including support for" |
| 2140 | .cindex "lookup" "inclusion in binary" |
| 2141 | Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file |
| 2142 | lookup, but not all systems have these components installed, so the default is |
| 2143 | not to include the relevant code in the binary. All the different kinds of file |
| 2144 | and database lookup that Exim supports are implemented as separate code modules |
| 2145 | which are included only if the relevant compile-time options are set. In the |
| 2146 | case of LDAP, NIS, and NIS+, the settings for &_Local/Makefile_& are: |
| 2147 | .code |
| 2148 | LOOKUP_LDAP=yes |
| 2149 | LOOKUP_NIS=yes |
| 2150 | LOOKUP_NISPLUS=yes |
| 2151 | .endd |
| 2152 | and similar settings apply to the other lookup types. They are all listed in |
| 2153 | &_src/EDITME_&. In many cases the relevant include files and interface |
| 2154 | libraries need to be installed before compiling Exim. |
| 2155 | .cindex "cdb" "including support for" |
| 2156 | However, there are some optional lookup types (such as cdb) for which |
| 2157 | the code is entirely contained within Exim, and no external include |
| 2158 | files or libraries are required. When a lookup type is not included in the |
| 2159 | binary, attempts to configure Exim to use it cause run time configuration |
| 2160 | errors. |
| 2161 | |
| 2162 | .cindex "pkg-config" "lookups" |
| 2163 | .cindex "pkg-config" "authenticators" |
| 2164 | Many systems now use a tool called &'pkg-config'& to encapsulate information |
| 2165 | about how to compile against a library; Exim has some initial support for |
| 2166 | being able to use pkg-config for lookups and authenticators. For any given |
| 2167 | makefile variable which starts &`LOOKUP_`& or &`AUTH_`&, you can add a new |
| 2168 | variable with the &`_PC`& suffix in the name and assign as the value the |
| 2169 | name of the package to be queried. The results of querying via the |
| 2170 | &'pkg-config'& command will be added to the appropriate Makefile variables |
| 2171 | with &`+=`& directives, so your version of &'make'& will need to support that |
| 2172 | syntax. For instance: |
| 2173 | .code |
| 2174 | LOOKUP_SQLITE=yes |
| 2175 | LOOKUP_SQLITE_PC=sqlite3 |
| 2176 | AUTH_GSASL=yes |
| 2177 | AUTH_GSASL_PC=libgsasl |
| 2178 | AUTH_HEIMDAL_GSSAPI=yes |
| 2179 | AUTH_HEIMDAL_GSSAPI_PC=heimdal-gssapi |
| 2180 | .endd |
| 2181 | |
| 2182 | .cindex "Perl" "including support for" |
| 2183 | Exim can be linked with an embedded Perl interpreter, allowing Perl |
| 2184 | subroutines to be called during string expansion. To enable this facility, |
| 2185 | .code |
| 2186 | EXIM_PERL=perl.o |
| 2187 | .endd |
| 2188 | must be defined in &_Local/Makefile_&. Details of this facility are given in |
| 2189 | chapter &<<CHAPperl>>&. |
| 2190 | |
| 2191 | .cindex "X11 libraries, location of" |
| 2192 | The location of the X11 libraries is something that varies a lot between |
| 2193 | operating systems, and there may be different versions of X11 to cope |
| 2194 | with. Exim itself makes no use of X11, but if you are compiling the Exim |
| 2195 | monitor, the X11 libraries must be available. |
| 2196 | The following three variables are set in &_OS/Makefile-Default_&: |
| 2197 | .code |
| 2198 | X11=/usr/X11R6 |
| 2199 | XINCLUDE=-I$(X11)/include |
| 2200 | XLFLAGS=-L$(X11)/lib |
| 2201 | .endd |
| 2202 | These are overridden in some of the operating-system configuration files. For |
| 2203 | example, in &_OS/Makefile-SunOS5_& there is |
| 2204 | .code |
| 2205 | X11=/usr/openwin |
| 2206 | XINCLUDE=-I$(X11)/include |
| 2207 | XLFLAGS=-L$(X11)/lib -R$(X11)/lib |
| 2208 | .endd |
| 2209 | If you need to override the default setting for your operating system, place a |
| 2210 | definition of all three of these variables into your |
| 2211 | &_Local/Makefile-<ostype>_& file. |
| 2212 | |
| 2213 | .cindex "EXTRALIBS" |
| 2214 | If you need to add any extra libraries to the link steps, these can be put in a |
| 2215 | variable called EXTRALIBS, which appears in all the link commands, but by |
| 2216 | default is not defined. In contrast, EXTRALIBS_EXIM is used only on the |
| 2217 | command for linking the main Exim binary, and not for any associated utilities. |
| 2218 | |
| 2219 | .cindex "DBM libraries" "configuration for building" |
| 2220 | There is also DBMLIB, which appears in the link commands for binaries that |
| 2221 | use DBM functions (see also section &<<SECTdb>>&). Finally, there is |
| 2222 | EXTRALIBS_EXIMON, which appears only in the link step for the Exim monitor |
| 2223 | binary, and which can be used, for example, to include additional X11 |
| 2224 | libraries. |
| 2225 | |
| 2226 | .cindex "configuration file" "editing" |
| 2227 | The make file copes with rebuilding Exim correctly if any of the configuration |
| 2228 | files are edited. However, if an optional configuration file is deleted, it is |
| 2229 | necessary to touch the associated non-optional file (that is, |
| 2230 | &_Local/Makefile_& or &_Local/eximon.conf_&) before rebuilding. |
| 2231 | |
| 2232 | |
| 2233 | .section "OS-specific header files" "SECID30" |
| 2234 | .cindex "&_os.h_&" |
| 2235 | .cindex "building Exim" "OS-specific C header files" |
| 2236 | The &_OS_& directory contains a number of files with names of the form |
| 2237 | &_os.h-<ostype>_&. These are system-specific C header files that should not |
| 2238 | normally need to be changed. There is a list of macro settings that are |
| 2239 | recognized in the file &_OS/os.configuring_&, which should be consulted if you |
| 2240 | are porting Exim to a new operating system. |
| 2241 | |
| 2242 | |
| 2243 | |
| 2244 | .section "Overriding build-time options for the monitor" "SECID31" |
| 2245 | .cindex "building Eximon" |
| 2246 | A similar process is used for overriding things when building the Exim monitor, |
| 2247 | where the files that are involved are |
| 2248 | .display |
| 2249 | &_OS/eximon.conf-Default_& |
| 2250 | &_OS/eximon.conf-_&<&'ostype'&> |
| 2251 | &_Local/eximon.conf_& |
| 2252 | &_Local/eximon.conf-_&<&'ostype'&> |
| 2253 | &_Local/eximon.conf-_&<&'archtype'&> |
| 2254 | &_Local/eximon.conf-_&<&'ostype'&>-<&'archtype'&> |
| 2255 | .endd |
| 2256 | .cindex "&_Local/eximon.conf_&" |
| 2257 | As with Exim itself, the final three files need not exist, and in this case the |
| 2258 | &_OS/eximon.conf-<ostype>_& file is also optional. The default values in |
| 2259 | &_OS/eximon.conf-Default_& can be overridden dynamically by setting environment |
| 2260 | variables of the same name, preceded by EXIMON_. For example, setting |
| 2261 | EXIMON_LOG_DEPTH in the environment overrides the value of |
| 2262 | LOG_DEPTH at run time. |
| 2263 | .ecindex IIDbuex |
| 2264 | |
| 2265 | |
| 2266 | .section "Installing Exim binaries and scripts" "SECID32" |
| 2267 | .cindex "installing Exim" |
| 2268 | .cindex "BIN_DIRECTORY" |
| 2269 | The command &`make install`& runs the &(exim_install)& script with no |
| 2270 | arguments. The script copies binaries and utility scripts into the directory |
| 2271 | whose name is specified by the BIN_DIRECTORY setting in &_Local/Makefile_&. |
| 2272 | .cindex "setuid" "installing Exim with" |
| 2273 | The install script copies files only if they are newer than the files they are |
| 2274 | going to replace. The Exim binary is required to be owned by root and have the |
| 2275 | &'setuid'& bit set, for normal configurations. Therefore, you must run &`make |
| 2276 | install`& as root so that it can set up the Exim binary in this way. However, in |
| 2277 | some special situations (for example, if a host is doing no local deliveries) |
| 2278 | it may be possible to run Exim without making the binary setuid root (see |
| 2279 | chapter &<<CHAPsecurity>>& for details). |
| 2280 | |
| 2281 | .cindex "CONFIGURE_FILE" |
| 2282 | Exim's run time configuration file is named by the CONFIGURE_FILE setting |
| 2283 | in &_Local/Makefile_&. If this names a single file, and the file does not |
| 2284 | exist, the default configuration file &_src/configure.default_& is copied there |
| 2285 | by the installation script. If a run time configuration file already exists, it |
| 2286 | is left alone. If CONFIGURE_FILE is a colon-separated list, naming several |
| 2287 | alternative files, no default is installed. |
| 2288 | |
| 2289 | .cindex "system aliases file" |
| 2290 | .cindex "&_/etc/aliases_&" |
| 2291 | One change is made to the default configuration file when it is installed: the |
| 2292 | default configuration contains a router that references a system aliases file. |
| 2293 | The path to this file is set to the value specified by |
| 2294 | SYSTEM_ALIASES_FILE in &_Local/Makefile_& (&_/etc/aliases_& by default). |
| 2295 | If the system aliases file does not exist, the installation script creates it, |
| 2296 | and outputs a comment to the user. |
| 2297 | |
| 2298 | The created file contains no aliases, but it does contain comments about the |
| 2299 | aliases a site should normally have. Mail aliases have traditionally been |
| 2300 | kept in &_/etc/aliases_&. However, some operating systems are now using |
| 2301 | &_/etc/mail/aliases_&. You should check if yours is one of these, and change |
| 2302 | Exim's configuration if necessary. |
| 2303 | |
| 2304 | The default configuration uses the local host's name as the only local domain, |
| 2305 | and is set up to do local deliveries into the shared directory &_/var/mail_&, |
| 2306 | running as the local user. System aliases and &_.forward_& files in users' home |
| 2307 | directories are supported, but no NIS or NIS+ support is configured. Domains |
| 2308 | other than the name of the local host are routed using the DNS, with delivery |
| 2309 | over SMTP. |
| 2310 | |
| 2311 | It is possible to install Exim for special purposes (such as building a binary |
| 2312 | distribution) in a private part of the file system. You can do this by a |
| 2313 | command such as |
| 2314 | .code |
| 2315 | make DESTDIR=/some/directory/ install |
| 2316 | .endd |
| 2317 | This has the effect of pre-pending the specified directory to all the file |
| 2318 | paths, except the name of the system aliases file that appears in the default |
| 2319 | configuration. (If a default alias file is created, its name &'is'& modified.) |
| 2320 | For backwards compatibility, ROOT is used if DESTDIR is not set, |
| 2321 | but this usage is deprecated. |
| 2322 | |
| 2323 | .cindex "installing Exim" "what is not installed" |
| 2324 | Running &'make install'& does not copy the Exim 4 conversion script |
| 2325 | &'convert4r4'&. You will probably run this only once if you are |
| 2326 | upgrading from Exim 3. None of the documentation files in the &_doc_& |
| 2327 | directory are copied, except for the info files when you have set |
| 2328 | INFO_DIRECTORY, as described in section &<<SECTinsinfdoc>>& below. |
| 2329 | |
| 2330 | For the utility programs, old versions are renamed by adding the suffix &_.O_& |
| 2331 | to their names. The Exim binary itself, however, is handled differently. It is |
| 2332 | installed under a name that includes the version number and the compile number, |
| 2333 | for example &_exim-&version()-1_&. The script then arranges for a symbolic link |
| 2334 | called &_exim_& to point to the binary. If you are updating a previous version |
| 2335 | of Exim, the script takes care to ensure that the name &_exim_& is never absent |
| 2336 | from the directory (as seen by other processes). |
| 2337 | |
| 2338 | .cindex "installing Exim" "testing the script" |
| 2339 | If you want to see what the &'make install'& will do before running it for |
| 2340 | real, you can pass the &%-n%& option to the installation script by this |
| 2341 | command: |
| 2342 | .code |
| 2343 | make INSTALL_ARG=-n install |
| 2344 | .endd |
| 2345 | The contents of the variable INSTALL_ARG are passed to the installation |
| 2346 | script. You do not need to be root to run this test. Alternatively, you can run |
| 2347 | the installation script directly, but this must be from within the build |
| 2348 | directory. For example, from the top-level Exim directory you could use this |
| 2349 | command: |
| 2350 | .code |
| 2351 | (cd build-SunOS5-5.5.1-sparc; ../scripts/exim_install -n) |
| 2352 | .endd |
| 2353 | .cindex "installing Exim" "install script options" |
| 2354 | There are two other options that can be supplied to the installation script. |
| 2355 | |
| 2356 | .ilist |
| 2357 | &%-no_chown%& bypasses the call to change the owner of the installed binary |
| 2358 | to root, and the call to make it a setuid binary. |
| 2359 | .next |
| 2360 | &%-no_symlink%& bypasses the setting up of the symbolic link &_exim_& to the |
| 2361 | installed binary. |
| 2362 | .endlist |
| 2363 | |
| 2364 | INSTALL_ARG can be used to pass these options to the script. For example: |
| 2365 | .code |
| 2366 | make INSTALL_ARG=-no_symlink install |
| 2367 | .endd |
| 2368 | The installation script can also be given arguments specifying which files are |
| 2369 | to be copied. For example, to install just the Exim binary, and nothing else, |
| 2370 | without creating the symbolic link, you could use: |
| 2371 | .code |
| 2372 | make INSTALL_ARG='-no_symlink exim' install |
| 2373 | .endd |
| 2374 | |
| 2375 | |
| 2376 | |
| 2377 | .section "Installing info documentation" "SECTinsinfdoc" |
| 2378 | .cindex "installing Exim" "&'info'& documentation" |
| 2379 | Not all systems use the GNU &'info'& system for documentation, and for this |
| 2380 | reason, the Texinfo source of Exim's documentation is not included in the main |
| 2381 | distribution. Instead it is available separately from the ftp site (see section |
| 2382 | &<<SECTavail>>&). |
| 2383 | |
| 2384 | If you have defined INFO_DIRECTORY in &_Local/Makefile_& and the Texinfo |
| 2385 | source of the documentation is found in the source tree, running &`make |
| 2386 | install`& automatically builds the info files and installs them. |
| 2387 | |
| 2388 | |
| 2389 | |
| 2390 | .section "Setting up the spool directory" "SECID33" |
| 2391 | .cindex "spool directory" "creating" |
| 2392 | When it starts up, Exim tries to create its spool directory if it does not |
| 2393 | exist. The Exim uid and gid are used for the owner and group of the spool |
| 2394 | directory. Sub-directories are automatically created in the spool directory as |
| 2395 | necessary. |
| 2396 | |
| 2397 | |
| 2398 | |
| 2399 | |
| 2400 | .section "Testing" "SECID34" |
| 2401 | .cindex "testing" "installation" |
| 2402 | Having installed Exim, you can check that the run time configuration file is |
| 2403 | syntactically valid by running the following command, which assumes that the |
| 2404 | Exim binary directory is within your PATH environment variable: |
| 2405 | .code |
| 2406 | exim -bV |
| 2407 | .endd |
| 2408 | If there are any errors in the configuration file, Exim outputs error messages. |
| 2409 | Otherwise it outputs the version number and build date, |
| 2410 | the DBM library that is being used, and information about which drivers and |
| 2411 | other optional code modules are included in the binary. |
| 2412 | Some simple routing tests can be done by using the address testing option. For |
| 2413 | example, |
| 2414 | .display |
| 2415 | &`exim -bt`& <&'local username'&> |
| 2416 | .endd |
| 2417 | should verify that it recognizes a local mailbox, and |
| 2418 | .display |
| 2419 | &`exim -bt`& <&'remote address'&> |
| 2420 | .endd |
| 2421 | a remote one. Then try getting it to deliver mail, both locally and remotely. |
| 2422 | This can be done by passing messages directly to Exim, without going through a |
| 2423 | user agent. For example: |
| 2424 | .code |
| 2425 | exim -v postmaster@your.domain.example |
| 2426 | From: user@your.domain.example |
| 2427 | To: postmaster@your.domain.example |
| 2428 | Subject: Testing Exim |
| 2429 | |
| 2430 | This is a test message. |
| 2431 | ^D |
| 2432 | .endd |
| 2433 | The &%-v%& option causes Exim to output some verification of what it is doing. |
| 2434 | In this case you should see copies of three log lines, one for the message's |
| 2435 | arrival, one for its delivery, and one containing &"Completed"&. |
| 2436 | |
| 2437 | .cindex "delivery" "problems with" |
| 2438 | If you encounter problems, look at Exim's log files (&'mainlog'& and |
| 2439 | &'paniclog'&) to see if there is any relevant information there. Another source |
| 2440 | of information is running Exim with debugging turned on, by specifying the |
| 2441 | &%-d%& option. If a message is stuck on Exim's spool, you can force a delivery |
| 2442 | with debugging turned on by a command of the form |
| 2443 | .display |
| 2444 | &`exim -d -M`& <&'exim-message-id'&> |
| 2445 | .endd |
| 2446 | You must be root or an &"admin user"& in order to do this. The &%-d%& option |
| 2447 | produces rather a lot of output, but you can cut this down to specific areas. |
| 2448 | For example, if you use &%-d-all+route%& only the debugging information |
| 2449 | relevant to routing is included. (See the &%-d%& option in chapter |
| 2450 | &<<CHAPcommandline>>& for more details.) |
| 2451 | |
| 2452 | .cindex '&"sticky"& bit' |
| 2453 | .cindex "lock files" |
| 2454 | One specific problem that has shown up on some sites is the inability to do |
| 2455 | local deliveries into a shared mailbox directory, because it does not have the |
| 2456 | &"sticky bit"& set on it. By default, Exim tries to create a lock file before |
| 2457 | writing to a mailbox file, and if it cannot create the lock file, the delivery |
| 2458 | is deferred. You can get round this either by setting the &"sticky bit"& on the |
| 2459 | directory, or by setting a specific group for local deliveries and allowing |
| 2460 | that group to create files in the directory (see the comments above the |
| 2461 | &(local_delivery)& transport in the default configuration file). Another |
| 2462 | approach is to configure Exim not to use lock files, but just to rely on |
| 2463 | &[fcntl()]& locking instead. However, you should do this only if all user |
| 2464 | agents also use &[fcntl()]& locking. For further discussion of locking issues, |
| 2465 | see chapter &<<CHAPappendfile>>&. |
| 2466 | |
| 2467 | One thing that cannot be tested on a system that is already running an MTA is |
| 2468 | the receipt of incoming SMTP mail on the standard SMTP port. However, the |
| 2469 | &%-oX%& option can be used to run an Exim daemon that listens on some other |
| 2470 | port, or &'inetd'& can be used to do this. The &%-bh%& option and the |
| 2471 | &'exim_checkaccess'& utility can be used to check out policy controls on |
| 2472 | incoming SMTP mail. |
| 2473 | |
| 2474 | Testing a new version on a system that is already running Exim can most easily |
| 2475 | be done by building a binary with a different CONFIGURE_FILE setting. From |
| 2476 | within the run time configuration, all other file and directory names |
| 2477 | that Exim uses can be altered, in order to keep it entirely clear of the |
| 2478 | production version. |
| 2479 | |
| 2480 | |
| 2481 | .section "Replacing another MTA with Exim" "SECID35" |
| 2482 | .cindex "replacing another MTA" |
| 2483 | Building and installing Exim for the first time does not of itself put it in |
| 2484 | general use. The name by which the system's MTA is called by mail user agents |
| 2485 | is either &_/usr/sbin/sendmail_&, or &_/usr/lib/sendmail_& (depending on the |
| 2486 | operating system), and it is necessary to make this name point to the &'exim'& |
| 2487 | binary in order to get the user agents to pass messages to Exim. This is |
| 2488 | normally done by renaming any existing file and making &_/usr/sbin/sendmail_& |
| 2489 | or &_/usr/lib/sendmail_& |
| 2490 | .cindex "symbolic link" "to &'exim'& binary" |
| 2491 | a symbolic link to the &'exim'& binary. It is a good idea to remove any setuid |
| 2492 | privilege and executable status from the old MTA. It is then necessary to stop |
| 2493 | and restart the mailer daemon, if one is running. |
| 2494 | |
| 2495 | .cindex "FreeBSD, MTA indirection" |
| 2496 | .cindex "&_/etc/mail/mailer.conf_&" |
| 2497 | Some operating systems have introduced alternative ways of switching MTAs. For |
| 2498 | example, if you are running FreeBSD, you need to edit the file |
| 2499 | &_/etc/mail/mailer.conf_& instead of setting up a symbolic link as just |
| 2500 | described. A typical example of the contents of this file for running Exim is |
| 2501 | as follows: |
| 2502 | .code |
| 2503 | sendmail /usr/exim/bin/exim |
| 2504 | send-mail /usr/exim/bin/exim |
| 2505 | mailq /usr/exim/bin/exim -bp |
| 2506 | newaliases /usr/bin/true |
| 2507 | .endd |
| 2508 | Once you have set up the symbolic link, or edited &_/etc/mail/mailer.conf_&, |
| 2509 | your Exim installation is &"live"&. Check it by sending a message from your |
| 2510 | favourite user agent. |
| 2511 | |
| 2512 | You should consider what to tell your users about the change of MTA. Exim may |
| 2513 | have different capabilities to what was previously running, and there are |
| 2514 | various operational differences such as the text of messages produced by |
| 2515 | command line options and in bounce messages. If you allow your users to make |
| 2516 | use of Exim's filtering capabilities, you should make the document entitled |
| 2517 | &'Exim's interface to mail filtering'& available to them. |
| 2518 | |
| 2519 | |
| 2520 | |
| 2521 | .section "Upgrading Exim" "SECID36" |
| 2522 | .cindex "upgrading Exim" |
| 2523 | If you are already running Exim on your host, building and installing a new |
| 2524 | version automatically makes it available to MUAs, or any other programs that |
| 2525 | call the MTA directly. However, if you are running an Exim daemon, you do need |
| 2526 | to send it a HUP signal, to make it re-execute itself, and thereby pick up the |
| 2527 | new binary. You do not need to stop processing mail in order to install a new |
| 2528 | version of Exim. The install script does not modify an existing runtime |
| 2529 | configuration file. |
| 2530 | |
| 2531 | |
| 2532 | |
| 2533 | |
| 2534 | .section "Stopping the Exim daemon on Solaris" "SECID37" |
| 2535 | .cindex "Solaris" "stopping Exim on" |
| 2536 | The standard command for stopping the mailer daemon on Solaris is |
| 2537 | .code |
| 2538 | /etc/init.d/sendmail stop |
| 2539 | .endd |
| 2540 | If &_/usr/lib/sendmail_& has been turned into a symbolic link, this script |
| 2541 | fails to stop Exim because it uses the command &'ps -e'& and greps the output |
| 2542 | for the text &"sendmail"&; this is not present because the actual program name |
| 2543 | (that is, &"exim"&) is given by the &'ps'& command with these options. A |
| 2544 | solution is to replace the line that finds the process id with something like |
| 2545 | .code |
| 2546 | pid=`cat /var/spool/exim/exim-daemon.pid` |
| 2547 | .endd |
| 2548 | to obtain the daemon's pid directly from the file that Exim saves it in. |
| 2549 | |
| 2550 | Note, however, that stopping the daemon does not &"stop Exim"&. Messages can |
| 2551 | still be received from local processes, and if automatic delivery is configured |
| 2552 | (the normal case), deliveries will still occur. |
| 2553 | |
| 2554 | |
| 2555 | |
| 2556 | |
| 2557 | . //////////////////////////////////////////////////////////////////////////// |
| 2558 | . //////////////////////////////////////////////////////////////////////////// |
| 2559 | |
| 2560 | .chapter "The Exim command line" "CHAPcommandline" |
| 2561 | .scindex IIDclo1 "command line" "options" |
| 2562 | .scindex IIDclo2 "options" "command line" |
| 2563 | Exim's command line takes the standard Unix form of a sequence of options, |
| 2564 | each starting with a hyphen character, followed by a number of arguments. The |
| 2565 | options are compatible with the main options of Sendmail, and there are also |
| 2566 | some additional options, some of which are compatible with Smail 3. Certain |
| 2567 | combinations of options do not make sense, and provoke an error if used. |
| 2568 | The form of the arguments depends on which options are set. |
| 2569 | |
| 2570 | |
| 2571 | .section "Setting options by program name" "SECID38" |
| 2572 | .cindex "&'mailq'&" |
| 2573 | If Exim is called under the name &'mailq'&, it behaves as if the option &%-bp%& |
| 2574 | were present before any other options. |
| 2575 | The &%-bp%& option requests a listing of the contents of the mail queue on the |
| 2576 | standard output. |
| 2577 | This feature is for compatibility with some systems that contain a command of |
| 2578 | that name in one of the standard libraries, symbolically linked to |
| 2579 | &_/usr/sbin/sendmail_& or &_/usr/lib/sendmail_&. |
| 2580 | |
| 2581 | .cindex "&'rsmtp'&" |
| 2582 | If Exim is called under the name &'rsmtp'& it behaves as if the option &%-bS%& |
| 2583 | were present before any other options, for compatibility with Smail. The |
| 2584 | &%-bS%& option is used for reading in a number of messages in batched SMTP |
| 2585 | format. |
| 2586 | |
| 2587 | .cindex "&'rmail'&" |
| 2588 | If Exim is called under the name &'rmail'& it behaves as if the &%-i%& and |
| 2589 | &%-oee%& options were present before any other options, for compatibility with |
| 2590 | Smail. The name &'rmail'& is used as an interface by some UUCP systems. |
| 2591 | |
| 2592 | .cindex "&'runq'&" |
| 2593 | .cindex "queue runner" |
| 2594 | If Exim is called under the name &'runq'& it behaves as if the option &%-q%& |
| 2595 | were present before any other options, for compatibility with Smail. The &%-q%& |
| 2596 | option causes a single queue runner process to be started. |
| 2597 | |
| 2598 | .cindex "&'newaliases'&" |
| 2599 | .cindex "alias file" "building" |
| 2600 | .cindex "Sendmail compatibility" "calling Exim as &'newaliases'&" |
| 2601 | If Exim is called under the name &'newaliases'& it behaves as if the option |
| 2602 | &%-bi%& were present before any other options, for compatibility with Sendmail. |
| 2603 | This option is used for rebuilding Sendmail's alias file. Exim does not have |
| 2604 | the concept of a single alias file, but can be configured to run a given |
| 2605 | command if called with the &%-bi%& option. |
| 2606 | |
| 2607 | |
| 2608 | .section "Trusted and admin users" "SECTtrustedadmin" |
| 2609 | Some Exim options are available only to &'trusted users'& and others are |
| 2610 | available only to &'admin users'&. In the description below, the phrases &"Exim |
| 2611 | user"& and &"Exim group"& mean the user and group defined by EXIM_USER and |
| 2612 | EXIM_GROUP in &_Local/Makefile_& or set by the &%exim_user%& and |
| 2613 | &%exim_group%& options. These do not necessarily have to use the name &"exim"&. |
| 2614 | |
| 2615 | .ilist |
| 2616 | .cindex "trusted users" "definition of" |
| 2617 | .cindex "user" "trusted definition of" |
| 2618 | The trusted users are root, the Exim user, any user listed in the |
| 2619 | &%trusted_users%& configuration option, and any user whose current group or any |
| 2620 | supplementary group is one of those listed in the &%trusted_groups%& |
| 2621 | configuration option. Note that the Exim group is not automatically trusted. |
| 2622 | |
| 2623 | .cindex '&"From"& line' |
| 2624 | .cindex "envelope sender" |
| 2625 | Trusted users are always permitted to use the &%-f%& option or a leading |
| 2626 | &"From&~"& line to specify the envelope sender of a message that is passed to |
| 2627 | Exim through the local interface (see the &%-bm%& and &%-f%& options below). |
| 2628 | See the &%untrusted_set_sender%& option for a way of permitting non-trusted |
| 2629 | users to set envelope senders. |
| 2630 | |
| 2631 | .cindex "&'From:'& header line" |
| 2632 | .cindex "&'Sender:'& header line" |
| 2633 | For a trusted user, there is never any check on the contents of the &'From:'& |
| 2634 | header line, and a &'Sender:'& line is never added. Furthermore, any existing |
| 2635 | &'Sender:'& line in incoming local (non-TCP/IP) messages is not removed. |
| 2636 | |
| 2637 | Trusted users may also specify a host name, host address, interface address, |
| 2638 | protocol name, ident value, and authentication data when submitting a message |
| 2639 | locally. Thus, they are able to insert messages into Exim's queue locally that |
| 2640 | have the characteristics of messages received from a remote host. Untrusted |
| 2641 | users may in some circumstances use &%-f%&, but can never set the other values |
| 2642 | that are available to trusted users. |
| 2643 | .next |
| 2644 | .cindex "user" "admin definition of" |
| 2645 | .cindex "admin user" "definition of" |
| 2646 | The admin users are root, the Exim user, and any user that is a member of the |
| 2647 | Exim group or of any group listed in the &%admin_groups%& configuration option. |
| 2648 | The current group does not have to be one of these groups. |
| 2649 | |
| 2650 | Admin users are permitted to list the queue, and to carry out certain |
| 2651 | operations on messages, for example, to force delivery failures. It is also |
| 2652 | necessary to be an admin user in order to see the full information provided by |
| 2653 | the Exim monitor, and full debugging output. |
| 2654 | |
| 2655 | By default, the use of the &%-M%&, &%-q%&, &%-R%&, and &%-S%& options to cause |
| 2656 | Exim to attempt delivery of messages on its queue is restricted to admin users. |
| 2657 | However, this restriction can be relaxed by setting the &%prod_requires_admin%& |
| 2658 | option false (that is, specifying &%no_prod_requires_admin%&). |
| 2659 | |
| 2660 | Similarly, the use of the &%-bp%& option to list all the messages in the queue |
| 2661 | is restricted to admin users unless &%queue_list_requires_admin%& is set |
| 2662 | false. |
| 2663 | .endlist |
| 2664 | |
| 2665 | |
| 2666 | &*Warning*&: If you configure your system so that admin users are able to |
| 2667 | edit Exim's configuration file, you are giving those users an easy way of |
| 2668 | getting root. There is further discussion of this issue at the start of chapter |
| 2669 | &<<CHAPconf>>&. |
| 2670 | |
| 2671 | |
| 2672 | |
| 2673 | |
| 2674 | .section "Command line options" "SECID39" |
| 2675 | Exim's command line options are described in alphabetical order below. If none |
| 2676 | of the options that specifies a specific action (such as starting the daemon or |
| 2677 | a queue runner, or testing an address, or receiving a message in a specific |
| 2678 | format, or listing the queue) are present, and there is at least one argument |
| 2679 | on the command line, &%-bm%& (accept a local message on the standard input, |
| 2680 | with the arguments specifying the recipients) is assumed. Otherwise, Exim |
| 2681 | outputs a brief message about itself and exits. |
| 2682 | |
| 2683 | . //////////////////////////////////////////////////////////////////////////// |
| 2684 | . Insert a stylized XML comment here, to identify the start of the command line |
| 2685 | . options. This is for the benefit of the Perl script that automatically |
| 2686 | . creates a man page for the options. |
| 2687 | . //////////////////////////////////////////////////////////////////////////// |
| 2688 | |
| 2689 | .literal xml |
| 2690 | <!-- === Start of command line options === --> |
| 2691 | .literal off |
| 2692 | |
| 2693 | |
| 2694 | .vlist |
| 2695 | .vitem &%--%& |
| 2696 | .oindex "--" |
| 2697 | .cindex "options" "command line; terminating" |
| 2698 | This is a pseudo-option whose only purpose is to terminate the options and |
| 2699 | therefore to cause subsequent command line items to be treated as arguments |
| 2700 | rather than options, even if they begin with hyphens. |
| 2701 | |
| 2702 | .vitem &%--help%& |
| 2703 | .oindex "&%--help%&" |
| 2704 | This option causes Exim to output a few sentences stating what it is. |
| 2705 | The same output is generated if the Exim binary is called with no options and |
| 2706 | no arguments. |
| 2707 | |
| 2708 | .vitem &%--version%& |
| 2709 | .oindex "&%--version%&" |
| 2710 | This option is an alias for &%-bV%& and causes version information to be |
| 2711 | displayed. |
| 2712 | |
| 2713 | .vitem &%-Ac%& &&& |
| 2714 | &%-Am%& |
| 2715 | .oindex "&%-Ac%&" |
| 2716 | .oindex "&%-Am%&" |
| 2717 | These options are used by Sendmail for selecting configuration files and are |
| 2718 | ignored by Exim. |
| 2719 | |
| 2720 | .vitem &%-B%&<&'type'&> |
| 2721 | .oindex "&%-B%&" |
| 2722 | .cindex "8-bit characters" |
| 2723 | .cindex "Sendmail compatibility" "8-bit characters" |
| 2724 | This is a Sendmail option for selecting 7 or 8 bit processing. Exim is 8-bit |
| 2725 | clean; it ignores this option. |
| 2726 | |
| 2727 | .vitem &%-bd%& |
| 2728 | .oindex "&%-bd%&" |
| 2729 | .cindex "daemon" |
| 2730 | .cindex "SMTP" "listener" |
| 2731 | .cindex "queue runner" |
| 2732 | This option runs Exim as a daemon, awaiting incoming SMTP connections. Usually |
| 2733 | the &%-bd%& option is combined with the &%-q%&<&'time'&> option, to specify |
| 2734 | that the daemon should also initiate periodic queue runs. |
| 2735 | |
| 2736 | The &%-bd%& option can be used only by an admin user. If either of the &%-d%& |
| 2737 | (debugging) or &%-v%& (verifying) options are set, the daemon does not |
| 2738 | disconnect from the controlling terminal. When running this way, it can be |
| 2739 | stopped by pressing ctrl-C. |
| 2740 | |
| 2741 | By default, Exim listens for incoming connections to the standard SMTP port on |
| 2742 | all the host's running interfaces. However, it is possible to listen on other |
| 2743 | ports, on multiple ports, and only on specific interfaces. Chapter |
| 2744 | &<<CHAPinterfaces>>& contains a description of the options that control this. |
| 2745 | |
| 2746 | When a listening daemon |
| 2747 | .cindex "daemon" "process id (pid)" |
| 2748 | .cindex "pid (process id)" "of daemon" |
| 2749 | is started without the use of &%-oX%& (that is, without overriding the normal |
| 2750 | configuration), it writes its process id to a file called &_exim-daemon.pid_& |
| 2751 | in Exim's spool directory. This location can be overridden by setting |
| 2752 | PID_FILE_PATH in &_Local/Makefile_&. The file is written while Exim is still |
| 2753 | running as root. |
| 2754 | |
| 2755 | When &%-oX%& is used on the command line to start a listening daemon, the |
| 2756 | process id is not written to the normal pid file path. However, &%-oP%& can be |
| 2757 | used to specify a path on the command line if a pid file is required. |
| 2758 | |
| 2759 | The SIGHUP signal |
| 2760 | .cindex "SIGHUP" |
| 2761 | .cindex "daemon" "restarting" |
| 2762 | can be used to cause the daemon to re-execute itself. This should be done |
| 2763 | whenever Exim's configuration file, or any file that is incorporated into it by |
| 2764 | means of the &%.include%& facility, is changed, and also whenever a new version |
| 2765 | of Exim is installed. It is not necessary to do this when other files that are |
| 2766 | referenced from the configuration (for example, alias files) are changed, |
| 2767 | because these are reread each time they are used. |
| 2768 | |
| 2769 | .vitem &%-bdf%& |
| 2770 | .oindex "&%-bdf%&" |
| 2771 | This option has the same effect as &%-bd%& except that it never disconnects |
| 2772 | from the controlling terminal, even when no debugging is specified. |
| 2773 | |
| 2774 | .vitem &%-be%& |
| 2775 | .oindex "&%-be%&" |
| 2776 | .cindex "testing" "string expansion" |
| 2777 | .cindex "expansion" "testing" |
| 2778 | Run Exim in expansion testing mode. Exim discards its root privilege, to |
| 2779 | prevent ordinary users from using this mode to read otherwise inaccessible |
| 2780 | files. If no arguments are given, Exim runs interactively, prompting for lines |
| 2781 | of data. Otherwise, it processes each argument in turn. |
| 2782 | |
| 2783 | If Exim was built with USE_READLINE=yes in &_Local/Makefile_&, it tries |
| 2784 | to load the &%libreadline%& library dynamically whenever the &%-be%& option is |
| 2785 | used without command line arguments. If successful, it uses the &[readline()]& |
| 2786 | function, which provides extensive line-editing facilities, for reading the |
| 2787 | test data. A line history is supported. |
| 2788 | |
| 2789 | Long expansion expressions can be split over several lines by using backslash |
| 2790 | continuations. As in Exim's run time configuration, white space at the start of |
| 2791 | continuation lines is ignored. Each argument or data line is passed through the |
| 2792 | string expansion mechanism, and the result is output. Variable values from the |
| 2793 | configuration file (for example, &$qualify_domain$&) are available, but no |
| 2794 | message-specific values (such as &$sender_domain$&) are set, because no message |
| 2795 | is being processed (but see &%-bem%& and &%-Mset%&). |
| 2796 | |
| 2797 | &*Note*&: If you use this mechanism to test lookups, and you change the data |
| 2798 | files or databases you are using, you must exit and restart Exim before trying |
| 2799 | the same lookup again. Otherwise, because each Exim process caches the results |
| 2800 | of lookups, you will just get the same result as before. |
| 2801 | |
| 2802 | .vitem &%-bem%&&~<&'filename'&> |
| 2803 | .oindex "&%-bem%&" |
| 2804 | .cindex "testing" "string expansion" |
| 2805 | .cindex "expansion" "testing" |
| 2806 | This option operates like &%-be%& except that it must be followed by the name |
| 2807 | of a file. For example: |
| 2808 | .code |
| 2809 | exim -bem /tmp/testmessage |
| 2810 | .endd |
| 2811 | The file is read as a message (as if receiving a locally-submitted non-SMTP |
| 2812 | message) before any of the test expansions are done. Thus, message-specific |
| 2813 | variables such as &$message_size$& and &$header_from:$& are available. However, |
| 2814 | no &'Received:'& header is added to the message. If the &%-t%& option is set, |
| 2815 | recipients are read from the headers in the normal way, and are shown in the |
| 2816 | &$recipients$& variable. Note that recipients cannot be given on the command |
| 2817 | line, because further arguments are taken as strings to expand (just like |
| 2818 | &%-be%&). |
| 2819 | |
| 2820 | .vitem &%-bF%&&~<&'filename'&> |
| 2821 | .oindex "&%-bF%&" |
| 2822 | .cindex "system filter" "testing" |
| 2823 | .cindex "testing" "system filter" |
| 2824 | This option is the same as &%-bf%& except that it assumes that the filter being |
| 2825 | tested is a system filter. The additional commands that are available only in |
| 2826 | system filters are recognized. |
| 2827 | |
| 2828 | .vitem &%-bf%&&~<&'filename'&> |
| 2829 | .oindex "&%-bf%&" |
| 2830 | .cindex "filter" "testing" |
| 2831 | .cindex "testing" "filter file" |
| 2832 | .cindex "forward file" "testing" |
| 2833 | .cindex "testing" "forward file" |
| 2834 | .cindex "Sieve filter" "testing" |
| 2835 | This option runs Exim in user filter testing mode; the file is the filter file |
| 2836 | to be tested, and a test message must be supplied on the standard input. If |
| 2837 | there are no message-dependent tests in the filter, an empty file can be |
| 2838 | supplied. |
| 2839 | |
| 2840 | If you want to test a system filter file, use &%-bF%& instead of &%-bf%&. You |
| 2841 | can use both &%-bF%& and &%-bf%& on the same command, in order to test a system |
| 2842 | filter and a user filter in the same run. For example: |
| 2843 | .code |
| 2844 | exim -bF /system/filter -bf /user/filter </test/message |
| 2845 | .endd |
| 2846 | This is helpful when the system filter adds header lines or sets filter |
| 2847 | variables that are used by the user filter. |
| 2848 | |
| 2849 | If the test filter file does not begin with one of the special lines |
| 2850 | .code |
| 2851 | # Exim filter |
| 2852 | # Sieve filter |
| 2853 | .endd |
| 2854 | it is taken to be a normal &_.forward_& file, and is tested for validity under |
| 2855 | that interpretation. See sections &<<SECTitenonfilred>>& to |
| 2856 | &<<SECTspecitredli>>& for a description of the possible contents of non-filter |
| 2857 | redirection lists. |
| 2858 | |
| 2859 | The result of an Exim command that uses &%-bf%&, provided no errors are |
| 2860 | detected, is a list of the actions that Exim would try to take if presented |
| 2861 | with the message for real. More details of filter testing are given in the |
| 2862 | separate document entitled &'Exim's interfaces to mail filtering'&. |
| 2863 | |
| 2864 | When testing a filter file, |
| 2865 | .cindex "&""From""& line" |
| 2866 | .cindex "envelope sender" |
| 2867 | .oindex "&%-f%&" "for filter testing" |
| 2868 | the envelope sender can be set by the &%-f%& option, |
| 2869 | or by a &"From&~"& line at the start of the test message. Various parameters |
| 2870 | that would normally be taken from the envelope recipient address of the message |
| 2871 | can be set by means of additional command line options (see the next four |
| 2872 | options). |
| 2873 | |
| 2874 | .vitem &%-bfd%&&~<&'domain'&> |
| 2875 | .oindex "&%-bfd%&" |
| 2876 | .vindex "&$qualify_domain$&" |
| 2877 | This sets the domain of the recipient address when a filter file is being |
| 2878 | tested by means of the &%-bf%& option. The default is the value of |
| 2879 | &$qualify_domain$&. |
| 2880 | |
| 2881 | .vitem &%-bfl%&&~<&'local&~part'&> |
| 2882 | .oindex "&%-bfl%&" |
| 2883 | This sets the local part of the recipient address when a filter file is being |
| 2884 | tested by means of the &%-bf%& option. The default is the username of the |
| 2885 | process that calls Exim. A local part should be specified with any prefix or |
| 2886 | suffix stripped, because that is how it appears to the filter when a message is |
| 2887 | actually being delivered. |
| 2888 | |
| 2889 | .vitem &%-bfp%&&~<&'prefix'&> |
| 2890 | .oindex "&%-bfp%&" |
| 2891 | This sets the prefix of the local part of the recipient address when a filter |
| 2892 | file is being tested by means of the &%-bf%& option. The default is an empty |
| 2893 | prefix. |
| 2894 | |
| 2895 | .vitem &%-bfs%&&~<&'suffix'&> |
| 2896 | .oindex "&%-bfs%&" |
| 2897 | This sets the suffix of the local part of the recipient address when a filter |
| 2898 | file is being tested by means of the &%-bf%& option. The default is an empty |
| 2899 | suffix. |
| 2900 | |
| 2901 | .vitem &%-bh%&&~<&'IP&~address'&> |
| 2902 | .oindex "&%-bh%&" |
| 2903 | .cindex "testing" "incoming SMTP" |
| 2904 | .cindex "SMTP" "testing incoming" |
| 2905 | .cindex "testing" "relay control" |
| 2906 | .cindex "relaying" "testing configuration" |
| 2907 | .cindex "policy control" "testing" |
| 2908 | .cindex "debugging" "&%-bh%& option" |
| 2909 | This option runs a fake SMTP session as if from the given IP address, using the |
| 2910 | standard input and output. The IP address may include a port number at the end, |
| 2911 | after a full stop. For example: |
| 2912 | .code |
| 2913 | exim -bh 10.9.8.7.1234 |
| 2914 | exim -bh fe80::a00:20ff:fe86:a061.5678 |
| 2915 | .endd |
| 2916 | When an IPv6 address is given, it is converted into canonical form. In the case |
| 2917 | of the second example above, the value of &$sender_host_address$& after |
| 2918 | conversion to the canonical form is |
| 2919 | &`fe80:0000:0000:0a00:20ff:fe86:a061.5678`&. |
| 2920 | |
| 2921 | Comments as to what is going on are written to the standard error file. These |
| 2922 | include lines beginning with &"LOG"& for anything that would have been logged. |
| 2923 | This facility is provided for testing configuration options for incoming |
| 2924 | messages, to make sure they implement the required policy. For example, you can |
| 2925 | test your relay controls using &%-bh%&. |
| 2926 | |
| 2927 | &*Warning 1*&: |
| 2928 | .cindex "RFC 1413" |
| 2929 | You can test features of the configuration that rely on ident (RFC 1413) |
| 2930 | information by using the &%-oMt%& option. However, Exim cannot actually perform |
| 2931 | an ident callout when testing using &%-bh%& because there is no incoming SMTP |
| 2932 | connection. |
| 2933 | |
| 2934 | &*Warning 2*&: Address verification callouts (see section &<<SECTcallver>>&) |
| 2935 | are also skipped when testing using &%-bh%&. If you want these callouts to |
| 2936 | occur, use &%-bhc%& instead. |
| 2937 | |
| 2938 | Messages supplied during the testing session are discarded, and nothing is |
| 2939 | written to any of the real log files. There may be pauses when DNS (and other) |
| 2940 | lookups are taking place, and of course these may time out. The &%-oMi%& option |
| 2941 | can be used to specify a specific IP interface and port if this is important, |
| 2942 | and &%-oMaa%& and &%-oMai%& can be used to set parameters as if the SMTP |
| 2943 | session were authenticated. |
| 2944 | |
| 2945 | The &'exim_checkaccess'& utility is a &"packaged"& version of &%-bh%& whose |
| 2946 | output just states whether a given recipient address from a given host is |
| 2947 | acceptable or not. See section &<<SECTcheckaccess>>&. |
| 2948 | |
| 2949 | Features such as authentication and encryption, where the client input is not |
| 2950 | plain text, cannot easily be tested with &%-bh%&. Instead, you should use a |
| 2951 | specialized SMTP test program such as |
| 2952 | &url(http://jetmore.org/john/code/#swaks,swaks). |
| 2953 | |
| 2954 | .vitem &%-bhc%&&~<&'IP&~address'&> |
| 2955 | .oindex "&%-bhc%&" |
| 2956 | This option operates in the same way as &%-bh%&, except that address |
| 2957 | verification callouts are performed if required. This includes consulting and |
| 2958 | updating the callout cache database. |
| 2959 | |
| 2960 | .vitem &%-bi%& |
| 2961 | .oindex "&%-bi%&" |
| 2962 | .cindex "alias file" "building" |
| 2963 | .cindex "building alias file" |
| 2964 | .cindex "Sendmail compatibility" "&%-bi%& option" |
| 2965 | Sendmail interprets the &%-bi%& option as a request to rebuild its alias file. |
| 2966 | Exim does not have the concept of a single alias file, and so it cannot mimic |
| 2967 | this behaviour. However, calls to &_/usr/lib/sendmail_& with the &%-bi%& option |
| 2968 | tend to appear in various scripts such as NIS make files, so the option must be |
| 2969 | recognized. |
| 2970 | |
| 2971 | If &%-bi%& is encountered, the command specified by the &%bi_command%& |
| 2972 | configuration option is run, under the uid and gid of the caller of Exim. If |
| 2973 | the &%-oA%& option is used, its value is passed to the command as an argument. |
| 2974 | The command set by &%bi_command%& may not contain arguments. The command can |
| 2975 | use the &'exim_dbmbuild'& utility, or some other means, to rebuild alias files |
| 2976 | if this is required. If the &%bi_command%& option is not set, calling Exim with |
| 2977 | &%-bi%& is a no-op. |
| 2978 | |
| 2979 | . // Keep :help first, then the rest in alphabetical order |
| 2980 | .vitem &%-bI:help%& |
| 2981 | .oindex "&%-bI:help%&" |
| 2982 | .cindex "querying exim information" |
| 2983 | We shall provide various options starting &`-bI:`& for querying Exim for |
| 2984 | information. The output of many of these will be intended for machine |
| 2985 | consumption. This one is not. The &%-bI:help%& option asks Exim for a |
| 2986 | synopsis of supported options beginning &`-bI:`&. Use of any of these |
| 2987 | options shall cause Exim to exit after producing the requested output. |
| 2988 | |
| 2989 | .vitem &%-bI:dscp%& |
| 2990 | .oindex "&%-bI:dscp%&" |
| 2991 | .cindex "DSCP" "values" |
| 2992 | This option causes Exim to emit an alphabetically sorted list of all |
| 2993 | recognised DSCP names. |
| 2994 | |
| 2995 | .vitem &%-bI:sieve%& |
| 2996 | .oindex "&%-bI:sieve%&" |
| 2997 | .cindex "Sieve filter" "capabilities" |
| 2998 | This option causes Exim to emit an alphabetically sorted list of all supported |
| 2999 | Sieve protocol extensions on stdout, one per line. This is anticipated to be |
| 3000 | useful for ManageSieve (RFC 5804) implementations, in providing that protocol's |
| 3001 | &`SIEVE`& capability response line. As the precise list may depend upon |
| 3002 | compile-time build options, which this option will adapt to, this is the only |
| 3003 | way to guarantee a correct response. |
| 3004 | |
| 3005 | .vitem &%-bm%& |
| 3006 | .oindex "&%-bm%&" |
| 3007 | .cindex "local message reception" |
| 3008 | This option runs an Exim receiving process that accepts an incoming, |
| 3009 | locally-generated message on the standard input. The recipients are given as the |
| 3010 | command arguments (except when &%-t%& is also present &-- see below). Each |
| 3011 | argument can be a comma-separated list of RFC 2822 addresses. This is the |
| 3012 | default option for selecting the overall action of an Exim call; it is assumed |
| 3013 | if no other conflicting option is present. |
| 3014 | |
| 3015 | If any addresses in the message are unqualified (have no domain), they are |
| 3016 | qualified by the values of the &%qualify_domain%& or &%qualify_recipient%& |
| 3017 | options, as appropriate. The &%-bnq%& option (see below) provides a way of |
| 3018 | suppressing this for special cases. |
| 3019 | |
| 3020 | Policy checks on the contents of local messages can be enforced by means of |
| 3021 | the non-SMTP ACL. See chapter &<<CHAPACL>>& for details. |
| 3022 | |
| 3023 | .cindex "return code" "for &%-bm%&" |
| 3024 | The return code is zero if the message is successfully accepted. Otherwise, the |
| 3025 | action is controlled by the &%-oe%&&'x'& option setting &-- see below. |
| 3026 | |
| 3027 | The format |
| 3028 | .cindex "message" "format" |
| 3029 | .cindex "format" "message" |
| 3030 | .cindex "&""From""& line" |
| 3031 | .cindex "UUCP" "&""From""& line" |
| 3032 | .cindex "Sendmail compatibility" "&""From""& line" |
| 3033 | of the message must be as defined in RFC 2822, except that, for |
| 3034 | compatibility with Sendmail and Smail, a line in one of the forms |
| 3035 | .code |
| 3036 | From sender Fri Jan 5 12:55 GMT 1997 |
| 3037 | From sender Fri, 5 Jan 97 12:55:01 |
| 3038 | .endd |
| 3039 | (with the weekday optional, and possibly with additional text after the date) |
| 3040 | is permitted to appear at the start of the message. There appears to be no |
| 3041 | authoritative specification of the format of this line. Exim recognizes it by |
| 3042 | matching against the regular expression defined by the &%uucp_from_pattern%& |
| 3043 | option, which can be changed if necessary. |
| 3044 | |
| 3045 | .oindex "&%-f%&" "overriding &""From""& line" |
| 3046 | The specified sender is treated as if it were given as the argument to the |
| 3047 | &%-f%& option, but if a &%-f%& option is also present, its argument is used in |
| 3048 | preference to the address taken from the message. The caller of Exim must be a |
| 3049 | trusted user for the sender of a message to be set in this way. |
| 3050 | |
| 3051 | .vitem &%-bmalware%&&~<&'filename'&> |
| 3052 | .oindex "&%-bmalware%&" |
| 3053 | .cindex "testing", "malware" |
| 3054 | .cindex "malware scan test" |
| 3055 | This debugging option causes Exim to scan the given file, |
| 3056 | using the malware scanning framework. The option of &%av_scanner%& influences |
| 3057 | this option, so if &%av_scanner%&'s value is dependent upon an expansion then |
| 3058 | the expansion should have defaults which apply to this invocation. ACLs are |
| 3059 | not invoked, so if &%av_scanner%& references an ACL variable then that variable |
| 3060 | will never be populated and &%-bmalware%& will fail. |
| 3061 | |
| 3062 | Exim will have changed working directory before resolving the filename, so |
| 3063 | using fully qualified pathnames is advisable. Exim will be running as the Exim |
| 3064 | user when it tries to open the file, rather than as the invoking user. |
| 3065 | This option requires admin privileges. |
| 3066 | |
| 3067 | The &%-bmalware%& option will not be extended to be more generally useful, |
| 3068 | there are better tools for file-scanning. This option exists to help |
| 3069 | administrators verify their Exim and AV scanner configuration. |
| 3070 | |
| 3071 | .vitem &%-bnq%& |
| 3072 | .oindex "&%-bnq%&" |
| 3073 | .cindex "address qualification, suppressing" |
| 3074 | By default, Exim automatically qualifies unqualified addresses (those |
| 3075 | without domains) that appear in messages that are submitted locally (that |
| 3076 | is, not over TCP/IP). This qualification applies both to addresses in |
| 3077 | envelopes, and addresses in header lines. Sender addresses are qualified using |
| 3078 | &%qualify_domain%&, and recipient addresses using &%qualify_recipient%& (which |
| 3079 | defaults to the value of &%qualify_domain%&). |
| 3080 | |
| 3081 | Sometimes, qualification is not wanted. For example, if &%-bS%& (batch SMTP) is |
| 3082 | being used to re-submit messages that originally came from remote hosts after |
| 3083 | content scanning, you probably do not want to qualify unqualified addresses in |
| 3084 | header lines. (Such lines will be present only if you have not enabled a header |
| 3085 | syntax check in the appropriate ACL.) |
| 3086 | |
| 3087 | The &%-bnq%& option suppresses all qualification of unqualified addresses in |
| 3088 | messages that originate on the local host. When this is used, unqualified |
| 3089 | addresses in the envelope provoke errors (causing message rejection) and |
| 3090 | unqualified addresses in header lines are left alone. |
| 3091 | |
| 3092 | |
| 3093 | .vitem &%-bP%& |
| 3094 | .oindex "&%-bP%&" |
| 3095 | .cindex "configuration options" "extracting" |
| 3096 | .cindex "options" "configuration &-- extracting" |
| 3097 | If this option is given with no arguments, it causes the values of all Exim's |
| 3098 | main configuration options to be written to the standard output. The values |
| 3099 | of one or more specific options can be requested by giving their names as |
| 3100 | arguments, for example: |
| 3101 | .code |
| 3102 | exim -bP qualify_domain hold_domains |
| 3103 | .endd |
| 3104 | .cindex "hiding configuration option values" |
| 3105 | .cindex "configuration options" "hiding value of" |
| 3106 | .cindex "options" "hiding value of" |
| 3107 | However, any option setting that is preceded by the word &"hide"& in the |
| 3108 | configuration file is not shown in full, except to an admin user. For other |
| 3109 | users, the output is as in this example: |
| 3110 | .code |
| 3111 | mysql_servers = <value not displayable> |
| 3112 | .endd |
| 3113 | If &%configure_file%& is given as an argument, the name of the run time |
| 3114 | configuration file is output. |
| 3115 | If a list of configuration files was supplied, the value that is output here |
| 3116 | is the name of the file that was actually used. |
| 3117 | |
| 3118 | .cindex "options" "hiding name of" |
| 3119 | If the &%-n%& flag is given, then for most modes of &%-bP%& operation the |
| 3120 | name will not be output. |
| 3121 | |
| 3122 | .cindex "daemon" "process id (pid)" |
| 3123 | .cindex "pid (process id)" "of daemon" |
| 3124 | If &%log_file_path%& or &%pid_file_path%& are given, the names of the |
| 3125 | directories where log files and daemon pid files are written are output, |
| 3126 | respectively. If these values are unset, log files are written in a |
| 3127 | sub-directory of the spool directory called &%log%&, and the pid file is |
| 3128 | written directly into the spool directory. |
| 3129 | |
| 3130 | If &%-bP%& is followed by a name preceded by &`+`&, for example, |
| 3131 | .code |
| 3132 | exim -bP +local_domains |
| 3133 | .endd |
| 3134 | it searches for a matching named list of any type (domain, host, address, or |
| 3135 | local part) and outputs what it finds. |
| 3136 | |
| 3137 | .cindex "options" "router &-- extracting" |
| 3138 | .cindex "options" "transport &-- extracting" |
| 3139 | .cindex "options" "authenticator &-- extracting" |
| 3140 | If one of the words &%router%&, &%transport%&, or &%authenticator%& is given, |
| 3141 | followed by the name of an appropriate driver instance, the option settings for |
| 3142 | that driver are output. For example: |
| 3143 | .code |
| 3144 | exim -bP transport local_delivery |
| 3145 | .endd |
| 3146 | The generic driver options are output first, followed by the driver's private |
| 3147 | options. A list of the names of drivers of a particular type can be obtained by |
| 3148 | using one of the words &%router_list%&, &%transport_list%&, or |
| 3149 | &%authenticator_list%&, and a complete list of all drivers with their option |
| 3150 | settings can be obtained by using &%routers%&, &%transports%&, or |
| 3151 | &%authenticators%&. |
| 3152 | |
| 3153 | .cindex "options" "macro &-- extracting" |
| 3154 | If invoked by an admin user, then &%macro%&, &%macro_list%& and &%macros%& |
| 3155 | are available, similarly to the drivers. Because macros are sometimes used |
| 3156 | for storing passwords, this option is restricted. |
| 3157 | The output format is one item per line. |
| 3158 | |
| 3159 | .vitem &%-bp%& |
| 3160 | .oindex "&%-bp%&" |
| 3161 | .cindex "queue" "listing messages on" |
| 3162 | .cindex "listing" "messages on the queue" |
| 3163 | This option requests a listing of the contents of the mail queue on the |
| 3164 | standard output. If the &%-bp%& option is followed by a list of message ids, |
| 3165 | just those messages are listed. By default, this option can be used only by an |
| 3166 | admin user. However, the &%queue_list_requires_admin%& option can be set false |
| 3167 | to allow any user to see the queue. |
| 3168 | |
| 3169 | Each message on the queue is displayed as in the following example: |
| 3170 | .code |
| 3171 | 25m 2.9K 0t5C6f-0000c8-00 <alice@wonderland.fict.example> |
| 3172 | red.king@looking-glass.fict.example |
| 3173 | <other addresses> |
| 3174 | .endd |
| 3175 | .cindex "message" "size in queue listing" |
| 3176 | .cindex "size" "of message" |
| 3177 | The first line contains the length of time the message has been on the queue |
| 3178 | (in this case 25 minutes), the size of the message (2.9K), the unique local |
| 3179 | identifier for the message, and the message sender, as contained in the |
| 3180 | envelope. For bounce messages, the sender address is empty, and appears as |
| 3181 | &"<>"&. If the message was submitted locally by an untrusted user who overrode |
| 3182 | the default sender address, the user's login name is shown in parentheses |
| 3183 | before the sender address. |
| 3184 | |
| 3185 | .cindex "frozen messages" "in queue listing" |
| 3186 | If the message is frozen (attempts to deliver it are suspended) then the text |
| 3187 | &"*** frozen ***"& is displayed at the end of this line. |
| 3188 | |
| 3189 | The recipients of the message (taken from the envelope, not the headers) are |
| 3190 | displayed on subsequent lines. Those addresses to which the message has already |
| 3191 | been delivered are marked with the letter D. If an original address gets |
| 3192 | expanded into several addresses via an alias or forward file, the original is |
| 3193 | displayed with a D only when deliveries for all of its child addresses are |
| 3194 | complete. |
| 3195 | |
| 3196 | |
| 3197 | .vitem &%-bpa%& |
| 3198 | .oindex "&%-bpa%&" |
| 3199 | This option operates like &%-bp%&, but in addition it shows delivered addresses |
| 3200 | that were generated from the original top level address(es) in each message by |
| 3201 | alias or forwarding operations. These addresses are flagged with &"+D"& instead |
| 3202 | of just &"D"&. |
| 3203 | |
| 3204 | |
| 3205 | .vitem &%-bpc%& |
| 3206 | .oindex "&%-bpc%&" |
| 3207 | .cindex "queue" "count of messages on" |
| 3208 | This option counts the number of messages on the queue, and writes the total |
| 3209 | to the standard output. It is restricted to admin users, unless |
| 3210 | &%queue_list_requires_admin%& is set false. |
| 3211 | |
| 3212 | |
| 3213 | .vitem &%-bpr%& |
| 3214 | .oindex "&%-bpr%&" |
| 3215 | This option operates like &%-bp%&, but the output is not sorted into |
| 3216 | chronological order of message arrival. This can speed it up when there are |
| 3217 | lots of messages on the queue, and is particularly useful if the output is |
| 3218 | going to be post-processed in a way that doesn't need the sorting. |
| 3219 | |
| 3220 | .vitem &%-bpra%& |
| 3221 | .oindex "&%-bpra%&" |
| 3222 | This option is a combination of &%-bpr%& and &%-bpa%&. |
| 3223 | |
| 3224 | .vitem &%-bpru%& |
| 3225 | .oindex "&%-bpru%&" |
| 3226 | This option is a combination of &%-bpr%& and &%-bpu%&. |
| 3227 | |
| 3228 | |
| 3229 | .vitem &%-bpu%& |
| 3230 | .oindex "&%-bpu%&" |
| 3231 | This option operates like &%-bp%& but shows only undelivered top-level |
| 3232 | addresses for each message displayed. Addresses generated by aliasing or |
| 3233 | forwarding are not shown, unless the message was deferred after processing by a |
| 3234 | router with the &%one_time%& option set. |
| 3235 | |
| 3236 | |
| 3237 | .vitem &%-brt%& |
| 3238 | .oindex "&%-brt%&" |
| 3239 | .cindex "testing" "retry configuration" |
| 3240 | .cindex "retry" "configuration testing" |
| 3241 | This option is for testing retry rules, and it must be followed by up to three |
| 3242 | arguments. It causes Exim to look for a retry rule that matches the values |
| 3243 | and to write it to the standard output. For example: |
| 3244 | .code |
| 3245 | exim -brt bach.comp.mus.example |
| 3246 | Retry rule: *.comp.mus.example F,2h,15m; F,4d,30m; |
| 3247 | .endd |
| 3248 | See chapter &<<CHAPretry>>& for a description of Exim's retry rules. The first |
| 3249 | argument, which is required, can be a complete address in the form |
| 3250 | &'local_part@domain'&, or it can be just a domain name. If the second argument |
| 3251 | contains a dot, it is interpreted as an optional second domain name; if no |
| 3252 | retry rule is found for the first argument, the second is tried. This ties in |
| 3253 | with Exim's behaviour when looking for retry rules for remote hosts &-- if no |
| 3254 | rule is found that matches the host, one that matches the mail domain is |
| 3255 | sought. Finally, an argument that is the name of a specific delivery error, as |
| 3256 | used in setting up retry rules, can be given. For example: |
| 3257 | .code |
| 3258 | exim -brt haydn.comp.mus.example quota_3d |
| 3259 | Retry rule: *@haydn.comp.mus.example quota_3d F,1h,15m |
| 3260 | .endd |
| 3261 | |
| 3262 | .vitem &%-brw%& |
| 3263 | .oindex "&%-brw%&" |
| 3264 | .cindex "testing" "rewriting" |
| 3265 | .cindex "rewriting" "testing" |
| 3266 | This option is for testing address rewriting rules, and it must be followed by |
| 3267 | a single argument, consisting of either a local part without a domain, or a |
| 3268 | complete address with a fully qualified domain. Exim outputs how this address |
| 3269 | would be rewritten for each possible place it might appear. See chapter |
| 3270 | &<<CHAPrewrite>>& for further details. |
| 3271 | |
| 3272 | .vitem &%-bS%& |
| 3273 | .oindex "&%-bS%&" |
| 3274 | .cindex "SMTP" "batched incoming" |
| 3275 | .cindex "batched SMTP input" |
| 3276 | This option is used for batched SMTP input, which is an alternative interface |
| 3277 | for non-interactive local message submission. A number of messages can be |
| 3278 | submitted in a single run. However, despite its name, this is not really SMTP |
| 3279 | input. Exim reads each message's envelope from SMTP commands on the standard |
| 3280 | input, but generates no responses. If the caller is trusted, or |
| 3281 | &%untrusted_set_sender%& is set, the senders in the SMTP MAIL commands are |
| 3282 | believed; otherwise the sender is always the caller of Exim. |
| 3283 | |
| 3284 | The message itself is read from the standard input, in SMTP format (leading |
| 3285 | dots doubled), terminated by a line containing just a single dot. An error is |
| 3286 | provoked if the terminating dot is missing. A further message may then follow. |
| 3287 | |
| 3288 | As for other local message submissions, the contents of incoming batch SMTP |
| 3289 | messages can be checked using the non-SMTP ACL (see chapter &<<CHAPACL>>&). |
| 3290 | Unqualified addresses are automatically qualified using &%qualify_domain%& and |
| 3291 | &%qualify_recipient%&, as appropriate, unless the &%-bnq%& option is used. |
| 3292 | |
| 3293 | Some other SMTP commands are recognized in the input. HELO and EHLO act |
| 3294 | as RSET; VRFY, EXPN, ETRN, and HELP act as NOOP; |
| 3295 | QUIT quits, ignoring the rest of the standard input. |
| 3296 | |
| 3297 | .cindex "return code" "for &%-bS%&" |
| 3298 | If any error is encountered, reports are written to the standard output and |
| 3299 | error streams, and Exim gives up immediately. The return code is 0 if no error |
| 3300 | was detected; it is 1 if one or more messages were accepted before the error |
| 3301 | was detected; otherwise it is 2. |
| 3302 | |
| 3303 | More details of input using batched SMTP are given in section |
| 3304 | &<<SECTincomingbatchedSMTP>>&. |
| 3305 | |
| 3306 | .vitem &%-bs%& |
| 3307 | .oindex "&%-bs%&" |
| 3308 | .cindex "SMTP" "local input" |
| 3309 | .cindex "local SMTP input" |
| 3310 | This option causes Exim to accept one or more messages by reading SMTP commands |
| 3311 | on the standard input, and producing SMTP replies on the standard output. SMTP |
| 3312 | policy controls, as defined in ACLs (see chapter &<<CHAPACL>>&) are applied. |
| 3313 | Some user agents use this interface as a way of passing locally-generated |
| 3314 | messages to the MTA. |
| 3315 | |
| 3316 | In |
| 3317 | .cindex "sender" "source of" |
| 3318 | this usage, if the caller of Exim is trusted, or &%untrusted_set_sender%& is |
| 3319 | set, the senders of messages are taken from the SMTP MAIL commands. |
| 3320 | Otherwise the content of these commands is ignored and the sender is set up as |
| 3321 | the calling user. Unqualified addresses are automatically qualified using |
| 3322 | &%qualify_domain%& and &%qualify_recipient%&, as appropriate, unless the |
| 3323 | &%-bnq%& option is used. |
| 3324 | |
| 3325 | .cindex "inetd" |
| 3326 | The |
| 3327 | &%-bs%& option is also used to run Exim from &'inetd'&, as an alternative to |
| 3328 | using a listening daemon. Exim can distinguish the two cases by checking |
| 3329 | whether the standard input is a TCP/IP socket. When Exim is called from |
| 3330 | &'inetd'&, the source of the mail is assumed to be remote, and the comments |
| 3331 | above concerning senders and qualification do not apply. In this situation, |
| 3332 | Exim behaves in exactly the same way as it does when receiving a message via |
| 3333 | the listening daemon. |
| 3334 | |
| 3335 | .vitem &%-bt%& |
| 3336 | .oindex "&%-bt%&" |
| 3337 | .cindex "testing" "addresses" |
| 3338 | .cindex "address" "testing" |
| 3339 | This option runs Exim in address testing mode, in which each argument is taken |
| 3340 | as a recipient address to be tested for deliverability. The results are |
| 3341 | written to the standard output. If a test fails, and the caller is not an admin |
| 3342 | user, no details of the failure are output, because these might contain |
| 3343 | sensitive information such as usernames and passwords for database lookups. |
| 3344 | |
| 3345 | If no arguments are given, Exim runs in an interactive manner, prompting with a |
| 3346 | right angle bracket for addresses to be tested. |
| 3347 | |
| 3348 | Unlike the &%-be%& test option, you cannot arrange for Exim to use the |
| 3349 | &[readline()]& function, because it is running as &'root'& and there are |
| 3350 | security issues. |
| 3351 | |
| 3352 | Each address is handled as if it were the recipient address of a message |
| 3353 | (compare the &%-bv%& option). It is passed to the routers and the result is |
| 3354 | written to the standard output. However, any router that has |
| 3355 | &%no_address_test%& set is bypassed. This can make &%-bt%& easier to use for |
| 3356 | genuine routing tests if your first router passes everything to a scanner |
| 3357 | program. |
| 3358 | |
| 3359 | .cindex "return code" "for &%-bt%&" |
| 3360 | The return code is 2 if any address failed outright; it is 1 if no address |
| 3361 | failed outright but at least one could not be resolved for some reason. Return |
| 3362 | code 0 is given only when all addresses succeed. |
| 3363 | |
| 3364 | .cindex "duplicate addresses" |
| 3365 | &*Note*&: When actually delivering a message, Exim removes duplicate recipient |
| 3366 | addresses after routing is complete, so that only one delivery takes place. |
| 3367 | This does not happen when testing with &%-bt%&; the full results of routing are |
| 3368 | always shown. |
| 3369 | |
| 3370 | &*Warning*&: &%-bt%& can only do relatively simple testing. If any of the |
| 3371 | routers in the configuration makes any tests on the sender address of a |
| 3372 | message, |
| 3373 | .oindex "&%-f%&" "for address testing" |
| 3374 | you can use the &%-f%& option to set an appropriate sender when running |
| 3375 | &%-bt%& tests. Without it, the sender is assumed to be the calling user at the |
| 3376 | default qualifying domain. However, if you have set up (for example) routers |
| 3377 | whose behaviour depends on the contents of an incoming message, you cannot test |
| 3378 | those conditions using &%-bt%&. The &%-N%& option provides a possible way of |
| 3379 | doing such tests. |
| 3380 | |
| 3381 | .vitem &%-bV%& |
| 3382 | .oindex "&%-bV%&" |
| 3383 | .cindex "version number of Exim" |
| 3384 | This option causes Exim to write the current version number, compilation |
| 3385 | number, and compilation date of the &'exim'& binary to the standard output. |
| 3386 | It also lists the DBM library that is being used, the optional modules (such as |
| 3387 | specific lookup types), the drivers that are included in the binary, and the |
| 3388 | name of the run time configuration file that is in use. |
| 3389 | |
| 3390 | As part of its operation, &%-bV%& causes Exim to read and syntax check its |
| 3391 | configuration file. However, this is a static check only. It cannot check |
| 3392 | values that are to be expanded. For example, although a misspelt ACL verb is |
| 3393 | detected, an error in the verb's arguments is not. You cannot rely on &%-bV%& |
| 3394 | alone to discover (for example) all the typos in the configuration; some |
| 3395 | realistic testing is needed. The &%-bh%& and &%-N%& options provide more |
| 3396 | dynamic testing facilities. |
| 3397 | |
| 3398 | .vitem &%-bv%& |
| 3399 | .oindex "&%-bv%&" |
| 3400 | .cindex "verifying address" "using &%-bv%&" |
| 3401 | .cindex "address" "verification" |
| 3402 | This option runs Exim in address verification mode, in which each argument is |
| 3403 | taken as a recipient address to be verified by the routers. (This does |
| 3404 | not involve any verification callouts). During normal operation, verification |
| 3405 | happens mostly as a consequence processing a &%verify%& condition in an ACL |
| 3406 | (see chapter &<<CHAPACL>>&). If you want to test an entire ACL, possibly |
| 3407 | including callouts, see the &%-bh%& and &%-bhc%& options. |
| 3408 | |
| 3409 | If verification fails, and the caller is not an admin user, no details of the |
| 3410 | failure are output, because these might contain sensitive information such as |
| 3411 | usernames and passwords for database lookups. |
| 3412 | |
| 3413 | If no arguments are given, Exim runs in an interactive manner, prompting with a |
| 3414 | right angle bracket for addresses to be verified. |
| 3415 | |
| 3416 | Unlike the &%-be%& test option, you cannot arrange for Exim to use the |
| 3417 | &[readline()]& function, because it is running as &'exim'& and there are |
| 3418 | security issues. |
| 3419 | |
| 3420 | Verification differs from address testing (the &%-bt%& option) in that routers |
| 3421 | that have &%no_verify%& set are skipped, and if the address is accepted by a |
| 3422 | router that has &%fail_verify%& set, verification fails. The address is |
| 3423 | verified as a recipient if &%-bv%& is used; to test verification for a sender |
| 3424 | address, &%-bvs%& should be used. |
| 3425 | |
| 3426 | If the &%-v%& option is not set, the output consists of a single line for each |
| 3427 | address, stating whether it was verified or not, and giving a reason in the |
| 3428 | latter case. Without &%-v%&, generating more than one address by redirection |
| 3429 | causes verification to end successfully, without considering the generated |
| 3430 | addresses. However, if just one address is generated, processing continues, |
| 3431 | and the generated address must verify successfully for the overall verification |
| 3432 | to succeed. |
| 3433 | |
| 3434 | When &%-v%& is set, more details are given of how the address has been handled, |
| 3435 | and in the case of address redirection, all the generated addresses are also |
| 3436 | considered. Verification may succeed for some and fail for others. |
| 3437 | |
| 3438 | The |
| 3439 | .cindex "return code" "for &%-bv%&" |
| 3440 | return code is 2 if any address failed outright; it is 1 if no address |
| 3441 | failed outright but at least one could not be resolved for some reason. Return |
| 3442 | code 0 is given only when all addresses succeed. |
| 3443 | |
| 3444 | If any of the routers in the configuration makes any tests on the sender |
| 3445 | address of a message, you should use the &%-f%& option to set an appropriate |
| 3446 | sender when running &%-bv%& tests. Without it, the sender is assumed to be the |
| 3447 | calling user at the default qualifying domain. |
| 3448 | |
| 3449 | .vitem &%-bvs%& |
| 3450 | .oindex "&%-bvs%&" |
| 3451 | This option acts like &%-bv%&, but verifies the address as a sender rather |
| 3452 | than a recipient address. This affects any rewriting and qualification that |
| 3453 | might happen. |
| 3454 | |
| 3455 | .vitem &%-bw%& |
| 3456 | .oindex "&%-bw%&" |
| 3457 | .cindex "daemon" |
| 3458 | .cindex "inetd" |
| 3459 | .cindex "inetd" "wait mode" |
| 3460 | This option runs Exim as a daemon, awaiting incoming SMTP connections, |
| 3461 | similarly to the &%-bd%& option. All port specifications on the command-line |
| 3462 | and in the configuration file are ignored. Queue-running may not be specified. |
| 3463 | |
| 3464 | In this mode, Exim expects to be passed a socket as fd 0 (stdin) which is |
| 3465 | listening for connections. This permits the system to start up and have |
| 3466 | inetd (or equivalent) listen on the SMTP ports, starting an Exim daemon for |
| 3467 | each port only when the first connection is received. |
| 3468 | |
| 3469 | If the option is given as &%-bw%&<&'time'&> then the time is a timeout, after |
| 3470 | which the daemon will exit, which should cause inetd to listen once more. |
| 3471 | |
| 3472 | .vitem &%-C%&&~<&'filelist'&> |
| 3473 | .oindex "&%-C%&" |
| 3474 | .cindex "configuration file" "alternate" |
| 3475 | .cindex "CONFIGURE_FILE" |
| 3476 | .cindex "alternate configuration file" |
| 3477 | This option causes Exim to find the run time configuration file from the given |
| 3478 | list instead of from the list specified by the CONFIGURE_FILE |
| 3479 | compile-time setting. Usually, the list will consist of just a single file |
| 3480 | name, but it can be a colon-separated list of names. In this case, the first |
| 3481 | file that exists is used. Failure to open an existing file stops Exim from |
| 3482 | proceeding any further along the list, and an error is generated. |
| 3483 | |
| 3484 | When this option is used by a caller other than root, and the list is different |
| 3485 | from the compiled-in list, Exim gives up its root privilege immediately, and |
| 3486 | runs with the real and effective uid and gid set to those of the caller. |
| 3487 | However, if a TRUSTED_CONFIG_LIST file is defined in &_Local/Makefile_&, that |
| 3488 | file contains a list of full pathnames, one per line, for configuration files |
| 3489 | which are trusted. Root privilege is retained for any configuration file so |
| 3490 | listed, as long as the caller is the Exim user (or the user specified in the |
| 3491 | CONFIGURE_OWNER option, if any), and as long as the configuration file is |
| 3492 | not writeable by inappropriate users or groups. |
| 3493 | |
| 3494 | Leaving TRUSTED_CONFIG_LIST unset precludes the possibility of testing a |
| 3495 | configuration using &%-C%& right through message reception and delivery, |
| 3496 | even if the caller is root. The reception works, but by that time, Exim is |
| 3497 | running as the Exim user, so when it re-executes to regain privilege for the |
| 3498 | delivery, the use of &%-C%& causes privilege to be lost. However, root can |
| 3499 | test reception and delivery using two separate commands (one to put a message |
| 3500 | on the queue, using &%-odq%&, and another to do the delivery, using &%-M%&). |
| 3501 | |
| 3502 | If ALT_CONFIG_PREFIX is defined &_in Local/Makefile_&, it specifies a |
| 3503 | prefix string with which any file named in a &%-C%& command line option |
| 3504 | must start. In addition, the file name must not contain the sequence &`/../`&. |
| 3505 | However, if the value of the &%-C%& option is identical to the value of |
| 3506 | CONFIGURE_FILE in &_Local/Makefile_&, Exim ignores &%-C%& and proceeds as |
| 3507 | usual. There is no default setting for ALT_CONFIG_PREFIX; when it is |
| 3508 | unset, any file name can be used with &%-C%&. |
| 3509 | |
| 3510 | ALT_CONFIG_PREFIX can be used to confine alternative configuration files |
| 3511 | to a directory to which only root has access. This prevents someone who has |
| 3512 | broken into the Exim account from running a privileged Exim with an arbitrary |
| 3513 | configuration file. |
| 3514 | |
| 3515 | The &%-C%& facility is useful for ensuring that configuration files are |
| 3516 | syntactically correct, but cannot be used for test deliveries, unless the |
| 3517 | caller is privileged, or unless it is an exotic configuration that does not |
| 3518 | require privilege. No check is made on the owner or group of the files |
| 3519 | specified by this option. |
| 3520 | |
| 3521 | |
| 3522 | .vitem &%-D%&<&'macro'&>=<&'value'&> |
| 3523 | .oindex "&%-D%&" |
| 3524 | .cindex "macro" "setting on command line" |
| 3525 | This option can be used to override macro definitions in the configuration file |
| 3526 | (see section &<<SECTmacrodefs>>&). However, like &%-C%&, if it is used by an |
| 3527 | unprivileged caller, it causes Exim to give up its root privilege. |
| 3528 | If DISABLE_D_OPTION is defined in &_Local/Makefile_&, the use of &%-D%& is |
| 3529 | completely disabled, and its use causes an immediate error exit. |
| 3530 | |
| 3531 | If WHITELIST_D_MACROS is defined in &_Local/Makefile_& then it should be a |
| 3532 | colon-separated list of macros which are considered safe and, if &%-D%& only |
| 3533 | supplies macros from this list, and the values are acceptable, then Exim will |
| 3534 | not give up root privilege if the caller is root, the Exim run-time user, or |
| 3535 | the CONFIGURE_OWNER, if set. This is a transition mechanism and is expected |
| 3536 | to be removed in the future. Acceptable values for the macros satisfy the |
| 3537 | regexp: &`^[A-Za-z0-9_/.-]*$`& |
| 3538 | |
| 3539 | The entire option (including equals sign if present) must all be within one |
| 3540 | command line item. &%-D%& can be used to set the value of a macro to the empty |
| 3541 | string, in which case the equals sign is optional. These two commands are |
| 3542 | synonymous: |
| 3543 | .code |
| 3544 | exim -DABC ... |
| 3545 | exim -DABC= ... |
| 3546 | .endd |
| 3547 | To include spaces in a macro definition item, quotes must be used. If you use |
| 3548 | quotes, spaces are permitted around the macro name and the equals sign. For |
| 3549 | example: |
| 3550 | .code |
| 3551 | exim '-D ABC = something' ... |
| 3552 | .endd |
| 3553 | &%-D%& may be repeated up to 10 times on a command line. |
| 3554 | |
| 3555 | |
| 3556 | .vitem &%-d%&<&'debug&~options'&> |
| 3557 | .oindex "&%-d%&" |
| 3558 | .cindex "debugging" "list of selectors" |
| 3559 | .cindex "debugging" "&%-d%& option" |
| 3560 | This option causes debugging information to be written to the standard |
| 3561 | error stream. It is restricted to admin users because debugging output may show |
| 3562 | database queries that contain password information. Also, the details of users' |
| 3563 | filter files should be protected. If a non-admin user uses &%-d%&, Exim |
| 3564 | writes an error message to the standard error stream and exits with a non-zero |
| 3565 | return code. |
| 3566 | |
| 3567 | When &%-d%& is used, &%-v%& is assumed. If &%-d%& is given on its own, a lot of |
| 3568 | standard debugging data is output. This can be reduced, or increased to include |
| 3569 | some more rarely needed information, by directly following &%-d%& with a string |
| 3570 | made up of names preceded by plus or minus characters. These add or remove sets |
| 3571 | of debugging data, respectively. For example, &%-d+filter%& adds filter |
| 3572 | debugging, whereas &%-d-all+filter%& selects only filter debugging. Note that |
| 3573 | no spaces are allowed in the debug setting. The available debugging categories |
| 3574 | are: |
| 3575 | .display |
| 3576 | &`acl `& ACL interpretation |
| 3577 | &`auth `& authenticators |
| 3578 | &`deliver `& general delivery logic |
| 3579 | &`dns `& DNS lookups (see also resolver) |
| 3580 | &`dnsbl `& DNS black list (aka RBL) code |
| 3581 | &`exec `& arguments for &[execv()]& calls |
| 3582 | &`expand `& detailed debugging for string expansions |
| 3583 | &`filter `& filter handling |
| 3584 | &`hints_lookup `& hints data lookups |
| 3585 | &`host_lookup `& all types of name-to-IP address handling |
| 3586 | &`ident `& ident lookup |
| 3587 | &`interface `& lists of local interfaces |
| 3588 | &`lists `& matching things in lists |
| 3589 | &`load `& system load checks |
| 3590 | &`local_scan `& can be used by &[local_scan()]& (see chapter &&& |
| 3591 | &<<CHAPlocalscan>>&) |
| 3592 | &`lookup `& general lookup code and all lookups |
| 3593 | &`memory `& memory handling |
| 3594 | &`pid `& add pid to debug output lines |
| 3595 | &`process_info `& setting info for the process log |
| 3596 | &`queue_run `& queue runs |
| 3597 | &`receive `& general message reception logic |
| 3598 | &`resolver `& turn on the DNS resolver's debugging output |
| 3599 | &`retry `& retry handling |
| 3600 | &`rewrite `& address rewriting |
| 3601 | &`route `& address routing |
| 3602 | &`timestamp `& add timestamp to debug output lines |
| 3603 | &`tls `& TLS logic |
| 3604 | &`transport `& transports |
| 3605 | &`uid `& changes of uid/gid and looking up uid/gid |
| 3606 | &`verify `& address verification logic |
| 3607 | &`all `& almost all of the above (see below), and also &%-v%& |
| 3608 | .endd |
| 3609 | The &`all`& option excludes &`memory`& when used as &`+all`&, but includes it |
| 3610 | for &`-all`&. The reason for this is that &`+all`& is something that people |
| 3611 | tend to use when generating debug output for Exim maintainers. If &`+memory`& |
| 3612 | is included, an awful lot of output that is very rarely of interest is |
| 3613 | generated, so it now has to be explicitly requested. However, &`-all`& does |
| 3614 | turn everything off. |
| 3615 | |
| 3616 | .cindex "resolver, debugging output" |
| 3617 | .cindex "DNS resolver, debugging output" |
| 3618 | The &`resolver`& option produces output only if the DNS resolver was compiled |
| 3619 | with DEBUG enabled. This is not the case in some operating systems. Also, |
| 3620 | unfortunately, debugging output from the DNS resolver is written to stdout |
| 3621 | rather than stderr. |
| 3622 | |
| 3623 | The default (&%-d%& with no argument) omits &`expand`&, &`filter`&, |
| 3624 | &`interface`&, &`load`&, &`memory`&, &`pid`&, &`resolver`&, and &`timestamp`&. |
| 3625 | However, the &`pid`& selector is forced when debugging is turned on for a |
| 3626 | daemon, which then passes it on to any re-executed Exims. Exim also |
| 3627 | automatically adds the pid to debug lines when several remote deliveries are |
| 3628 | run in parallel. |
| 3629 | |
| 3630 | The &`timestamp`& selector causes the current time to be inserted at the start |
| 3631 | of all debug output lines. This can be useful when trying to track down delays |
| 3632 | in processing. |
| 3633 | |
| 3634 | If the &%debug_print%& option is set in any driver, it produces output whenever |
| 3635 | any debugging is selected, or if &%-v%& is used. |
| 3636 | |
| 3637 | .vitem &%-dd%&<&'debug&~options'&> |
| 3638 | .oindex "&%-dd%&" |
| 3639 | This option behaves exactly like &%-d%& except when used on a command that |
| 3640 | starts a daemon process. In that case, debugging is turned off for the |
| 3641 | subprocesses that the daemon creates. Thus, it is useful for monitoring the |
| 3642 | behaviour of the daemon without creating as much output as full debugging does. |
| 3643 | |
| 3644 | .vitem &%-dropcr%& |
| 3645 | .oindex "&%-dropcr%&" |
| 3646 | This is an obsolete option that is now a no-op. It used to affect the way Exim |
| 3647 | handled CR and LF characters in incoming messages. What happens now is |
| 3648 | described in section &<<SECTlineendings>>&. |
| 3649 | |
| 3650 | .vitem &%-E%& |
| 3651 | .oindex "&%-E%&" |
| 3652 | .cindex "bounce message" "generating" |
| 3653 | This option specifies that an incoming message is a locally-generated delivery |
| 3654 | failure report. It is used internally by Exim when handling delivery failures |
| 3655 | and is not intended for external use. Its only effect is to stop Exim |
| 3656 | generating certain messages to the postmaster, as otherwise message cascades |
| 3657 | could occur in some situations. As part of the same option, a message id may |
| 3658 | follow the characters &%-E%&. If it does, the log entry for the receipt of the |
| 3659 | new message contains the id, following &"R="&, as a cross-reference. |
| 3660 | |
| 3661 | .vitem &%-e%&&'x'& |
| 3662 | .oindex "&%-e%&&'x'&" |
| 3663 | There are a number of Sendmail options starting with &%-oe%& which seem to be |
| 3664 | called by various programs without the leading &%o%& in the option. For |
| 3665 | example, the &%vacation%& program uses &%-eq%&. Exim treats all options of the |
| 3666 | form &%-e%&&'x'& as synonymous with the corresponding &%-oe%&&'x'& options. |
| 3667 | |
| 3668 | .vitem &%-F%&&~<&'string'&> |
| 3669 | .oindex "&%-F%&" |
| 3670 | .cindex "sender" "name" |
| 3671 | .cindex "name" "of sender" |
| 3672 | This option sets the sender's full name for use when a locally-generated |
| 3673 | message is being accepted. In the absence of this option, the user's &'gecos'& |
| 3674 | entry from the password data is used. As users are generally permitted to alter |
| 3675 | their &'gecos'& entries, no security considerations are involved. White space |
| 3676 | between &%-F%& and the <&'string'&> is optional. |
| 3677 | |
| 3678 | .vitem &%-f%&&~<&'address'&> |
| 3679 | .oindex "&%-f%&" |
| 3680 | .cindex "sender" "address" |
| 3681 | .cindex "address" "sender" |
| 3682 | .cindex "trusted users" |
| 3683 | .cindex "envelope sender" |
| 3684 | .cindex "user" "trusted" |
| 3685 | This option sets the address of the envelope sender of a locally-generated |
| 3686 | message (also known as the return path). The option can normally be used only |
| 3687 | by a trusted user, but &%untrusted_set_sender%& can be set to allow untrusted |
| 3688 | users to use it. |
| 3689 | |
| 3690 | Processes running as root or the Exim user are always trusted. Other |
| 3691 | trusted users are defined by the &%trusted_users%& or &%trusted_groups%& |
| 3692 | options. In the absence of &%-f%&, or if the caller is not trusted, the sender |
| 3693 | of a local message is set to the caller's login name at the default qualify |
| 3694 | domain. |
| 3695 | |
| 3696 | There is one exception to the restriction on the use of &%-f%&: an empty sender |
| 3697 | can be specified by any user, trusted or not, to create a message that can |
| 3698 | never provoke a bounce. An empty sender can be specified either as an empty |
| 3699 | string, or as a pair of angle brackets with nothing between them, as in these |
| 3700 | examples of shell commands: |
| 3701 | .code |
| 3702 | exim -f '<>' user@domain |
| 3703 | exim -f "" user@domain |
| 3704 | .endd |
| 3705 | In addition, the use of &%-f%& is not restricted when testing a filter file |
| 3706 | with &%-bf%& or when testing or verifying addresses using the &%-bt%& or |
| 3707 | &%-bv%& options. |
| 3708 | |
| 3709 | Allowing untrusted users to change the sender address does not of itself make |
| 3710 | it possible to send anonymous mail. Exim still checks that the &'From:'& header |
| 3711 | refers to the local user, and if it does not, it adds a &'Sender:'& header, |
| 3712 | though this can be overridden by setting &%no_local_from_check%&. |
| 3713 | |
| 3714 | White |
| 3715 | .cindex "&""From""& line" |
| 3716 | space between &%-f%& and the <&'address'&> is optional (that is, they can be |
| 3717 | given as two arguments or one combined argument). The sender of a |
| 3718 | locally-generated message can also be set (when permitted) by an initial |
| 3719 | &"From&~"& line in the message &-- see the description of &%-bm%& above &-- but |
| 3720 | if &%-f%& is also present, it overrides &"From&~"&. |
| 3721 | |
| 3722 | .vitem &%-G%& |
| 3723 | .oindex "&%-G%&" |
| 3724 | .cindex "submission fixups, suppressing (command-line)" |
| 3725 | This option is equivalent to an ACL applying: |
| 3726 | .code |
| 3727 | control = suppress_local_fixups |
| 3728 | .endd |
| 3729 | for every message received. Note that Sendmail will complain about such |
| 3730 | bad formatting, where Exim silently just does not fix it up. This may change |
| 3731 | in future. |
| 3732 | |
| 3733 | As this affects audit information, the caller must be a trusted user to use |
| 3734 | this option. |
| 3735 | |
| 3736 | .vitem &%-h%&&~<&'number'&> |
| 3737 | .oindex "&%-h%&" |
| 3738 | .cindex "Sendmail compatibility" "&%-h%& option ignored" |
| 3739 | This option is accepted for compatibility with Sendmail, but has no effect. (In |
| 3740 | Sendmail it overrides the &"hop count"& obtained by counting &'Received:'& |
| 3741 | headers.) |
| 3742 | |
| 3743 | .vitem &%-i%& |
| 3744 | .oindex "&%-i%&" |
| 3745 | .cindex "Solaris" "&'mail'& command" |
| 3746 | .cindex "dot" "in incoming non-SMTP message" |
| 3747 | This option, which has the same effect as &%-oi%&, specifies that a dot on a |
| 3748 | line by itself should not terminate an incoming, non-SMTP message. I can find |
| 3749 | no documentation for this option in Solaris 2.4 Sendmail, but the &'mailx'& |
| 3750 | command in Solaris 2.4 uses it. See also &%-ti%&. |
| 3751 | |
| 3752 | .vitem &%-L%&&~<&'tag'&> |
| 3753 | .oindex "&%-L%&" |
| 3754 | .cindex "syslog" "process name; set with flag" |
| 3755 | This option is equivalent to setting &%syslog_processname%& in the config |
| 3756 | file and setting &%log_file_path%& to &`syslog`&. |
| 3757 | Its use is restricted to administrators. The configuration file has to be |
| 3758 | read and parsed, to determine access rights, before this is set and takes |
| 3759 | effect, so early configuration file errors will not honour this flag. |
| 3760 | |
| 3761 | The tag should not be longer than 32 characters. |
| 3762 | |
| 3763 | .vitem &%-M%&&~<&'message&~id'&>&~<&'message&~id'&>&~... |
| 3764 | .oindex "&%-M%&" |
| 3765 | .cindex "forcing delivery" |
| 3766 | .cindex "delivery" "forcing attempt" |
| 3767 | .cindex "frozen messages" "forcing delivery" |
| 3768 | This option requests Exim to run a delivery attempt on each message in turn. If |
| 3769 | any of the messages are frozen, they are automatically thawed before the |
| 3770 | delivery attempt. The settings of &%queue_domains%&, &%queue_smtp_domains%&, |
| 3771 | and &%hold_domains%& are ignored. |
| 3772 | |
| 3773 | Retry |
| 3774 | .cindex "hints database" "overriding retry hints" |
| 3775 | hints for any of the addresses are overridden &-- Exim tries to deliver even if |
| 3776 | the normal retry time has not yet been reached. This option requires the caller |
| 3777 | to be an admin user. However, there is an option called &%prod_requires_admin%& |
| 3778 | which can be set false to relax this restriction (and also the same requirement |
| 3779 | for the &%-q%&, &%-R%&, and &%-S%& options). |
| 3780 | |
| 3781 | The deliveries happen synchronously, that is, the original Exim process does |
| 3782 | not terminate until all the delivery attempts have finished. No output is |
| 3783 | produced unless there is a serious error. If you want to see what is happening, |
| 3784 | use the &%-v%& option as well, or inspect Exim's main log. |
| 3785 | |
| 3786 | .vitem &%-Mar%&&~<&'message&~id'&>&~<&'address'&>&~<&'address'&>&~... |
| 3787 | .oindex "&%-Mar%&" |
| 3788 | .cindex "message" "adding recipients" |
| 3789 | .cindex "recipient" "adding" |
| 3790 | This option requests Exim to add the addresses to the list of recipients of the |
| 3791 | message (&"ar"& for &"add recipients"&). The first argument must be a message |
| 3792 | id, and the remaining ones must be email addresses. However, if the message is |
| 3793 | active (in the middle of a delivery attempt), it is not altered. This option |
| 3794 | can be used only by an admin user. |
| 3795 | |
| 3796 | .vitem "&%-MC%&&~<&'transport'&>&~<&'hostname'&>&~<&'sequence&~number'&>&&& |
| 3797 | &~<&'message&~id'&>" |
| 3798 | .oindex "&%-MC%&" |
| 3799 | .cindex "SMTP" "passed connection" |
| 3800 | .cindex "SMTP" "multiple deliveries" |
| 3801 | .cindex "multiple SMTP deliveries" |
| 3802 | This option is not intended for use by external callers. It is used internally |
| 3803 | by Exim to invoke another instance of itself to deliver a waiting message using |
| 3804 | an existing SMTP connection, which is passed as the standard input. Details are |
| 3805 | given in chapter &<<CHAPSMTP>>&. This must be the final option, and the caller |
| 3806 | must be root or the Exim user in order to use it. |
| 3807 | |
| 3808 | .vitem &%-MCA%& |
| 3809 | .oindex "&%-MCA%&" |
| 3810 | This option is not intended for use by external callers. It is used internally |
| 3811 | by Exim in conjunction with the &%-MC%& option. It signifies that the |
| 3812 | connection to the remote host has been authenticated. |
| 3813 | |
| 3814 | .vitem &%-MCP%& |
| 3815 | .oindex "&%-MCP%&" |
| 3816 | This option is not intended for use by external callers. It is used internally |
| 3817 | by Exim in conjunction with the &%-MC%& option. It signifies that the server to |
| 3818 | which Exim is connected supports pipelining. |
| 3819 | |
| 3820 | .vitem &%-MCQ%&&~<&'process&~id'&>&~<&'pipe&~fd'&> |
| 3821 | .oindex "&%-MCQ%&" |
| 3822 | This option is not intended for use by external callers. It is used internally |
| 3823 | by Exim in conjunction with the &%-MC%& option when the original delivery was |
| 3824 | started by a queue runner. It passes on the process id of the queue runner, |
| 3825 | together with the file descriptor number of an open pipe. Closure of the pipe |
| 3826 | signals the final completion of the sequence of processes that are passing |
| 3827 | messages through the same SMTP connection. |
| 3828 | |
| 3829 | .vitem &%-MCS%& |
| 3830 | .oindex "&%-MCS%&" |
| 3831 | This option is not intended for use by external callers. It is used internally |
| 3832 | by Exim in conjunction with the &%-MC%& option, and passes on the fact that the |
| 3833 | SMTP SIZE option should be used on messages delivered down the existing |
| 3834 | connection. |
| 3835 | |
| 3836 | .vitem &%-MCT%& |
| 3837 | .oindex "&%-MCT%&" |
| 3838 | This option is not intended for use by external callers. It is used internally |
| 3839 | by Exim in conjunction with the &%-MC%& option, and passes on the fact that the |
| 3840 | host to which Exim is connected supports TLS encryption. |
| 3841 | |
| 3842 | .vitem &%-Mc%&&~<&'message&~id'&>&~<&'message&~id'&>&~... |
| 3843 | .oindex "&%-Mc%&" |
| 3844 | .cindex "hints database" "not overridden by &%-Mc%&" |
| 3845 | .cindex "delivery" "manually started &-- not forced" |
| 3846 | This option requests Exim to run a delivery attempt on each message in turn, |
| 3847 | but unlike the &%-M%& option, it does check for retry hints, and respects any |
| 3848 | that are found. This option is not very useful to external callers. It is |
| 3849 | provided mainly for internal use by Exim when it needs to re-invoke itself in |
| 3850 | order to regain root privilege for a delivery (see chapter &<<CHAPsecurity>>&). |
| 3851 | However, &%-Mc%& can be useful when testing, in order to run a delivery that |
| 3852 | respects retry times and other options such as &%hold_domains%& that are |
| 3853 | overridden when &%-M%& is used. Such a delivery does not count as a queue run. |
| 3854 | If you want to run a specific delivery as if in a queue run, you should use |
| 3855 | &%-q%& with a message id argument. A distinction between queue run deliveries |
| 3856 | and other deliveries is made in one or two places. |
| 3857 | |
| 3858 | .vitem &%-Mes%&&~<&'message&~id'&>&~<&'address'&> |
| 3859 | .oindex "&%-Mes%&" |
| 3860 | .cindex "message" "changing sender" |
| 3861 | .cindex "sender" "changing" |
| 3862 | This option requests Exim to change the sender address in the message to the |
| 3863 | given address, which must be a fully qualified address or &"<>"& (&"es"& for |
| 3864 | &"edit sender"&). There must be exactly two arguments. The first argument must |
| 3865 | be a message id, and the second one an email address. However, if the message |
| 3866 | is active (in the middle of a delivery attempt), its status is not altered. |
| 3867 | This option can be used only by an admin user. |
| 3868 | |
| 3869 | .vitem &%-Mf%&&~<&'message&~id'&>&~<&'message&~id'&>&~... |
| 3870 | .oindex "&%-Mf%&" |
| 3871 | .cindex "freezing messages" |
| 3872 | .cindex "message" "manually freezing" |
| 3873 | This option requests Exim to mark each listed message as &"frozen"&. This |
| 3874 | prevents any delivery attempts taking place until the message is &"thawed"&, |
| 3875 | either manually or as a result of the &%auto_thaw%& configuration option. |
| 3876 | However, if any of the messages are active (in the middle of a delivery |
| 3877 | attempt), their status is not altered. This option can be used only by an admin |
| 3878 | user. |
| 3879 | |
| 3880 | .vitem &%-Mg%&&~<&'message&~id'&>&~<&'message&~id'&>&~... |
| 3881 | .oindex "&%-Mg%&" |
| 3882 | .cindex "giving up on messages" |
| 3883 | .cindex "message" "abandoning delivery attempts" |
| 3884 | .cindex "delivery" "abandoning further attempts" |
| 3885 | This option requests Exim to give up trying to deliver the listed messages, |
| 3886 | including any that are frozen. However, if any of the messages are active, |
| 3887 | their status is not altered. For non-bounce messages, a delivery error message |
| 3888 | is sent to the sender, containing the text &"cancelled by administrator"&. |
| 3889 | Bounce messages are just discarded. This option can be used only by an admin |
| 3890 | user. |
| 3891 | |
| 3892 | .vitem &%-Mmad%&&~<&'message&~id'&>&~<&'message&~id'&>&~... |
| 3893 | .oindex "&%-Mmad%&" |
| 3894 | .cindex "delivery" "cancelling all" |
| 3895 | This option requests Exim to mark all the recipient addresses in the messages |
| 3896 | as already delivered (&"mad"& for &"mark all delivered"&). However, if any |
| 3897 | message is active (in the middle of a delivery attempt), its status is not |
| 3898 | altered. This option can be used only by an admin user. |
| 3899 | |
| 3900 | .vitem &%-Mmd%&&~<&'message&~id'&>&~<&'address'&>&~<&'address'&>&~... |
| 3901 | .oindex "&%-Mmd%&" |
| 3902 | .cindex "delivery" "cancelling by address" |
| 3903 | .cindex "recipient" "removing" |
| 3904 | .cindex "removing recipients" |
| 3905 | This option requests Exim to mark the given addresses as already delivered |
| 3906 | (&"md"& for &"mark delivered"&). The first argument must be a message id, and |
| 3907 | the remaining ones must be email addresses. These are matched to recipient |
| 3908 | addresses in the message in a case-sensitive manner. If the message is active |
| 3909 | (in the middle of a delivery attempt), its status is not altered. This option |
| 3910 | can be used only by an admin user. |
| 3911 | |
| 3912 | .vitem &%-Mrm%&&~<&'message&~id'&>&~<&'message&~id'&>&~... |
| 3913 | .oindex "&%-Mrm%&" |
| 3914 | .cindex "removing messages" |
| 3915 | .cindex "abandoning mail" |
| 3916 | .cindex "message" "manually discarding" |
| 3917 | This option requests Exim to remove the given messages from the queue. No |
| 3918 | bounce messages are sent; each message is simply forgotten. However, if any of |
| 3919 | the messages are active, their status is not altered. This option can be used |
| 3920 | only by an admin user or by the user who originally caused the message to be |
| 3921 | placed on the queue. |
| 3922 | |
| 3923 | .vitem &%-Mset%&&~<&'message&~id'&> |
| 3924 | .oindex "&%-Mset%& |
| 3925 | .cindex "testing" "string expansion" |
| 3926 | .cindex "expansion" "testing" |
| 3927 | This option is useful only in conjunction with &%-be%& (that is, when testing |
| 3928 | string expansions). Exim loads the given message from its spool before doing |
| 3929 | the test expansions, thus setting message-specific variables such as |
| 3930 | &$message_size$& and the header variables. The &$recipients$& variable is made |
| 3931 | available. This feature is provided to make it easier to test expansions that |
| 3932 | make use of these variables. However, this option can be used only by an admin |
| 3933 | user. See also &%-bem%&. |
| 3934 | |
| 3935 | .vitem &%-Mt%&&~<&'message&~id'&>&~<&'message&~id'&>&~... |
| 3936 | .oindex "&%-Mt%&" |
| 3937 | .cindex "thawing messages" |
| 3938 | .cindex "unfreezing messages" |
| 3939 | .cindex "frozen messages" "thawing" |
| 3940 | .cindex "message" "thawing frozen" |
| 3941 | This option requests Exim to &"thaw"& any of the listed messages that are |
| 3942 | &"frozen"&, so that delivery attempts can resume. However, if any of the |
| 3943 | messages are active, their status is not altered. This option can be used only |
| 3944 | by an admin user. |
| 3945 | |
| 3946 | .vitem &%-Mvb%&&~<&'message&~id'&> |
| 3947 | .oindex "&%-Mvb%&" |
| 3948 | .cindex "listing" "message body" |
| 3949 | .cindex "message" "listing body of" |
| 3950 | This option causes the contents of the message body (-D) spool file to be |
| 3951 | written to the standard output. This option can be used only by an admin user. |
| 3952 | |
| 3953 | .vitem &%-Mvc%&&~<&'message&~id'&> |
| 3954 | .oindex "&%-Mvc%&" |
| 3955 | .cindex "message" "listing in RFC 2822 format" |
| 3956 | .cindex "listing" "message in RFC 2822 format" |
| 3957 | This option causes a copy of the complete message (header lines plus body) to |
| 3958 | be written to the standard output in RFC 2822 format. This option can be used |
| 3959 | only by an admin user. |
| 3960 | |
| 3961 | .vitem &%-Mvh%&&~<&'message&~id'&> |
| 3962 | .oindex "&%-Mvh%&" |
| 3963 | .cindex "listing" "message headers" |
| 3964 | .cindex "header lines" "listing" |
| 3965 | .cindex "message" "listing header lines" |
| 3966 | This option causes the contents of the message headers (-H) spool file to be |
| 3967 | written to the standard output. This option can be used only by an admin user. |
| 3968 | |
| 3969 | .vitem &%-Mvl%&&~<&'message&~id'&> |
| 3970 | .oindex "&%-Mvl%&" |
| 3971 | .cindex "listing" "message log" |
| 3972 | .cindex "message" "listing message log" |
| 3973 | This option causes the contents of the message log spool file to be written to |
| 3974 | the standard output. This option can be used only by an admin user. |
| 3975 | |
| 3976 | .vitem &%-m%& |
| 3977 | .oindex "&%-m%&" |
| 3978 | This is apparently a synonym for &%-om%& that is accepted by Sendmail, so Exim |
| 3979 | treats it that way too. |
| 3980 | |
| 3981 | .vitem &%-N%& |
| 3982 | .oindex "&%-N%&" |
| 3983 | .cindex "debugging" "&%-N%& option" |
| 3984 | .cindex "debugging" "suppressing delivery" |
| 3985 | This is a debugging option that inhibits delivery of a message at the transport |
| 3986 | level. It implies &%-v%&. Exim goes through many of the motions of delivery &-- |
| 3987 | it just doesn't actually transport the message, but instead behaves as if it |
| 3988 | had successfully done so. However, it does not make any updates to the retry |
| 3989 | database, and the log entries for deliveries are flagged with &"*>"& rather |
| 3990 | than &"=>"&. |
| 3991 | |
| 3992 | Because &%-N%& discards any message to which it applies, only root or the Exim |
| 3993 | user are allowed to use it with &%-bd%&, &%-q%&, &%-R%& or &%-M%&. In other |
| 3994 | words, an ordinary user can use it only when supplying an incoming message to |
| 3995 | which it will apply. Although transportation never fails when &%-N%& is set, an |
| 3996 | address may be deferred because of a configuration problem on a transport, or a |
| 3997 | routing problem. Once &%-N%& has been used for a delivery attempt, it sticks to |
| 3998 | the message, and applies to any subsequent delivery attempts that may happen |
| 3999 | for that message. |
| 4000 | |
| 4001 | .vitem &%-n%& |
| 4002 | .oindex "&%-n%&" |
| 4003 | This option is interpreted by Sendmail to mean &"no aliasing"&. |
| 4004 | For normal modes of operation, it is ignored by Exim. |
| 4005 | When combined with &%-bP%& it suppresses the name of an option from being output. |
| 4006 | |
| 4007 | .vitem &%-O%&&~<&'data'&> |
| 4008 | .oindex "&%-O%&" |
| 4009 | This option is interpreted by Sendmail to mean &`set option`&. It is ignored by |
| 4010 | Exim. |
| 4011 | |
| 4012 | .vitem &%-oA%&&~<&'file&~name'&> |
| 4013 | .oindex "&%-oA%&" |
| 4014 | .cindex "Sendmail compatibility" "&%-oA%& option" |
| 4015 | This option is used by Sendmail in conjunction with &%-bi%& to specify an |
| 4016 | alternative alias file name. Exim handles &%-bi%& differently; see the |
| 4017 | description above. |
| 4018 | |
| 4019 | .vitem &%-oB%&&~<&'n'&> |
| 4020 | .oindex "&%-oB%&" |
| 4021 | .cindex "SMTP" "passed connection" |
| 4022 | .cindex "SMTP" "multiple deliveries" |
| 4023 | .cindex "multiple SMTP deliveries" |
| 4024 | This is a debugging option which limits the maximum number of messages that can |
| 4025 | be delivered down one SMTP connection, overriding the value set in any &(smtp)& |
| 4026 | transport. If <&'n'&> is omitted, the limit is set to 1. |
| 4027 | |
| 4028 | .vitem &%-odb%& |
| 4029 | .oindex "&%-odb%&" |
| 4030 | .cindex "background delivery" |
| 4031 | .cindex "delivery" "in the background" |
| 4032 | This option applies to all modes in which Exim accepts incoming messages, |
| 4033 | including the listening daemon. It requests &"background"& delivery of such |
| 4034 | messages, which means that the accepting process automatically starts a |
| 4035 | delivery process for each message received, but does not wait for the delivery |
| 4036 | processes to finish. |
| 4037 | |
| 4038 | When all the messages have been received, the reception process exits, |
| 4039 | leaving the delivery processes to finish in their own time. The standard output |
| 4040 | and error streams are closed at the start of each delivery process. |
| 4041 | This is the default action if none of the &%-od%& options are present. |
| 4042 | |
| 4043 | If one of the queueing options in the configuration file |
| 4044 | (&%queue_only%& or &%queue_only_file%&, for example) is in effect, &%-odb%& |
| 4045 | overrides it if &%queue_only_override%& is set true, which is the default |
| 4046 | setting. If &%queue_only_override%& is set false, &%-odb%& has no effect. |
| 4047 | |
| 4048 | .vitem &%-odf%& |
| 4049 | .oindex "&%-odf%&" |
| 4050 | .cindex "foreground delivery" |
| 4051 | .cindex "delivery" "in the foreground" |
| 4052 | This option requests &"foreground"& (synchronous) delivery when Exim has |
| 4053 | accepted a locally-generated message. (For the daemon it is exactly the same as |
| 4054 | &%-odb%&.) A delivery process is automatically started to deliver the message, |
| 4055 | and Exim waits for it to complete before proceeding. |
| 4056 | |
| 4057 | The original Exim reception process does not finish until the delivery |
| 4058 | process for the final message has ended. The standard error stream is left open |
| 4059 | during deliveries. |
| 4060 | |
| 4061 | However, like &%-odb%&, this option has no effect if &%queue_only_override%& is |
| 4062 | false and one of the queueing options in the configuration file is in effect. |
| 4063 | |
| 4064 | If there is a temporary delivery error during foreground delivery, the |
| 4065 | message is left on the queue for later delivery, and the original reception |
| 4066 | process exits. See chapter &<<CHAPnonqueueing>>& for a way of setting up a |
| 4067 | restricted configuration that never queues messages. |
| 4068 | |
| 4069 | |
| 4070 | .vitem &%-odi%& |
| 4071 | .oindex "&%-odi%&" |
| 4072 | This option is synonymous with &%-odf%&. It is provided for compatibility with |
| 4073 | Sendmail. |
| 4074 | |
| 4075 | .vitem &%-odq%& |
| 4076 | .oindex "&%-odq%&" |
| 4077 | .cindex "non-immediate delivery" |
| 4078 | .cindex "delivery" "suppressing immediate" |
| 4079 | .cindex "queueing incoming messages" |
| 4080 | This option applies to all modes in which Exim accepts incoming messages, |
| 4081 | including the listening daemon. It specifies that the accepting process should |
| 4082 | not automatically start a delivery process for each message received. Messages |
| 4083 | are placed on the queue, and remain there until a subsequent queue runner |
| 4084 | process encounters them. There are several configuration options (such as |
| 4085 | &%queue_only%&) that can be used to queue incoming messages under certain |
| 4086 | conditions. This option overrides all of them and also &%-odqs%&. It always |
| 4087 | forces queueing. |
| 4088 | |
| 4089 | .vitem &%-odqs%& |
| 4090 | .oindex "&%-odqs%&" |
| 4091 | .cindex "SMTP" "delaying delivery" |
| 4092 | This option is a hybrid between &%-odb%&/&%-odi%& and &%-odq%&. |
| 4093 | However, like &%-odb%& and &%-odi%&, this option has no effect if |
| 4094 | &%queue_only_override%& is false and one of the queueing options in the |
| 4095 | configuration file is in effect. |
| 4096 | |
| 4097 | When &%-odqs%& does operate, a delivery process is started for each incoming |
| 4098 | message, in the background by default, but in the foreground if &%-odi%& is |
| 4099 | also present. The recipient addresses are routed, and local deliveries are done |
| 4100 | in the normal way. However, if any SMTP deliveries are required, they are not |
| 4101 | done at this time, so the message remains on the queue until a subsequent queue |
| 4102 | runner process encounters it. Because routing was done, Exim knows which |
| 4103 | messages are waiting for which hosts, and so a number of messages for the same |
| 4104 | host can be sent in a single SMTP connection. The &%queue_smtp_domains%& |
| 4105 | configuration option has the same effect for specific domains. See also the |
| 4106 | &%-qq%& option. |
| 4107 | |
| 4108 | .vitem &%-oee%& |
| 4109 | .oindex "&%-oee%&" |
| 4110 | .cindex "error" "reporting" |
| 4111 | If an error is detected while a non-SMTP message is being received (for |
| 4112 | example, a malformed address), the error is reported to the sender in a mail |
| 4113 | message. |
| 4114 | |
| 4115 | .cindex "return code" "for &%-oee%&" |
| 4116 | Provided |
| 4117 | this error message is successfully sent, the Exim receiving process |
| 4118 | exits with a return code of zero. If not, the return code is 2 if the problem |
| 4119 | is that the original message has no recipients, or 1 for any other error. |
| 4120 | This is the default &%-oe%&&'x'& option if Exim is called as &'rmail'&. |
| 4121 | |
| 4122 | .vitem &%-oem%& |
| 4123 | .oindex "&%-oem%&" |
| 4124 | .cindex "error" "reporting" |
| 4125 | .cindex "return code" "for &%-oem%&" |
| 4126 | This is the same as &%-oee%&, except that Exim always exits with a non-zero |
| 4127 | return code, whether or not the error message was successfully sent. |
| 4128 | This is the default &%-oe%&&'x'& option, unless Exim is called as &'rmail'&. |
| 4129 | |
| 4130 | .vitem &%-oep%& |
| 4131 | .oindex "&%-oep%&" |
| 4132 | .cindex "error" "reporting" |
| 4133 | If an error is detected while a non-SMTP message is being received, the |
| 4134 | error is reported by writing a message to the standard error file (stderr). |
| 4135 | .cindex "return code" "for &%-oep%&" |
| 4136 | The return code is 1 for all errors. |
| 4137 | |
| 4138 | .vitem &%-oeq%& |
| 4139 | .oindex "&%-oeq%&" |
| 4140 | .cindex "error" "reporting" |
| 4141 | This option is supported for compatibility with Sendmail, but has the same |
| 4142 | effect as &%-oep%&. |
| 4143 | |
| 4144 | .vitem &%-oew%& |
| 4145 | .oindex "&%-oew%&" |
| 4146 | .cindex "error" "reporting" |
| 4147 | This option is supported for compatibility with Sendmail, but has the same |
| 4148 | effect as &%-oem%&. |
| 4149 | |
| 4150 | .vitem &%-oi%& |
| 4151 | .oindex "&%-oi%&" |
| 4152 | .cindex "dot" "in incoming non-SMTP message" |
| 4153 | This option, which has the same effect as &%-i%&, specifies that a dot on a |
| 4154 | line by itself should not terminate an incoming, non-SMTP message. Otherwise, a |
| 4155 | single dot does terminate, though Exim does no special processing for other |
| 4156 | lines that start with a dot. This option is set by default if Exim is called as |
| 4157 | &'rmail'&. See also &%-ti%&. |
| 4158 | |
| 4159 | .vitem &%-oitrue%& |
| 4160 | .oindex "&%-oitrue%&" |
| 4161 | This option is treated as synonymous with &%-oi%&. |
| 4162 | |
| 4163 | .vitem &%-oMa%&&~<&'host&~address'&> |
| 4164 | .oindex "&%-oMa%&" |
| 4165 | .cindex "sender" "host address, specifying for local message" |
| 4166 | A number of options starting with &%-oM%& can be used to set values associated |
| 4167 | with remote hosts on locally-submitted messages (that is, messages not received |
| 4168 | over TCP/IP). These options can be used by any caller in conjunction with the |
| 4169 | &%-bh%&, &%-be%&, &%-bf%&, &%-bF%&, &%-bt%&, or &%-bv%& testing options. In |
| 4170 | other circumstances, they are ignored unless the caller is trusted. |
| 4171 | |
| 4172 | The &%-oMa%& option sets the sender host address. This may include a port |
| 4173 | number at the end, after a full stop (period). For example: |
| 4174 | .code |
| 4175 | exim -bs -oMa 10.9.8.7.1234 |
| 4176 | .endd |
| 4177 | An alternative syntax is to enclose the IP address in square brackets, |
| 4178 | followed by a colon and the port number: |
| 4179 | .code |
| 4180 | exim -bs -oMa [10.9.8.7]:1234 |
| 4181 | .endd |
| 4182 | The IP address is placed in the &$sender_host_address$& variable, and the |
| 4183 | port, if present, in &$sender_host_port$&. If both &%-oMa%& and &%-bh%& |
| 4184 | are present on the command line, the sender host IP address is taken from |
| 4185 | whichever one is last. |
| 4186 | |
| 4187 | .vitem &%-oMaa%&&~<&'name'&> |
| 4188 | .oindex "&%-oMaa%&" |
| 4189 | .cindex "authentication" "name, specifying for local message" |
| 4190 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMaa%& |
| 4191 | option sets the value of &$sender_host_authenticated$& (the authenticator |
| 4192 | name). See chapter &<<CHAPSMTPAUTH>>& for a discussion of SMTP authentication. |
| 4193 | This option can be used with &%-bh%& and &%-bs%& to set up an |
| 4194 | authenticated SMTP session without actually using the SMTP AUTH command. |
| 4195 | |
| 4196 | .vitem &%-oMai%&&~<&'string'&> |
| 4197 | .oindex "&%-oMai%&" |
| 4198 | .cindex "authentication" "id, specifying for local message" |
| 4199 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMai%& |
| 4200 | option sets the value of &$authenticated_id$& (the id that was authenticated). |
| 4201 | This overrides the default value (the caller's login id, except with &%-bh%&, |
| 4202 | where there is no default) for messages from local sources. See chapter |
| 4203 | &<<CHAPSMTPAUTH>>& for a discussion of authenticated ids. |
| 4204 | |
| 4205 | .vitem &%-oMas%&&~<&'address'&> |
| 4206 | .oindex "&%-oMas%&" |
| 4207 | .cindex "authentication" "sender, specifying for local message" |
| 4208 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMas%& |
| 4209 | option sets the authenticated sender value in &$authenticated_sender$&. It |
| 4210 | overrides the sender address that is created from the caller's login id for |
| 4211 | messages from local sources, except when &%-bh%& is used, when there is no |
| 4212 | default. For both &%-bh%& and &%-bs%&, an authenticated sender that is |
| 4213 | specified on a MAIL command overrides this value. See chapter |
| 4214 | &<<CHAPSMTPAUTH>>& for a discussion of authenticated senders. |
| 4215 | |
| 4216 | .vitem &%-oMi%&&~<&'interface&~address'&> |
| 4217 | .oindex "&%-oMi%&" |
| 4218 | .cindex "interface" "address, specifying for local message" |
| 4219 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMi%& |
| 4220 | option sets the IP interface address value. A port number may be included, |
| 4221 | using the same syntax as for &%-oMa%&. The interface address is placed in |
| 4222 | &$received_ip_address$& and the port number, if present, in &$received_port$&. |
| 4223 | |
| 4224 | .vitem &%-oMm%&&~<&'message&~reference'&> |
| 4225 | .oindex "&%-oMm%&" |
| 4226 | .cindex "message reference" "message reference, specifying for local message" |
| 4227 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMm%& |
| 4228 | option sets the message reference, e.g. message-id, and is logged during |
| 4229 | delivery. This is useful when some kind of audit trail is required to tie |
| 4230 | messages together. The format of the message reference is checked and will |
| 4231 | abort if the format is invalid. The option will only be accepted if exim is |
| 4232 | running in trusted mode, not as any regular user. |
| 4233 | |
| 4234 | The best example of a message reference is when Exim sends a bounce message. |
| 4235 | The message reference is the message-id of the original message for which Exim |
| 4236 | is sending the bounce. |
| 4237 | |
| 4238 | .vitem &%-oMr%&&~<&'protocol&~name'&> |
| 4239 | .oindex "&%-oMr%&" |
| 4240 | .cindex "protocol, specifying for local message" |
| 4241 | .vindex "&$received_protocol$&" |
| 4242 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMr%& |
| 4243 | option sets the received protocol value that is stored in |
| 4244 | &$received_protocol$&. However, it does not apply (and is ignored) when &%-bh%& |
| 4245 | or &%-bs%& is used. For &%-bh%&, the protocol is forced to one of the standard |
| 4246 | SMTP protocol names (see the description of &$received_protocol$& in section |
| 4247 | &<<SECTexpvar>>&). For &%-bs%&, the protocol is always &"local-"& followed by |
| 4248 | one of those same names. For &%-bS%& (batched SMTP) however, the protocol can |
| 4249 | be set by &%-oMr%&. |
| 4250 | |
| 4251 | .vitem &%-oMs%&&~<&'host&~name'&> |
| 4252 | .oindex "&%-oMs%&" |
| 4253 | .cindex "sender" "host name, specifying for local message" |
| 4254 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMs%& |
| 4255 | option sets the sender host name in &$sender_host_name$&. When this option is |
| 4256 | present, Exim does not attempt to look up a host name from an IP address; it |
| 4257 | uses the name it is given. |
| 4258 | |
| 4259 | .vitem &%-oMt%&&~<&'ident&~string'&> |
| 4260 | .oindex "&%-oMt%&" |
| 4261 | .cindex "sender" "ident string, specifying for local message" |
| 4262 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMt%& |
| 4263 | option sets the sender ident value in &$sender_ident$&. The default setting for |
| 4264 | local callers is the login id of the calling process, except when &%-bh%& is |
| 4265 | used, when there is no default. |
| 4266 | |
| 4267 | .vitem &%-om%& |
| 4268 | .oindex "&%-om%&" |
| 4269 | .cindex "Sendmail compatibility" "&%-om%& option ignored" |
| 4270 | In Sendmail, this option means &"me too"&, indicating that the sender of a |
| 4271 | message should receive a copy of the message if the sender appears in an alias |
| 4272 | expansion. Exim always does this, so the option does nothing. |
| 4273 | |
| 4274 | .vitem &%-oo%& |
| 4275 | .oindex "&%-oo%&" |
| 4276 | .cindex "Sendmail compatibility" "&%-oo%& option ignored" |
| 4277 | This option is ignored. In Sendmail it specifies &"old style headers"&, |
| 4278 | whatever that means. |
| 4279 | |
| 4280 | .vitem &%-oP%&&~<&'path'&> |
| 4281 | .oindex "&%-oP%&" |
| 4282 | .cindex "pid (process id)" "of daemon" |
| 4283 | .cindex "daemon" "process id (pid)" |
| 4284 | This option is useful only in conjunction with &%-bd%& or &%-q%& with a time |
| 4285 | value. The option specifies the file to which the process id of the daemon is |
| 4286 | written. When &%-oX%& is used with &%-bd%&, or when &%-q%& with a time is used |
| 4287 | without &%-bd%&, this is the only way of causing Exim to write a pid file, |
| 4288 | because in those cases, the normal pid file is not used. |
| 4289 | |
| 4290 | .vitem &%-or%&&~<&'time'&> |
| 4291 | .oindex "&%-or%&" |
| 4292 | .cindex "timeout" "for non-SMTP input" |
| 4293 | This option sets a timeout value for incoming non-SMTP messages. If it is not |
| 4294 | set, Exim will wait forever for the standard input. The value can also be set |
| 4295 | by the &%receive_timeout%& option. The format used for specifying times is |
| 4296 | described in section &<<SECTtimeformat>>&. |
| 4297 | |
| 4298 | .vitem &%-os%&&~<&'time'&> |
| 4299 | .oindex "&%-os%&" |
| 4300 | .cindex "timeout" "for SMTP input" |
| 4301 | .cindex "SMTP" "input timeout" |
| 4302 | This option sets a timeout value for incoming SMTP messages. The timeout |
| 4303 | applies to each SMTP command and block of data. The value can also be set by |
| 4304 | the &%smtp_receive_timeout%& option; it defaults to 5 minutes. The format used |
| 4305 | for specifying times is described in section &<<SECTtimeformat>>&. |
| 4306 | |
| 4307 | .vitem &%-ov%& |
| 4308 | .oindex "&%-ov%&" |
| 4309 | This option has exactly the same effect as &%-v%&. |
| 4310 | |
| 4311 | .vitem &%-oX%&&~<&'number&~or&~string'&> |
| 4312 | .oindex "&%-oX%&" |
| 4313 | .cindex "TCP/IP" "setting listening ports" |
| 4314 | .cindex "TCP/IP" "setting listening interfaces" |
| 4315 | .cindex "port" "receiving TCP/IP" |
| 4316 | This option is relevant only when the &%-bd%& (start listening daemon) option |
| 4317 | is also given. It controls which ports and interfaces the daemon uses. Details |
| 4318 | of the syntax, and how it interacts with configuration file options, are given |
| 4319 | in chapter &<<CHAPinterfaces>>&. When &%-oX%& is used to start a daemon, no pid |
| 4320 | file is written unless &%-oP%& is also present to specify a pid file name. |
| 4321 | |
| 4322 | .vitem &%-pd%& |
| 4323 | .oindex "&%-pd%&" |
| 4324 | .cindex "Perl" "starting the interpreter" |
| 4325 | This option applies when an embedded Perl interpreter is linked with Exim (see |
| 4326 | chapter &<<CHAPperl>>&). It overrides the setting of the &%perl_at_start%& |
| 4327 | option, forcing the starting of the interpreter to be delayed until it is |
| 4328 | needed. |
| 4329 | |
| 4330 | .vitem &%-ps%& |
| 4331 | .oindex "&%-ps%&" |
| 4332 | .cindex "Perl" "starting the interpreter" |
| 4333 | This option applies when an embedded Perl interpreter is linked with Exim (see |
| 4334 | chapter &<<CHAPperl>>&). It overrides the setting of the &%perl_at_start%& |
| 4335 | option, forcing the starting of the interpreter to occur as soon as Exim is |
| 4336 | started. |
| 4337 | |
| 4338 | .vitem &%-p%&<&'rval'&>:<&'sval'&> |
| 4339 | .oindex "&%-p%&" |
| 4340 | For compatibility with Sendmail, this option is equivalent to |
| 4341 | .display |
| 4342 | &`-oMr`& <&'rval'&> &`-oMs`& <&'sval'&> |
| 4343 | .endd |
| 4344 | It sets the incoming protocol and host name (for trusted callers). The |
| 4345 | host name and its colon can be omitted when only the protocol is to be set. |
| 4346 | Note the Exim already has two private options, &%-pd%& and &%-ps%&, that refer |
| 4347 | to embedded Perl. It is therefore impossible to set a protocol value of &`d`& |
| 4348 | or &`s`& using this option (but that does not seem a real limitation). |
| 4349 | |
| 4350 | .vitem &%-q%& |
| 4351 | .oindex "&%-q%&" |
| 4352 | .cindex "queue runner" "starting manually" |
| 4353 | This option is normally restricted to admin users. However, there is a |
| 4354 | configuration option called &%prod_requires_admin%& which can be set false to |
| 4355 | relax this restriction (and also the same requirement for the &%-M%&, &%-R%&, |
| 4356 | and &%-S%& options). |
| 4357 | |
| 4358 | .cindex "queue runner" "description of operation" |
| 4359 | The &%-q%& option starts one queue runner process. This scans the queue of |
| 4360 | waiting messages, and runs a delivery process for each one in turn. It waits |
| 4361 | for each delivery process to finish before starting the next one. A delivery |
| 4362 | process may not actually do any deliveries if the retry times for the addresses |
| 4363 | have not been reached. Use &%-qf%& (see below) if you want to override this. |
| 4364 | |
| 4365 | If |
| 4366 | .cindex "SMTP" "passed connection" |
| 4367 | .cindex "SMTP" "multiple deliveries" |
| 4368 | .cindex "multiple SMTP deliveries" |
| 4369 | the delivery process spawns other processes to deliver other messages down |
| 4370 | passed SMTP connections, the queue runner waits for these to finish before |
| 4371 | proceeding. |
| 4372 | |
| 4373 | When all the queued messages have been considered, the original queue runner |
| 4374 | process terminates. In other words, a single pass is made over the waiting |
| 4375 | mail, one message at a time. Use &%-q%& with a time (see below) if you want |
| 4376 | this to be repeated periodically. |
| 4377 | |
| 4378 | Exim processes the waiting messages in an unpredictable order. It isn't very |
| 4379 | random, but it is likely to be different each time, which is all that matters. |
| 4380 | If one particular message screws up a remote MTA, other messages to the same |
| 4381 | MTA have a chance of getting through if they get tried first. |
| 4382 | |
| 4383 | It is possible to cause the messages to be processed in lexical message id |
| 4384 | order, which is essentially the order in which they arrived, by setting the |
| 4385 | &%queue_run_in_order%& option, but this is not recommended for normal use. |
| 4386 | |
| 4387 | .vitem &%-q%&<&'qflags'&> |
| 4388 | The &%-q%& option may be followed by one or more flag letters that change its |
| 4389 | behaviour. They are all optional, but if more than one is present, they must |
| 4390 | appear in the correct order. Each flag is described in a separate item below. |
| 4391 | |
| 4392 | .vitem &%-qq...%& |
| 4393 | .oindex "&%-qq%&" |
| 4394 | .cindex "queue" "double scanning" |
| 4395 | .cindex "queue" "routing" |
| 4396 | .cindex "routing" "whole queue before delivery" |
| 4397 | An option starting with &%-qq%& requests a two-stage queue run. In the first |
| 4398 | stage, the queue is scanned as if the &%queue_smtp_domains%& option matched |
| 4399 | every domain. Addresses are routed, local deliveries happen, but no remote |
| 4400 | transports are run. |
| 4401 | |
| 4402 | .cindex "hints database" "remembering routing" |
| 4403 | The hints database that remembers which messages are waiting for specific hosts |
| 4404 | is updated, as if delivery to those hosts had been deferred. After this is |
| 4405 | complete, a second, normal queue scan happens, with routing and delivery taking |
| 4406 | place as normal. Messages that are routed to the same host should mostly be |
| 4407 | delivered down a single SMTP |
| 4408 | .cindex "SMTP" "passed connection" |
| 4409 | .cindex "SMTP" "multiple deliveries" |
| 4410 | .cindex "multiple SMTP deliveries" |
| 4411 | connection because of the hints that were set up during the first queue scan. |
| 4412 | This option may be useful for hosts that are connected to the Internet |
| 4413 | intermittently. |
| 4414 | |
| 4415 | .vitem &%-q[q]i...%& |
| 4416 | .oindex "&%-qi%&" |
| 4417 | .cindex "queue" "initial delivery" |
| 4418 | If the &'i'& flag is present, the queue runner runs delivery processes only for |
| 4419 | those messages that haven't previously been tried. (&'i'& stands for &"initial |
| 4420 | delivery"&.) This can be helpful if you are putting messages on the queue using |
| 4421 | &%-odq%& and want a queue runner just to process the new messages. |
| 4422 | |
| 4423 | .vitem &%-q[q][i]f...%& |
| 4424 | .oindex "&%-qf%&" |
| 4425 | .cindex "queue" "forcing delivery" |
| 4426 | .cindex "delivery" "forcing in queue run" |
| 4427 | If one &'f'& flag is present, a delivery attempt is forced for each non-frozen |
| 4428 | message, whereas without &'f'& only those non-frozen addresses that have passed |
| 4429 | their retry times are tried. |
| 4430 | |
| 4431 | .vitem &%-q[q][i]ff...%& |
| 4432 | .oindex "&%-qff%&" |
| 4433 | .cindex "frozen messages" "forcing delivery" |
| 4434 | If &'ff'& is present, a delivery attempt is forced for every message, whether |
| 4435 | frozen or not. |
| 4436 | |
| 4437 | .vitem &%-q[q][i][f[f]]l%& |
| 4438 | .oindex "&%-ql%&" |
| 4439 | .cindex "queue" "local deliveries only" |
| 4440 | The &'l'& (the letter &"ell"&) flag specifies that only local deliveries are to |
| 4441 | be done. If a message requires any remote deliveries, it remains on the queue |
| 4442 | for later delivery. |
| 4443 | |
| 4444 | .vitem &%-q%&<&'qflags'&>&~<&'start&~id'&>&~<&'end&~id'&> |
| 4445 | .cindex "queue" "delivering specific messages" |
| 4446 | When scanning the queue, Exim can be made to skip over messages whose ids are |
| 4447 | lexically less than a given value by following the &%-q%& option with a |
| 4448 | starting message id. For example: |
| 4449 | .code |
| 4450 | exim -q 0t5C6f-0000c8-00 |
| 4451 | .endd |
| 4452 | Messages that arrived earlier than &`0t5C6f-0000c8-00`& are not inspected. If a |
| 4453 | second message id is given, messages whose ids are lexically greater than it |
| 4454 | are also skipped. If the same id is given twice, for example, |
| 4455 | .code |
| 4456 | exim -q 0t5C6f-0000c8-00 0t5C6f-0000c8-00 |
| 4457 | .endd |
| 4458 | just one delivery process is started, for that message. This differs from |
| 4459 | &%-M%& in that retry data is respected, and it also differs from &%-Mc%& in |
| 4460 | that it counts as a delivery from a queue run. Note that the selection |
| 4461 | mechanism does not affect the order in which the messages are scanned. There |
| 4462 | are also other ways of selecting specific sets of messages for delivery in a |
| 4463 | queue run &-- see &%-R%& and &%-S%&. |
| 4464 | |
| 4465 | .vitem &%-q%&<&'qflags'&><&'time'&> |
| 4466 | .cindex "queue runner" "starting periodically" |
| 4467 | .cindex "periodic queue running" |
| 4468 | When a time value is present, the &%-q%& option causes Exim to run as a daemon, |
| 4469 | starting a queue runner process at intervals specified by the given time value |
| 4470 | (whose format is described in section &<<SECTtimeformat>>&). This form of the |
| 4471 | &%-q%& option is commonly combined with the &%-bd%& option, in which case a |
| 4472 | single daemon process handles both functions. A common way of starting up a |
| 4473 | combined daemon at system boot time is to use a command such as |
| 4474 | .code |
| 4475 | /usr/exim/bin/exim -bd -q30m |
| 4476 | .endd |
| 4477 | Such a daemon listens for incoming SMTP calls, and also starts a queue runner |
| 4478 | process every 30 minutes. |
| 4479 | |
| 4480 | When a daemon is started by &%-q%& with a time value, but without &%-bd%&, no |
| 4481 | pid file is written unless one is explicitly requested by the &%-oP%& option. |
| 4482 | |
| 4483 | .vitem &%-qR%&<&'rsflags'&>&~<&'string'&> |
| 4484 | .oindex "&%-qR%&" |
| 4485 | This option is synonymous with &%-R%&. It is provided for Sendmail |
| 4486 | compatibility. |
| 4487 | |
| 4488 | .vitem &%-qS%&<&'rsflags'&>&~<&'string'&> |
| 4489 | .oindex "&%-qS%&" |
| 4490 | This option is synonymous with &%-S%&. |
| 4491 | |
| 4492 | .vitem &%-R%&<&'rsflags'&>&~<&'string'&> |
| 4493 | .oindex "&%-R%&" |
| 4494 | .cindex "queue runner" "for specific recipients" |
| 4495 | .cindex "delivery" "to given domain" |
| 4496 | .cindex "domain" "delivery to" |
| 4497 | The <&'rsflags'&> may be empty, in which case the white space before the string |
| 4498 | is optional, unless the string is &'f'&, &'ff'&, &'r'&, &'rf'&, or &'rff'&, |
| 4499 | which are the possible values for <&'rsflags'&>. White space is required if |
| 4500 | <&'rsflags'&> is not empty. |
| 4501 | |
| 4502 | This option is similar to &%-q%& with no time value, that is, it causes Exim to |
| 4503 | perform a single queue run, except that, when scanning the messages on the |
| 4504 | queue, Exim processes only those that have at least one undelivered recipient |
| 4505 | address containing the given string, which is checked in a case-independent |
| 4506 | way. If the <&'rsflags'&> start with &'r'&, <&'string'&> is interpreted as a |
| 4507 | regular expression; otherwise it is a literal string. |
| 4508 | |
| 4509 | If you want to do periodic queue runs for messages with specific recipients, |
| 4510 | you can combine &%-R%& with &%-q%& and a time value. For example: |
| 4511 | .code |
| 4512 | exim -q25m -R @special.domain.example |
| 4513 | .endd |
| 4514 | This example does a queue run for messages with recipients in the given domain |
| 4515 | every 25 minutes. Any additional flags that are specified with &%-q%& are |
| 4516 | applied to each queue run. |
| 4517 | |
| 4518 | Once a message is selected for delivery by this mechanism, all its addresses |
| 4519 | are processed. For the first selected message, Exim overrides any retry |
| 4520 | information and forces a delivery attempt for each undelivered address. This |
| 4521 | means that if delivery of any address in the first message is successful, any |
| 4522 | existing retry information is deleted, and so delivery attempts for that |
| 4523 | address in subsequently selected messages (which are processed without forcing) |
| 4524 | will run. However, if delivery of any address does not succeed, the retry |
| 4525 | information is updated, and in subsequently selected messages, the failing |
| 4526 | address will be skipped. |
| 4527 | |
| 4528 | .cindex "frozen messages" "forcing delivery" |
| 4529 | If the <&'rsflags'&> contain &'f'& or &'ff'&, the delivery forcing applies to |
| 4530 | all selected messages, not just the first; frozen messages are included when |
| 4531 | &'ff'& is present. |
| 4532 | |
| 4533 | The &%-R%& option makes it straightforward to initiate delivery of all messages |
| 4534 | to a given domain after a host has been down for some time. When the SMTP |
| 4535 | command ETRN is accepted by its ACL (see chapter &<<CHAPACL>>&), its default |
| 4536 | effect is to run Exim with the &%-R%& option, but it can be configured to run |
| 4537 | an arbitrary command instead. |
| 4538 | |
| 4539 | .vitem &%-r%& |
| 4540 | .oindex "&%-r%&" |
| 4541 | This is a documented (for Sendmail) obsolete alternative name for &%-f%&. |
| 4542 | |
| 4543 | .vitem &%-S%&<&'rsflags'&>&~<&'string'&> |
| 4544 | .oindex "&%-S%&" |
| 4545 | .cindex "delivery" "from given sender" |
| 4546 | .cindex "queue runner" "for specific senders" |
| 4547 | This option acts like &%-R%& except that it checks the string against each |
| 4548 | message's sender instead of against the recipients. If &%-R%& is also set, both |
| 4549 | conditions must be met for a message to be selected. If either of the options |
| 4550 | has &'f'& or &'ff'& in its flags, the associated action is taken. |
| 4551 | |
| 4552 | .vitem &%-Tqt%&&~<&'times'&> |
| 4553 | .oindex "&%-Tqt%&" |
| 4554 | This is an option that is exclusively for use by the Exim testing suite. It is not |
| 4555 | recognized when Exim is run normally. It allows for the setting up of explicit |
| 4556 | &"queue times"& so that various warning/retry features can be tested. |
| 4557 | |
| 4558 | .vitem &%-t%& |
| 4559 | .oindex "&%-t%&" |
| 4560 | .cindex "recipient" "extracting from header lines" |
| 4561 | .cindex "&'Bcc:'& header line" |
| 4562 | .cindex "&'Cc:'& header line" |
| 4563 | .cindex "&'To:'& header line" |
| 4564 | When Exim is receiving a locally-generated, non-SMTP message on its standard |
| 4565 | input, the &%-t%& option causes the recipients of the message to be obtained |
| 4566 | from the &'To:'&, &'Cc:'&, and &'Bcc:'& header lines in the message instead of |
| 4567 | from the command arguments. The addresses are extracted before any rewriting |
| 4568 | takes place and the &'Bcc:'& header line, if present, is then removed. |
| 4569 | |
| 4570 | .cindex "Sendmail compatibility" "&%-t%& option" |
| 4571 | If the command has any arguments, they specify addresses to which the message |
| 4572 | is &'not'& to be delivered. That is, the argument addresses are removed from |
| 4573 | the recipients list obtained from the headers. This is compatible with Smail 3 |
| 4574 | and in accordance with the documented behaviour of several versions of |
| 4575 | Sendmail, as described in man pages on a number of operating systems (e.g. |
| 4576 | Solaris 8, IRIX 6.5, HP-UX 11). However, some versions of Sendmail &'add'& |
| 4577 | argument addresses to those obtained from the headers, and the O'Reilly |
| 4578 | Sendmail book documents it that way. Exim can be made to add argument addresses |
| 4579 | instead of subtracting them by setting the option |
| 4580 | &%extract_addresses_remove_arguments%& false. |
| 4581 | |
| 4582 | .cindex "&%Resent-%& header lines" "with &%-t%&" |
| 4583 | If there are any &%Resent-%& header lines in the message, Exim extracts |
| 4584 | recipients from all &'Resent-To:'&, &'Resent-Cc:'&, and &'Resent-Bcc:'& header |
| 4585 | lines instead of from &'To:'&, &'Cc:'&, and &'Bcc:'&. This is for compatibility |
| 4586 | with Sendmail and other MTAs. (Prior to release 4.20, Exim gave an error if |
| 4587 | &%-t%& was used in conjunction with &%Resent-%& header lines.) |
| 4588 | |
| 4589 | RFC 2822 talks about different sets of &%Resent-%& header lines (for when a |
| 4590 | message is resent several times). The RFC also specifies that they should be |
| 4591 | added at the front of the message, and separated by &'Received:'& lines. It is |
| 4592 | not at all clear how &%-t%& should operate in the present of multiple sets, |
| 4593 | nor indeed exactly what constitutes a &"set"&. |
| 4594 | In practice, it seems that MUAs do not follow the RFC. The &%Resent-%& lines |
| 4595 | are often added at the end of the header, and if a message is resent more than |
| 4596 | once, it is common for the original set of &%Resent-%& headers to be renamed as |
| 4597 | &%X-Resent-%& when a new set is added. This removes any possible ambiguity. |
| 4598 | |
| 4599 | .vitem &%-ti%& |
| 4600 | .oindex "&%-ti%&" |
| 4601 | This option is exactly equivalent to &%-t%& &%-i%&. It is provided for |
| 4602 | compatibility with Sendmail. |
| 4603 | |
| 4604 | .vitem &%-tls-on-connect%& |
| 4605 | .oindex "&%-tls-on-connect%&" |
| 4606 | .cindex "TLS" "use without STARTTLS" |
| 4607 | .cindex "TLS" "automatic start" |
| 4608 | This option is available when Exim is compiled with TLS support. It forces all |
| 4609 | incoming SMTP connections to behave as if the incoming port is listed in the |
| 4610 | &%tls_on_connect_ports%& option. See section &<<SECTsupobssmt>>& and chapter |
| 4611 | &<<CHAPTLS>>& for further details. |
| 4612 | |
| 4613 | |
| 4614 | .vitem &%-U%& |
| 4615 | .oindex "&%-U%&" |
| 4616 | .cindex "Sendmail compatibility" "&%-U%& option ignored" |
| 4617 | Sendmail uses this option for &"initial message submission"&, and its |
| 4618 | documentation states that in future releases, it may complain about |
| 4619 | syntactically invalid messages rather than fixing them when this flag is not |
| 4620 | set. Exim ignores this option. |
| 4621 | |
| 4622 | .vitem &%-v%& |
| 4623 | .oindex "&%-v%&" |
| 4624 | This option causes Exim to write information to the standard error stream, |
| 4625 | describing what it is doing. In particular, it shows the log lines for |
| 4626 | receiving and delivering a message, and if an SMTP connection is made, the SMTP |
| 4627 | dialogue is shown. Some of the log lines shown may not actually be written to |
| 4628 | the log if the setting of &%log_selector%& discards them. Any relevant |
| 4629 | selectors are shown with each log line. If none are shown, the logging is |
| 4630 | unconditional. |
| 4631 | |
| 4632 | .vitem &%-x%& |
| 4633 | .oindex "&%-x%&" |
| 4634 | AIX uses &%-x%& for a private purpose (&"mail from a local mail program has |
| 4635 | National Language Support extended characters in the body of the mail item"&). |
| 4636 | It sets &%-x%& when calling the MTA from its &%mail%& command. Exim ignores |
| 4637 | this option. |
| 4638 | |
| 4639 | .vitem &%-X%&&~<&'logfile'&> |
| 4640 | .oindex "&%-X%&" |
| 4641 | This option is interpreted by Sendmail to cause debug information to be sent |
| 4642 | to the named file. It is ignored by Exim. |
| 4643 | .endlist |
| 4644 | |
| 4645 | .ecindex IIDclo1 |
| 4646 | .ecindex IIDclo2 |
| 4647 | |
| 4648 | |
| 4649 | . //////////////////////////////////////////////////////////////////////////// |
| 4650 | . Insert a stylized DocBook comment here, to identify the end of the command |
| 4651 | . line options. This is for the benefit of the Perl script that automatically |
| 4652 | . creates a man page for the options. |
| 4653 | . //////////////////////////////////////////////////////////////////////////// |
| 4654 | |
| 4655 | .literal xml |
| 4656 | <!-- === End of command line options === --> |
| 4657 | .literal off |
| 4658 | |
| 4659 | |
| 4660 | |
| 4661 | |
| 4662 | |
| 4663 | . //////////////////////////////////////////////////////////////////////////// |
| 4664 | . //////////////////////////////////////////////////////////////////////////// |
| 4665 | |
| 4666 | |
| 4667 | .chapter "The Exim run time configuration file" "CHAPconf" &&& |
| 4668 | "The runtime configuration file" |
| 4669 | |
| 4670 | .cindex "run time configuration" |
| 4671 | .cindex "configuration file" "general description" |
| 4672 | .cindex "CONFIGURE_FILE" |
| 4673 | .cindex "configuration file" "errors in" |
| 4674 | .cindex "error" "in configuration file" |
| 4675 | .cindex "return code" "for bad configuration" |
| 4676 | Exim uses a single run time configuration file that is read whenever an Exim |
| 4677 | binary is executed. Note that in normal operation, this happens frequently, |
| 4678 | because Exim is designed to operate in a distributed manner, without central |
| 4679 | control. |
| 4680 | |
| 4681 | If a syntax error is detected while reading the configuration file, Exim |
| 4682 | writes a message on the standard error, and exits with a non-zero return code. |
| 4683 | The message is also written to the panic log. &*Note*&: Only simple syntax |
| 4684 | errors can be detected at this time. The values of any expanded options are |
| 4685 | not checked until the expansion happens, even when the expansion does not |
| 4686 | actually alter the string. |
| 4687 | |
| 4688 | The name of the configuration file is compiled into the binary for security |
| 4689 | reasons, and is specified by the CONFIGURE_FILE compilation option. In |
| 4690 | most configurations, this specifies a single file. However, it is permitted to |
| 4691 | give a colon-separated list of file names, in which case Exim uses the first |
| 4692 | existing file in the list. |
| 4693 | |
| 4694 | .cindex "EXIM_USER" |
| 4695 | .cindex "EXIM_GROUP" |
| 4696 | .cindex "CONFIGURE_OWNER" |
| 4697 | .cindex "CONFIGURE_GROUP" |
| 4698 | .cindex "configuration file" "ownership" |
| 4699 | .cindex "ownership" "configuration file" |
| 4700 | The run time configuration file must be owned by root or by the user that is |
| 4701 | specified at compile time by the CONFIGURE_OWNER option (if set). The |
| 4702 | configuration file must not be world-writeable, or group-writeable unless its |
| 4703 | group is the root group or the one specified at compile time by the |
| 4704 | CONFIGURE_GROUP option. |
| 4705 | |
| 4706 | &*Warning*&: In a conventional configuration, where the Exim binary is setuid |
| 4707 | to root, anybody who is able to edit the run time configuration file has an |
| 4708 | easy way to run commands as root. If you specify a user or group in the |
| 4709 | CONFIGURE_OWNER or CONFIGURE_GROUP options, then that user and/or any users |
| 4710 | who are members of that group will trivially be able to obtain root privileges. |
| 4711 | |
| 4712 | Up to Exim version 4.72, the run time configuration file was also permitted to |
| 4713 | be writeable by the Exim user and/or group. That has been changed in Exim 4.73 |
| 4714 | since it offered a simple privilege escalation for any attacker who managed to |
| 4715 | compromise the Exim user account. |
| 4716 | |
| 4717 | A default configuration file, which will work correctly in simple situations, |
| 4718 | is provided in the file &_src/configure.default_&. If CONFIGURE_FILE |
| 4719 | defines just one file name, the installation process copies the default |
| 4720 | configuration to a new file of that name if it did not previously exist. If |
| 4721 | CONFIGURE_FILE is a list, no default is automatically installed. Chapter |
| 4722 | &<<CHAPdefconfil>>& is a &"walk-through"& discussion of the default |
| 4723 | configuration. |
| 4724 | |
| 4725 | |
| 4726 | |
| 4727 | .section "Using a different configuration file" "SECID40" |
| 4728 | .cindex "configuration file" "alternate" |
| 4729 | A one-off alternate configuration can be specified by the &%-C%& command line |
| 4730 | option, which may specify a single file or a list of files. However, when |
| 4731 | &%-C%& is used, Exim gives up its root privilege, unless called by root (or |
| 4732 | unless the argument for &%-C%& is identical to the built-in value from |
| 4733 | CONFIGURE_FILE), or is listed in the TRUSTED_CONFIG_LIST file and the caller |
| 4734 | is the Exim user or the user specified in the CONFIGURE_OWNER setting. &%-C%& |
| 4735 | is useful mainly for checking the syntax of configuration files before |
| 4736 | installing them. No owner or group checks are done on a configuration file |
| 4737 | specified by &%-C%&, if root privilege has been dropped. |
| 4738 | |
| 4739 | Even the Exim user is not trusted to specify an arbitrary configuration file |
| 4740 | with the &%-C%& option to be used with root privileges, unless that file is |
| 4741 | listed in the TRUSTED_CONFIG_LIST file. This locks out the possibility of |
| 4742 | testing a configuration using &%-C%& right through message reception and |
| 4743 | delivery, even if the caller is root. The reception works, but by that time, |
| 4744 | Exim is running as the Exim user, so when it re-execs to regain privilege for |
| 4745 | the delivery, the use of &%-C%& causes privilege to be lost. However, root |
| 4746 | can test reception and delivery using two separate commands (one to put a |
| 4747 | message on the queue, using &%-odq%&, and another to do the delivery, using |
| 4748 | &%-M%&). |
| 4749 | |
| 4750 | If ALT_CONFIG_PREFIX is defined &_in Local/Makefile_&, it specifies a |
| 4751 | prefix string with which any file named in a &%-C%& command line option must |
| 4752 | start. In addition, the file name must not contain the sequence &"&`/../`&"&. |
| 4753 | There is no default setting for ALT_CONFIG_PREFIX; when it is unset, any file |
| 4754 | name can be used with &%-C%&. |
| 4755 | |
| 4756 | One-off changes to a configuration can be specified by the &%-D%& command line |
| 4757 | option, which defines and overrides values for macros used inside the |
| 4758 | configuration file. However, like &%-C%&, the use of this option by a |
| 4759 | non-privileged user causes Exim to discard its root privilege. |
| 4760 | If DISABLE_D_OPTION is defined in &_Local/Makefile_&, the use of &%-D%& is |
| 4761 | completely disabled, and its use causes an immediate error exit. |
| 4762 | |
| 4763 | The WHITELIST_D_MACROS option in &_Local/Makefile_& permits the binary builder |
| 4764 | to declare certain macro names trusted, such that root privilege will not |
| 4765 | necessarily be discarded. |
| 4766 | WHITELIST_D_MACROS defines a colon-separated list of macros which are |
| 4767 | considered safe and, if &%-D%& only supplies macros from this list, and the |
| 4768 | values are acceptable, then Exim will not give up root privilege if the caller |
| 4769 | is root, the Exim run-time user, or the CONFIGURE_OWNER, if set. This is a |
| 4770 | transition mechanism and is expected to be removed in the future. Acceptable |
| 4771 | values for the macros satisfy the regexp: &`^[A-Za-z0-9_/.-]*$`& |
| 4772 | |
| 4773 | Some sites may wish to use the same Exim binary on different machines that |
| 4774 | share a file system, but to use different configuration files on each machine. |
| 4775 | If CONFIGURE_FILE_USE_NODE is defined in &_Local/Makefile_&, Exim first |
| 4776 | looks for a file whose name is the configuration file name followed by a dot |
| 4777 | and the machine's node name, as obtained from the &[uname()]& function. If this |
| 4778 | file does not exist, the standard name is tried. This processing occurs for |
| 4779 | each file name in the list given by CONFIGURE_FILE or &%-C%&. |
| 4780 | |
| 4781 | In some esoteric situations different versions of Exim may be run under |
| 4782 | different effective uids and the CONFIGURE_FILE_USE_EUID is defined to |
| 4783 | help with this. See the comments in &_src/EDITME_& for details. |
| 4784 | |
| 4785 | |
| 4786 | |
| 4787 | .section "Configuration file format" "SECTconffilfor" |
| 4788 | .cindex "configuration file" "format of" |
| 4789 | .cindex "format" "configuration file" |
| 4790 | Exim's configuration file is divided into a number of different parts. General |
| 4791 | option settings must always appear at the start of the file. The other parts |
| 4792 | are all optional, and may appear in any order. Each part other than the first |
| 4793 | is introduced by the word &"begin"& followed by the name of the part. The |
| 4794 | optional parts are: |
| 4795 | |
| 4796 | .ilist |
| 4797 | &'ACL'&: Access control lists for controlling incoming SMTP mail (see chapter |
| 4798 | &<<CHAPACL>>&). |
| 4799 | .next |
| 4800 | .cindex "AUTH" "configuration" |
| 4801 | &'authenticators'&: Configuration settings for the authenticator drivers. These |
| 4802 | are concerned with the SMTP AUTH command (see chapter &<<CHAPSMTPAUTH>>&). |
| 4803 | .next |
| 4804 | &'routers'&: Configuration settings for the router drivers. Routers process |
| 4805 | addresses and determine how the message is to be delivered (see chapters |
| 4806 | &<<CHAProutergeneric>>&&--&<<CHAPredirect>>&). |
| 4807 | .next |
| 4808 | &'transports'&: Configuration settings for the transport drivers. Transports |
| 4809 | define mechanisms for copying messages to destinations (see chapters |
| 4810 | &<<CHAPtransportgeneric>>&&--&<<CHAPsmtptrans>>&). |
| 4811 | .next |
| 4812 | &'retry'&: Retry rules, for use when a message cannot be delivered immediately. |
| 4813 | If there is no retry section, or if it is empty (that is, no retry rules are |
| 4814 | defined), Exim will not retry deliveries. In this situation, temporary errors |
| 4815 | are treated the same as permanent errors. Retry rules are discussed in chapter |
| 4816 | &<<CHAPretry>>&. |
| 4817 | .next |
| 4818 | &'rewrite'&: Global address rewriting rules, for use when a message arrives and |
| 4819 | when new addresses are generated during delivery. Rewriting is discussed in |
| 4820 | chapter &<<CHAPrewrite>>&. |
| 4821 | .next |
| 4822 | &'local_scan'&: Private options for the &[local_scan()]& function. If you |
| 4823 | want to use this feature, you must set |
| 4824 | .code |
| 4825 | LOCAL_SCAN_HAS_OPTIONS=yes |
| 4826 | .endd |
| 4827 | in &_Local/Makefile_& before building Exim. Details of the &[local_scan()]& |
| 4828 | facility are given in chapter &<<CHAPlocalscan>>&. |
| 4829 | .endlist |
| 4830 | |
| 4831 | .cindex "configuration file" "leading white space in" |
| 4832 | .cindex "configuration file" "trailing white space in" |
| 4833 | .cindex "white space" "in configuration file" |
| 4834 | Leading and trailing white space in configuration lines is always ignored. |
| 4835 | |
| 4836 | Blank lines in the file, and lines starting with a # character (ignoring |
| 4837 | leading white space) are treated as comments and are ignored. &*Note*&: A |
| 4838 | # character other than at the beginning of a line is not treated specially, |
| 4839 | and does not introduce a comment. |
| 4840 | |
| 4841 | Any non-comment line can be continued by ending it with a backslash. Note that |
| 4842 | the general rule for white space means that trailing white space after the |
| 4843 | backslash and leading white space at the start of continuation |
| 4844 | lines is ignored. Comment lines beginning with # (but not empty lines) may |
| 4845 | appear in the middle of a sequence of continuation lines. |
| 4846 | |
| 4847 | A convenient way to create a configuration file is to start from the |
| 4848 | default, which is supplied in &_src/configure.default_&, and add, delete, or |
| 4849 | change settings as required. |
| 4850 | |
| 4851 | The ACLs, retry rules, and rewriting rules have their own syntax which is |
| 4852 | described in chapters &<<CHAPACL>>&, &<<CHAPretry>>&, and &<<CHAPrewrite>>&, |
| 4853 | respectively. The other parts of the configuration file have some syntactic |
| 4854 | items in common, and these are described below, from section &<<SECTcos>>& |
| 4855 | onwards. Before that, the inclusion, macro, and conditional facilities are |
| 4856 | described. |
| 4857 | |
| 4858 | |
| 4859 | |
| 4860 | .section "File inclusions in the configuration file" "SECID41" |
| 4861 | .cindex "inclusions in configuration file" |
| 4862 | .cindex "configuration file" "including other files" |
| 4863 | .cindex "&`.include`& in configuration file" |
| 4864 | .cindex "&`.include_if_exists`& in configuration file" |
| 4865 | You can include other files inside Exim's run time configuration file by |
| 4866 | using this syntax: |
| 4867 | .display |
| 4868 | &`.include`& <&'file name'&> |
| 4869 | &`.include_if_exists`& <&'file name'&> |
| 4870 | .endd |
| 4871 | on a line by itself. Double quotes round the file name are optional. If you use |
| 4872 | the first form, a configuration error occurs if the file does not exist; the |
| 4873 | second form does nothing for non-existent files. In all cases, an absolute file |
| 4874 | name is required. |
| 4875 | |
| 4876 | Includes may be nested to any depth, but remember that Exim reads its |
| 4877 | configuration file often, so it is a good idea to keep them to a minimum. |
| 4878 | If you change the contents of an included file, you must HUP the daemon, |
| 4879 | because an included file is read only when the configuration itself is read. |
| 4880 | |
| 4881 | The processing of inclusions happens early, at a physical line level, so, like |
| 4882 | comment lines, an inclusion can be used in the middle of an option setting, |
| 4883 | for example: |
| 4884 | .code |
| 4885 | hosts_lookup = a.b.c \ |
| 4886 | .include /some/file |
| 4887 | .endd |
| 4888 | Include processing happens after macro processing (see below). Its effect is to |
| 4889 | process the lines of the included file as if they occurred inline where the |
| 4890 | inclusion appears. |
| 4891 | |
| 4892 | |
| 4893 | |
| 4894 | .section "Macros in the configuration file" "SECTmacrodefs" |
| 4895 | .cindex "macro" "description of" |
| 4896 | .cindex "configuration file" "macros" |
| 4897 | If a line in the main part of the configuration (that is, before the first |
| 4898 | &"begin"& line) begins with an upper case letter, it is taken as a macro |
| 4899 | definition, and must be of the form |
| 4900 | .display |
| 4901 | <&'name'&> = <&'rest of line'&> |
| 4902 | .endd |
| 4903 | The name must consist of letters, digits, and underscores, and need not all be |
| 4904 | in upper case, though that is recommended. The rest of the line, including any |
| 4905 | continuations, is the replacement text, and has leading and trailing white |
| 4906 | space removed. Quotes are not removed. The replacement text can never end with |
| 4907 | a backslash character, but this doesn't seem to be a serious limitation. |
| 4908 | |
| 4909 | Macros may also be defined between router, transport, authenticator, or ACL |
| 4910 | definitions. They may not, however, be defined within an individual driver or |
| 4911 | ACL, or in the &%local_scan%&, retry, or rewrite sections of the configuration. |
| 4912 | |
| 4913 | .section "Macro substitution" "SECID42" |
| 4914 | Once a macro is defined, all subsequent lines in the file (and any included |
| 4915 | files) are scanned for the macro name; if there are several macros, the line is |
| 4916 | scanned for each in turn, in the order in which the macros are defined. The |
| 4917 | replacement text is not re-scanned for the current macro, though it is scanned |
| 4918 | for subsequently defined macros. For this reason, a macro name may not contain |
| 4919 | the name of a previously defined macro as a substring. You could, for example, |
| 4920 | define |
| 4921 | .display |
| 4922 | &`ABCD_XYZ = `&<&'something'&> |
| 4923 | &`ABCD = `&<&'something else'&> |
| 4924 | .endd |
| 4925 | but putting the definitions in the opposite order would provoke a configuration |
| 4926 | error. Macro expansion is applied to individual physical lines from the file, |
| 4927 | before checking for line continuation or file inclusion (see above). If a line |
| 4928 | consists solely of a macro name, and the expansion of the macro is empty, the |
| 4929 | line is ignored. A macro at the start of a line may turn the line into a |
| 4930 | comment line or a &`.include`& line. |
| 4931 | |
| 4932 | |
| 4933 | .section "Redefining macros" "SECID43" |
| 4934 | Once defined, the value of a macro can be redefined later in the configuration |
| 4935 | (or in an included file). Redefinition is specified by using &'=='& instead of |
| 4936 | &'='&. For example: |
| 4937 | .code |
| 4938 | MAC = initial value |
| 4939 | ... |
| 4940 | MAC == updated value |
| 4941 | .endd |
| 4942 | Redefinition does not alter the order in which the macros are applied to the |
| 4943 | subsequent lines of the configuration file. It is still the same order in which |
| 4944 | the macros were originally defined. All that changes is the macro's value. |
| 4945 | Redefinition makes it possible to accumulate values. For example: |
| 4946 | .code |
| 4947 | MAC = initial value |
| 4948 | ... |
| 4949 | MAC == MAC and something added |
| 4950 | .endd |
| 4951 | This can be helpful in situations where the configuration file is built |
| 4952 | from a number of other files. |
| 4953 | |
| 4954 | .section "Overriding macro values" "SECID44" |
| 4955 | The values set for macros in the configuration file can be overridden by the |
| 4956 | &%-D%& command line option, but Exim gives up its root privilege when &%-D%& is |
| 4957 | used, unless called by root or the Exim user. A definition on the command line |
| 4958 | using the &%-D%& option causes all definitions and redefinitions within the |
| 4959 | file to be ignored. |
| 4960 | |
| 4961 | |
| 4962 | |
| 4963 | .section "Example of macro usage" "SECID45" |
| 4964 | As an example of macro usage, consider a configuration where aliases are looked |
| 4965 | up in a MySQL database. It helps to keep the file less cluttered if long |
| 4966 | strings such as SQL statements are defined separately as macros, for example: |
| 4967 | .code |
| 4968 | ALIAS_QUERY = select mailbox from user where \ |
| 4969 | login='${quote_mysql:$local_part}'; |
| 4970 | .endd |
| 4971 | This can then be used in a &(redirect)& router setting like this: |
| 4972 | .code |
| 4973 | data = ${lookup mysql{ALIAS_QUERY}} |
| 4974 | .endd |
| 4975 | In earlier versions of Exim macros were sometimes used for domain, host, or |
| 4976 | address lists. In Exim 4 these are handled better by named lists &-- see |
| 4977 | section &<<SECTnamedlists>>&. |
| 4978 | |
| 4979 | |
| 4980 | .section "Conditional skips in the configuration file" "SECID46" |
| 4981 | .cindex "configuration file" "conditional skips" |
| 4982 | .cindex "&`.ifdef`&" |
| 4983 | You can use the directives &`.ifdef`&, &`.ifndef`&, &`.elifdef`&, |
| 4984 | &`.elifndef`&, &`.else`&, and &`.endif`& to dynamically include or exclude |
| 4985 | portions of the configuration file. The processing happens whenever the file is |
| 4986 | read (that is, when an Exim binary starts to run). |
| 4987 | |
| 4988 | The implementation is very simple. Instances of the first four directives must |
| 4989 | be followed by text that includes the names of one or macros. The condition |
| 4990 | that is tested is whether or not any macro substitution has taken place in the |
| 4991 | line. Thus: |
| 4992 | .code |
| 4993 | .ifdef AAA |
| 4994 | message_size_limit = 50M |
| 4995 | .else |
| 4996 | message_size_limit = 100M |
| 4997 | .endif |
| 4998 | .endd |
| 4999 | sets a message size limit of 50M if the macro &`AAA`& is defined, and 100M |
| 5000 | otherwise. If there is more than one macro named on the line, the condition |
| 5001 | is true if any of them are defined. That is, it is an &"or"& condition. To |
| 5002 | obtain an &"and"& condition, you need to use nested &`.ifdef`&s. |
| 5003 | |
| 5004 | Although you can use a macro expansion to generate one of these directives, |
| 5005 | it is not very useful, because the condition &"there was a macro substitution |
| 5006 | in this line"& will always be true. |
| 5007 | |
| 5008 | Text following &`.else`& and &`.endif`& is ignored, and can be used as comment |
| 5009 | to clarify complicated nestings. |
| 5010 | |
| 5011 | |
| 5012 | |
| 5013 | .section "Common option syntax" "SECTcos" |
| 5014 | .cindex "common option syntax" |
| 5015 | .cindex "syntax of common options" |
| 5016 | .cindex "configuration file" "common option syntax" |
| 5017 | For the main set of options, driver options, and &[local_scan()]& options, |
| 5018 | each setting is on a line by itself, and starts with a name consisting of |
| 5019 | lower-case letters and underscores. Many options require a data value, and in |
| 5020 | these cases the name must be followed by an equals sign (with optional white |
| 5021 | space) and then the value. For example: |
| 5022 | .code |
| 5023 | qualify_domain = mydomain.example.com |
| 5024 | .endd |
| 5025 | .cindex "hiding configuration option values" |
| 5026 | .cindex "configuration options" "hiding value of" |
| 5027 | .cindex "options" "hiding value of" |
| 5028 | Some option settings may contain sensitive data, for example, passwords for |
| 5029 | accessing databases. To stop non-admin users from using the &%-bP%& command |
| 5030 | line option to read these values, you can precede the option settings with the |
| 5031 | word &"hide"&. For example: |
| 5032 | .code |
| 5033 | hide mysql_servers = localhost/users/admin/secret-password |
| 5034 | .endd |
| 5035 | For non-admin users, such options are displayed like this: |
| 5036 | .code |
| 5037 | mysql_servers = <value not displayable> |
| 5038 | .endd |
| 5039 | If &"hide"& is used on a driver option, it hides the value of that option on |
| 5040 | all instances of the same driver. |
| 5041 | |
| 5042 | The following sections describe the syntax used for the different data types |
| 5043 | that are found in option settings. |
| 5044 | |
| 5045 | |
| 5046 | .section "Boolean options" "SECID47" |
| 5047 | .cindex "format" "boolean" |
| 5048 | .cindex "boolean configuration values" |
| 5049 | .oindex "&%no_%&&'xxx'&" |
| 5050 | .oindex "&%not_%&&'xxx'&" |
| 5051 | Options whose type is given as boolean are on/off switches. There are two |
| 5052 | different ways of specifying such options: with and without a data value. If |
| 5053 | the option name is specified on its own without data, the switch is turned on; |
| 5054 | if it is preceded by &"no_"& or &"not_"& the switch is turned off. However, |
| 5055 | boolean options may be followed by an equals sign and one of the words |
| 5056 | &"true"&, &"false"&, &"yes"&, or &"no"&, as an alternative syntax. For example, |
| 5057 | the following two settings have exactly the same effect: |
| 5058 | .code |
| 5059 | queue_only |
| 5060 | queue_only = true |
| 5061 | .endd |
| 5062 | The following two lines also have the same (opposite) effect: |
| 5063 | .code |
| 5064 | no_queue_only |
| 5065 | queue_only = false |
| 5066 | .endd |
| 5067 | You can use whichever syntax you prefer. |
| 5068 | |
| 5069 | |
| 5070 | |
| 5071 | |
| 5072 | .section "Integer values" "SECID48" |
| 5073 | .cindex "integer configuration values" |
| 5074 | .cindex "format" "integer" |
| 5075 | If an option's type is given as &"integer"&, the value can be given in decimal, |
| 5076 | hexadecimal, or octal. If it starts with a digit greater than zero, a decimal |
| 5077 | number is assumed. Otherwise, it is treated as an octal number unless it starts |
| 5078 | with the characters &"0x"&, in which case the remainder is interpreted as a |
| 5079 | hexadecimal number. |
| 5080 | |
| 5081 | If an integer value is followed by the letter K, it is multiplied by 1024; if |
| 5082 | it is followed by the letter M, it is multiplied by 1024x1024. When the values |
| 5083 | of integer option settings are output, values which are an exact multiple of |
| 5084 | 1024 or 1024x1024 are sometimes, but not always, printed using the letters K |
| 5085 | and M. The printing style is independent of the actual input format that was |
| 5086 | used. |
| 5087 | |
| 5088 | |
| 5089 | .section "Octal integer values" "SECID49" |
| 5090 | .cindex "integer format" |
| 5091 | .cindex "format" "octal integer" |
| 5092 | If an option's type is given as &"octal integer"&, its value is always |
| 5093 | interpreted as an octal number, whether or not it starts with the digit zero. |
| 5094 | Such options are always output in octal. |
| 5095 | |
| 5096 | |
| 5097 | .section "Fixed point numbers" "SECID50" |
| 5098 | .cindex "fixed point configuration values" |
| 5099 | .cindex "format" "fixed point" |
| 5100 | If an option's type is given as &"fixed-point"&, its value must be a decimal |
| 5101 | integer, optionally followed by a decimal point and up to three further digits. |
| 5102 | |
| 5103 | |
| 5104 | |
| 5105 | .section "Time intervals" "SECTtimeformat" |
| 5106 | .cindex "time interval" "specifying in configuration" |
| 5107 | .cindex "format" "time interval" |
| 5108 | A time interval is specified as a sequence of numbers, each followed by one of |
| 5109 | the following letters, with no intervening white space: |
| 5110 | |
| 5111 | .table2 30pt |
| 5112 | .irow &%s%& seconds |
| 5113 | .irow &%m%& minutes |
| 5114 | .irow &%h%& hours |
| 5115 | .irow &%d%& days |
| 5116 | .irow &%w%& weeks |
| 5117 | .endtable |
| 5118 | |
| 5119 | For example, &"3h50m"& specifies 3 hours and 50 minutes. The values of time |
| 5120 | intervals are output in the same format. Exim does not restrict the values; it |
| 5121 | is perfectly acceptable, for example, to specify &"90m"& instead of &"1h30m"&. |
| 5122 | |
| 5123 | |
| 5124 | |
| 5125 | .section "String values" "SECTstrings" |
| 5126 | .cindex "string" "format of configuration values" |
| 5127 | .cindex "format" "string" |
| 5128 | If an option's type is specified as &"string"&, the value can be specified with |
| 5129 | or without double-quotes. If it does not start with a double-quote, the value |
| 5130 | consists of the remainder of the line plus any continuation lines, starting at |
| 5131 | the first character after any leading white space, with trailing white space |
| 5132 | removed, and with no interpretation of the characters in the string. Because |
| 5133 | Exim removes comment lines (those beginning with #) at an early stage, they can |
| 5134 | appear in the middle of a multi-line string. The following two settings are |
| 5135 | therefore equivalent: |
| 5136 | .code |
| 5137 | trusted_users = uucp:mail |
| 5138 | trusted_users = uucp:\ |
| 5139 | # This comment line is ignored |
| 5140 | mail |
| 5141 | .endd |
| 5142 | .cindex "string" "quoted" |
| 5143 | .cindex "escape characters in quoted strings" |
| 5144 | If a string does start with a double-quote, it must end with a closing |
| 5145 | double-quote, and any backslash characters other than those used for line |
| 5146 | continuation are interpreted as escape characters, as follows: |
| 5147 | |
| 5148 | .table2 100pt |
| 5149 | .irow &`\\`& "single backslash" |
| 5150 | .irow &`\n`& "newline" |
| 5151 | .irow &`\r`& "carriage return" |
| 5152 | .irow &`\t`& "tab" |
| 5153 | .irow "&`\`&<&'octal digits'&>" "up to 3 octal digits specify one character" |
| 5154 | .irow "&`\x`&<&'hex digits'&>" "up to 2 hexadecimal digits specify one &&& |
| 5155 | character" |
| 5156 | .endtable |
| 5157 | |
| 5158 | If a backslash is followed by some other character, including a double-quote |
| 5159 | character, that character replaces the pair. |
| 5160 | |
| 5161 | Quoting is necessary only if you want to make use of the backslash escapes to |
| 5162 | insert special characters, or if you need to specify a value with leading or |
| 5163 | trailing spaces. These cases are rare, so quoting is almost never needed in |
| 5164 | current versions of Exim. In versions of Exim before 3.14, quoting was required |
| 5165 | in order to continue lines, so you may come across older configuration files |
| 5166 | and examples that apparently quote unnecessarily. |
| 5167 | |
| 5168 | |
| 5169 | .section "Expanded strings" "SECID51" |
| 5170 | .cindex "expansion" "definition of" |
| 5171 | Some strings in the configuration file are subjected to &'string expansion'&, |
| 5172 | by which means various parts of the string may be changed according to the |
| 5173 | circumstances (see chapter &<<CHAPexpand>>&). The input syntax for such strings |
| 5174 | is as just described; in particular, the handling of backslashes in quoted |
| 5175 | strings is done as part of the input process, before expansion takes place. |
| 5176 | However, backslash is also an escape character for the expander, so any |
| 5177 | backslashes that are required for that reason must be doubled if they are |
| 5178 | within a quoted configuration string. |
| 5179 | |
| 5180 | |
| 5181 | .section "User and group names" "SECID52" |
| 5182 | .cindex "user name" "format of" |
| 5183 | .cindex "format" "user name" |
| 5184 | .cindex "groups" "name format" |
| 5185 | .cindex "format" "group name" |
| 5186 | User and group names are specified as strings, using the syntax described |
| 5187 | above, but the strings are interpreted specially. A user or group name must |
| 5188 | either consist entirely of digits, or be a name that can be looked up using the |
| 5189 | &[getpwnam()]& or &[getgrnam()]& function, as appropriate. |
| 5190 | |
| 5191 | |
| 5192 | .section "List construction" "SECTlistconstruct" |
| 5193 | .cindex "list" "syntax of in configuration" |
| 5194 | .cindex "format" "list item in configuration" |
| 5195 | .cindex "string" "list, definition of" |
| 5196 | The data for some configuration options is a list of items, with colon as the |
| 5197 | default separator. Many of these options are shown with type &"string list"& in |
| 5198 | the descriptions later in this document. Others are listed as &"domain list"&, |
| 5199 | &"host list"&, &"address list"&, or &"local part list"&. Syntactically, they |
| 5200 | are all the same; however, those other than &"string list"& are subject to |
| 5201 | particular kinds of interpretation, as described in chapter |
| 5202 | &<<CHAPdomhosaddlists>>&. |
| 5203 | |
| 5204 | In all these cases, the entire list is treated as a single string as far as the |
| 5205 | input syntax is concerned. The &%trusted_users%& setting in section |
| 5206 | &<<SECTstrings>>& above is an example. If a colon is actually needed in an item |
| 5207 | in a list, it must be entered as two colons. Leading and trailing white space |
| 5208 | on each item in a list is ignored. This makes it possible to include items that |
| 5209 | start with a colon, and in particular, certain forms of IPv6 address. For |
| 5210 | example, the list |
| 5211 | .code |
| 5212 | local_interfaces = 127.0.0.1 : ::::1 |
| 5213 | .endd |
| 5214 | contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address ::1. |
| 5215 | |
| 5216 | &*Note*&: Although leading and trailing white space is ignored in individual |
| 5217 | list items, it is not ignored when parsing the list. The space after the first |
| 5218 | colon in the example above is necessary. If it were not there, the list would |
| 5219 | be interpreted as the two items 127.0.0.1:: and 1. |
| 5220 | |
| 5221 | .section "Changing list separators" "SECID53" |
| 5222 | .cindex "list separator" "changing" |
| 5223 | .cindex "IPv6" "addresses in lists" |
| 5224 | Doubling colons in IPv6 addresses is an unwelcome chore, so a mechanism was |
| 5225 | introduced to allow the separator character to be changed. If a list begins |
| 5226 | with a left angle bracket, followed by any punctuation character, that |
| 5227 | character is used instead of colon as the list separator. For example, the list |
| 5228 | above can be rewritten to use a semicolon separator like this: |
| 5229 | .code |
| 5230 | local_interfaces = <; 127.0.0.1 ; ::1 |
| 5231 | .endd |
| 5232 | This facility applies to all lists, with the exception of the list in |
| 5233 | &%log_file_path%&. It is recommended that the use of non-colon separators be |
| 5234 | confined to circumstances where they really are needed. |
| 5235 | |
| 5236 | .cindex "list separator" "newline as" |
| 5237 | .cindex "newline" "as list separator" |
| 5238 | It is also possible to use newline and other control characters (those with |
| 5239 | code values less than 32, plus DEL) as separators in lists. Such separators |
| 5240 | must be provided literally at the time the list is processed. For options that |
| 5241 | are string-expanded, you can write the separator using a normal escape |
| 5242 | sequence. This will be processed by the expander before the string is |
| 5243 | interpreted as a list. For example, if a newline-separated list of domains is |
| 5244 | generated by a lookup, you can process it directly by a line such as this: |
| 5245 | .code |
| 5246 | domains = <\n ${lookup mysql{.....}} |
| 5247 | .endd |
| 5248 | This avoids having to change the list separator in such data. You are unlikely |
| 5249 | to want to use a control character as a separator in an option that is not |
| 5250 | expanded, because the value is literal text. However, it can be done by giving |
| 5251 | the value in quotes. For example: |
| 5252 | .code |
| 5253 | local_interfaces = "<\n 127.0.0.1 \n ::1" |
| 5254 | .endd |
| 5255 | Unlike printing character separators, which can be included in list items by |
| 5256 | doubling, it is not possible to include a control character as data when it is |
| 5257 | set as the separator. Two such characters in succession are interpreted as |
| 5258 | enclosing an empty list item. |
| 5259 | |
| 5260 | |
| 5261 | |
| 5262 | .section "Empty items in lists" "SECTempitelis" |
| 5263 | .cindex "list" "empty item in" |
| 5264 | An empty item at the end of a list is always ignored. In other words, trailing |
| 5265 | separator characters are ignored. Thus, the list in |
| 5266 | .code |
| 5267 | senders = user@domain : |
| 5268 | .endd |
| 5269 | contains only a single item. If you want to include an empty string as one item |
| 5270 | in a list, it must not be the last item. For example, this list contains three |
| 5271 | items, the second of which is empty: |
| 5272 | .code |
| 5273 | senders = user1@domain : : user2@domain |
| 5274 | .endd |
| 5275 | &*Note*&: There must be white space between the two colons, as otherwise they |
| 5276 | are interpreted as representing a single colon data character (and the list |
| 5277 | would then contain just one item). If you want to specify a list that contains |
| 5278 | just one, empty item, you can do it as in this example: |
| 5279 | .code |
| 5280 | senders = : |
| 5281 | .endd |
| 5282 | In this case, the first item is empty, and the second is discarded because it |
| 5283 | is at the end of the list. |
| 5284 | |
| 5285 | |
| 5286 | |
| 5287 | |
| 5288 | .section "Format of driver configurations" "SECTfordricon" |
| 5289 | .cindex "drivers" "configuration format" |
| 5290 | There are separate parts in the configuration for defining routers, transports, |
| 5291 | and authenticators. In each part, you are defining a number of driver |
| 5292 | instances, each with its own set of options. Each driver instance is defined by |
| 5293 | a sequence of lines like this: |
| 5294 | .display |
| 5295 | <&'instance name'&>: |
| 5296 | <&'option'&> |
| 5297 | ... |
| 5298 | <&'option'&> |
| 5299 | .endd |
| 5300 | In the following example, the instance name is &(localuser)&, and it is |
| 5301 | followed by three options settings: |
| 5302 | .code |
| 5303 | localuser: |
| 5304 | driver = accept |
| 5305 | check_local_user |
| 5306 | transport = local_delivery |
| 5307 | .endd |
| 5308 | For each driver instance, you specify which Exim code module it uses &-- by the |
| 5309 | setting of the &%driver%& option &-- and (optionally) some configuration |
| 5310 | settings. For example, in the case of transports, if you want a transport to |
| 5311 | deliver with SMTP you would use the &(smtp)& driver; if you want to deliver to |
| 5312 | a local file you would use the &(appendfile)& driver. Each of the drivers is |
| 5313 | described in detail in its own separate chapter later in this manual. |
| 5314 | |
| 5315 | You can have several routers, transports, or authenticators that are based on |
| 5316 | the same underlying driver (each must have a different instance name). |
| 5317 | |
| 5318 | The order in which routers are defined is important, because addresses are |
| 5319 | passed to individual routers one by one, in order. The order in which |
| 5320 | transports are defined does not matter at all. The order in which |
| 5321 | authenticators are defined is used only when Exim, as a client, is searching |
| 5322 | them to find one that matches an authentication mechanism offered by the |
| 5323 | server. |
| 5324 | |
| 5325 | .cindex "generic options" |
| 5326 | .cindex "options" "generic &-- definition of" |
| 5327 | Within a driver instance definition, there are two kinds of option: &'generic'& |
| 5328 | and &'private'&. The generic options are those that apply to all drivers of the |
| 5329 | same type (that is, all routers, all transports or all authenticators). The |
| 5330 | &%driver%& option is a generic option that must appear in every definition. |
| 5331 | .cindex "private options" |
| 5332 | The private options are special for each driver, and none need appear, because |
| 5333 | they all have default values. |
| 5334 | |
| 5335 | The options may appear in any order, except that the &%driver%& option must |
| 5336 | precede any private options, since these depend on the particular driver. For |
| 5337 | this reason, it is recommended that &%driver%& always be the first option. |
| 5338 | |
| 5339 | Driver instance names, which are used for reference in log entries and |
| 5340 | elsewhere, can be any sequence of letters, digits, and underscores (starting |
| 5341 | with a letter) and must be unique among drivers of the same type. A router and |
| 5342 | a transport (for example) can each have the same name, but no two router |
| 5343 | instances can have the same name. The name of a driver instance should not be |
| 5344 | confused with the name of the underlying driver module. For example, the |
| 5345 | configuration lines: |
| 5346 | .code |
| 5347 | remote_smtp: |
| 5348 | driver = smtp |
| 5349 | .endd |
| 5350 | create an instance of the &(smtp)& transport driver whose name is |
| 5351 | &(remote_smtp)&. The same driver code can be used more than once, with |
| 5352 | different instance names and different option settings each time. A second |
| 5353 | instance of the &(smtp)& transport, with different options, might be defined |
| 5354 | thus: |
| 5355 | .code |
| 5356 | special_smtp: |
| 5357 | driver = smtp |
| 5358 | port = 1234 |
| 5359 | command_timeout = 10s |
| 5360 | .endd |
| 5361 | The names &(remote_smtp)& and &(special_smtp)& would be used to reference |
| 5362 | these transport instances from routers, and these names would appear in log |
| 5363 | lines. |
| 5364 | |
| 5365 | Comment lines may be present in the middle of driver specifications. The full |
| 5366 | list of option settings for any particular driver instance, including all the |
| 5367 | defaulted values, can be extracted by making use of the &%-bP%& command line |
| 5368 | option. |
| 5369 | |
| 5370 | |
| 5371 | |
| 5372 | |
| 5373 | |
| 5374 | |
| 5375 | . //////////////////////////////////////////////////////////////////////////// |
| 5376 | . //////////////////////////////////////////////////////////////////////////// |
| 5377 | |
| 5378 | .chapter "The default configuration file" "CHAPdefconfil" |
| 5379 | .scindex IIDconfiwal "configuration file" "default &""walk through""&" |
| 5380 | .cindex "default" "configuration file &""walk through""&" |
| 5381 | The default configuration file supplied with Exim as &_src/configure.default_& |
| 5382 | is sufficient for a host with simple mail requirements. As an introduction to |
| 5383 | the way Exim is configured, this chapter &"walks through"& the default |
| 5384 | configuration, giving brief explanations of the settings. Detailed descriptions |
| 5385 | of the options are given in subsequent chapters. The default configuration file |
| 5386 | itself contains extensive comments about ways you might want to modify the |
| 5387 | initial settings. However, note that there are many options that are not |
| 5388 | mentioned at all in the default configuration. |
| 5389 | |
| 5390 | |
| 5391 | |
| 5392 | .section "Main configuration settings" "SECTdefconfmain" |
| 5393 | The main (global) configuration option settings must always come first in the |
| 5394 | file. The first thing you'll see in the file, after some initial comments, is |
| 5395 | the line |
| 5396 | .code |
| 5397 | # primary_hostname = |
| 5398 | .endd |
| 5399 | This is a commented-out setting of the &%primary_hostname%& option. Exim needs |
| 5400 | to know the official, fully qualified name of your host, and this is where you |
| 5401 | can specify it. However, in most cases you do not need to set this option. When |
| 5402 | it is unset, Exim uses the &[uname()]& system function to obtain the host name. |
| 5403 | |
| 5404 | The first three non-comment configuration lines are as follows: |
| 5405 | .code |
| 5406 | domainlist local_domains = @ |
| 5407 | domainlist relay_to_domains = |
| 5408 | hostlist relay_from_hosts = 127.0.0.1 |
| 5409 | .endd |
| 5410 | These are not, in fact, option settings. They are definitions of two named |
| 5411 | domain lists and one named host list. Exim allows you to give names to lists of |
| 5412 | domains, hosts, and email addresses, in order to make it easier to manage the |
| 5413 | configuration file (see section &<<SECTnamedlists>>&). |
| 5414 | |
| 5415 | The first line defines a domain list called &'local_domains'&; this is used |
| 5416 | later in the configuration to identify domains that are to be delivered |
| 5417 | on the local host. |
| 5418 | |
| 5419 | .cindex "@ in a domain list" |
| 5420 | There is just one item in this list, the string &"@"&. This is a special form |
| 5421 | of entry which means &"the name of the local host"&. Thus, if the local host is |
| 5422 | called &'a.host.example'&, mail to &'any.user@a.host.example'& is expected to |
| 5423 | be delivered locally. Because the local host's name is referenced indirectly, |
| 5424 | the same configuration file can be used on different hosts. |
| 5425 | |
| 5426 | The second line defines a domain list called &'relay_to_domains'&, but the |
| 5427 | list itself is empty. Later in the configuration we will come to the part that |
| 5428 | controls mail relaying through the local host; it allows relaying to any |
| 5429 | domains in this list. By default, therefore, no relaying on the basis of a mail |
| 5430 | domain is permitted. |
| 5431 | |
| 5432 | The third line defines a host list called &'relay_from_hosts'&. This list is |
| 5433 | used later in the configuration to permit relaying from any host or IP address |
| 5434 | that matches the list. The default contains just the IP address of the IPv4 |
| 5435 | loopback interface, which means that processes on the local host are able to |
| 5436 | submit mail for relaying by sending it over TCP/IP to that interface. No other |
| 5437 | hosts are permitted to submit messages for relaying. |
| 5438 | |
| 5439 | Just to be sure there's no misunderstanding: at this point in the configuration |
| 5440 | we aren't actually setting up any controls. We are just defining some domains |
| 5441 | and hosts that will be used in the controls that are specified later. |
| 5442 | |
| 5443 | The next two configuration lines are genuine option settings: |
| 5444 | .code |
| 5445 | acl_smtp_rcpt = acl_check_rcpt |
| 5446 | acl_smtp_data = acl_check_data |
| 5447 | .endd |
| 5448 | These options specify &'Access Control Lists'& (ACLs) that are to be used |
| 5449 | during an incoming SMTP session for every recipient of a message (every RCPT |
| 5450 | command), and after the contents of the message have been received, |
| 5451 | respectively. The names of the lists are &'acl_check_rcpt'& and |
| 5452 | &'acl_check_data'&, and we will come to their definitions below, in the ACL |
| 5453 | section of the configuration. The RCPT ACL controls which recipients are |
| 5454 | accepted for an incoming message &-- if a configuration does not provide an ACL |
| 5455 | to check recipients, no SMTP mail can be accepted. The DATA ACL allows the |
| 5456 | contents of a message to be checked. |
| 5457 | |
| 5458 | Two commented-out option settings are next: |
| 5459 | .code |
| 5460 | # av_scanner = clamd:/tmp/clamd |
| 5461 | # spamd_address = 127.0.0.1 783 |
| 5462 | .endd |
| 5463 | These are example settings that can be used when Exim is compiled with the |
| 5464 | content-scanning extension. The first specifies the interface to the virus |
| 5465 | scanner, and the second specifies the interface to SpamAssassin. Further |
| 5466 | details are given in chapter &<<CHAPexiscan>>&. |
| 5467 | |
| 5468 | Three more commented-out option settings follow: |
| 5469 | .code |
| 5470 | # tls_advertise_hosts = * |
| 5471 | # tls_certificate = /etc/ssl/exim.crt |
| 5472 | # tls_privatekey = /etc/ssl/exim.pem |
| 5473 | .endd |
| 5474 | These are example settings that can be used when Exim is compiled with |
| 5475 | support for TLS (aka SSL) as described in section &<<SECTinctlsssl>>&. The |
| 5476 | first one specifies the list of clients that are allowed to use TLS when |
| 5477 | connecting to this server; in this case the wildcard means all clients. The |
| 5478 | other options specify where Exim should find its TLS certificate and private |
| 5479 | key, which together prove the server's identity to any clients that connect. |
| 5480 | More details are given in chapter &<<CHAPTLS>>&. |
| 5481 | |
| 5482 | Another two commented-out option settings follow: |
| 5483 | .code |
| 5484 | # daemon_smtp_ports = 25 : 465 : 587 |
| 5485 | # tls_on_connect_ports = 465 |
| 5486 | .endd |
| 5487 | .cindex "port" "465 and 587" |
| 5488 | .cindex "port" "for message submission" |
| 5489 | .cindex "message" "submission, ports for" |
| 5490 | .cindex "ssmtp protocol" |
| 5491 | .cindex "smtps protocol" |
| 5492 | .cindex "SMTP" "ssmtp protocol" |
| 5493 | .cindex "SMTP" "smtps protocol" |
| 5494 | These options provide better support for roaming users who wish to use this |
| 5495 | server for message submission. They are not much use unless you have turned on |
| 5496 | TLS (as described in the previous paragraph) and authentication (about which |
| 5497 | more in section &<<SECTdefconfauth>>&). The usual SMTP port 25 is often blocked |
| 5498 | on end-user networks, so RFC 4409 specifies that message submission should use |
| 5499 | port 587 instead. However some software (notably Microsoft Outlook) cannot be |
| 5500 | configured to use port 587 correctly, so these settings also enable the |
| 5501 | non-standard &"smtps"& (aka &"ssmtp"&) port 465 (see section |
| 5502 | &<<SECTsupobssmt>>&). |
| 5503 | |
| 5504 | Two more commented-out options settings follow: |
| 5505 | .code |
| 5506 | # qualify_domain = |
| 5507 | # qualify_recipient = |
| 5508 | .endd |
| 5509 | The first of these specifies a domain that Exim uses when it constructs a |
| 5510 | complete email address from a local login name. This is often needed when Exim |
| 5511 | receives a message from a local process. If you do not set &%qualify_domain%&, |
| 5512 | the value of &%primary_hostname%& is used. If you set both of these options, |
| 5513 | you can have different qualification domains for sender and recipient |
| 5514 | addresses. If you set only the first one, its value is used in both cases. |
| 5515 | |
| 5516 | .cindex "domain literal" "recognizing format" |
| 5517 | The following line must be uncommented if you want Exim to recognize |
| 5518 | addresses of the form &'user@[10.11.12.13]'& that is, with a &"domain literal"& |
| 5519 | (an IP address within square brackets) instead of a named domain. |
| 5520 | .code |
| 5521 | # allow_domain_literals |
| 5522 | .endd |
| 5523 | The RFCs still require this form, but many people think that in the modern |
| 5524 | Internet it makes little sense to permit mail to be sent to specific hosts by |
| 5525 | quoting their IP addresses. This ancient format has been used by people who |
| 5526 | try to abuse hosts by using them for unwanted relaying. However, some |
| 5527 | people believe there are circumstances (for example, messages addressed to |
| 5528 | &'postmaster'&) where domain literals are still useful. |
| 5529 | |
| 5530 | The next configuration line is a kind of trigger guard: |
| 5531 | .code |
| 5532 | never_users = root |
| 5533 | .endd |
| 5534 | It specifies that no delivery must ever be run as the root user. The normal |
| 5535 | convention is to set up &'root'& as an alias for the system administrator. This |
| 5536 | setting is a guard against slips in the configuration. |
| 5537 | The list of users specified by &%never_users%& is not, however, the complete |
| 5538 | list; the build-time configuration in &_Local/Makefile_& has an option called |
| 5539 | FIXED_NEVER_USERS specifying a list that cannot be overridden. The |
| 5540 | contents of &%never_users%& are added to this list. By default |
| 5541 | FIXED_NEVER_USERS also specifies root. |
| 5542 | |
| 5543 | When a remote host connects to Exim in order to send mail, the only information |
| 5544 | Exim has about the host's identity is its IP address. The next configuration |
| 5545 | line, |
| 5546 | .code |
| 5547 | host_lookup = * |
| 5548 | .endd |
| 5549 | specifies that Exim should do a reverse DNS lookup on all incoming connections, |
| 5550 | in order to get a host name. This improves the quality of the logging |
| 5551 | information, but if you feel it is too expensive, you can remove it entirely, |
| 5552 | or restrict the lookup to hosts on &"nearby"& networks. |
| 5553 | Note that it is not always possible to find a host name from an IP address, |
| 5554 | because not all DNS reverse zones are maintained, and sometimes DNS servers are |
| 5555 | unreachable. |
| 5556 | |
| 5557 | The next two lines are concerned with &'ident'& callbacks, as defined by RFC |
| 5558 | 1413 (hence their names): |
| 5559 | .code |
| 5560 | rfc1413_query_hosts = * |
| 5561 | rfc1413_query_timeout = 0s |
| 5562 | .endd |
| 5563 | These settings cause Exim to avoid ident callbacks for all incoming SMTP calls. |
| 5564 | Few hosts offer RFC1413 service these days; calls have to be |
| 5565 | terminated by a timeout and this needlessly delays the startup |
| 5566 | of an incoming SMTP connection. |
| 5567 | If you have hosts for which you trust RFC1413 and need this |
| 5568 | information, you can change this. |
| 5569 | |
| 5570 | This line enables an efficiency SMTP option. It is negociated by clients |
| 5571 | and not expected to cause problems but can be disabled if needed. |
| 5572 | .code |
| 5573 | prdr_enable = true |
| 5574 | .endd |
| 5575 | |
| 5576 | When Exim receives messages over SMTP connections, it expects all addresses to |
| 5577 | be fully qualified with a domain, as required by the SMTP definition. However, |
| 5578 | if you are running a server to which simple clients submit messages, you may |
| 5579 | find that they send unqualified addresses. The two commented-out options: |
| 5580 | .code |
| 5581 | # sender_unqualified_hosts = |
| 5582 | # recipient_unqualified_hosts = |
| 5583 | .endd |
| 5584 | show how you can specify hosts that are permitted to send unqualified sender |
| 5585 | and recipient addresses, respectively. |
| 5586 | |
| 5587 | The &%percent_hack_domains%& option is also commented out: |
| 5588 | .code |
| 5589 | # percent_hack_domains = |
| 5590 | .endd |
| 5591 | It provides a list of domains for which the &"percent hack"& is to operate. |
| 5592 | This is an almost obsolete form of explicit email routing. If you do not know |
| 5593 | anything about it, you can safely ignore this topic. |
| 5594 | |
| 5595 | The last two settings in the main part of the default configuration are |
| 5596 | concerned with messages that have been &"frozen"& on Exim's queue. When a |
| 5597 | message is frozen, Exim no longer continues to try to deliver it. Freezing |
| 5598 | occurs when a bounce message encounters a permanent failure because the sender |
| 5599 | address of the original message that caused the bounce is invalid, so the |
| 5600 | bounce cannot be delivered. This is probably the most common case, but there |
| 5601 | are also other conditions that cause freezing, and frozen messages are not |
| 5602 | always bounce messages. |
| 5603 | .code |
| 5604 | ignore_bounce_errors_after = 2d |
| 5605 | timeout_frozen_after = 7d |
| 5606 | .endd |
| 5607 | The first of these options specifies that failing bounce messages are to be |
| 5608 | discarded after 2 days on the queue. The second specifies that any frozen |
| 5609 | message (whether a bounce message or not) is to be timed out (and discarded) |
| 5610 | after a week. In this configuration, the first setting ensures that no failing |
| 5611 | bounce message ever lasts a week. |
| 5612 | |
| 5613 | |
| 5614 | |
| 5615 | .section "ACL configuration" "SECID54" |
| 5616 | .cindex "default" "ACLs" |
| 5617 | .cindex "&ACL;" "default configuration" |
| 5618 | In the default configuration, the ACL section follows the main configuration. |
| 5619 | It starts with the line |
| 5620 | .code |
| 5621 | begin acl |
| 5622 | .endd |
| 5623 | and it contains the definitions of two ACLs, called &'acl_check_rcpt'& and |
| 5624 | &'acl_check_data'&, that were referenced in the settings of &%acl_smtp_rcpt%& |
| 5625 | and &%acl_smtp_data%& above. |
| 5626 | |
| 5627 | .cindex "RCPT" "ACL for" |
| 5628 | The first ACL is used for every RCPT command in an incoming SMTP message. Each |
| 5629 | RCPT command specifies one of the message's recipients. The ACL statements |
| 5630 | are considered in order, until the recipient address is either accepted or |
| 5631 | rejected. The RCPT command is then accepted or rejected, according to the |
| 5632 | result of the ACL processing. |
| 5633 | .code |
| 5634 | acl_check_rcpt: |
| 5635 | .endd |
| 5636 | This line, consisting of a name terminated by a colon, marks the start of the |
| 5637 | ACL, and names it. |
| 5638 | .code |
| 5639 | accept hosts = : |
| 5640 | .endd |
| 5641 | This ACL statement accepts the recipient if the sending host matches the list. |
| 5642 | But what does that strange list mean? It doesn't actually contain any host |
| 5643 | names or IP addresses. The presence of the colon puts an empty item in the |
| 5644 | list; Exim matches this only if the incoming message did not come from a remote |
| 5645 | host, because in that case, the remote hostname is empty. The colon is |
| 5646 | important. Without it, the list itself is empty, and can never match anything. |
| 5647 | |
| 5648 | What this statement is doing is to accept unconditionally all recipients in |
| 5649 | messages that are submitted by SMTP from local processes using the standard |
| 5650 | input and output (that is, not using TCP/IP). A number of MUAs operate in this |
| 5651 | manner. |
| 5652 | .code |
| 5653 | deny message = Restricted characters in address |
| 5654 | domains = +local_domains |
| 5655 | local_parts = ^[.] : ^.*[@%!/|] |
| 5656 | |
| 5657 | deny message = Restricted characters in address |
| 5658 | domains = !+local_domains |
| 5659 | local_parts = ^[./|] : ^.*[@%!] : ^.*/\\.\\./ |
| 5660 | .endd |
| 5661 | These statements are concerned with local parts that contain any of the |
| 5662 | characters &"@"&, &"%"&, &"!"&, &"/"&, &"|"&, or dots in unusual places. |
| 5663 | Although these characters are entirely legal in local parts (in the case of |
| 5664 | &"@"& and leading dots, only if correctly quoted), they do not commonly occur |
| 5665 | in Internet mail addresses. |
| 5666 | |
| 5667 | The first three have in the past been associated with explicitly routed |
| 5668 | addresses (percent is still sometimes used &-- see the &%percent_hack_domains%& |
| 5669 | option). Addresses containing these characters are regularly tried by spammers |
| 5670 | in an attempt to bypass relaying restrictions, and also by open relay testing |
| 5671 | programs. Unless you really need them it is safest to reject these characters |
| 5672 | at this early stage. This configuration is heavy-handed in rejecting these |
| 5673 | characters for all messages it accepts from remote hosts. This is a deliberate |
| 5674 | policy of being as safe as possible. |
| 5675 | |
| 5676 | The first rule above is stricter, and is applied to messages that are addressed |
| 5677 | to one of the local domains handled by this host. This is implemented by the |
| 5678 | first condition, which restricts it to domains that are listed in the |
| 5679 | &'local_domains'& domain list. The &"+"& character is used to indicate a |
| 5680 | reference to a named list. In this configuration, there is just one domain in |
| 5681 | &'local_domains'&, but in general there may be many. |
| 5682 | |
| 5683 | The second condition on the first statement uses two regular expressions to |
| 5684 | block local parts that begin with a dot or contain &"@"&, &"%"&, &"!"&, &"/"&, |
| 5685 | or &"|"&. If you have local accounts that include these characters, you will |
| 5686 | have to modify this rule. |
| 5687 | |
| 5688 | Empty components (two dots in a row) are not valid in RFC 2822, but Exim |
| 5689 | allows them because they have been encountered in practice. (Consider the |
| 5690 | common convention of local parts constructed as |
| 5691 | &"&'first-initial.second-initial.family-name'&"& when applied to someone like |
| 5692 | the author of Exim, who has no second initial.) However, a local part starting |
| 5693 | with a dot or containing &"/../"& can cause trouble if it is used as part of a |
| 5694 | file name (for example, for a mailing list). This is also true for local parts |
| 5695 | that contain slashes. A pipe symbol can also be troublesome if the local part |
| 5696 | is incorporated unthinkingly into a shell command line. |
| 5697 | |
| 5698 | The second rule above applies to all other domains, and is less strict. This |
| 5699 | allows your own users to send outgoing messages to sites that use slashes |
| 5700 | and vertical bars in their local parts. It blocks local parts that begin |
| 5701 | with a dot, slash, or vertical bar, but allows these characters within the |
| 5702 | local part. However, the sequence &"/../"& is barred. The use of &"@"&, &"%"&, |
| 5703 | and &"!"& is blocked, as before. The motivation here is to prevent your users |
| 5704 | (or your users' viruses) from mounting certain kinds of attack on remote sites. |
| 5705 | .code |
| 5706 | accept local_parts = postmaster |
| 5707 | domains = +local_domains |
| 5708 | .endd |
| 5709 | This statement, which has two conditions, accepts an incoming address if the |
| 5710 | local part is &'postmaster'& and the domain is one of those listed in the |
| 5711 | &'local_domains'& domain list. The &"+"& character is used to indicate a |
| 5712 | reference to a named list. In this configuration, there is just one domain in |
| 5713 | &'local_domains'&, but in general there may be many. |
| 5714 | |
| 5715 | The presence of this statement means that mail to postmaster is never blocked |
| 5716 | by any of the subsequent tests. This can be helpful while sorting out problems |
| 5717 | in cases where the subsequent tests are incorrectly denying access. |
| 5718 | .code |
| 5719 | require verify = sender |
| 5720 | .endd |
| 5721 | This statement requires the sender address to be verified before any subsequent |
| 5722 | ACL statement can be used. If verification fails, the incoming recipient |
| 5723 | address is refused. Verification consists of trying to route the address, to |
| 5724 | see if a bounce message could be delivered to it. In the case of remote |
| 5725 | addresses, basic verification checks only the domain, but &'callouts'& can be |
| 5726 | used for more verification if required. Section &<<SECTaddressverification>>& |
| 5727 | discusses the details of address verification. |
| 5728 | .code |
| 5729 | accept hosts = +relay_from_hosts |
| 5730 | control = submission |
| 5731 | .endd |
| 5732 | This statement accepts the address if the message is coming from one of the |
| 5733 | hosts that are defined as being allowed to relay through this host. Recipient |
| 5734 | verification is omitted here, because in many cases the clients are dumb MUAs |
| 5735 | that do not cope well with SMTP error responses. For the same reason, the |
| 5736 | second line specifies &"submission mode"& for messages that are accepted. This |
| 5737 | is described in detail in section &<<SECTsubmodnon>>&; it causes Exim to fix |
| 5738 | messages that are deficient in some way, for example, because they lack a |
| 5739 | &'Date:'& header line. If you are actually relaying out from MTAs, you should |
| 5740 | probably add recipient verification here, and disable submission mode. |
| 5741 | .code |
| 5742 | accept authenticated = * |
| 5743 | control = submission |
| 5744 | .endd |
| 5745 | This statement accepts the address if the client host has authenticated itself. |
| 5746 | Submission mode is again specified, on the grounds that such messages are most |
| 5747 | likely to come from MUAs. The default configuration does not define any |
| 5748 | authenticators, though it does include some nearly complete commented-out |
| 5749 | examples described in &<<SECTdefconfauth>>&. This means that no client can in |
| 5750 | fact authenticate until you complete the authenticator definitions. |
| 5751 | .code |
| 5752 | require message = relay not permitted |
| 5753 | domains = +local_domains : +relay_to_domains |
| 5754 | .endd |
| 5755 | This statement rejects the address if its domain is neither a local domain nor |
| 5756 | one of the domains for which this host is a relay. |
| 5757 | .code |
| 5758 | require verify = recipient |
| 5759 | .endd |
| 5760 | This statement requires the recipient address to be verified; if verification |
| 5761 | fails, the address is rejected. |
| 5762 | .code |
| 5763 | # deny message = rejected because $sender_host_address \ |
| 5764 | # is in a black list at $dnslist_domain\n\ |
| 5765 | # $dnslist_text |
| 5766 | # dnslists = black.list.example |
| 5767 | # |
| 5768 | # warn dnslists = black.list.example |
| 5769 | # add_header = X-Warning: $sender_host_address is in \ |
| 5770 | # a black list at $dnslist_domain |
| 5771 | # log_message = found in $dnslist_domain |
| 5772 | .endd |
| 5773 | These commented-out lines are examples of how you could configure Exim to check |
| 5774 | sending hosts against a DNS black list. The first statement rejects messages |
| 5775 | from blacklisted hosts, whereas the second just inserts a warning header |
| 5776 | line. |
| 5777 | .code |
| 5778 | # require verify = csa |
| 5779 | .endd |
| 5780 | This commented-out line is an example of how you could turn on client SMTP |
| 5781 | authorization (CSA) checking. Such checks do DNS lookups for special SRV |
| 5782 | records. |
| 5783 | .code |
| 5784 | accept |
| 5785 | .endd |
| 5786 | The final statement in the first ACL unconditionally accepts any recipient |
| 5787 | address that has successfully passed all the previous tests. |
| 5788 | .code |
| 5789 | acl_check_data: |
| 5790 | .endd |
| 5791 | This line marks the start of the second ACL, and names it. Most of the contents |
| 5792 | of this ACL are commented out: |
| 5793 | .code |
| 5794 | # deny malware = * |
| 5795 | # message = This message contains a virus \ |
| 5796 | # ($malware_name). |
| 5797 | .endd |
| 5798 | These lines are examples of how to arrange for messages to be scanned for |
| 5799 | viruses when Exim has been compiled with the content-scanning extension, and a |
| 5800 | suitable virus scanner is installed. If the message is found to contain a |
| 5801 | virus, it is rejected with the given custom error message. |
| 5802 | .code |
| 5803 | # warn spam = nobody |
| 5804 | # message = X-Spam_score: $spam_score\n\ |
| 5805 | # X-Spam_score_int: $spam_score_int\n\ |
| 5806 | # X-Spam_bar: $spam_bar\n\ |
| 5807 | # X-Spam_report: $spam_report |
| 5808 | .endd |
| 5809 | These lines are an example of how to arrange for messages to be scanned by |
| 5810 | SpamAssassin when Exim has been compiled with the content-scanning extension, |
| 5811 | and SpamAssassin has been installed. The SpamAssassin check is run with |
| 5812 | &`nobody`& as its user parameter, and the results are added to the message as a |
| 5813 | series of extra header line. In this case, the message is not rejected, |
| 5814 | whatever the spam score. |
| 5815 | .code |
| 5816 | accept |
| 5817 | .endd |
| 5818 | This final line in the DATA ACL accepts the message unconditionally. |
| 5819 | |
| 5820 | |
| 5821 | .section "Router configuration" "SECID55" |
| 5822 | .cindex "default" "routers" |
| 5823 | .cindex "routers" "default" |
| 5824 | The router configuration comes next in the default configuration, introduced |
| 5825 | by the line |
| 5826 | .code |
| 5827 | begin routers |
| 5828 | .endd |
| 5829 | Routers are the modules in Exim that make decisions about where to send |
| 5830 | messages. An address is passed to each router in turn, until it is either |
| 5831 | accepted, or failed. This means that the order in which you define the routers |
| 5832 | matters. Each router is fully described in its own chapter later in this |
| 5833 | manual. Here we give only brief overviews. |
| 5834 | .code |
| 5835 | # domain_literal: |
| 5836 | # driver = ipliteral |
| 5837 | # domains = !+local_domains |
| 5838 | # transport = remote_smtp |
| 5839 | .endd |
| 5840 | .cindex "domain literal" "default router" |
| 5841 | This router is commented out because the majority of sites do not want to |
| 5842 | support domain literal addresses (those of the form &'user@[10.9.8.7]'&). If |
| 5843 | you uncomment this router, you also need to uncomment the setting of |
| 5844 | &%allow_domain_literals%& in the main part of the configuration. |
| 5845 | .code |
| 5846 | dnslookup: |
| 5847 | driver = dnslookup |
| 5848 | domains = ! +local_domains |
| 5849 | transport = remote_smtp |
| 5850 | ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8 |
| 5851 | no_more |
| 5852 | .endd |
| 5853 | The first uncommented router handles addresses that do not involve any local |
| 5854 | domains. This is specified by the line |
| 5855 | .code |
| 5856 | domains = ! +local_domains |
| 5857 | .endd |
| 5858 | The &%domains%& option lists the domains to which this router applies, but the |
| 5859 | exclamation mark is a negation sign, so the router is used only for domains |
| 5860 | that are not in the domain list called &'local_domains'& (which was defined at |
| 5861 | the start of the configuration). The plus sign before &'local_domains'& |
| 5862 | indicates that it is referring to a named list. Addresses in other domains are |
| 5863 | passed on to the following routers. |
| 5864 | |
| 5865 | The name of the router driver is &(dnslookup)&, |
| 5866 | and is specified by the &%driver%& option. Do not be confused by the fact that |
| 5867 | the name of this router instance is the same as the name of the driver. The |
| 5868 | instance name is arbitrary, but the name set in the &%driver%& option must be |
| 5869 | one of the driver modules that is in the Exim binary. |
| 5870 | |
| 5871 | The &(dnslookup)& router routes addresses by looking up their domains in the |
| 5872 | DNS in order to obtain a list of hosts to which the address is routed. If the |
| 5873 | router succeeds, the address is queued for the &(remote_smtp)& transport, as |
| 5874 | specified by the &%transport%& option. If the router does not find the domain |
| 5875 | in the DNS, no further routers are tried because of the &%no_more%& setting, so |
| 5876 | the address fails and is bounced. |
| 5877 | |
| 5878 | The &%ignore_target_hosts%& option specifies a list of IP addresses that are to |
| 5879 | be entirely ignored. This option is present because a number of cases have been |
| 5880 | encountered where MX records in the DNS point to host names |
| 5881 | whose IP addresses are 0.0.0.0 or are in the 127 subnet (typically 127.0.0.1). |
| 5882 | Completely ignoring these IP addresses causes Exim to fail to route the |
| 5883 | email address, so it bounces. Otherwise, Exim would log a routing problem, and |
| 5884 | continue to try to deliver the message periodically until the address timed |
| 5885 | out. |
| 5886 | .code |
| 5887 | system_aliases: |
| 5888 | driver = redirect |
| 5889 | allow_fail |
| 5890 | allow_defer |
| 5891 | data = ${lookup{$local_part}lsearch{/etc/aliases}} |
| 5892 | # user = exim |
| 5893 | file_transport = address_file |
| 5894 | pipe_transport = address_pipe |
| 5895 | .endd |
| 5896 | Control reaches this and subsequent routers only for addresses in the local |
| 5897 | domains. This router checks to see whether the local part is defined as an |
| 5898 | alias in the &_/etc/aliases_& file, and if so, redirects it according to the |
| 5899 | data that it looks up from that file. If no data is found for the local part, |
| 5900 | the value of the &%data%& option is empty, causing the address to be passed to |
| 5901 | the next router. |
| 5902 | |
| 5903 | &_/etc/aliases_& is a conventional name for the system aliases file that is |
| 5904 | often used. That is why it is referenced by from the default configuration |
| 5905 | file. However, you can change this by setting SYSTEM_ALIASES_FILE in |
| 5906 | &_Local/Makefile_& before building Exim. |
| 5907 | .code |
| 5908 | userforward: |
| 5909 | driver = redirect |
| 5910 | check_local_user |
| 5911 | # local_part_suffix = +* : -* |
| 5912 | # local_part_suffix_optional |
| 5913 | file = $home/.forward |
| 5914 | # allow_filter |
| 5915 | no_verify |
| 5916 | no_expn |
| 5917 | check_ancestor |
| 5918 | file_transport = address_file |
| 5919 | pipe_transport = address_pipe |
| 5920 | reply_transport = address_reply |
| 5921 | .endd |
| 5922 | This is the most complicated router in the default configuration. It is another |
| 5923 | redirection router, but this time it is looking for forwarding data set up by |
| 5924 | individual users. The &%check_local_user%& setting specifies a check that the |
| 5925 | local part of the address is the login name of a local user. If it is not, the |
| 5926 | router is skipped. The two commented options that follow &%check_local_user%&, |
| 5927 | namely: |
| 5928 | .code |
| 5929 | # local_part_suffix = +* : -* |
| 5930 | # local_part_suffix_optional |
| 5931 | .endd |
| 5932 | .vindex "&$local_part_suffix$&" |
| 5933 | show how you can specify the recognition of local part suffixes. If the first |
| 5934 | is uncommented, a suffix beginning with either a plus or a minus sign, followed |
| 5935 | by any sequence of characters, is removed from the local part and placed in the |
| 5936 | variable &$local_part_suffix$&. The second suffix option specifies that the |
| 5937 | presence of a suffix in the local part is optional. When a suffix is present, |
| 5938 | the check for a local login uses the local part with the suffix removed. |
| 5939 | |
| 5940 | When a local user account is found, the file called &_.forward_& in the user's |
| 5941 | home directory is consulted. If it does not exist, or is empty, the router |
| 5942 | declines. Otherwise, the contents of &_.forward_& are interpreted as |
| 5943 | redirection data (see chapter &<<CHAPredirect>>& for more details). |
| 5944 | |
| 5945 | .cindex "Sieve filter" "enabling in default router" |
| 5946 | Traditional &_.forward_& files contain just a list of addresses, pipes, or |
| 5947 | files. Exim supports this by default. However, if &%allow_filter%& is set (it |
| 5948 | is commented out by default), the contents of the file are interpreted as a set |
| 5949 | of Exim or Sieve filtering instructions, provided the file begins with &"#Exim |
| 5950 | filter"& or &"#Sieve filter"&, respectively. User filtering is discussed in the |
| 5951 | separate document entitled &'Exim's interfaces to mail filtering'&. |
| 5952 | |
| 5953 | The &%no_verify%& and &%no_expn%& options mean that this router is skipped when |
| 5954 | verifying addresses, or when running as a consequence of an SMTP EXPN command. |
| 5955 | There are two reasons for doing this: |
| 5956 | |
| 5957 | .olist |
| 5958 | Whether or not a local user has a &_.forward_& file is not really relevant when |
| 5959 | checking an address for validity; it makes sense not to waste resources doing |
| 5960 | unnecessary work. |
| 5961 | .next |
| 5962 | More importantly, when Exim is verifying addresses or handling an EXPN |
| 5963 | command during an SMTP session, it is running as the Exim user, not as root. |
| 5964 | The group is the Exim group, and no additional groups are set up. |
| 5965 | It may therefore not be possible for Exim to read users' &_.forward_& files at |
| 5966 | this time. |
| 5967 | .endlist |
| 5968 | |
| 5969 | The setting of &%check_ancestor%& prevents the router from generating a new |
| 5970 | address that is the same as any previous address that was redirected. (This |
| 5971 | works round a problem concerning a bad interaction between aliasing and |
| 5972 | forwarding &-- see section &<<SECTredlocmai>>&). |
| 5973 | |
| 5974 | The final three option settings specify the transports that are to be used when |
| 5975 | forwarding generates a direct delivery to a file, or to a pipe, or sets up an |
| 5976 | auto-reply, respectively. For example, if a &_.forward_& file contains |
| 5977 | .code |
| 5978 | a.nother@elsewhere.example, /home/spqr/archive |
| 5979 | .endd |
| 5980 | the delivery to &_/home/spqr/archive_& is done by running the &%address_file%& |
| 5981 | transport. |
| 5982 | .code |
| 5983 | localuser: |
| 5984 | driver = accept |
| 5985 | check_local_user |
| 5986 | # local_part_suffix = +* : -* |
| 5987 | # local_part_suffix_optional |
| 5988 | transport = local_delivery |
| 5989 | .endd |
| 5990 | The final router sets up delivery into local mailboxes, provided that the local |
| 5991 | part is the name of a local login, by accepting the address and assigning it to |
| 5992 | the &(local_delivery)& transport. Otherwise, we have reached the end of the |
| 5993 | routers, so the address is bounced. The commented suffix settings fulfil the |
| 5994 | same purpose as they do for the &(userforward)& router. |
| 5995 | |
| 5996 | |
| 5997 | .section "Transport configuration" "SECID56" |
| 5998 | .cindex "default" "transports" |
| 5999 | .cindex "transports" "default" |
| 6000 | Transports define mechanisms for actually delivering messages. They operate |
| 6001 | only when referenced from routers, so the order in which they are defined does |
| 6002 | not matter. The transports section of the configuration starts with |
| 6003 | .code |
| 6004 | begin transports |
| 6005 | .endd |
| 6006 | One remote transport and four local transports are defined. |
| 6007 | .code |
| 6008 | remote_smtp: |
| 6009 | driver = smtp |
| 6010 | hosts_try_prdr = * |
| 6011 | .endd |
| 6012 | This transport is used for delivering messages over SMTP connections. |
| 6013 | The list of remote hosts comes from the router. |
| 6014 | The &%hosts_try_prdr%& option enables an efficiency SMTP option. |
| 6015 | It is negotiated between client and server |
| 6016 | and not expected to cause problems but can be disabled if needed. |
| 6017 | All other options are defaulted. |
| 6018 | .code |
| 6019 | local_delivery: |
| 6020 | driver = appendfile |
| 6021 | file = /var/mail/$local_part |
| 6022 | delivery_date_add |
| 6023 | envelope_to_add |
| 6024 | return_path_add |
| 6025 | # group = mail |
| 6026 | # mode = 0660 |
| 6027 | .endd |
| 6028 | This &(appendfile)& transport is used for local delivery to user mailboxes in |
| 6029 | traditional BSD mailbox format. By default it runs under the uid and gid of the |
| 6030 | local user, which requires the sticky bit to be set on the &_/var/mail_& |
| 6031 | directory. Some systems use the alternative approach of running mail deliveries |
| 6032 | under a particular group instead of using the sticky bit. The commented options |
| 6033 | show how this can be done. |
| 6034 | |
| 6035 | Exim adds three headers to the message as it delivers it: &'Delivery-date:'&, |
| 6036 | &'Envelope-to:'& and &'Return-path:'&. This action is requested by the three |
| 6037 | similarly-named options above. |
| 6038 | .code |
| 6039 | address_pipe: |
| 6040 | driver = pipe |
| 6041 | return_output |
| 6042 | .endd |
| 6043 | This transport is used for handling deliveries to pipes that are generated by |
| 6044 | redirection (aliasing or users' &_.forward_& files). The &%return_output%& |
| 6045 | option specifies that any output generated by the pipe is to be returned to the |
| 6046 | sender. |
| 6047 | .code |
| 6048 | address_file: |
| 6049 | driver = appendfile |
| 6050 | delivery_date_add |
| 6051 | envelope_to_add |
| 6052 | return_path_add |
| 6053 | .endd |
| 6054 | This transport is used for handling deliveries to files that are generated by |
| 6055 | redirection. The name of the file is not specified in this instance of |
| 6056 | &(appendfile)&, because it comes from the &(redirect)& router. |
| 6057 | .code |
| 6058 | address_reply: |
| 6059 | driver = autoreply |
| 6060 | .endd |
| 6061 | This transport is used for handling automatic replies generated by users' |
| 6062 | filter files. |
| 6063 | |
| 6064 | |
| 6065 | |
| 6066 | .section "Default retry rule" "SECID57" |
| 6067 | .cindex "retry" "default rule" |
| 6068 | .cindex "default" "retry rule" |
| 6069 | The retry section of the configuration file contains rules which affect the way |
| 6070 | Exim retries deliveries that cannot be completed at the first attempt. It is |
| 6071 | introduced by the line |
| 6072 | .code |
| 6073 | begin retry |
| 6074 | .endd |
| 6075 | In the default configuration, there is just one rule, which applies to all |
| 6076 | errors: |
| 6077 | .code |
| 6078 | * * F,2h,15m; G,16h,1h,1.5; F,4d,6h |
| 6079 | .endd |
| 6080 | This causes any temporarily failing address to be retried every 15 minutes for |
| 6081 | 2 hours, then at intervals starting at one hour and increasing by a factor of |
| 6082 | 1.5 until 16 hours have passed, then every 6 hours up to 4 days. If an address |
| 6083 | is not delivered after 4 days of temporary failure, it is bounced. |
| 6084 | |
| 6085 | If the retry section is removed from the configuration, or is empty (that is, |
| 6086 | if no retry rules are defined), Exim will not retry deliveries. This turns |
| 6087 | temporary errors into permanent errors. |
| 6088 | |
| 6089 | |
| 6090 | .section "Rewriting configuration" "SECID58" |
| 6091 | The rewriting section of the configuration, introduced by |
| 6092 | .code |
| 6093 | begin rewrite |
| 6094 | .endd |
| 6095 | contains rules for rewriting addresses in messages as they arrive. There are no |
| 6096 | rewriting rules in the default configuration file. |
| 6097 | |
| 6098 | |
| 6099 | |
| 6100 | .section "Authenticators configuration" "SECTdefconfauth" |
| 6101 | .cindex "AUTH" "configuration" |
| 6102 | The authenticators section of the configuration, introduced by |
| 6103 | .code |
| 6104 | begin authenticators |
| 6105 | .endd |
| 6106 | defines mechanisms for the use of the SMTP AUTH command. The default |
| 6107 | configuration file contains two commented-out example authenticators |
| 6108 | which support plaintext username/password authentication using the |
| 6109 | standard PLAIN mechanism and the traditional but non-standard LOGIN |
| 6110 | mechanism, with Exim acting as the server. PLAIN and LOGIN are enough |
| 6111 | to support most MUA software. |
| 6112 | |
| 6113 | The example PLAIN authenticator looks like this: |
| 6114 | .code |
| 6115 | #PLAIN: |
| 6116 | # driver = plaintext |
| 6117 | # server_set_id = $auth2 |
| 6118 | # server_prompts = : |
| 6119 | # server_condition = Authentication is not yet configured |
| 6120 | # server_advertise_condition = ${if def:tls_in_cipher } |
| 6121 | .endd |
| 6122 | And the example LOGIN authenticator looks like this: |
| 6123 | .code |
| 6124 | #LOGIN: |
| 6125 | # driver = plaintext |
| 6126 | # server_set_id = $auth1 |
| 6127 | # server_prompts = <| Username: | Password: |
| 6128 | # server_condition = Authentication is not yet configured |
| 6129 | # server_advertise_condition = ${if def:tls_in_cipher } |
| 6130 | .endd |
| 6131 | |
| 6132 | The &%server_set_id%& option makes Exim remember the authenticated username |
| 6133 | in &$authenticated_id$&, which can be used later in ACLs or routers. The |
| 6134 | &%server_prompts%& option configures the &(plaintext)& authenticator so |
| 6135 | that it implements the details of the specific authentication mechanism, |
| 6136 | i.e. PLAIN or LOGIN. The &%server_advertise_condition%& setting controls |
| 6137 | when Exim offers authentication to clients; in the examples, this is only |
| 6138 | when TLS or SSL has been started, so to enable the authenticators you also |
| 6139 | need to add support for TLS as described in section &<<SECTdefconfmain>>&. |
| 6140 | |
| 6141 | The &%server_condition%& setting defines how to verify that the username and |
| 6142 | password are correct. In the examples it just produces an error message. |
| 6143 | To make the authenticators work, you can use a string expansion |
| 6144 | expression like one of the examples in chapter &<<CHAPplaintext>>&. |
| 6145 | |
| 6146 | Beware that the sequence of the parameters to PLAIN and LOGIN differ; the |
| 6147 | usercode and password are in different positions. |
| 6148 | Chapter &<<CHAPplaintext>>& covers both. |
| 6149 | |
| 6150 | .ecindex IIDconfiwal |
| 6151 | |
| 6152 | |
| 6153 | |
| 6154 | . //////////////////////////////////////////////////////////////////////////// |
| 6155 | . //////////////////////////////////////////////////////////////////////////// |
| 6156 | |
| 6157 | .chapter "Regular expressions" "CHAPregexp" |
| 6158 | |
| 6159 | .cindex "regular expressions" "library" |
| 6160 | .cindex "PCRE" |
| 6161 | Exim supports the use of regular expressions in many of its options. It |
| 6162 | uses the PCRE regular expression library; this provides regular expression |
| 6163 | matching that is compatible with Perl 5. The syntax and semantics of |
| 6164 | regular expressions is discussed in many Perl reference books, and also in |
| 6165 | Jeffrey Friedl's &'Mastering Regular Expressions'&, which is published by |
| 6166 | O'Reilly (see &url(http://www.oreilly.com/catalog/regex2/)). |
| 6167 | |
| 6168 | The documentation for the syntax and semantics of the regular expressions that |
| 6169 | are supported by PCRE is included in the PCRE distribution, and no further |
| 6170 | description is included here. The PCRE functions are called from Exim using |
| 6171 | the default option settings (that is, with no PCRE options set), except that |
| 6172 | the PCRE_CASELESS option is set when the matching is required to be |
| 6173 | case-insensitive. |
| 6174 | |
| 6175 | In most cases, when a regular expression is required in an Exim configuration, |
| 6176 | it has to start with a circumflex, in order to distinguish it from plain text |
| 6177 | or an &"ends with"& wildcard. In this example of a configuration setting, the |
| 6178 | second item in the colon-separated list is a regular expression. |
| 6179 | .code |
| 6180 | domains = a.b.c : ^\\d{3} : *.y.z : ... |
| 6181 | .endd |
| 6182 | The doubling of the backslash is required because of string expansion that |
| 6183 | precedes interpretation &-- see section &<<SECTlittext>>& for more discussion |
| 6184 | of this issue, and a way of avoiding the need for doubling backslashes. The |
| 6185 | regular expression that is eventually used in this example contains just one |
| 6186 | backslash. The circumflex is included in the regular expression, and has the |
| 6187 | normal effect of &"anchoring"& it to the start of the string that is being |
| 6188 | matched. |
| 6189 | |
| 6190 | There are, however, two cases where a circumflex is not required for the |
| 6191 | recognition of a regular expression: these are the &%match%& condition in a |
| 6192 | string expansion, and the &%matches%& condition in an Exim filter file. In |
| 6193 | these cases, the relevant string is always treated as a regular expression; if |
| 6194 | it does not start with a circumflex, the expression is not anchored, and can |
| 6195 | match anywhere in the subject string. |
| 6196 | |
| 6197 | In all cases, if you want a regular expression to match at the end of a string, |
| 6198 | you must code the $ metacharacter to indicate this. For example: |
| 6199 | .code |
| 6200 | domains = ^\\d{3}\\.example |
| 6201 | .endd |
| 6202 | matches the domain &'123.example'&, but it also matches &'123.example.com'&. |
| 6203 | You need to use: |
| 6204 | .code |
| 6205 | domains = ^\\d{3}\\.example\$ |
| 6206 | .endd |
| 6207 | if you want &'example'& to be the top-level domain. The backslash before the |
| 6208 | $ is needed because string expansion also interprets dollar characters. |
| 6209 | |
| 6210 | |
| 6211 | |
| 6212 | . //////////////////////////////////////////////////////////////////////////// |
| 6213 | . //////////////////////////////////////////////////////////////////////////// |
| 6214 | |
| 6215 | .chapter "File and database lookups" "CHAPfdlookup" |
| 6216 | .scindex IIDfidalo1 "file" "lookups" |
| 6217 | .scindex IIDfidalo2 "database" "lookups" |
| 6218 | .cindex "lookup" "description of" |
| 6219 | Exim can be configured to look up data in files or databases as it processes |
| 6220 | messages. Two different kinds of syntax are used: |
| 6221 | |
| 6222 | .olist |
| 6223 | A string that is to be expanded may contain explicit lookup requests. These |
| 6224 | cause parts of the string to be replaced by data that is obtained from the |
| 6225 | lookup. Lookups of this type are conditional expansion items. Different results |
| 6226 | can be defined for the cases of lookup success and failure. See chapter |
| 6227 | &<<CHAPexpand>>&, where string expansions are described in detail. |
| 6228 | .next |
| 6229 | Lists of domains, hosts, and email addresses can contain lookup requests as a |
| 6230 | way of avoiding excessively long linear lists. In this case, the data that is |
| 6231 | returned by the lookup is often (but not always) discarded; whether the lookup |
| 6232 | succeeds or fails is what really counts. These kinds of list are described in |
| 6233 | chapter &<<CHAPdomhosaddlists>>&. |
| 6234 | .endlist |
| 6235 | |
| 6236 | String expansions, lists, and lookups interact with each other in such a way |
| 6237 | that there is no order in which to describe any one of them that does not |
| 6238 | involve references to the others. Each of these three chapters makes more sense |
| 6239 | if you have read the other two first. If you are reading this for the first |
| 6240 | time, be aware that some of it will make a lot more sense after you have read |
| 6241 | chapters &<<CHAPdomhosaddlists>>& and &<<CHAPexpand>>&. |
| 6242 | |
| 6243 | .section "Examples of different lookup syntax" "SECID60" |
| 6244 | It is easy to confuse the two different kinds of lookup, especially as the |
| 6245 | lists that may contain the second kind are always expanded before being |
| 6246 | processed as lists. Therefore, they may also contain lookups of the first kind. |
| 6247 | Be careful to distinguish between the following two examples: |
| 6248 | .code |
| 6249 | domains = ${lookup{$sender_host_address}lsearch{/some/file}} |
| 6250 | domains = lsearch;/some/file |
| 6251 | .endd |
| 6252 | The first uses a string expansion, the result of which must be a domain list. |
| 6253 | No strings have been specified for a successful or a failing lookup; the |
| 6254 | defaults in this case are the looked-up data and an empty string, respectively. |
| 6255 | The expansion takes place before the string is processed as a list, and the |
| 6256 | file that is searched could contain lines like this: |
| 6257 | .code |
| 6258 | 192.168.3.4: domain1:domain2:... |
| 6259 | 192.168.1.9: domain3:domain4:... |
| 6260 | .endd |
| 6261 | When the lookup succeeds, the result of the expansion is a list of domains (and |
| 6262 | possibly other types of item that are allowed in domain lists). |
| 6263 | |
| 6264 | In the second example, the lookup is a single item in a domain list. It causes |
| 6265 | Exim to use a lookup to see if the domain that is being processed can be found |
| 6266 | in the file. The file could contains lines like this: |
| 6267 | .code |
| 6268 | domain1: |
| 6269 | domain2: |
| 6270 | .endd |
| 6271 | Any data that follows the keys is not relevant when checking that the domain |
| 6272 | matches the list item. |
| 6273 | |
| 6274 | It is possible, though no doubt confusing, to use both kinds of lookup at once. |
| 6275 | Consider a file containing lines like this: |
| 6276 | .code |
| 6277 | 192.168.5.6: lsearch;/another/file |
| 6278 | .endd |
| 6279 | If the value of &$sender_host_address$& is 192.168.5.6, expansion of the |
| 6280 | first &%domains%& setting above generates the second setting, which therefore |
| 6281 | causes a second lookup to occur. |
| 6282 | |
| 6283 | The rest of this chapter describes the different lookup types that are |
| 6284 | available. Any of them can be used in any part of the configuration where a |
| 6285 | lookup is permitted. |
| 6286 | |
| 6287 | |
| 6288 | .section "Lookup types" "SECID61" |
| 6289 | .cindex "lookup" "types of" |
| 6290 | .cindex "single-key lookup" "definition of" |
| 6291 | Two different types of data lookup are implemented: |
| 6292 | |
| 6293 | .ilist |
| 6294 | The &'single-key'& type requires the specification of a file in which to look, |
| 6295 | and a single key to search for. The key must be a non-empty string for the |
| 6296 | lookup to succeed. The lookup type determines how the file is searched. |
| 6297 | .next |
| 6298 | .cindex "query-style lookup" "definition of" |
| 6299 | The &'query-style'& type accepts a generalized database query. No particular |
| 6300 | key value is assumed by Exim for query-style lookups. You can use whichever |
| 6301 | Exim variables you need to construct the database query. |
| 6302 | .endlist |
| 6303 | |
| 6304 | The code for each lookup type is in a separate source file that is included in |
| 6305 | the binary of Exim only if the corresponding compile-time option is set. The |
| 6306 | default settings in &_src/EDITME_& are: |
| 6307 | .code |
| 6308 | LOOKUP_DBM=yes |
| 6309 | LOOKUP_LSEARCH=yes |
| 6310 | .endd |
| 6311 | which means that only linear searching and DBM lookups are included by default. |
| 6312 | For some types of lookup (e.g. SQL databases), you need to install appropriate |
| 6313 | libraries and header files before building Exim. |
| 6314 | |
| 6315 | |
| 6316 | |
| 6317 | |
| 6318 | .section "Single-key lookup types" "SECTsinglekeylookups" |
| 6319 | .cindex "lookup" "single-key types" |
| 6320 | .cindex "single-key lookup" "list of types" |
| 6321 | The following single-key lookup types are implemented: |
| 6322 | |
| 6323 | .ilist |
| 6324 | .cindex "cdb" "description of" |
| 6325 | .cindex "lookup" "cdb" |
| 6326 | .cindex "binary zero" "in lookup key" |
| 6327 | &(cdb)&: The given file is searched as a Constant DataBase file, using the key |
| 6328 | string without a terminating binary zero. The cdb format is designed for |
| 6329 | indexed files that are read frequently and never updated, except by total |
| 6330 | re-creation. As such, it is particularly suitable for large files containing |
| 6331 | aliases or other indexed data referenced by an MTA. Information about cdb can |
| 6332 | be found in several places: |
| 6333 | .display |
| 6334 | &url(http://www.pobox.com/~djb/cdb.html) |
| 6335 | &url(ftp://ftp.corpit.ru/pub/tinycdb/) |
| 6336 | &url(http://packages.debian.org/stable/utils/freecdb.html) |
| 6337 | .endd |
| 6338 | A cdb distribution is not needed in order to build Exim with cdb support, |
| 6339 | because the code for reading cdb files is included directly in Exim itself. |
| 6340 | However, no means of building or testing cdb files is provided with Exim, so |
| 6341 | you need to obtain a cdb distribution in order to do this. |
| 6342 | .next |
| 6343 | .cindex "DBM" "lookup type" |
| 6344 | .cindex "lookup" "dbm" |
| 6345 | .cindex "binary zero" "in lookup key" |
| 6346 | &(dbm)&: Calls to DBM library functions are used to extract data from the given |
| 6347 | DBM file by looking up the record with the given key. A terminating binary |
| 6348 | zero is included in the key that is passed to the DBM library. See section |
| 6349 | &<<SECTdb>>& for a discussion of DBM libraries. |
| 6350 | |
| 6351 | .cindex "Berkeley DB library" "file format" |
| 6352 | For all versions of Berkeley DB, Exim uses the DB_HASH style of database |
| 6353 | when building DBM files using the &%exim_dbmbuild%& utility. However, when |
| 6354 | using Berkeley DB versions 3 or 4, it opens existing databases for reading with |
| 6355 | the DB_UNKNOWN option. This enables it to handle any of the types of database |
| 6356 | that the library supports, and can be useful for accessing DBM files created by |
| 6357 | other applications. (For earlier DB versions, DB_HASH is always used.) |
| 6358 | .next |
| 6359 | .cindex "lookup" "dbmjz" |
| 6360 | .cindex "lookup" "dbm &-- embedded NULs" |
| 6361 | .cindex "sasldb2" |
| 6362 | .cindex "dbmjz lookup type" |
| 6363 | &(dbmjz)&: This is the same as &(dbm)&, except that the lookup key is |
| 6364 | interpreted as an Exim list; the elements of the list are joined together with |
| 6365 | ASCII NUL characters to form the lookup key. An example usage would be to |
| 6366 | authenticate incoming SMTP calls using the passwords from Cyrus SASL's |
| 6367 | &_/etc/sasldb2_& file with the &(gsasl)& authenticator or Exim's own |
| 6368 | &(cram_md5)& authenticator. |
| 6369 | .next |
| 6370 | .cindex "lookup" "dbmnz" |
| 6371 | .cindex "lookup" "dbm &-- terminating zero" |
| 6372 | .cindex "binary zero" "in lookup key" |
| 6373 | .cindex "Courier" |
| 6374 | .cindex "&_/etc/userdbshadow.dat_&" |
| 6375 | .cindex "dbmnz lookup type" |
| 6376 | &(dbmnz)&: This is the same as &(dbm)&, except that a terminating binary zero |
| 6377 | is not included in the key that is passed to the DBM library. You may need this |
| 6378 | if you want to look up data in files that are created by or shared with some |
| 6379 | other application that does not use terminating zeros. For example, you need to |
| 6380 | use &(dbmnz)& rather than &(dbm)& if you want to authenticate incoming SMTP |
| 6381 | calls using the passwords from Courier's &_/etc/userdbshadow.dat_& file. Exim's |
| 6382 | utility program for creating DBM files (&'exim_dbmbuild'&) includes the zeros |
| 6383 | by default, but has an option to omit them (see section &<<SECTdbmbuild>>&). |
| 6384 | .next |
| 6385 | .cindex "lookup" "dsearch" |
| 6386 | .cindex "dsearch lookup type" |
| 6387 | &(dsearch)&: The given file must be a directory; this is searched for an entry |
| 6388 | whose name is the key by calling the &[lstat()]& function. The key may not |
| 6389 | contain any forward slash characters. If &[lstat()]& succeeds, the result of |
| 6390 | the lookup is the name of the entry, which may be a file, directory, |
| 6391 | symbolic link, or any other kind of directory entry. An example of how this |
| 6392 | lookup can be used to support virtual domains is given in section |
| 6393 | &<<SECTvirtualdomains>>&. |
| 6394 | .next |
| 6395 | .cindex "lookup" "iplsearch" |
| 6396 | .cindex "iplsearch lookup type" |
| 6397 | &(iplsearch)&: The given file is a text file containing keys and data. A key is |
| 6398 | terminated by a colon or white space or the end of the line. The keys in the |
| 6399 | file must be IP addresses, or IP addresses with CIDR masks. Keys that involve |
| 6400 | IPv6 addresses must be enclosed in quotes to prevent the first internal colon |
| 6401 | being interpreted as a key terminator. For example: |
| 6402 | .code |
| 6403 | 1.2.3.4: data for 1.2.3.4 |
| 6404 | 192.168.0.0/16: data for 192.168.0.0/16 |
| 6405 | "abcd::cdab": data for abcd::cdab |
| 6406 | "abcd:abcd::/32" data for abcd:abcd::/32 |
| 6407 | .endd |
| 6408 | The key for an &(iplsearch)& lookup must be an IP address (without a mask). The |
| 6409 | file is searched linearly, using the CIDR masks where present, until a matching |
| 6410 | key is found. The first key that matches is used; there is no attempt to find a |
| 6411 | &"best"& match. Apart from the way the keys are matched, the processing for |
| 6412 | &(iplsearch)& is the same as for &(lsearch)&. |
| 6413 | |
| 6414 | &*Warning 1*&: Unlike most other single-key lookup types, a file of data for |
| 6415 | &(iplsearch)& can &'not'& be turned into a DBM or cdb file, because those |
| 6416 | lookup types support only literal keys. |
| 6417 | |
| 6418 | &*Warning 2*&: In a host list, you must always use &(net-iplsearch)& so that |
| 6419 | the implicit key is the host's IP address rather than its name (see section |
| 6420 | &<<SECThoslispatsikey>>&). |
| 6421 | .next |
| 6422 | .cindex "linear search" |
| 6423 | .cindex "lookup" "lsearch" |
| 6424 | .cindex "lsearch lookup type" |
| 6425 | .cindex "case sensitivity" "in lsearch lookup" |
| 6426 | &(lsearch)&: The given file is a text file that is searched linearly for a |
| 6427 | line beginning with the search key, terminated by a colon or white space or the |
| 6428 | end of the line. The search is case-insensitive; that is, upper and lower case |
| 6429 | letters are treated as the same. The first occurrence of the key that is found |
| 6430 | in the file is used. |
| 6431 | |
| 6432 | White space between the key and the colon is permitted. The remainder of the |
| 6433 | line, with leading and trailing white space removed, is the data. This can be |
| 6434 | continued onto subsequent lines by starting them with any amount of white |
| 6435 | space, but only a single space character is included in the data at such a |
| 6436 | junction. If the data begins with a colon, the key must be terminated by a |
| 6437 | colon, for example: |
| 6438 | .code |
| 6439 | baduser: :fail: |
| 6440 | .endd |
| 6441 | Empty lines and lines beginning with # are ignored, even if they occur in the |
| 6442 | middle of an item. This is the traditional textual format of alias files. Note |
| 6443 | that the keys in an &(lsearch)& file are literal strings. There is no |
| 6444 | wildcarding of any kind. |
| 6445 | |
| 6446 | .cindex "lookup" "lsearch &-- colons in keys" |
| 6447 | .cindex "white space" "in lsearch key" |
| 6448 | In most &(lsearch)& files, keys are not required to contain colons or # |
| 6449 | characters, or white space. However, if you need this feature, it is available. |
| 6450 | If a key begins with a doublequote character, it is terminated only by a |
| 6451 | matching quote (or end of line), and the normal escaping rules apply to its |
| 6452 | contents (see section &<<SECTstrings>>&). An optional colon is permitted after |
| 6453 | quoted keys (exactly as for unquoted keys). There is no special handling of |
| 6454 | quotes for the data part of an &(lsearch)& line. |
| 6455 | |
| 6456 | .next |
| 6457 | .cindex "NIS lookup type" |
| 6458 | .cindex "lookup" "NIS" |
| 6459 | .cindex "binary zero" "in lookup key" |
| 6460 | &(nis)&: The given file is the name of a NIS map, and a NIS lookup is done with |
| 6461 | the given key, without a terminating binary zero. There is a variant called |
| 6462 | &(nis0)& which does include the terminating binary zero in the key. This is |
| 6463 | reportedly needed for Sun-style alias files. Exim does not recognize NIS |
| 6464 | aliases; the full map names must be used. |
| 6465 | |
| 6466 | .next |
| 6467 | .cindex "wildlsearch lookup type" |
| 6468 | .cindex "lookup" "wildlsearch" |
| 6469 | .cindex "nwildlsearch lookup type" |
| 6470 | .cindex "lookup" "nwildlsearch" |
| 6471 | &(wildlsearch)& or &(nwildlsearch)&: These search a file linearly, like |
| 6472 | &(lsearch)&, but instead of being interpreted as a literal string, each key in |
| 6473 | the file may be wildcarded. The difference between these two lookup types is |
| 6474 | that for &(wildlsearch)&, each key in the file is string-expanded before being |
| 6475 | used, whereas for &(nwildlsearch)&, no expansion takes place. |
| 6476 | |
| 6477 | .cindex "case sensitivity" "in (n)wildlsearch lookup" |
| 6478 | Like &(lsearch)&, the testing is done case-insensitively. However, keys in the |
| 6479 | file that are regular expressions can be made case-sensitive by the use of |
| 6480 | &`(-i)`& within the pattern. The following forms of wildcard are recognized: |
| 6481 | |
| 6482 | . ==== As this is a nested list, any displays it contains must be indented |
| 6483 | . ==== as otherwise they are too far to the left. |
| 6484 | |
| 6485 | .olist |
| 6486 | The string may begin with an asterisk to mean &"ends with"&. For example: |
| 6487 | .code |
| 6488 | *.a.b.c data for anything.a.b.c |
| 6489 | *fish data for anythingfish |
| 6490 | .endd |
| 6491 | .next |
| 6492 | The string may begin with a circumflex to indicate a regular expression. For |
| 6493 | example, for &(wildlsearch)&: |
| 6494 | .code |
| 6495 | ^\N\d+\.a\.b\N data for <digits>.a.b |
| 6496 | .endd |
| 6497 | Note the use of &`\N`& to disable expansion of the contents of the regular |
| 6498 | expression. If you are using &(nwildlsearch)&, where the keys are not |
| 6499 | string-expanded, the equivalent entry is: |
| 6500 | .code |
| 6501 | ^\d+\.a\.b data for <digits>.a.b |
| 6502 | .endd |
| 6503 | The case-insensitive flag is set at the start of compiling the regular |
| 6504 | expression, but it can be turned off by using &`(-i)`& at an appropriate point. |
| 6505 | For example, to make the entire pattern case-sensitive: |
| 6506 | .code |
| 6507 | ^(?-i)\d+\.a\.b data for <digits>.a.b |
| 6508 | .endd |
| 6509 | |
| 6510 | If the regular expression contains white space or colon characters, you must |
| 6511 | either quote it (see &(lsearch)& above), or represent these characters in other |
| 6512 | ways. For example, &`\s`& can be used for white space and &`\x3A`& for a |
| 6513 | colon. This may be easier than quoting, because if you quote, you have to |
| 6514 | escape all the backslashes inside the quotes. |
| 6515 | |
| 6516 | &*Note*&: It is not possible to capture substrings in a regular expression |
| 6517 | match for later use, because the results of all lookups are cached. If a lookup |
| 6518 | is repeated, the result is taken from the cache, and no actual pattern matching |
| 6519 | takes place. The values of all the numeric variables are unset after a |
| 6520 | &((n)wildlsearch)& match. |
| 6521 | |
| 6522 | .next |
| 6523 | Although I cannot see it being of much use, the general matching function that |
| 6524 | is used to implement &((n)wildlsearch)& means that the string may begin with a |
| 6525 | lookup name terminated by a semicolon, and followed by lookup data. For |
| 6526 | example: |
| 6527 | .code |
| 6528 | cdb;/some/file data for keys that match the file |
| 6529 | .endd |
| 6530 | The data that is obtained from the nested lookup is discarded. |
| 6531 | .endlist olist |
| 6532 | |
| 6533 | Keys that do not match any of these patterns are interpreted literally. The |
| 6534 | continuation rules for the data are the same as for &(lsearch)&, and keys may |
| 6535 | be followed by optional colons. |
| 6536 | |
| 6537 | &*Warning*&: Unlike most other single-key lookup types, a file of data for |
| 6538 | &((n)wildlsearch)& can &'not'& be turned into a DBM or cdb file, because those |
| 6539 | lookup types support only literal keys. |
| 6540 | .endlist ilist |
| 6541 | |
| 6542 | |
| 6543 | .section "Query-style lookup types" "SECID62" |
| 6544 | .cindex "lookup" "query-style types" |
| 6545 | .cindex "query-style lookup" "list of types" |
| 6546 | The supported query-style lookup types are listed below. Further details about |
| 6547 | many of them are given in later sections. |
| 6548 | |
| 6549 | .ilist |
| 6550 | .cindex "DNS" "as a lookup type" |
| 6551 | .cindex "lookup" "DNS" |
| 6552 | &(dnsdb)&: This does a DNS search for one or more records whose domain names |
| 6553 | are given in the supplied query. The resulting data is the contents of the |
| 6554 | records. See section &<<SECTdnsdb>>&. |
| 6555 | .next |
| 6556 | .cindex "InterBase lookup type" |
| 6557 | .cindex "lookup" "InterBase" |
| 6558 | &(ibase)&: This does a lookup in an InterBase database. |
| 6559 | .next |
| 6560 | .cindex "LDAP" "lookup type" |
| 6561 | .cindex "lookup" "LDAP" |
| 6562 | &(ldap)&: This does an LDAP lookup using a query in the form of a URL, and |
| 6563 | returns attributes from a single entry. There is a variant called &(ldapm)& |
| 6564 | that permits values from multiple entries to be returned. A third variant |
| 6565 | called &(ldapdn)& returns the Distinguished Name of a single entry instead of |
| 6566 | any attribute values. See section &<<SECTldap>>&. |
| 6567 | .next |
| 6568 | .cindex "MySQL" "lookup type" |
| 6569 | .cindex "lookup" "MySQL" |
| 6570 | &(mysql)&: The format of the query is an SQL statement that is passed to a |
| 6571 | MySQL database. See section &<<SECTsql>>&. |
| 6572 | .next |
| 6573 | .cindex "NIS+ lookup type" |
| 6574 | .cindex "lookup" "NIS+" |
| 6575 | &(nisplus)&: This does a NIS+ lookup using a query that can specify the name of |
| 6576 | the field to be returned. See section &<<SECTnisplus>>&. |
| 6577 | .next |
| 6578 | .cindex "Oracle" "lookup type" |
| 6579 | .cindex "lookup" "Oracle" |
| 6580 | &(oracle)&: The format of the query is an SQL statement that is passed to an |
| 6581 | Oracle database. See section &<<SECTsql>>&. |
| 6582 | .next |
| 6583 | .cindex "lookup" "passwd" |
| 6584 | .cindex "passwd lookup type" |
| 6585 | .cindex "&_/etc/passwd_&" |
| 6586 | &(passwd)& is a query-style lookup with queries that are just user names. The |
| 6587 | lookup calls &[getpwnam()]& to interrogate the system password data, and on |
| 6588 | success, the result string is the same as you would get from an &(lsearch)& |
| 6589 | lookup on a traditional &_/etc/passwd file_&, though with &`*`& for the |
| 6590 | password value. For example: |
| 6591 | .code |
| 6592 | *:42:42:King Rat:/home/kr:/bin/bash |
| 6593 | .endd |
| 6594 | .next |
| 6595 | .cindex "PostgreSQL lookup type" |
| 6596 | .cindex "lookup" "PostgreSQL" |
| 6597 | &(pgsql)&: The format of the query is an SQL statement that is passed to a |
| 6598 | PostgreSQL database. See section &<<SECTsql>>&. |
| 6599 | |
| 6600 | .next |
| 6601 | .cindex "sqlite lookup type" |
| 6602 | .cindex "lookup" "sqlite" |
| 6603 | &(sqlite)&: The format of the query is a file name followed by an SQL statement |
| 6604 | that is passed to an SQLite database. See section &<<SECTsqlite>>&. |
| 6605 | |
| 6606 | .next |
| 6607 | &(testdb)&: This is a lookup type that is used for testing Exim. It is |
| 6608 | not likely to be useful in normal operation. |
| 6609 | .next |
| 6610 | .cindex "whoson lookup type" |
| 6611 | .cindex "lookup" "whoson" |
| 6612 | &(whoson)&: &'Whoson'& (&url(http://whoson.sourceforge.net)) is a protocol that |
| 6613 | allows a server to check whether a particular (dynamically allocated) IP |
| 6614 | address is currently allocated to a known (trusted) user and, optionally, to |
| 6615 | obtain the identity of the said user. For SMTP servers, &'Whoson'& was popular |
| 6616 | at one time for &"POP before SMTP"& authentication, but that approach has been |
| 6617 | superseded by SMTP authentication. In Exim, &'Whoson'& can be used to implement |
| 6618 | &"POP before SMTP"& checking using ACL statements such as |
| 6619 | .code |
| 6620 | require condition = \ |
| 6621 | ${lookup whoson {$sender_host_address}{yes}{no}} |
| 6622 | .endd |
| 6623 | The query consists of a single IP address. The value returned is the name of |
| 6624 | the authenticated user, which is stored in the variable &$value$&. However, in |
| 6625 | this example, the data in &$value$& is not used; the result of the lookup is |
| 6626 | one of the fixed strings &"yes"& or &"no"&. |
| 6627 | .endlist |
| 6628 | |
| 6629 | |
| 6630 | |
| 6631 | .section "Temporary errors in lookups" "SECID63" |
| 6632 | .cindex "lookup" "temporary error in" |
| 6633 | Lookup functions can return temporary error codes if the lookup cannot be |
| 6634 | completed. For example, an SQL or LDAP database might be unavailable. For this |
| 6635 | reason, it is not advisable to use a lookup that might do this for critical |
| 6636 | options such as a list of local domains. |
| 6637 | |
| 6638 | When a lookup cannot be completed in a router or transport, delivery |
| 6639 | of the message (to the relevant address) is deferred, as for any other |
| 6640 | temporary error. In other circumstances Exim may assume the lookup has failed, |
| 6641 | or may give up altogether. |
| 6642 | |
| 6643 | |
| 6644 | |
| 6645 | .section "Default values in single-key lookups" "SECTdefaultvaluelookups" |
| 6646 | .cindex "wildcard lookups" |
| 6647 | .cindex "lookup" "default values" |
| 6648 | .cindex "lookup" "wildcard" |
| 6649 | .cindex "lookup" "* added to type" |
| 6650 | .cindex "default" "in single-key lookups" |
| 6651 | In this context, a &"default value"& is a value specified by the administrator |
| 6652 | that is to be used if a lookup fails. |
| 6653 | |
| 6654 | &*Note:*& This section applies only to single-key lookups. For query-style |
| 6655 | lookups, the facilities of the query language must be used. An attempt to |
| 6656 | specify a default for a query-style lookup provokes an error. |
| 6657 | |
| 6658 | If &"*"& is added to a single-key lookup type (for example, &%lsearch*%&) |
| 6659 | and the initial lookup fails, the key &"*"& is looked up in the file to |
| 6660 | provide a default value. See also the section on partial matching below. |
| 6661 | |
| 6662 | .cindex "*@ with single-key lookup" |
| 6663 | .cindex "lookup" "*@ added to type" |
| 6664 | .cindex "alias file" "per-domain default" |
| 6665 | Alternatively, if &"*@"& is added to a single-key lookup type (for example |
| 6666 | &%dbm*@%&) then, if the initial lookup fails and the key contains an @ |
| 6667 | character, a second lookup is done with everything before the last @ replaced |
| 6668 | by *. This makes it possible to provide per-domain defaults in alias files |
| 6669 | that include the domains in the keys. If the second lookup fails (or doesn't |
| 6670 | take place because there is no @ in the key), &"*"& is looked up. |
| 6671 | For example, a &(redirect)& router might contain: |
| 6672 | .code |
| 6673 | data = ${lookup{$local_part@$domain}lsearch*@{/etc/mix-aliases}} |
| 6674 | .endd |
| 6675 | Suppose the address that is being processed is &'jane@eyre.example'&. Exim |
| 6676 | looks up these keys, in this order: |
| 6677 | .code |
| 6678 | jane@eyre.example |
| 6679 | *@eyre.example |
| 6680 | * |
| 6681 | .endd |
| 6682 | The data is taken from whichever key it finds first. &*Note*&: In an |
| 6683 | &(lsearch)& file, this does not mean the first of these keys in the file. A |
| 6684 | complete scan is done for each key, and only if it is not found at all does |
| 6685 | Exim move on to try the next key. |
| 6686 | |
| 6687 | |
| 6688 | |
| 6689 | .section "Partial matching in single-key lookups" "SECTpartiallookup" |
| 6690 | .cindex "partial matching" |
| 6691 | .cindex "wildcard lookups" |
| 6692 | .cindex "lookup" "partial matching" |
| 6693 | .cindex "lookup" "wildcard" |
| 6694 | .cindex "asterisk" "in search type" |
| 6695 | The normal operation of a single-key lookup is to search the file for an exact |
| 6696 | match with the given key. However, in a number of situations where domains are |
| 6697 | being looked up, it is useful to be able to do partial matching. In this case, |
| 6698 | information in the file that has a key starting with &"*."& is matched by any |
| 6699 | domain that ends with the components that follow the full stop. For example, if |
| 6700 | a key in a DBM file is |
| 6701 | .code |
| 6702 | *.dates.fict.example |
| 6703 | .endd |
| 6704 | then when partial matching is enabled this is matched by (amongst others) |
| 6705 | &'2001.dates.fict.example'& and &'1984.dates.fict.example'&. It is also matched |
| 6706 | by &'dates.fict.example'&, if that does not appear as a separate key in the |
| 6707 | file. |
| 6708 | |
| 6709 | &*Note*&: Partial matching is not available for query-style lookups. It is |
| 6710 | also not available for any lookup items in address lists (see section |
| 6711 | &<<SECTaddresslist>>&). |
| 6712 | |
| 6713 | Partial matching is implemented by doing a series of separate lookups using |
| 6714 | keys constructed by modifying the original subject key. This means that it can |
| 6715 | be used with any of the single-key lookup types, provided that |
| 6716 | partial matching keys |
| 6717 | beginning with a special prefix (default &"*."&) are included in the data file. |
| 6718 | Keys in the file that do not begin with the prefix are matched only by |
| 6719 | unmodified subject keys when partial matching is in use. |
| 6720 | |
| 6721 | Partial matching is requested by adding the string &"partial-"& to the front of |
| 6722 | the name of a single-key lookup type, for example, &%partial-dbm%&. When this |
| 6723 | is done, the subject key is first looked up unmodified; if that fails, &"*."& |
| 6724 | is added at the start of the subject key, and it is looked up again. If that |
| 6725 | fails, further lookups are tried with dot-separated components removed from the |
| 6726 | start of the subject key, one-by-one, and &"*."& added on the front of what |
| 6727 | remains. |
| 6728 | |
| 6729 | A minimum number of two non-* components are required. This can be adjusted |
| 6730 | by including a number before the hyphen in the search type. For example, |
| 6731 | &%partial3-lsearch%& specifies a minimum of three non-* components in the |
| 6732 | modified keys. Omitting the number is equivalent to &"partial2-"&. If the |
| 6733 | subject key is &'2250.dates.fict.example'& then the following keys are looked |
| 6734 | up when the minimum number of non-* components is two: |
| 6735 | .code |
| 6736 | 2250.dates.fict.example |
| 6737 | *.2250.dates.fict.example |
| 6738 | *.dates.fict.example |
| 6739 | *.fict.example |
| 6740 | .endd |
| 6741 | As soon as one key in the sequence is successfully looked up, the lookup |
| 6742 | finishes. |
| 6743 | |
| 6744 | .cindex "lookup" "partial matching &-- changing prefix" |
| 6745 | .cindex "prefix" "for partial matching" |
| 6746 | The use of &"*."& as the partial matching prefix is a default that can be |
| 6747 | changed. The motivation for this feature is to allow Exim to operate with file |
| 6748 | formats that are used by other MTAs. A different prefix can be supplied in |
| 6749 | parentheses instead of the hyphen after &"partial"&. For example: |
| 6750 | .code |
| 6751 | domains = partial(.)lsearch;/some/file |
| 6752 | .endd |
| 6753 | In this example, if the domain is &'a.b.c'&, the sequence of lookups is |
| 6754 | &`a.b.c`&, &`.a.b.c`&, and &`.b.c`& (the default minimum of 2 non-wild |
| 6755 | components is unchanged). The prefix may consist of any punctuation characters |
| 6756 | other than a closing parenthesis. It may be empty, for example: |
| 6757 | .code |
| 6758 | domains = partial1()cdb;/some/file |
| 6759 | .endd |
| 6760 | For this example, if the domain is &'a.b.c'&, the sequence of lookups is |
| 6761 | &`a.b.c`&, &`b.c`&, and &`c`&. |
| 6762 | |
| 6763 | If &"partial0"& is specified, what happens at the end (when the lookup with |
| 6764 | just one non-wild component has failed, and the original key is shortened right |
| 6765 | down to the null string) depends on the prefix: |
| 6766 | |
| 6767 | .ilist |
| 6768 | If the prefix has zero length, the whole lookup fails. |
| 6769 | .next |
| 6770 | If the prefix has length 1, a lookup for just the prefix is done. For |
| 6771 | example, the final lookup for &"partial0(.)"& is for &`.`& alone. |
| 6772 | .next |
| 6773 | Otherwise, if the prefix ends in a dot, the dot is removed, and the |
| 6774 | remainder is looked up. With the default prefix, therefore, the final lookup is |
| 6775 | for &"*"& on its own. |
| 6776 | .next |
| 6777 | Otherwise, the whole prefix is looked up. |
| 6778 | .endlist |
| 6779 | |
| 6780 | |
| 6781 | If the search type ends in &"*"& or &"*@"& (see section |
| 6782 | &<<SECTdefaultvaluelookups>>& above), the search for an ultimate default that |
| 6783 | this implies happens after all partial lookups have failed. If &"partial0"& is |
| 6784 | specified, adding &"*"& to the search type has no effect with the default |
| 6785 | prefix, because the &"*"& key is already included in the sequence of partial |
| 6786 | lookups. However, there might be a use for lookup types such as |
| 6787 | &"partial0(.)lsearch*"&. |
| 6788 | |
| 6789 | The use of &"*"& in lookup partial matching differs from its use as a wildcard |
| 6790 | in domain lists and the like. Partial matching works only in terms of |
| 6791 | dot-separated components; a key such as &`*fict.example`& |
| 6792 | in a database file is useless, because the asterisk in a partial matching |
| 6793 | subject key is always followed by a dot. |
| 6794 | |
| 6795 | |
| 6796 | |
| 6797 | |
| 6798 | .section "Lookup caching" "SECID64" |
| 6799 | .cindex "lookup" "caching" |
| 6800 | .cindex "caching" "lookup data" |
| 6801 | Exim caches all lookup results in order to avoid needless repetition of |
| 6802 | lookups. However, because (apart from the daemon) Exim operates as a collection |
| 6803 | of independent, short-lived processes, this caching applies only within a |
| 6804 | single Exim process. There is no inter-process lookup caching facility. |
| 6805 | |
| 6806 | For single-key lookups, Exim keeps the relevant files open in case there is |
| 6807 | another lookup that needs them. In some types of configuration this can lead to |
| 6808 | many files being kept open for messages with many recipients. To avoid hitting |
| 6809 | the operating system limit on the number of simultaneously open files, Exim |
| 6810 | closes the least recently used file when it needs to open more files than its |
| 6811 | own internal limit, which can be changed via the &%lookup_open_max%& option. |
| 6812 | |
| 6813 | The single-key lookup files are closed and the lookup caches are flushed at |
| 6814 | strategic points during delivery &-- for example, after all routing is |
| 6815 | complete. |
| 6816 | |
| 6817 | |
| 6818 | |
| 6819 | |
| 6820 | .section "Quoting lookup data" "SECID65" |
| 6821 | .cindex "lookup" "quoting" |
| 6822 | .cindex "quoting" "in lookups" |
| 6823 | When data from an incoming message is included in a query-style lookup, there |
| 6824 | is the possibility of special characters in the data messing up the syntax of |
| 6825 | the query. For example, a NIS+ query that contains |
| 6826 | .code |
| 6827 | [name=$local_part] |
| 6828 | .endd |
| 6829 | will be broken if the local part happens to contain a closing square bracket. |
| 6830 | For NIS+, data can be enclosed in double quotes like this: |
| 6831 | .code |
| 6832 | [name="$local_part"] |
| 6833 | .endd |
| 6834 | but this still leaves the problem of a double quote in the data. The rule for |
| 6835 | NIS+ is that double quotes must be doubled. Other lookup types have different |
| 6836 | rules, and to cope with the differing requirements, an expansion operator |
| 6837 | of the following form is provided: |
| 6838 | .code |
| 6839 | ${quote_<lookup-type>:<string>} |
| 6840 | .endd |
| 6841 | For example, the safest way to write the NIS+ query is |
| 6842 | .code |
| 6843 | [name="${quote_nisplus:$local_part}"] |
| 6844 | .endd |
| 6845 | See chapter &<<CHAPexpand>>& for full coverage of string expansions. The quote |
| 6846 | operator can be used for all lookup types, but has no effect for single-key |
| 6847 | lookups, since no quoting is ever needed in their key strings. |
| 6848 | |
| 6849 | |
| 6850 | |
| 6851 | |
| 6852 | .section "More about dnsdb" "SECTdnsdb" |
| 6853 | .cindex "dnsdb lookup" |
| 6854 | .cindex "lookup" "dnsdb" |
| 6855 | .cindex "DNS" "as a lookup type" |
| 6856 | The &(dnsdb)& lookup type uses the DNS as its database. A simple query consists |
| 6857 | of a record type and a domain name, separated by an equals sign. For example, |
| 6858 | an expansion string could contain: |
| 6859 | .code |
| 6860 | ${lookup dnsdb{mx=a.b.example}{$value}fail} |
| 6861 | .endd |
| 6862 | If the lookup succeeds, the result is placed in &$value$&, which in this case |
| 6863 | is used on its own as the result. If the lookup does not succeed, the |
| 6864 | &`fail`& keyword causes a &'forced expansion failure'& &-- see section |
| 6865 | &<<SECTforexpfai>>& for an explanation of what this means. |
| 6866 | |
| 6867 | The supported DNS record types are A, CNAME, MX, NS, PTR, SPF, SRV, TLSA and TXT, |
| 6868 | and, when Exim is compiled with IPv6 support, AAAA (and A6 if that is also |
| 6869 | configured). If no type is given, TXT is assumed. When the type is PTR, |
| 6870 | the data can be an IP address, written as normal; inversion and the addition of |
| 6871 | &%in-addr.arpa%& or &%ip6.arpa%& happens automatically. For example: |
| 6872 | .code |
| 6873 | ${lookup dnsdb{ptr=192.168.4.5}{$value}fail} |
| 6874 | .endd |
| 6875 | If the data for a PTR record is not a syntactically valid IP address, it is not |
| 6876 | altered and nothing is added. |
| 6877 | |
| 6878 | .cindex "MX record" "in &(dnsdb)& lookup" |
| 6879 | .cindex "SRV record" "in &(dnsdb)& lookup" |
| 6880 | For an MX lookup, both the preference value and the host name are returned for |
| 6881 | each record, separated by a space. For an SRV lookup, the priority, weight, |
| 6882 | port, and host name are returned for each record, separated by spaces. |
| 6883 | |
| 6884 | For any record type, if multiple records are found (or, for A6 lookups, if a |
| 6885 | single record leads to multiple addresses), the data is returned as a |
| 6886 | concatenation, with newline as the default separator. The order, of course, |
| 6887 | depends on the DNS resolver. You can specify a different separator character |
| 6888 | between multiple records by putting a right angle-bracket followed immediately |
| 6889 | by the new separator at the start of the query. For example: |
| 6890 | .code |
| 6891 | ${lookup dnsdb{>: a=host1.example}} |
| 6892 | .endd |
| 6893 | It is permitted to specify a space as the separator character. Further |
| 6894 | white space is ignored. |
| 6895 | |
| 6896 | .cindex "TXT record" "in &(dnsdb)& lookup" |
| 6897 | .cindex "SPF record" "in &(dnsdb)& lookup" |
| 6898 | For TXT records with multiple items of data, only the first item is returned, |
| 6899 | unless a separator for them is specified using a comma after the separator |
| 6900 | character followed immediately by the TXT record item separator. To concatenate |
| 6901 | items without a separator, use a semicolon instead. For SPF records the |
| 6902 | default behaviour is to concatenate multiple items without using a separator. |
| 6903 | .code |
| 6904 | ${lookup dnsdb{>\n,: txt=a.b.example}} |
| 6905 | ${lookup dnsdb{>\n; txt=a.b.example}} |
| 6906 | ${lookup dnsdb{spf=example.org}} |
| 6907 | .endd |
| 6908 | It is permitted to specify a space as the separator character. Further |
| 6909 | white space is ignored. |
| 6910 | |
| 6911 | .section "Pseudo dnsdb record types" "SECID66" |
| 6912 | .cindex "MX record" "in &(dnsdb)& lookup" |
| 6913 | By default, both the preference value and the host name are returned for |
| 6914 | each MX record, separated by a space. If you want only host names, you can use |
| 6915 | the pseudo-type MXH: |
| 6916 | .code |
| 6917 | ${lookup dnsdb{mxh=a.b.example}} |
| 6918 | .endd |
| 6919 | In this case, the preference values are omitted, and just the host names are |
| 6920 | returned. |
| 6921 | |
| 6922 | .cindex "name server for enclosing domain" |
| 6923 | Another pseudo-type is ZNS (for &"zone NS"&). It performs a lookup for NS |
| 6924 | records on the given domain, but if none are found, it removes the first |
| 6925 | component of the domain name, and tries again. This process continues until NS |
| 6926 | records are found or there are no more components left (or there is a DNS |
| 6927 | error). In other words, it may return the name servers for a top-level domain, |
| 6928 | but it never returns the root name servers. If there are no NS records for the |
| 6929 | top-level domain, the lookup fails. Consider these examples: |
| 6930 | .code |
| 6931 | ${lookup dnsdb{zns=xxx.quercite.com}} |
| 6932 | ${lookup dnsdb{zns=xxx.edu}} |
| 6933 | .endd |
| 6934 | Assuming that in each case there are no NS records for the full domain name, |
| 6935 | the first returns the name servers for &%quercite.com%&, and the second returns |
| 6936 | the name servers for &%edu%&. |
| 6937 | |
| 6938 | You should be careful about how you use this lookup because, unless the |
| 6939 | top-level domain does not exist, the lookup always returns some host names. The |
| 6940 | sort of use to which this might be put is for seeing if the name servers for a |
| 6941 | given domain are on a blacklist. You can probably assume that the name servers |
| 6942 | for the high-level domains such as &%com%& or &%co.uk%& are not going to be on |
| 6943 | such a list. |
| 6944 | |
| 6945 | .cindex "CSA" "in &(dnsdb)& lookup" |
| 6946 | A third pseudo-type is CSA (Client SMTP Authorization). This looks up SRV |
| 6947 | records according to the CSA rules, which are described in section |
| 6948 | &<<SECTverifyCSA>>&. Although &(dnsdb)& supports SRV lookups directly, this is |
| 6949 | not sufficient because of the extra parent domain search behaviour of CSA. The |
| 6950 | result of a successful lookup such as: |
| 6951 | .code |
| 6952 | ${lookup dnsdb {csa=$sender_helo_name}} |
| 6953 | .endd |
| 6954 | has two space-separated fields: an authorization code and a target host name. |
| 6955 | The authorization code can be &"Y"& for yes, &"N"& for no, &"X"& for explicit |
| 6956 | authorization required but absent, or &"?"& for unknown. |
| 6957 | |
| 6958 | .cindex "A+" "in &(dnsdb)& lookup" |
| 6959 | The pseudo-type A+ performs an A6 lookup (if configured) followed by an AAAA |
| 6960 | and then an A lookup. All results are returned; defer processing |
| 6961 | (see below) is handled separately for each lookup. Example: |
| 6962 | .code |
| 6963 | ${lookup dnsdb {>; a+=$sender_helo_name}} |
| 6964 | .endd |
| 6965 | |
| 6966 | |
| 6967 | .section "Multiple dnsdb lookups" "SECID67" |
| 6968 | In the previous sections, &(dnsdb)& lookups for a single domain are described. |
| 6969 | However, you can specify a list of domains or IP addresses in a single |
| 6970 | &(dnsdb)& lookup. The list is specified in the normal Exim way, with colon as |
| 6971 | the default separator, but with the ability to change this. For example: |
| 6972 | .code |
| 6973 | ${lookup dnsdb{one.domain.com:two.domain.com}} |
| 6974 | ${lookup dnsdb{a=one.host.com:two.host.com}} |
| 6975 | ${lookup dnsdb{ptr = <; 1.2.3.4 ; 4.5.6.8}} |
| 6976 | .endd |
| 6977 | In order to retain backwards compatibility, there is one special case: if |
| 6978 | the lookup type is PTR and no change of separator is specified, Exim looks |
| 6979 | to see if the rest of the string is precisely one IPv6 address. In this |
| 6980 | case, it does not treat it as a list. |
| 6981 | |
| 6982 | The data from each lookup is concatenated, with newline separators by default, |
| 6983 | in the same way that multiple DNS records for a single item are handled. A |
| 6984 | different separator can be specified, as described above. |
| 6985 | |
| 6986 | Modifiers for &(dnsdb)& lookups are givien by optional keywords, |
| 6987 | each followed by a comma, |
| 6988 | that may appear before the record type. |
| 6989 | |
| 6990 | The &(dnsdb)& lookup fails only if all the DNS lookups fail. If there is a |
| 6991 | temporary DNS error for any of them, the behaviour is controlled by |
| 6992 | a defer-option modifier. |
| 6993 | The possible keywords are |
| 6994 | &"defer_strict"&, &"defer_never"&, and &"defer_lax"&. |
| 6995 | With &"strict"& behaviour, any temporary DNS error causes the |
| 6996 | whole lookup to defer. With &"never"& behaviour, a temporary DNS error is |
| 6997 | ignored, and the behaviour is as if the DNS lookup failed to find anything. |
| 6998 | With &"lax"& behaviour, all the queries are attempted, but a temporary DNS |
| 6999 | error causes the whole lookup to defer only if none of the other lookups |
| 7000 | succeed. The default is &"lax"&, so the following lookups are equivalent: |
| 7001 | .code |
| 7002 | ${lookup dnsdb{defer_lax,a=one.host.com:two.host.com}} |
| 7003 | ${lookup dnsdb{a=one.host.com:two.host.com}} |
| 7004 | .endd |
| 7005 | Thus, in the default case, as long as at least one of the DNS lookups |
| 7006 | yields some data, the lookup succeeds. |
| 7007 | |
| 7008 | .new |
| 7009 | .cindex "DNSSEC" "dns lookup" |
| 7010 | Use of &(DNSSEC)& is controlled by a dnssec modifier. |
| 7011 | The possible keywords are |
| 7012 | &"dnssec_strict"&, &"dnssec_lax"&, and &"dnssec_never"&. |
| 7013 | With &"strict"& or &"lax"& DNSSEC information is requested |
| 7014 | with the lookup. |
| 7015 | With &"strict"& a response from the DNS resolver that |
| 7016 | is not labelled as authenticated data |
| 7017 | is treated as equivalent to a temporary DNS error. |
| 7018 | The default is &"never"&. |
| 7019 | |
| 7020 | See also the &$lookup_dnssec_authenticated$& variable. |
| 7021 | .wen |
| 7022 | |
| 7023 | |
| 7024 | |
| 7025 | |
| 7026 | .section "More about LDAP" "SECTldap" |
| 7027 | .cindex "LDAP" "lookup, more about" |
| 7028 | .cindex "lookup" "LDAP" |
| 7029 | .cindex "Solaris" "LDAP" |
| 7030 | The original LDAP implementation came from the University of Michigan; this has |
| 7031 | become &"Open LDAP"&, and there are now two different releases. Another |
| 7032 | implementation comes from Netscape, and Solaris 7 and subsequent releases |
| 7033 | contain inbuilt LDAP support. Unfortunately, though these are all compatible at |
| 7034 | the lookup function level, their error handling is different. For this reason |
| 7035 | it is necessary to set a compile-time variable when building Exim with LDAP, to |
| 7036 | indicate which LDAP library is in use. One of the following should appear in |
| 7037 | your &_Local/Makefile_&: |
| 7038 | .code |
| 7039 | LDAP_LIB_TYPE=UMICHIGAN |
| 7040 | LDAP_LIB_TYPE=OPENLDAP1 |
| 7041 | LDAP_LIB_TYPE=OPENLDAP2 |
| 7042 | LDAP_LIB_TYPE=NETSCAPE |
| 7043 | LDAP_LIB_TYPE=SOLARIS |
| 7044 | .endd |
| 7045 | If LDAP_LIB_TYPE is not set, Exim assumes &`OPENLDAP1`&, which has the |
| 7046 | same interface as the University of Michigan version. |
| 7047 | |
| 7048 | There are three LDAP lookup types in Exim. These behave slightly differently in |
| 7049 | the way they handle the results of a query: |
| 7050 | |
| 7051 | .ilist |
| 7052 | &(ldap)& requires the result to contain just one entry; if there are more, it |
| 7053 | gives an error. |
| 7054 | .next |
| 7055 | &(ldapdn)& also requires the result to contain just one entry, but it is the |
| 7056 | Distinguished Name that is returned rather than any attribute values. |
| 7057 | .next |
| 7058 | &(ldapm)& permits the result to contain more than one entry; the attributes |
| 7059 | from all of them are returned. |
| 7060 | .endlist |
| 7061 | |
| 7062 | |
| 7063 | For &(ldap)& and &(ldapm)&, if a query finds only entries with no attributes, |
| 7064 | Exim behaves as if the entry did not exist, and the lookup fails. The format of |
| 7065 | the data returned by a successful lookup is described in the next section. |
| 7066 | First we explain how LDAP queries are coded. |
| 7067 | |
| 7068 | |
| 7069 | .section "Format of LDAP queries" "SECTforldaque" |
| 7070 | .cindex "LDAP" "query format" |
| 7071 | An LDAP query takes the form of a URL as defined in RFC 2255. For example, in |
| 7072 | the configuration of a &(redirect)& router one might have this setting: |
| 7073 | .code |
| 7074 | data = ${lookup ldap \ |
| 7075 | {ldap:///cn=$local_part,o=University%20of%20Cambridge,\ |
| 7076 | c=UK?mailbox?base?}} |
| 7077 | .endd |
| 7078 | .cindex "LDAP" "with TLS" |
| 7079 | The URL may begin with &`ldap`& or &`ldaps`& if your LDAP library supports |
| 7080 | secure (encrypted) LDAP connections. The second of these ensures that an |
| 7081 | encrypted TLS connection is used. |
| 7082 | |
| 7083 | With sufficiently modern LDAP libraries, Exim supports forcing TLS over regular |
| 7084 | LDAP connections, rather than the SSL-on-connect &`ldaps`&. |
| 7085 | See the &%ldap_start_tls%& option. |
| 7086 | |
| 7087 | .new |
| 7088 | Starting with Exim 4.83, the initialization of LDAP with TLS is more tightly |
| 7089 | controlled. Every part of the TLS configuration can be configured by settings in |
| 7090 | &_exim.conf_&. Depending on the version of the client libraries installed on |
| 7091 | your system, some of the initialization may have required setting options in |
| 7092 | &_/etc/ldap.conf_& or &_~/.ldaprc_& to get TLS working with self-signed |
| 7093 | certificates. This revealed a nuance where the current UID that exim was |
| 7094 | running as could affect which config files it read. With Exim 4.83, these |
| 7095 | methods become optional, only taking effect if not specifically set in |
| 7096 | &_exim.conf_&. |
| 7097 | .wen |
| 7098 | |
| 7099 | |
| 7100 | .section "LDAP quoting" "SECID68" |
| 7101 | .cindex "LDAP" "quoting" |
| 7102 | Two levels of quoting are required in LDAP queries, the first for LDAP itself |
| 7103 | and the second because the LDAP query is represented as a URL. Furthermore, |
| 7104 | within an LDAP query, two different kinds of quoting are required. For this |
| 7105 | reason, there are two different LDAP-specific quoting operators. |
| 7106 | |
| 7107 | The &%quote_ldap%& operator is designed for use on strings that are part of |
| 7108 | filter specifications. Conceptually, it first does the following conversions on |
| 7109 | the string: |
| 7110 | .code |
| 7111 | * => \2A |
| 7112 | ( => \28 |
| 7113 | ) => \29 |
| 7114 | \ => \5C |
| 7115 | .endd |
| 7116 | in accordance with RFC 2254. The resulting string is then quoted according |
| 7117 | to the rules for URLs, that is, all non-alphanumeric characters except |
| 7118 | .code |
| 7119 | ! $ ' - . _ ( ) * + |
| 7120 | .endd |
| 7121 | are converted to their hex values, preceded by a percent sign. For example: |
| 7122 | .code |
| 7123 | ${quote_ldap: a(bc)*, a<yz>; } |
| 7124 | .endd |
| 7125 | yields |
| 7126 | .code |
| 7127 | %20a%5C28bc%5C29%5C2A%2C%20a%3Cyz%3E%3B%20 |
| 7128 | .endd |
| 7129 | Removing the URL quoting, this is (with a leading and a trailing space): |
| 7130 | .code |
| 7131 | a\28bc\29\2A, a<yz>; |
| 7132 | .endd |
| 7133 | The &%quote_ldap_dn%& operator is designed for use on strings that are part of |
| 7134 | base DN specifications in queries. Conceptually, it first converts the string |
| 7135 | by inserting a backslash in front of any of the following characters: |
| 7136 | .code |
| 7137 | , + " \ < > ; |
| 7138 | .endd |
| 7139 | It also inserts a backslash before any leading spaces or # characters, and |
| 7140 | before any trailing spaces. (These rules are in RFC 2253.) The resulting string |
| 7141 | is then quoted according to the rules for URLs. For example: |
| 7142 | .code |
| 7143 | ${quote_ldap_dn: a(bc)*, a<yz>; } |
| 7144 | .endd |
| 7145 | yields |
| 7146 | .code |
| 7147 | %5C%20a(bc)*%5C%2C%20a%5C%3Cyz%5C%3E%5C%3B%5C%20 |
| 7148 | .endd |
| 7149 | Removing the URL quoting, this is (with a trailing space): |
| 7150 | .code |
| 7151 | \ a(bc)*\, a\<yz\>\;\ |
| 7152 | .endd |
| 7153 | There are some further comments about quoting in the section on LDAP |
| 7154 | authentication below. |
| 7155 | |
| 7156 | |
| 7157 | .section "LDAP connections" "SECID69" |
| 7158 | .cindex "LDAP" "connections" |
| 7159 | The connection to an LDAP server may either be over TCP/IP, or, when OpenLDAP |
| 7160 | is in use, via a Unix domain socket. The example given above does not specify |
| 7161 | an LDAP server. A server that is reached by TCP/IP can be specified in a query |
| 7162 | by starting it with |
| 7163 | .code |
| 7164 | ldap://<hostname>:<port>/... |
| 7165 | .endd |
| 7166 | If the port (and preceding colon) are omitted, the standard LDAP port (389) is |
| 7167 | used. When no server is specified in a query, a list of default servers is |
| 7168 | taken from the &%ldap_default_servers%& configuration option. This supplies a |
| 7169 | colon-separated list of servers which are tried in turn until one successfully |
| 7170 | handles a query, or there is a serious error. Successful handling either |
| 7171 | returns the requested data, or indicates that it does not exist. Serious errors |
| 7172 | are syntactical, or multiple values when only a single value is expected. |
| 7173 | Errors which cause the next server to be tried are connection failures, bind |
| 7174 | failures, and timeouts. |
| 7175 | |
| 7176 | For each server name in the list, a port number can be given. The standard way |
| 7177 | of specifying a host and port is to use a colon separator (RFC 1738). Because |
| 7178 | &%ldap_default_servers%& is a colon-separated list, such colons have to be |
| 7179 | doubled. For example |
| 7180 | .code |
| 7181 | ldap_default_servers = ldap1.example.com::145:ldap2.example.com |
| 7182 | .endd |
| 7183 | If &%ldap_default_servers%& is unset, a URL with no server name is passed |
| 7184 | to the LDAP library with no server name, and the library's default (normally |
| 7185 | the local host) is used. |
| 7186 | |
| 7187 | If you are using the OpenLDAP library, you can connect to an LDAP server using |
| 7188 | a Unix domain socket instead of a TCP/IP connection. This is specified by using |
| 7189 | &`ldapi`& instead of &`ldap`& in LDAP queries. What follows here applies only |
| 7190 | to OpenLDAP. If Exim is compiled with a different LDAP library, this feature is |
| 7191 | not available. |
| 7192 | |
| 7193 | For this type of connection, instead of a host name for the server, a pathname |
| 7194 | for the socket is required, and the port number is not relevant. The pathname |
| 7195 | can be specified either as an item in &%ldap_default_servers%&, or inline in |
| 7196 | the query. In the former case, you can have settings such as |
| 7197 | .code |
| 7198 | ldap_default_servers = /tmp/ldap.sock : backup.ldap.your.domain |
| 7199 | .endd |
| 7200 | When the pathname is given in the query, you have to escape the slashes as |
| 7201 | &`%2F`& to fit in with the LDAP URL syntax. For example: |
| 7202 | .code |
| 7203 | ${lookup ldap {ldapi://%2Ftmp%2Fldap.sock/o=... |
| 7204 | .endd |
| 7205 | When Exim processes an LDAP lookup and finds that the &"hostname"& is really |
| 7206 | a pathname, it uses the Unix domain socket code, even if the query actually |
| 7207 | specifies &`ldap`& or &`ldaps`&. In particular, no encryption is used for a |
| 7208 | socket connection. This behaviour means that you can use a setting of |
| 7209 | &%ldap_default_servers%& such as in the example above with traditional &`ldap`& |
| 7210 | or &`ldaps`& queries, and it will work. First, Exim tries a connection via |
| 7211 | the Unix domain socket; if that fails, it tries a TCP/IP connection to the |
| 7212 | backup host. |
| 7213 | |
| 7214 | If an explicit &`ldapi`& type is given in a query when a host name is |
| 7215 | specified, an error is diagnosed. However, if there are more items in |
| 7216 | &%ldap_default_servers%&, they are tried. In other words: |
| 7217 | |
| 7218 | .ilist |
| 7219 | Using a pathname with &`ldap`& or &`ldaps`& forces the use of the Unix domain |
| 7220 | interface. |
| 7221 | .next |
| 7222 | Using &`ldapi`& with a host name causes an error. |
| 7223 | .endlist |
| 7224 | |
| 7225 | |
| 7226 | Using &`ldapi`& with no host or path in the query, and no setting of |
| 7227 | &%ldap_default_servers%&, does whatever the library does by default. |
| 7228 | |
| 7229 | |
| 7230 | |
| 7231 | .section "LDAP authentication and control information" "SECID70" |
| 7232 | .cindex "LDAP" "authentication" |
| 7233 | The LDAP URL syntax provides no way of passing authentication and other control |
| 7234 | information to the server. To make this possible, the URL in an LDAP query may |
| 7235 | be preceded by any number of <&'name'&>=<&'value'&> settings, separated by |
| 7236 | spaces. If a value contains spaces it must be enclosed in double quotes, and |
| 7237 | when double quotes are used, backslash is interpreted in the usual way inside |
| 7238 | them. The following names are recognized: |
| 7239 | .display |
| 7240 | &`DEREFERENCE`& set the dereferencing parameter |
| 7241 | &`NETTIME `& set a timeout for a network operation |
| 7242 | &`USER `& set the DN, for authenticating the LDAP bind |
| 7243 | &`PASS `& set the password, likewise |
| 7244 | &`REFERRALS `& set the referrals parameter |
| 7245 | .new |
| 7246 | &`SERVERS `& set alternate server list for this query only |
| 7247 | .wen |
| 7248 | &`SIZE `& set the limit for the number of entries returned |
| 7249 | &`TIME `& set the maximum waiting time for a query |
| 7250 | .endd |
| 7251 | The value of the DEREFERENCE parameter must be one of the words &"never"&, |
| 7252 | &"searching"&, &"finding"&, or &"always"&. The value of the REFERRALS parameter |
| 7253 | must be &"follow"& (the default) or &"nofollow"&. The latter stops the LDAP |
| 7254 | library from trying to follow referrals issued by the LDAP server. |
| 7255 | |
| 7256 | The name CONNECT is an obsolete name for NETTIME, retained for |
| 7257 | backwards compatibility. This timeout (specified as a number of seconds) is |
| 7258 | enforced from the client end for operations that can be carried out over a |
| 7259 | network. Specifically, it applies to network connections and calls to the |
| 7260 | &'ldap_result()'& function. If the value is greater than zero, it is used if |
| 7261 | LDAP_OPT_NETWORK_TIMEOUT is defined in the LDAP headers (OpenLDAP), or |
| 7262 | if LDAP_X_OPT_CONNECT_TIMEOUT is defined in the LDAP headers (Netscape |
| 7263 | SDK 4.1). A value of zero forces an explicit setting of &"no timeout"& for |
| 7264 | Netscape SDK; for OpenLDAP no action is taken. |
| 7265 | |
| 7266 | The TIME parameter (also a number of seconds) is passed to the server to |
| 7267 | set a server-side limit on the time taken to complete a search. |
| 7268 | |
| 7269 | .new |
| 7270 | The SERVERS parameter allows you to specify an alternate list of ldap servers |
| 7271 | to use for an individual lookup. The global ldap_servers option provides a |
| 7272 | default list of ldap servers, and a single lookup can specify a single ldap |
| 7273 | server to use. But when you need to do a lookup with a list of servers that is |
| 7274 | different than the default list (maybe different order, maybe a completely |
| 7275 | different set of servers), the SERVERS parameter allows you to specify this |
| 7276 | alternate list. |
| 7277 | .wen |
| 7278 | |
| 7279 | Here is an example of an LDAP query in an Exim lookup that uses some of these |
| 7280 | values. This is a single line, folded to fit on the page: |
| 7281 | .code |
| 7282 | ${lookup ldap |
| 7283 | {user="cn=manager,o=University of Cambridge,c=UK" pass=secret |
| 7284 | ldap:///o=University%20of%20Cambridge,c=UK?sn?sub?(cn=foo)} |
| 7285 | {$value}fail} |
| 7286 | .endd |
| 7287 | The encoding of spaces as &`%20`& is a URL thing which should not be done for |
| 7288 | any of the auxiliary data. Exim configuration settings that include lookups |
| 7289 | which contain password information should be preceded by &"hide"& to prevent |
| 7290 | non-admin users from using the &%-bP%& option to see their values. |
| 7291 | |
| 7292 | The auxiliary data items may be given in any order. The default is no |
| 7293 | connection timeout (the system timeout is used), no user or password, no limit |
| 7294 | on the number of entries returned, and no time limit on queries. |
| 7295 | |
| 7296 | When a DN is quoted in the USER= setting for LDAP authentication, Exim |
| 7297 | removes any URL quoting that it may contain before passing it LDAP. Apparently |
| 7298 | some libraries do this for themselves, but some do not. Removing the URL |
| 7299 | quoting has two advantages: |
| 7300 | |
| 7301 | .ilist |
| 7302 | It makes it possible to use the same &%quote_ldap_dn%& expansion for USER= |
| 7303 | DNs as with DNs inside actual queries. |
| 7304 | .next |
| 7305 | It permits spaces inside USER= DNs. |
| 7306 | .endlist |
| 7307 | |
| 7308 | For example, a setting such as |
| 7309 | .code |
| 7310 | USER=cn=${quote_ldap_dn:$1} |
| 7311 | .endd |
| 7312 | should work even if &$1$& contains spaces. |
| 7313 | |
| 7314 | Expanded data for the PASS= value should be quoted using the &%quote%& |
| 7315 | expansion operator, rather than the LDAP quote operators. The only reason this |
| 7316 | field needs quoting is to ensure that it conforms to the Exim syntax, which |
| 7317 | does not allow unquoted spaces. For example: |
| 7318 | .code |
| 7319 | PASS=${quote:$3} |
| 7320 | .endd |
| 7321 | The LDAP authentication mechanism can be used to check passwords as part of |
| 7322 | SMTP authentication. See the &%ldapauth%& expansion string condition in chapter |
| 7323 | &<<CHAPexpand>>&. |
| 7324 | |
| 7325 | |
| 7326 | |
| 7327 | .section "Format of data returned by LDAP" "SECID71" |
| 7328 | .cindex "LDAP" "returned data formats" |
| 7329 | The &(ldapdn)& lookup type returns the Distinguished Name from a single entry |
| 7330 | as a sequence of values, for example |
| 7331 | .code |
| 7332 | cn=manager, o=University of Cambridge, c=UK |
| 7333 | .endd |
| 7334 | The &(ldap)& lookup type generates an error if more than one entry matches the |
| 7335 | search filter, whereas &(ldapm)& permits this case, and inserts a newline in |
| 7336 | the result between the data from different entries. It is possible for multiple |
| 7337 | values to be returned for both &(ldap)& and &(ldapm)&, but in the former case |
| 7338 | you know that whatever values are returned all came from a single entry in the |
| 7339 | directory. |
| 7340 | |
| 7341 | In the common case where you specify a single attribute in your LDAP query, the |
| 7342 | result is not quoted, and does not contain the attribute name. If the attribute |
| 7343 | has multiple values, they are separated by commas. |
| 7344 | |
| 7345 | If you specify multiple attributes, the result contains space-separated, quoted |
| 7346 | strings, each preceded by the attribute name and an equals sign. Within the |
| 7347 | quotes, the quote character, backslash, and newline are escaped with |
| 7348 | backslashes, and commas are used to separate multiple values for the attribute. |
| 7349 | Apart from the escaping, the string within quotes takes the same form as the |
| 7350 | output when a single attribute is requested. Specifying no attributes is the |
| 7351 | same as specifying all of an entry's attributes. |
| 7352 | |
| 7353 | Here are some examples of the output format. The first line of each pair is an |
| 7354 | LDAP query, and the second is the data that is returned. The attribute called |
| 7355 | &%attr1%& has two values, whereas &%attr2%& has only one value: |
| 7356 | .code |
| 7357 | ldap:///o=base?attr1?sub?(uid=fred) |
| 7358 | value1.1, value1.2 |
| 7359 | |
| 7360 | ldap:///o=base?attr2?sub?(uid=fred) |
| 7361 | value two |
| 7362 | |
| 7363 | ldap:///o=base?attr1,attr2?sub?(uid=fred) |
| 7364 | attr1="value1.1, value1.2" attr2="value two" |
| 7365 | |
| 7366 | ldap:///o=base??sub?(uid=fred) |
| 7367 | objectClass="top" attr1="value1.1, value1.2" attr2="value two" |
| 7368 | .endd |
| 7369 | The &%extract%& operator in string expansions can be used to pick out |
| 7370 | individual fields from data that consists of &'key'&=&'value'& pairs. You can |
| 7371 | make use of Exim's &%-be%& option to run expansion tests and thereby check the |
| 7372 | results of LDAP lookups. |
| 7373 | |
| 7374 | |
| 7375 | |
| 7376 | |
| 7377 | .section "More about NIS+" "SECTnisplus" |
| 7378 | .cindex "NIS+ lookup type" |
| 7379 | .cindex "lookup" "NIS+" |
| 7380 | NIS+ queries consist of a NIS+ &'indexed name'& followed by an optional colon |
| 7381 | and field name. If this is given, the result of a successful query is the |
| 7382 | contents of the named field; otherwise the result consists of a concatenation |
| 7383 | of &'field-name=field-value'& pairs, separated by spaces. Empty values and |
| 7384 | values containing spaces are quoted. For example, the query |
| 7385 | .code |
| 7386 | [name=mg1456],passwd.org_dir |
| 7387 | .endd |
| 7388 | might return the string |
| 7389 | .code |
| 7390 | name=mg1456 passwd="" uid=999 gid=999 gcos="Martin Guerre" |
| 7391 | home=/home/mg1456 shell=/bin/bash shadow="" |
| 7392 | .endd |
| 7393 | (split over two lines here to fit on the page), whereas |
| 7394 | .code |
| 7395 | [name=mg1456],passwd.org_dir:gcos |
| 7396 | .endd |
| 7397 | would just return |
| 7398 | .code |
| 7399 | Martin Guerre |
| 7400 | .endd |
| 7401 | with no quotes. A NIS+ lookup fails if NIS+ returns more than one table entry |
| 7402 | for the given indexed key. The effect of the &%quote_nisplus%& expansion |
| 7403 | operator is to double any quote characters within the text. |
| 7404 | |
| 7405 | |
| 7406 | |
| 7407 | .section "SQL lookups" "SECTsql" |
| 7408 | .cindex "SQL lookup types" |
| 7409 | .cindex "MySQL" "lookup type" |
| 7410 | .cindex "PostgreSQL lookup type" |
| 7411 | .cindex "lookup" "MySQL" |
| 7412 | .cindex "lookup" "PostgreSQL" |
| 7413 | .cindex "Oracle" "lookup type" |
| 7414 | .cindex "lookup" "Oracle" |
| 7415 | .cindex "InterBase lookup type" |
| 7416 | .cindex "lookup" "InterBase" |
| 7417 | Exim can support lookups in InterBase, MySQL, Oracle, PostgreSQL, and SQLite |
| 7418 | databases. Queries for these databases contain SQL statements, so an example |
| 7419 | might be |
| 7420 | .code |
| 7421 | ${lookup mysql{select mailbox from users where id='userx'}\ |
| 7422 | {$value}fail} |
| 7423 | .endd |
| 7424 | If the result of the query contains more than one field, the data for each |
| 7425 | field in the row is returned, preceded by its name, so the result of |
| 7426 | .code |
| 7427 | ${lookup pgsql{select home,name from users where id='userx'}\ |
| 7428 | {$value}} |
| 7429 | .endd |
| 7430 | might be |
| 7431 | .code |
| 7432 | home=/home/userx name="Mister X" |
| 7433 | .endd |
| 7434 | Empty values and values containing spaces are double quoted, with embedded |
| 7435 | quotes escaped by a backslash. If the result of the query contains just one |
| 7436 | field, the value is passed back verbatim, without a field name, for example: |
| 7437 | .code |
| 7438 | Mister X |
| 7439 | .endd |
| 7440 | If the result of the query yields more than one row, it is all concatenated, |
| 7441 | with a newline between the data for each row. |
| 7442 | |
| 7443 | |
| 7444 | .section "More about MySQL, PostgreSQL, Oracle, and InterBase" "SECID72" |
| 7445 | .cindex "MySQL" "lookup type" |
| 7446 | .cindex "PostgreSQL lookup type" |
| 7447 | .cindex "lookup" "MySQL" |
| 7448 | .cindex "lookup" "PostgreSQL" |
| 7449 | .cindex "Oracle" "lookup type" |
| 7450 | .cindex "lookup" "Oracle" |
| 7451 | .cindex "InterBase lookup type" |
| 7452 | .cindex "lookup" "InterBase" |
| 7453 | If any MySQL, PostgreSQL, Oracle, or InterBase lookups are used, the |
| 7454 | &%mysql_servers%&, &%pgsql_servers%&, &%oracle_servers%&, or &%ibase_servers%& |
| 7455 | option (as appropriate) must be set to a colon-separated list of server |
| 7456 | information. |
| 7457 | (For MySQL and PostgreSQL only, the global option need not be set if all |
| 7458 | queries contain their own server information &-- see section |
| 7459 | &<<SECTspeserque>>&.) Each item in the list is a slash-separated list of four |
| 7460 | items: host name, database name, user name, and password. In the case of |
| 7461 | Oracle, the host name field is used for the &"service name"&, and the database |
| 7462 | name field is not used and should be empty. For example: |
| 7463 | .code |
| 7464 | hide oracle_servers = oracle.plc.example//userx/abcdwxyz |
| 7465 | .endd |
| 7466 | Because password data is sensitive, you should always precede the setting with |
| 7467 | &"hide"&, to prevent non-admin users from obtaining the setting via the &%-bP%& |
| 7468 | option. Here is an example where two MySQL servers are listed: |
| 7469 | .code |
| 7470 | hide mysql_servers = localhost/users/root/secret:\ |
| 7471 | otherhost/users/root/othersecret |
| 7472 | .endd |
| 7473 | For MySQL and PostgreSQL, a host may be specified as <&'name'&>:<&'port'&> but |
| 7474 | because this is a colon-separated list, the colon has to be doubled. For each |
| 7475 | query, these parameter groups are tried in order until a connection is made and |
| 7476 | a query is successfully processed. The result of a query may be that no data is |
| 7477 | found, but that is still a successful query. In other words, the list of |
| 7478 | servers provides a backup facility, not a list of different places to look. |
| 7479 | |
| 7480 | The &%quote_mysql%&, &%quote_pgsql%&, and &%quote_oracle%& expansion operators |
| 7481 | convert newline, tab, carriage return, and backspace to \n, \t, \r, and \b |
| 7482 | respectively, and the characters single-quote, double-quote, and backslash |
| 7483 | itself are escaped with backslashes. The &%quote_pgsql%& expansion operator, in |
| 7484 | addition, escapes the percent and underscore characters. This cannot be done |
| 7485 | for MySQL because these escapes are not recognized in contexts where these |
| 7486 | characters are not special. |
| 7487 | |
| 7488 | .section "Specifying the server in the query" "SECTspeserque" |
| 7489 | For MySQL and PostgreSQL lookups (but not currently for Oracle and InterBase), |
| 7490 | it is possible to specify a list of servers with an individual query. This is |
| 7491 | done by starting the query with |
| 7492 | .display |
| 7493 | &`servers=`&&'server1:server2:server3:...'&&`;`& |
| 7494 | .endd |
| 7495 | Each item in the list may take one of two forms: |
| 7496 | .olist |
| 7497 | If it contains no slashes it is assumed to be just a host name. The appropriate |
| 7498 | global option (&%mysql_servers%& or &%pgsql_servers%&) is searched for a host |
| 7499 | of the same name, and the remaining parameters (database, user, password) are |
| 7500 | taken from there. |
| 7501 | .next |
| 7502 | If it contains any slashes, it is taken as a complete parameter set. |
| 7503 | .endlist |
| 7504 | The list of servers is used in exactly the same way as the global list. |
| 7505 | Once a connection to a server has happened and a query has been |
| 7506 | successfully executed, processing of the lookup ceases. |
| 7507 | |
| 7508 | This feature is intended for use in master/slave situations where updates |
| 7509 | are occurring and you want to update the master rather than a slave. If the |
| 7510 | master is in the list as a backup for reading, you might have a global setting |
| 7511 | like this: |
| 7512 | .code |
| 7513 | mysql_servers = slave1/db/name/pw:\ |
| 7514 | slave2/db/name/pw:\ |
| 7515 | master/db/name/pw |
| 7516 | .endd |
| 7517 | In an updating lookup, you could then write: |
| 7518 | .code |
| 7519 | ${lookup mysql{servers=master; UPDATE ...} } |
| 7520 | .endd |
| 7521 | That query would then be sent only to the master server. If, on the other hand, |
| 7522 | the master is not to be used for reading, and so is not present in the global |
| 7523 | option, you can still update it by a query of this form: |
| 7524 | .code |
| 7525 | ${lookup pgsql{servers=master/db/name/pw; UPDATE ...} } |
| 7526 | .endd |
| 7527 | |
| 7528 | |
| 7529 | .section "Special MySQL features" "SECID73" |
| 7530 | For MySQL, an empty host name or the use of &"localhost"& in &%mysql_servers%& |
| 7531 | causes a connection to the server on the local host by means of a Unix domain |
| 7532 | socket. An alternate socket can be specified in parentheses. The full syntax of |
| 7533 | each item in &%mysql_servers%& is: |
| 7534 | .display |
| 7535 | <&'hostname'&>::<&'port'&>(<&'socket name'&>)/<&'database'&>/&&& |
| 7536 | <&'user'&>/<&'password'&> |
| 7537 | .endd |
| 7538 | Any of the three sub-parts of the first field can be omitted. For normal use on |
| 7539 | the local host it can be left blank or set to just &"localhost"&. |
| 7540 | |
| 7541 | No database need be supplied &-- but if it is absent here, it must be given in |
| 7542 | the queries. |
| 7543 | |
| 7544 | If a MySQL query is issued that does not request any data (an insert, update, |
| 7545 | or delete command), the result of the lookup is the number of rows affected. |
| 7546 | |
| 7547 | &*Warning*&: This can be misleading. If an update does not actually change |
| 7548 | anything (for example, setting a field to the value it already has), the result |
| 7549 | is zero because no rows are affected. |
| 7550 | |
| 7551 | |
| 7552 | .section "Special PostgreSQL features" "SECID74" |
| 7553 | PostgreSQL lookups can also use Unix domain socket connections to the database. |
| 7554 | This is usually faster and costs less CPU time than a TCP/IP connection. |
| 7555 | However it can be used only if the mail server runs on the same machine as the |
| 7556 | database server. A configuration line for PostgreSQL via Unix domain sockets |
| 7557 | looks like this: |
| 7558 | .code |
| 7559 | hide pgsql_servers = (/tmp/.s.PGSQL.5432)/db/user/password : ... |
| 7560 | .endd |
| 7561 | In other words, instead of supplying a host name, a path to the socket is |
| 7562 | given. The path name is enclosed in parentheses so that its slashes aren't |
| 7563 | visually confused with the delimiters for the other server parameters. |
| 7564 | |
| 7565 | If a PostgreSQL query is issued that does not request any data (an insert, |
| 7566 | update, or delete command), the result of the lookup is the number of rows |
| 7567 | affected. |
| 7568 | |
| 7569 | .section "More about SQLite" "SECTsqlite" |
| 7570 | .cindex "lookup" "SQLite" |
| 7571 | .cindex "sqlite lookup type" |
| 7572 | SQLite is different to the other SQL lookups because a file name is required in |
| 7573 | addition to the SQL query. An SQLite database is a single file, and there is no |
| 7574 | daemon as in the other SQL databases. The interface to Exim requires the name |
| 7575 | of the file, as an absolute path, to be given at the start of the query. It is |
| 7576 | separated from the query by white space. This means that the path name cannot |
| 7577 | contain white space. Here is a lookup expansion example: |
| 7578 | .code |
| 7579 | ${lookup sqlite {/some/thing/sqlitedb \ |
| 7580 | select name from aliases where id='userx';}} |
| 7581 | .endd |
| 7582 | In a list, the syntax is similar. For example: |
| 7583 | .code |
| 7584 | domainlist relay_to_domains = sqlite;/some/thing/sqlitedb \ |
| 7585 | select * from relays where ip='$sender_host_address'; |
| 7586 | .endd |
| 7587 | The only character affected by the &%quote_sqlite%& operator is a single |
| 7588 | quote, which it doubles. |
| 7589 | |
| 7590 | The SQLite library handles multiple simultaneous accesses to the database |
| 7591 | internally. Multiple readers are permitted, but only one process can |
| 7592 | update at once. Attempts to access the database while it is being updated |
| 7593 | are rejected after a timeout period, during which the SQLite library |
| 7594 | waits for the lock to be released. In Exim, the default timeout is set |
| 7595 | to 5 seconds, but it can be changed by means of the &%sqlite_lock_timeout%& |
| 7596 | option. |
| 7597 | .ecindex IIDfidalo1 |
| 7598 | .ecindex IIDfidalo2 |
| 7599 | |
| 7600 | |
| 7601 | . //////////////////////////////////////////////////////////////////////////// |
| 7602 | . //////////////////////////////////////////////////////////////////////////// |
| 7603 | |
| 7604 | .chapter "Domain, host, address, and local part lists" &&& |
| 7605 | "CHAPdomhosaddlists" &&& |
| 7606 | "Domain, host, and address lists" |
| 7607 | .scindex IIDdohoadli "lists of domains; hosts; etc." |
| 7608 | A number of Exim configuration options contain lists of domains, hosts, |
| 7609 | email addresses, or local parts. For example, the &%hold_domains%& option |
| 7610 | contains a list of domains whose delivery is currently suspended. These lists |
| 7611 | are also used as data in ACL statements (see chapter &<<CHAPACL>>&), and as |
| 7612 | arguments to expansion conditions such as &%match_domain%&. |
| 7613 | |
| 7614 | Each item in one of these lists is a pattern to be matched against a domain, |
| 7615 | host, email address, or local part, respectively. In the sections below, the |
| 7616 | different types of pattern for each case are described, but first we cover some |
| 7617 | general facilities that apply to all four kinds of list. |
| 7618 | |
| 7619 | |
| 7620 | |
| 7621 | .section "Expansion of lists" "SECID75" |
| 7622 | .cindex "expansion" "of lists" |
| 7623 | Each list is expanded as a single string before it is used. The result of |
| 7624 | expansion must be a list, possibly containing empty items, which is split up |
| 7625 | into separate items for matching. By default, colon is the separator character, |
| 7626 | but this can be varied if necessary. See sections &<<SECTlistconstruct>>& and |
| 7627 | &<<SECTempitelis>>& for details of the list syntax; the second of these |
| 7628 | discusses the way to specify empty list items. |
| 7629 | |
| 7630 | |
| 7631 | If the string expansion is forced to fail, Exim behaves as if the item it is |
| 7632 | testing (domain, host, address, or local part) is not in the list. Other |
| 7633 | expansion failures cause temporary errors. |
| 7634 | |
| 7635 | If an item in a list is a regular expression, backslashes, dollars and possibly |
| 7636 | other special characters in the expression must be protected against |
| 7637 | misinterpretation by the string expander. The easiest way to do this is to use |
| 7638 | the &`\N`& expansion feature to indicate that the contents of the regular |
| 7639 | expression should not be expanded. For example, in an ACL you might have: |
| 7640 | .code |
| 7641 | deny senders = \N^\d{8}\w@.*\.baddomain\.example$\N : \ |
| 7642 | ${lookup{$domain}lsearch{/badsenders/bydomain}} |
| 7643 | .endd |
| 7644 | The first item is a regular expression that is protected from expansion by |
| 7645 | &`\N`&, whereas the second uses the expansion to obtain a list of unwanted |
| 7646 | senders based on the receiving domain. |
| 7647 | |
| 7648 | |
| 7649 | |
| 7650 | |
| 7651 | .section "Negated items in lists" "SECID76" |
| 7652 | .cindex "list" "negation" |
| 7653 | .cindex "negation" "in lists" |
| 7654 | Items in a list may be positive or negative. Negative items are indicated by a |
| 7655 | leading exclamation mark, which may be followed by optional white space. A list |
| 7656 | defines a set of items (domains, etc). When Exim processes one of these lists, |
| 7657 | it is trying to find out whether a domain, host, address, or local part |
| 7658 | (respectively) is in the set that is defined by the list. It works like this: |
| 7659 | |
| 7660 | The list is scanned from left to right. If a positive item is matched, the |
| 7661 | subject that is being checked is in the set; if a negative item is matched, the |
| 7662 | subject is not in the set. If the end of the list is reached without the |
| 7663 | subject having matched any of the patterns, it is in the set if the last item |
| 7664 | was a negative one, but not if it was a positive one. For example, the list in |
| 7665 | .code |
| 7666 | domainlist relay_to_domains = !a.b.c : *.b.c |
| 7667 | .endd |
| 7668 | matches any domain ending in &'.b.c'& except for &'a.b.c'&. Domains that match |
| 7669 | neither &'a.b.c'& nor &'*.b.c'& do not match, because the last item in the |
| 7670 | list is positive. However, if the setting were |
| 7671 | .code |
| 7672 | domainlist relay_to_domains = !a.b.c |
| 7673 | .endd |
| 7674 | then all domains other than &'a.b.c'& would match because the last item in the |
| 7675 | list is negative. In other words, a list that ends with a negative item behaves |
| 7676 | as if it had an extra item &`:*`& on the end. |
| 7677 | |
| 7678 | Another way of thinking about positive and negative items in lists is to read |
| 7679 | the connector as &"or"& after a positive item and as &"and"& after a negative |
| 7680 | item. |
| 7681 | |
| 7682 | |
| 7683 | |
| 7684 | .section "File names in lists" "SECTfilnamlis" |
| 7685 | .cindex "list" "file name in" |
| 7686 | If an item in a domain, host, address, or local part list is an absolute file |
| 7687 | name (beginning with a slash character), each line of the file is read and |
| 7688 | processed as if it were an independent item in the list, except that further |
| 7689 | file names are not allowed, |
| 7690 | and no expansion of the data from the file takes place. |
| 7691 | Empty lines in the file are ignored, and the file may also contain comment |
| 7692 | lines: |
| 7693 | |
| 7694 | .ilist |
| 7695 | For domain and host lists, if a # character appears anywhere in a line of the |
| 7696 | file, it and all following characters are ignored. |
| 7697 | .next |
| 7698 | Because local parts may legitimately contain # characters, a comment in an |
| 7699 | address list or local part list file is recognized only if # is preceded by |
| 7700 | white space or the start of the line. For example: |
| 7701 | .code |
| 7702 | not#comment@x.y.z # but this is a comment |
| 7703 | .endd |
| 7704 | .endlist |
| 7705 | |
| 7706 | Putting a file name in a list has the same effect as inserting each line of the |
| 7707 | file as an item in the list (blank lines and comments excepted). However, there |
| 7708 | is one important difference: the file is read each time the list is processed, |
| 7709 | so if its contents vary over time, Exim's behaviour changes. |
| 7710 | |
| 7711 | If a file name is preceded by an exclamation mark, the sense of any match |
| 7712 | within the file is inverted. For example, if |
| 7713 | .code |
| 7714 | hold_domains = !/etc/nohold-domains |
| 7715 | .endd |
| 7716 | and the file contains the lines |
| 7717 | .code |
| 7718 | !a.b.c |
| 7719 | *.b.c |
| 7720 | .endd |
| 7721 | then &'a.b.c'& is in the set of domains defined by &%hold_domains%&, whereas |
| 7722 | any domain matching &`*.b.c`& is not. |
| 7723 | |
| 7724 | |
| 7725 | |
| 7726 | .section "An lsearch file is not an out-of-line list" "SECID77" |
| 7727 | As will be described in the sections that follow, lookups can be used in lists |
| 7728 | to provide indexed methods of checking list membership. There has been some |
| 7729 | confusion about the way &(lsearch)& lookups work in lists. Because |
| 7730 | an &(lsearch)& file contains plain text and is scanned sequentially, it is |
| 7731 | sometimes thought that it is allowed to contain wild cards and other kinds of |
| 7732 | non-constant pattern. This is not the case. The keys in an &(lsearch)& file are |
| 7733 | always fixed strings, just as for any other single-key lookup type. |
| 7734 | |
| 7735 | If you want to use a file to contain wild-card patterns that form part of a |
| 7736 | list, just give the file name on its own, without a search type, as described |
| 7737 | in the previous section. You could also use the &(wildlsearch)& or |
| 7738 | &(nwildlsearch)&, but there is no advantage in doing this. |
| 7739 | |
| 7740 | |
| 7741 | |
| 7742 | |
| 7743 | .section "Named lists" "SECTnamedlists" |
| 7744 | .cindex "named lists" |
| 7745 | .cindex "list" "named" |
| 7746 | A list of domains, hosts, email addresses, or local parts can be given a name |
| 7747 | which is then used to refer to the list elsewhere in the configuration. This is |
| 7748 | particularly convenient if the same list is required in several different |
| 7749 | places. It also allows lists to be given meaningful names, which can improve |
| 7750 | the readability of the configuration. For example, it is conventional to define |
| 7751 | a domain list called &'local_domains'& for all the domains that are handled |
| 7752 | locally on a host, using a configuration line such as |
| 7753 | .code |
| 7754 | domainlist local_domains = localhost:my.dom.example |
| 7755 | .endd |
| 7756 | Named lists are referenced by giving their name preceded by a plus sign, so, |
| 7757 | for example, a router that is intended to handle local domains would be |
| 7758 | configured with the line |
| 7759 | .code |
| 7760 | domains = +local_domains |
| 7761 | .endd |
| 7762 | The first router in a configuration is often one that handles all domains |
| 7763 | except the local ones, using a configuration with a negated item like this: |
| 7764 | .code |
| 7765 | dnslookup: |
| 7766 | driver = dnslookup |
| 7767 | domains = ! +local_domains |
| 7768 | transport = remote_smtp |
| 7769 | no_more |
| 7770 | .endd |
| 7771 | The four kinds of named list are created by configuration lines starting with |
| 7772 | the words &%domainlist%&, &%hostlist%&, &%addresslist%&, or &%localpartlist%&, |
| 7773 | respectively. Then there follows the name that you are defining, followed by an |
| 7774 | equals sign and the list itself. For example: |
| 7775 | .code |
| 7776 | hostlist relay_from_hosts = 192.168.23.0/24 : my.friend.example |
| 7777 | addresslist bad_senders = cdb;/etc/badsenders |
| 7778 | .endd |
| 7779 | A named list may refer to other named lists: |
| 7780 | .code |
| 7781 | domainlist dom1 = first.example : second.example |
| 7782 | domainlist dom2 = +dom1 : third.example |
| 7783 | domainlist dom3 = fourth.example : +dom2 : fifth.example |
| 7784 | .endd |
| 7785 | &*Warning*&: If the last item in a referenced list is a negative one, the |
| 7786 | effect may not be what you intended, because the negation does not propagate |
| 7787 | out to the higher level. For example, consider: |
| 7788 | .code |
| 7789 | domainlist dom1 = !a.b |
| 7790 | domainlist dom2 = +dom1 : *.b |
| 7791 | .endd |
| 7792 | The second list specifies &"either in the &%dom1%& list or &'*.b'&"&. The first |
| 7793 | list specifies just &"not &'a.b'&"&, so the domain &'x.y'& matches it. That |
| 7794 | means it matches the second list as well. The effect is not the same as |
| 7795 | .code |
| 7796 | domainlist dom2 = !a.b : *.b |
| 7797 | .endd |
| 7798 | where &'x.y'& does not match. It's best to avoid negation altogether in |
| 7799 | referenced lists if you can. |
| 7800 | |
| 7801 | Named lists may have a performance advantage. When Exim is routing an |
| 7802 | address or checking an incoming message, it caches the result of tests on named |
| 7803 | lists. So, if you have a setting such as |
| 7804 | .code |
| 7805 | domains = +local_domains |
| 7806 | .endd |
| 7807 | on several of your routers |
| 7808 | or in several ACL statements, |
| 7809 | the actual test is done only for the first one. However, the caching works only |
| 7810 | if there are no expansions within the list itself or any sublists that it |
| 7811 | references. In other words, caching happens only for lists that are known to be |
| 7812 | the same each time they are referenced. |
| 7813 | |
| 7814 | By default, there may be up to 16 named lists of each type. This limit can be |
| 7815 | extended by changing a compile-time variable. The use of domain and host lists |
| 7816 | is recommended for concepts such as local domains, relay domains, and relay |
| 7817 | hosts. The default configuration is set up like this. |
| 7818 | |
| 7819 | |
| 7820 | |
| 7821 | .section "Named lists compared with macros" "SECID78" |
| 7822 | .cindex "list" "named compared with macro" |
| 7823 | .cindex "macro" "compared with named list" |
| 7824 | At first sight, named lists might seem to be no different from macros in the |
| 7825 | configuration file. However, macros are just textual substitutions. If you |
| 7826 | write |
| 7827 | .code |
| 7828 | ALIST = host1 : host2 |
| 7829 | auth_advertise_hosts = !ALIST |
| 7830 | .endd |
| 7831 | it probably won't do what you want, because that is exactly the same as |
| 7832 | .code |
| 7833 | auth_advertise_hosts = !host1 : host2 |
| 7834 | .endd |
| 7835 | Notice that the second host name is not negated. However, if you use a host |
| 7836 | list, and write |
| 7837 | .code |
| 7838 | hostlist alist = host1 : host2 |
| 7839 | auth_advertise_hosts = ! +alist |
| 7840 | .endd |
| 7841 | the negation applies to the whole list, and so that is equivalent to |
| 7842 | .code |
| 7843 | auth_advertise_hosts = !host1 : !host2 |
| 7844 | .endd |
| 7845 | |
| 7846 | |
| 7847 | .section "Named list caching" "SECID79" |
| 7848 | .cindex "list" "caching of named" |
| 7849 | .cindex "caching" "named lists" |
| 7850 | While processing a message, Exim caches the result of checking a named list if |
| 7851 | it is sure that the list is the same each time. In practice, this means that |
| 7852 | the cache operates only if the list contains no $ characters, which guarantees |
| 7853 | that it will not change when it is expanded. Sometimes, however, you may have |
| 7854 | an expanded list that you know will be the same each time within a given |
| 7855 | message. For example: |
| 7856 | .code |
| 7857 | domainlist special_domains = \ |
| 7858 | ${lookup{$sender_host_address}cdb{/some/file}} |
| 7859 | .endd |
| 7860 | This provides a list of domains that depends only on the sending host's IP |
| 7861 | address. If this domain list is referenced a number of times (for example, |
| 7862 | in several ACL lines, or in several routers) the result of the check is not |
| 7863 | cached by default, because Exim does not know that it is going to be the |
| 7864 | same list each time. |
| 7865 | |
| 7866 | By appending &`_cache`& to &`domainlist`& you can tell Exim to go ahead and |
| 7867 | cache the result anyway. For example: |
| 7868 | .code |
| 7869 | domainlist_cache special_domains = ${lookup{... |
| 7870 | .endd |
| 7871 | If you do this, you should be absolutely sure that caching is going to do |
| 7872 | the right thing in all cases. When in doubt, leave it out. |
| 7873 | |
| 7874 | |
| 7875 | |
| 7876 | .section "Domain lists" "SECTdomainlist" |
| 7877 | .cindex "domain list" "patterns for" |
| 7878 | .cindex "list" "domain list" |
| 7879 | Domain lists contain patterns that are to be matched against a mail domain. |
| 7880 | The following types of item may appear in domain lists: |
| 7881 | |
| 7882 | .ilist |
| 7883 | .cindex "primary host name" |
| 7884 | .cindex "host name" "matched in domain list" |
| 7885 | .oindex "&%primary_hostname%&" |
| 7886 | .cindex "domain list" "matching primary host name" |
| 7887 | .cindex "@ in a domain list" |
| 7888 | If a pattern consists of a single @ character, it matches the local host name, |
| 7889 | as set by the &%primary_hostname%& option (or defaulted). This makes it |
| 7890 | possible to use the same configuration file on several different hosts that |
| 7891 | differ only in their names. |
| 7892 | .next |
| 7893 | .cindex "@[] in a domain list" |
| 7894 | .cindex "domain list" "matching local IP interfaces" |
| 7895 | .cindex "domain literal" |
| 7896 | If a pattern consists of the string &`@[]`& it matches an IP address enclosed |
| 7897 | in square brackets (as in an email address that contains a domain literal), but |
| 7898 | only if that IP address is recognized as local for email routing purposes. The |
| 7899 | &%local_interfaces%& and &%extra_local_interfaces%& options can be used to |
| 7900 | control which of a host's several IP addresses are treated as local. |
| 7901 | In today's Internet, the use of domain literals is controversial. |
| 7902 | .next |
| 7903 | .cindex "@mx_any" |
| 7904 | .cindex "@mx_primary" |
| 7905 | .cindex "@mx_secondary" |
| 7906 | .cindex "domain list" "matching MX pointers to local host" |
| 7907 | If a pattern consists of the string &`@mx_any`& it matches any domain that |
| 7908 | has an MX record pointing to the local host or to any host that is listed in |
| 7909 | .oindex "&%hosts_treat_as_local%&" |
| 7910 | &%hosts_treat_as_local%&. The items &`@mx_primary`& and &`@mx_secondary`& |
| 7911 | are similar, except that the first matches only when a primary MX target is the |
| 7912 | local host, and the second only when no primary MX target is the local host, |
| 7913 | but a secondary MX target is. &"Primary"& means an MX record with the lowest |
| 7914 | preference value &-- there may of course be more than one of them. |
| 7915 | |
| 7916 | The MX lookup that takes place when matching a pattern of this type is |
| 7917 | performed with the resolver options for widening names turned off. Thus, for |
| 7918 | example, a single-component domain will &'not'& be expanded by adding the |
| 7919 | resolver's default domain. See the &%qualify_single%& and &%search_parents%& |
| 7920 | options of the &(dnslookup)& router for a discussion of domain widening. |
| 7921 | |
| 7922 | Sometimes you may want to ignore certain IP addresses when using one of these |
| 7923 | patterns. You can specify this by following the pattern with &`/ignore=`&<&'ip |
| 7924 | list'&>, where <&'ip list'&> is a list of IP addresses. These addresses are |
| 7925 | ignored when processing the pattern (compare the &%ignore_target_hosts%& option |
| 7926 | on a router). For example: |
| 7927 | .code |
| 7928 | domains = @mx_any/ignore=127.0.0.1 |
| 7929 | .endd |
| 7930 | This example matches any domain that has an MX record pointing to one of |
| 7931 | the local host's IP addresses other than 127.0.0.1. |
| 7932 | |
| 7933 | The list of IP addresses is in fact processed by the same code that processes |
| 7934 | host lists, so it may contain CIDR-coded network specifications and it may also |
| 7935 | contain negative items. |
| 7936 | |
| 7937 | Because the list of IP addresses is a sublist within a domain list, you have to |
| 7938 | be careful about delimiters if there is more than one address. Like any other |
| 7939 | list, the default delimiter can be changed. Thus, you might have: |
| 7940 | .code |
| 7941 | domains = @mx_any/ignore=<;127.0.0.1;0.0.0.0 : \ |
| 7942 | an.other.domain : ... |
| 7943 | .endd |
| 7944 | so that the sublist uses semicolons for delimiters. When IPv6 addresses are |
| 7945 | involved, it is easiest to change the delimiter for the main list as well: |
| 7946 | .code |
| 7947 | domains = <? @mx_any/ignore=<;127.0.0.1;::1 ? \ |
| 7948 | an.other.domain ? ... |
| 7949 | .endd |
| 7950 | .next |
| 7951 | .cindex "asterisk" "in domain list" |
| 7952 | .cindex "domain list" "asterisk in" |
| 7953 | .cindex "domain list" "matching &""ends with""&" |
| 7954 | If a pattern starts with an asterisk, the remaining characters of the pattern |
| 7955 | are compared with the terminating characters of the domain. The use of &"*"& in |
| 7956 | domain lists differs from its use in partial matching lookups. In a domain |
| 7957 | list, the character following the asterisk need not be a dot, whereas partial |
| 7958 | matching works only in terms of dot-separated components. For example, a domain |
| 7959 | list item such as &`*key.ex`& matches &'donkey.ex'& as well as |
| 7960 | &'cipher.key.ex'&. |
| 7961 | |
| 7962 | .next |
| 7963 | .cindex "regular expressions" "in domain list" |
| 7964 | .cindex "domain list" "matching regular expression" |
| 7965 | If a pattern starts with a circumflex character, it is treated as a regular |
| 7966 | expression, and matched against the domain using a regular expression matching |
| 7967 | function. The circumflex is treated as part of the regular expression. |
| 7968 | Email domains are case-independent, so this regular expression match is by |
| 7969 | default case-independent, but you can make it case-dependent by starting it |
| 7970 | with &`(?-i)`&. References to descriptions of the syntax of regular expressions |
| 7971 | are given in chapter &<<CHAPregexp>>&. |
| 7972 | |
| 7973 | &*Warning*&: Because domain lists are expanded before being processed, you |
| 7974 | must escape any backslash and dollar characters in the regular expression, or |
| 7975 | use the special &`\N`& sequence (see chapter &<<CHAPexpand>>&) to specify that |
| 7976 | it is not to be expanded (unless you really do want to build a regular |
| 7977 | expression by expansion, of course). |
| 7978 | .next |
| 7979 | .cindex "lookup" "in domain list" |
| 7980 | .cindex "domain list" "matching by lookup" |
| 7981 | If a pattern starts with the name of a single-key lookup type followed by a |
| 7982 | semicolon (for example, &"dbm;"& or &"lsearch;"&), the remainder of the pattern |
| 7983 | must be a file name in a suitable format for the lookup type. For example, for |
| 7984 | &"cdb;"& it must be an absolute path: |
| 7985 | .code |
| 7986 | domains = cdb;/etc/mail/local_domains.cdb |
| 7987 | .endd |
| 7988 | The appropriate type of lookup is done on the file using the domain name as the |
| 7989 | key. In most cases, the data that is looked up is not used; Exim is interested |
| 7990 | only in whether or not the key is present in the file. However, when a lookup |
| 7991 | is used for the &%domains%& option on a router |
| 7992 | or a &%domains%& condition in an ACL statement, the data is preserved in the |
| 7993 | &$domain_data$& variable and can be referred to in other router options or |
| 7994 | other statements in the same ACL. |
| 7995 | |
| 7996 | .next |
| 7997 | Any of the single-key lookup type names may be preceded by |
| 7998 | &`partial`&<&'n'&>&`-`&, where the <&'n'&> is optional, for example, |
| 7999 | .code |
| 8000 | domains = partial-dbm;/partial/domains |
| 8001 | .endd |
| 8002 | This causes partial matching logic to be invoked; a description of how this |
| 8003 | works is given in section &<<SECTpartiallookup>>&. |
| 8004 | |
| 8005 | .next |
| 8006 | .cindex "asterisk" "in lookup type" |
| 8007 | Any of the single-key lookup types may be followed by an asterisk. This causes |
| 8008 | a default lookup for a key consisting of a single asterisk to be done if the |
| 8009 | original lookup fails. This is not a useful feature when using a domain list to |
| 8010 | select particular domains (because any domain would match), but it might have |
| 8011 | value if the result of the lookup is being used via the &$domain_data$& |
| 8012 | expansion variable. |
| 8013 | .next |
| 8014 | If the pattern starts with the name of a query-style lookup type followed by a |
| 8015 | semicolon (for example, &"nisplus;"& or &"ldap;"&), the remainder of the |
| 8016 | pattern must be an appropriate query for the lookup type, as described in |
| 8017 | chapter &<<CHAPfdlookup>>&. For example: |
| 8018 | .code |
| 8019 | hold_domains = mysql;select domain from holdlist \ |
| 8020 | where domain = '${quote_mysql:$domain}'; |
| 8021 | .endd |
| 8022 | In most cases, the data that is looked up is not used (so for an SQL query, for |
| 8023 | example, it doesn't matter what field you select). Exim is interested only in |
| 8024 | whether or not the query succeeds. However, when a lookup is used for the |
| 8025 | &%domains%& option on a router, the data is preserved in the &$domain_data$& |
| 8026 | variable and can be referred to in other options. |
| 8027 | .next |
| 8028 | .cindex "domain list" "matching literal domain name" |
| 8029 | If none of the above cases apply, a caseless textual comparison is made |
| 8030 | between the pattern and the domain. |
| 8031 | .endlist |
| 8032 | |
| 8033 | Here is an example that uses several different kinds of pattern: |
| 8034 | .code |
| 8035 | domainlist funny_domains = \ |
| 8036 | @ : \ |
| 8037 | lib.unseen.edu : \ |
| 8038 | *.foundation.fict.example : \ |
| 8039 | \N^[1-2]\d{3}\.fict\.example$\N : \ |
| 8040 | partial-dbm;/opt/data/penguin/book : \ |
| 8041 | nis;domains.byname : \ |
| 8042 | nisplus;[name=$domain,status=local],domains.org_dir |
| 8043 | .endd |
| 8044 | There are obvious processing trade-offs among the various matching modes. Using |
| 8045 | an asterisk is faster than a regular expression, and listing a few names |
| 8046 | explicitly probably is too. The use of a file or database lookup is expensive, |
| 8047 | but may be the only option if hundreds of names are required. Because the |
| 8048 | patterns are tested in order, it makes sense to put the most commonly matched |
| 8049 | patterns earlier. |
| 8050 | |
| 8051 | |
| 8052 | |
| 8053 | .section "Host lists" "SECThostlist" |
| 8054 | .cindex "host list" "patterns in" |
| 8055 | .cindex "list" "host list" |
| 8056 | Host lists are used to control what remote hosts are allowed to do. For |
| 8057 | example, some hosts may be allowed to use the local host as a relay, and some |
| 8058 | may be permitted to use the SMTP ETRN command. Hosts can be identified in |
| 8059 | two different ways, by name or by IP address. In a host list, some types of |
| 8060 | pattern are matched to a host name, and some are matched to an IP address. |
| 8061 | You need to be particularly careful with this when single-key lookups are |
| 8062 | involved, to ensure that the right value is being used as the key. |
| 8063 | |
| 8064 | |
| 8065 | .section "Special host list patterns" "SECID80" |
| 8066 | .cindex "empty item in hosts list" |
| 8067 | .cindex "host list" "empty string in" |
| 8068 | If a host list item is the empty string, it matches only when no remote host is |
| 8069 | involved. This is the case when a message is being received from a local |
| 8070 | process using SMTP on the standard input, that is, when a TCP/IP connection is |
| 8071 | not used. |
| 8072 | |
| 8073 | .cindex "asterisk" "in host list" |
| 8074 | The special pattern &"*"& in a host list matches any host or no host. Neither |
| 8075 | the IP address nor the name is actually inspected. |
| 8076 | |
| 8077 | |
| 8078 | |
| 8079 | .section "Host list patterns that match by IP address" "SECThoslispatip" |
| 8080 | .cindex "host list" "matching IP addresses" |
| 8081 | If an IPv4 host calls an IPv6 host and the call is accepted on an IPv6 socket, |
| 8082 | the incoming address actually appears in the IPv6 host as |
| 8083 | &`::ffff:`&<&'v4address'&>. When such an address is tested against a host |
| 8084 | list, it is converted into a traditional IPv4 address first. (Not all operating |
| 8085 | systems accept IPv4 calls on IPv6 sockets, as there have been some security |
| 8086 | concerns.) |
| 8087 | |
| 8088 | The following types of pattern in a host list check the remote host by |
| 8089 | inspecting its IP address: |
| 8090 | |
| 8091 | .ilist |
| 8092 | If the pattern is a plain domain name (not a regular expression, not starting |
| 8093 | with *, not a lookup of any kind), Exim calls the operating system function |
| 8094 | to find the associated IP address(es). Exim uses the newer |
| 8095 | &[getipnodebyname()]& function when available, otherwise &[gethostbyname()]&. |
| 8096 | This typically causes a forward DNS lookup of the name. The result is compared |
| 8097 | with the IP address of the subject host. |
| 8098 | |
| 8099 | If there is a temporary problem (such as a DNS timeout) with the host name |
| 8100 | lookup, a temporary error occurs. For example, if the list is being used in an |
| 8101 | ACL condition, the ACL gives a &"defer"& response, usually leading to a |
| 8102 | temporary SMTP error code. If no IP address can be found for the host name, |
| 8103 | what happens is described in section &<<SECTbehipnot>>& below. |
| 8104 | |
| 8105 | .next |
| 8106 | .cindex "@ in a host list" |
| 8107 | If the pattern is &"@"&, the primary host name is substituted and used as a |
| 8108 | domain name, as just described. |
| 8109 | |
| 8110 | .next |
| 8111 | If the pattern is an IP address, it is matched against the IP address of the |
| 8112 | subject host. IPv4 addresses are given in the normal &"dotted-quad"& notation. |
| 8113 | IPv6 addresses can be given in colon-separated format, but the colons have to |
| 8114 | be doubled so as not to be taken as item separators when the default list |
| 8115 | separator is used. IPv6 addresses are recognized even when Exim is compiled |
| 8116 | without IPv6 support. This means that if they appear in a host list on an |
| 8117 | IPv4-only host, Exim will not treat them as host names. They are just addresses |
| 8118 | that can never match a client host. |
| 8119 | |
| 8120 | .next |
| 8121 | .cindex "@[] in a host list" |
| 8122 | If the pattern is &"@[]"&, it matches the IP address of any IP interface on |
| 8123 | the local host. For example, if the local host is an IPv4 host with one |
| 8124 | interface address 10.45.23.56, these two ACL statements have the same effect: |
| 8125 | .code |
| 8126 | accept hosts = 127.0.0.1 : 10.45.23.56 |
| 8127 | accept hosts = @[] |
| 8128 | .endd |
| 8129 | .next |
| 8130 | .cindex "CIDR notation" |
| 8131 | If the pattern is an IP address followed by a slash and a mask length (for |
| 8132 | example 10.11.42.0/24), it is matched against the IP address of the subject |
| 8133 | host under the given mask. This allows, an entire network of hosts to be |
| 8134 | included (or excluded) by a single item. The mask uses CIDR notation; it |
| 8135 | specifies the number of address bits that must match, starting from the most |
| 8136 | significant end of the address. |
| 8137 | |
| 8138 | &*Note*&: The mask is &'not'& a count of addresses, nor is it the high number |
| 8139 | of a range of addresses. It is the number of bits in the network portion of the |
| 8140 | address. The above example specifies a 24-bit netmask, so it matches all 256 |
| 8141 | addresses in the 10.11.42.0 network. An item such as |
| 8142 | .code |
| 8143 | 192.168.23.236/31 |
| 8144 | .endd |
| 8145 | matches just two addresses, 192.168.23.236 and 192.168.23.237. A mask value of |
| 8146 | 32 for an IPv4 address is the same as no mask at all; just a single address |
| 8147 | matches. |
| 8148 | |
| 8149 | Here is another example which shows an IPv4 and an IPv6 network: |
| 8150 | .code |
| 8151 | recipient_unqualified_hosts = 192.168.0.0/16: \ |
| 8152 | 3ffe::ffff::836f::::/48 |
| 8153 | .endd |
| 8154 | The doubling of list separator characters applies only when these items |
| 8155 | appear inline in a host list. It is not required when indirecting via a file. |
| 8156 | For example: |
| 8157 | .code |
| 8158 | recipient_unqualified_hosts = /opt/exim/unqualnets |
| 8159 | .endd |
| 8160 | could make use of a file containing |
| 8161 | .code |
| 8162 | 172.16.0.0/12 |
| 8163 | 3ffe:ffff:836f::/48 |
| 8164 | .endd |
| 8165 | to have exactly the same effect as the previous example. When listing IPv6 |
| 8166 | addresses inline, it is usually more convenient to use the facility for |
| 8167 | changing separator characters. This list contains the same two networks: |
| 8168 | .code |
| 8169 | recipient_unqualified_hosts = <; 172.16.0.0/12; \ |
| 8170 | 3ffe:ffff:836f::/48 |
| 8171 | .endd |
| 8172 | The separator is changed to semicolon by the leading &"<;"& at the start of the |
| 8173 | list. |
| 8174 | .endlist |
| 8175 | |
| 8176 | |
| 8177 | |
| 8178 | .section "Host list patterns for single-key lookups by host address" &&& |
| 8179 | "SECThoslispatsikey" |
| 8180 | .cindex "host list" "lookup of IP address" |
| 8181 | When a host is to be identified by a single-key lookup of its complete IP |
| 8182 | address, the pattern takes this form: |
| 8183 | .display |
| 8184 | &`net-<`&&'single-key-search-type'&&`>;<`&&'search-data'&&`>`& |
| 8185 | .endd |
| 8186 | For example: |
| 8187 | .code |
| 8188 | hosts_lookup = net-cdb;/hosts-by-ip.db |
| 8189 | .endd |
| 8190 | The text form of the IP address of the subject host is used as the lookup key. |
| 8191 | IPv6 addresses are converted to an unabbreviated form, using lower case |
| 8192 | letters, with dots as separators because colon is the key terminator in |
| 8193 | &(lsearch)& files. [Colons can in fact be used in keys in &(lsearch)& files by |
| 8194 | quoting the keys, but this is a facility that was added later.] The data |
| 8195 | returned by the lookup is not used. |
| 8196 | |
| 8197 | .cindex "IP address" "masking" |
| 8198 | .cindex "host list" "masked IP address" |
| 8199 | Single-key lookups can also be performed using masked IP addresses, using |
| 8200 | patterns of this form: |
| 8201 | .display |
| 8202 | &`net<`&&'number'&&`>-<`&&'single-key-search-type'&&`>;<`&&'search-data'&&`>`& |
| 8203 | .endd |
| 8204 | For example: |
| 8205 | .code |
| 8206 | net24-dbm;/networks.db |
| 8207 | .endd |
| 8208 | The IP address of the subject host is masked using <&'number'&> as the mask |
| 8209 | length. A textual string is constructed from the masked value, followed by the |
| 8210 | mask, and this is used as the lookup key. For example, if the host's IP address |
| 8211 | is 192.168.34.6, the key that is looked up for the above example is |
| 8212 | &"192.168.34.0/24"&. |
| 8213 | |
| 8214 | When an IPv6 address is converted to a string, dots are normally used instead |
| 8215 | of colons, so that keys in &(lsearch)& files need not contain colons (which |
| 8216 | terminate &(lsearch)& keys). This was implemented some time before the ability |
| 8217 | to quote keys was made available in &(lsearch)& files. However, the more |
| 8218 | recently implemented &(iplsearch)& files do require colons in IPv6 keys |
| 8219 | (notated using the quoting facility) so as to distinguish them from IPv4 keys. |
| 8220 | For this reason, when the lookup type is &(iplsearch)&, IPv6 addresses are |
| 8221 | converted using colons and not dots. In all cases, full, unabbreviated IPv6 |
| 8222 | addresses are always used. |
| 8223 | |
| 8224 | Ideally, it would be nice to tidy up this anomalous situation by changing to |
| 8225 | colons in all cases, given that quoting is now available for &(lsearch)&. |
| 8226 | However, this would be an incompatible change that might break some existing |
| 8227 | configurations. |
| 8228 | |
| 8229 | &*Warning*&: Specifying &%net32-%& (for an IPv4 address) or &%net128-%& (for an |
| 8230 | IPv6 address) is not the same as specifying just &%net-%& without a number. In |
| 8231 | the former case the key strings include the mask value, whereas in the latter |
| 8232 | case the IP address is used on its own. |
| 8233 | |
| 8234 | |
| 8235 | |
| 8236 | .section "Host list patterns that match by host name" "SECThoslispatnam" |
| 8237 | .cindex "host" "lookup failures" |
| 8238 | .cindex "unknown host name" |
| 8239 | .cindex "host list" "matching host name" |
| 8240 | There are several types of pattern that require Exim to know the name of the |
| 8241 | remote host. These are either wildcard patterns or lookups by name. (If a |
| 8242 | complete hostname is given without any wildcarding, it is used to find an IP |
| 8243 | address to match against, as described in section &<<SECThoslispatip>>& |
| 8244 | above.) |
| 8245 | |
| 8246 | If the remote host name is not already known when Exim encounters one of these |
| 8247 | patterns, it has to be found from the IP address. |
| 8248 | Although many sites on the Internet are conscientious about maintaining reverse |
| 8249 | DNS data for their hosts, there are also many that do not do this. |
| 8250 | Consequently, a name cannot always be found, and this may lead to unwanted |
| 8251 | effects. Take care when configuring host lists with wildcarded name patterns. |
| 8252 | Consider what will happen if a name cannot be found. |
| 8253 | |
| 8254 | Because of the problems of determining host names from IP addresses, matching |
| 8255 | against host names is not as common as matching against IP addresses. |
| 8256 | |
| 8257 | By default, in order to find a host name, Exim first does a reverse DNS lookup; |
| 8258 | if no name is found in the DNS, the system function (&[gethostbyaddr()]& or |
| 8259 | &[getipnodebyaddr()]& if available) is tried. The order in which these lookups |
| 8260 | are done can be changed by setting the &%host_lookup_order%& option. For |
| 8261 | security, once Exim has found one or more names, it looks up the IP addresses |
| 8262 | for these names and compares them with the IP address that it started with. |
| 8263 | Only those names whose IP addresses match are accepted. Any other names are |
| 8264 | discarded. If no names are left, Exim behaves as if the host name cannot be |
| 8265 | found. In the most common case there is only one name and one IP address. |
| 8266 | |
| 8267 | There are some options that control what happens if a host name cannot be |
| 8268 | found. These are described in section &<<SECTbehipnot>>& below. |
| 8269 | |
| 8270 | .cindex "host" "alias for" |
| 8271 | .cindex "alias for host" |
| 8272 | As a result of aliasing, hosts may have more than one name. When processing any |
| 8273 | of the following types of pattern, all the host's names are checked: |
| 8274 | |
| 8275 | .ilist |
| 8276 | .cindex "asterisk" "in host list" |
| 8277 | If a pattern starts with &"*"& the remainder of the item must match the end of |
| 8278 | the host name. For example, &`*.b.c`& matches all hosts whose names end in |
| 8279 | &'.b.c'&. This special simple form is provided because this is a very common |
| 8280 | requirement. Other kinds of wildcarding require the use of a regular |
| 8281 | expression. |
| 8282 | .next |
| 8283 | .cindex "regular expressions" "in host list" |
| 8284 | .cindex "host list" "regular expression in" |
| 8285 | If the item starts with &"^"& it is taken to be a regular expression which is |
| 8286 | matched against the host name. Host names are case-independent, so this regular |
| 8287 | expression match is by default case-independent, but you can make it |
| 8288 | case-dependent by starting it with &`(?-i)`&. References to descriptions of the |
| 8289 | syntax of regular expressions are given in chapter &<<CHAPregexp>>&. For |
| 8290 | example, |
| 8291 | .code |
| 8292 | ^(a|b)\.c\.d$ |
| 8293 | .endd |
| 8294 | is a regular expression that matches either of the two hosts &'a.c.d'& or |
| 8295 | &'b.c.d'&. When a regular expression is used in a host list, you must take care |
| 8296 | that backslash and dollar characters are not misinterpreted as part of the |
| 8297 | string expansion. The simplest way to do this is to use &`\N`& to mark that |
| 8298 | part of the string as non-expandable. For example: |
| 8299 | .code |
| 8300 | sender_unqualified_hosts = \N^(a|b)\.c\.d$\N : .... |
| 8301 | .endd |
| 8302 | &*Warning*&: If you want to match a complete host name, you must include the |
| 8303 | &`$`& terminating metacharacter in the regular expression, as in the above |
| 8304 | example. Without it, a match at the start of the host name is all that is |
| 8305 | required. |
| 8306 | .endlist |
| 8307 | |
| 8308 | |
| 8309 | |
| 8310 | |
| 8311 | .section "Behaviour when an IP address or name cannot be found" "SECTbehipnot" |
| 8312 | .cindex "host" "lookup failures, permanent" |
| 8313 | While processing a host list, Exim may need to look up an IP address from a |
| 8314 | name (see section &<<SECThoslispatip>>&), or it may need to look up a host name |
| 8315 | from an IP address (see section &<<SECThoslispatnam>>&). In either case, the |
| 8316 | behaviour when it fails to find the information it is seeking is the same. |
| 8317 | |
| 8318 | &*Note*&: This section applies to permanent lookup failures. It does &'not'& |
| 8319 | apply to temporary DNS errors, whose handling is described in the next section. |
| 8320 | |
| 8321 | .cindex "&`+include_unknown`&" |
| 8322 | .cindex "&`+ignore_unknown`&" |
| 8323 | Exim parses a host list from left to right. If it encounters a permanent |
| 8324 | lookup failure in any item in the host list before it has found a match, |
| 8325 | Exim treats it as a failure and the default behavior is as if the host |
| 8326 | does not match the list. This may not always be what you want to happen. |
| 8327 | To change Exim's behaviour, the special items &`+include_unknown`& or |
| 8328 | &`+ignore_unknown`& may appear in the list (at top level &-- they are |
| 8329 | not recognized in an indirected file). |
| 8330 | |
| 8331 | .ilist |
| 8332 | If any item that follows &`+include_unknown`& requires information that |
| 8333 | cannot found, Exim behaves as if the host does match the list. For example, |
| 8334 | .code |
| 8335 | host_reject_connection = +include_unknown:*.enemy.ex |
| 8336 | .endd |
| 8337 | rejects connections from any host whose name matches &`*.enemy.ex`&, and also |
| 8338 | any hosts whose name it cannot find. |
| 8339 | |
| 8340 | .next |
| 8341 | If any item that follows &`+ignore_unknown`& requires information that cannot |
| 8342 | be found, Exim ignores that item and proceeds to the rest of the list. For |
| 8343 | example: |
| 8344 | .code |
| 8345 | accept hosts = +ignore_unknown : friend.example : \ |
| 8346 | 192.168.4.5 |
| 8347 | .endd |
| 8348 | accepts from any host whose name is &'friend.example'& and from 192.168.4.5, |
| 8349 | whether or not its host name can be found. Without &`+ignore_unknown`&, if no |
| 8350 | name can be found for 192.168.4.5, it is rejected. |
| 8351 | .endlist |
| 8352 | |
| 8353 | Both &`+include_unknown`& and &`+ignore_unknown`& may appear in the same |
| 8354 | list. The effect of each one lasts until the next, or until the end of the |
| 8355 | list. |
| 8356 | |
| 8357 | .new |
| 8358 | .section "Mixing wildcarded host names and addresses in host lists" &&& |
| 8359 | "SECTmixwilhos" |
| 8360 | .cindex "host list" "mixing names and addresses in" |
| 8361 | |
| 8362 | This section explains the host/ip processing logic with the same concepts |
| 8363 | as the previous section, but specifically addresses what happens when a |
| 8364 | wildcarded hostname is one of the items in the hostlist. |
| 8365 | |
| 8366 | .ilist |
| 8367 | If you have name lookups or wildcarded host names and |
| 8368 | IP addresses in the same host list, you should normally put the IP |
| 8369 | addresses first. For example, in an ACL you could have: |
| 8370 | .code |
| 8371 | accept hosts = 10.9.8.7 : *.friend.example |
| 8372 | .endd |
| 8373 | The reason you normally would order it this way lies in the |
| 8374 | left-to-right way that Exim processes lists. It can test IP addresses |
| 8375 | without doing any DNS lookups, but when it reaches an item that requires |
| 8376 | a host name, it fails if it cannot find a host name to compare with the |
| 8377 | pattern. If the above list is given in the opposite order, the |
| 8378 | &%accept%& statement fails for a host whose name cannot be found, even |
| 8379 | if its IP address is 10.9.8.7. |
| 8380 | |
| 8381 | .next |
| 8382 | If you really do want to do the name check first, and still recognize the IP |
| 8383 | address, you can rewrite the ACL like this: |
| 8384 | .code |
| 8385 | accept hosts = *.friend.example |
| 8386 | accept hosts = 10.9.8.7 |
| 8387 | .endd |
| 8388 | If the first &%accept%& fails, Exim goes on to try the second one. See chapter |
| 8389 | &<<CHAPACL>>& for details of ACLs. Alternatively, you can use |
| 8390 | &`+ignore_unknown`&, which was discussed in depth in the first example in |
| 8391 | this section. |
| 8392 | .endlist |
| 8393 | .wen |
| 8394 | |
| 8395 | |
| 8396 | .section "Temporary DNS errors when looking up host information" &&& |
| 8397 | "SECTtemdnserr" |
| 8398 | .cindex "host" "lookup failures, temporary" |
| 8399 | .cindex "&`+include_defer`&" |
| 8400 | .cindex "&`+ignore_defer`&" |
| 8401 | A temporary DNS lookup failure normally causes a defer action (except when |
| 8402 | &%dns_again_means_nonexist%& converts it into a permanent error). However, |
| 8403 | host lists can include &`+ignore_defer`& and &`+include_defer`&, analagous to |
| 8404 | &`+ignore_unknown`& and &`+include_unknown`&, as described in the previous |
| 8405 | section. These options should be used with care, probably only in non-critical |
| 8406 | host lists such as whitelists. |
| 8407 | |
| 8408 | |
| 8409 | |
| 8410 | .section "Host list patterns for single-key lookups by host name" &&& |
| 8411 | "SECThoslispatnamsk" |
| 8412 | .cindex "unknown host name" |
| 8413 | .cindex "host list" "matching host name" |
| 8414 | If a pattern is of the form |
| 8415 | .display |
| 8416 | <&'single-key-search-type'&>;<&'search-data'&> |
| 8417 | .endd |
| 8418 | for example |
| 8419 | .code |
| 8420 | dbm;/host/accept/list |
| 8421 | .endd |
| 8422 | a single-key lookup is performed, using the host name as its key. If the |
| 8423 | lookup succeeds, the host matches the item. The actual data that is looked up |
| 8424 | is not used. |
| 8425 | |
| 8426 | &*Reminder*&: With this kind of pattern, you must have host &'names'& as |
| 8427 | keys in the file, not IP addresses. If you want to do lookups based on IP |
| 8428 | addresses, you must precede the search type with &"net-"& (see section |
| 8429 | &<<SECThoslispatsikey>>&). There is, however, no reason why you could not use |
| 8430 | two items in the same list, one doing an address lookup and one doing a name |
| 8431 | lookup, both using the same file. |
| 8432 | |
| 8433 | |
| 8434 | |
| 8435 | .section "Host list patterns for query-style lookups" "SECID81" |
| 8436 | If a pattern is of the form |
| 8437 | .display |
| 8438 | <&'query-style-search-type'&>;<&'query'&> |
| 8439 | .endd |
| 8440 | the query is obeyed, and if it succeeds, the host matches the item. The actual |
| 8441 | data that is looked up is not used. The variables &$sender_host_address$& and |
| 8442 | &$sender_host_name$& can be used in the query. For example: |
| 8443 | .code |
| 8444 | hosts_lookup = pgsql;\ |
| 8445 | select ip from hostlist where ip='$sender_host_address' |
| 8446 | .endd |
| 8447 | The value of &$sender_host_address$& for an IPv6 address contains colons. You |
| 8448 | can use the &%sg%& expansion item to change this if you need to. If you want to |
| 8449 | use masked IP addresses in database queries, you can use the &%mask%& expansion |
| 8450 | operator. |
| 8451 | |
| 8452 | If the query contains a reference to &$sender_host_name$&, Exim automatically |
| 8453 | looks up the host name if it has not already done so. (See section |
| 8454 | &<<SECThoslispatnam>>& for comments on finding host names.) |
| 8455 | |
| 8456 | Historical note: prior to release 4.30, Exim would always attempt to find a |
| 8457 | host name before running the query, unless the search type was preceded by |
| 8458 | &`net-`&. This is no longer the case. For backwards compatibility, &`net-`& is |
| 8459 | still recognized for query-style lookups, but its presence or absence has no |
| 8460 | effect. (Of course, for single-key lookups, &`net-`& &'is'& important. |
| 8461 | See section &<<SECThoslispatsikey>>&.) |
| 8462 | |
| 8463 | |
| 8464 | |
| 8465 | |
| 8466 | |
| 8467 | .section "Address lists" "SECTaddresslist" |
| 8468 | .cindex "list" "address list" |
| 8469 | .cindex "address list" "empty item" |
| 8470 | .cindex "address list" "patterns" |
| 8471 | Address lists contain patterns that are matched against mail addresses. There |
| 8472 | is one special case to be considered: the sender address of a bounce message is |
| 8473 | always empty. You can test for this by providing an empty item in an address |
| 8474 | list. For example, you can set up a router to process bounce messages by |
| 8475 | using this option setting: |
| 8476 | .code |
| 8477 | senders = : |
| 8478 | .endd |
| 8479 | The presence of the colon creates an empty item. If you do not provide any |
| 8480 | data, the list is empty and matches nothing. The empty sender can also be |
| 8481 | detected by a regular expression that matches an empty string, |
| 8482 | and by a query-style lookup that succeeds when &$sender_address$& is empty. |
| 8483 | |
| 8484 | Non-empty items in an address list can be straightforward email addresses. For |
| 8485 | example: |
| 8486 | .code |
| 8487 | senders = jbc@askone.example : hs@anacreon.example |
| 8488 | .endd |
| 8489 | A certain amount of wildcarding is permitted. If a pattern contains an @ |
| 8490 | character, but is not a regular expression and does not begin with a |
| 8491 | semicolon-terminated lookup type (described below), the local part of the |
| 8492 | subject address is compared with the local part of the pattern, which may start |
| 8493 | with an asterisk. If the local parts match, the domain is checked in exactly |
| 8494 | the same way as for a pattern in a domain list. For example, the domain can be |
| 8495 | wildcarded, refer to a named list, or be a lookup: |
| 8496 | .code |
| 8497 | deny senders = *@*.spamming.site:\ |
| 8498 | *@+hostile_domains:\ |
| 8499 | bozo@partial-lsearch;/list/of/dodgy/sites:\ |
| 8500 | *@dbm;/bad/domains.db |
| 8501 | .endd |
| 8502 | .cindex "local part" "starting with !" |
| 8503 | .cindex "address list" "local part starting with !" |
| 8504 | If a local part that begins with an exclamation mark is required, it has to be |
| 8505 | specified using a regular expression, because otherwise the exclamation mark is |
| 8506 | treated as a sign of negation, as is standard in lists. |
| 8507 | |
| 8508 | If a non-empty pattern that is not a regular expression or a lookup does not |
| 8509 | contain an @ character, it is matched against the domain part of the subject |
| 8510 | address. The only two formats that are recognized this way are a literal |
| 8511 | domain, or a domain pattern that starts with *. In both these cases, the effect |
| 8512 | is the same as if &`*@`& preceded the pattern. For example: |
| 8513 | .code |
| 8514 | deny senders = enemy.domain : *.enemy.domain |
| 8515 | .endd |
| 8516 | |
| 8517 | The following kinds of more complicated address list pattern can match any |
| 8518 | address, including the empty address that is characteristic of bounce message |
| 8519 | senders: |
| 8520 | |
| 8521 | .ilist |
| 8522 | .cindex "regular expressions" "in address list" |
| 8523 | .cindex "address list" "regular expression in" |
| 8524 | If (after expansion) a pattern starts with &"^"&, a regular expression match is |
| 8525 | done against the complete address, with the pattern as the regular expression. |
| 8526 | You must take care that backslash and dollar characters are not misinterpreted |
| 8527 | as part of the string expansion. The simplest way to do this is to use &`\N`& |
| 8528 | to mark that part of the string as non-expandable. For example: |
| 8529 | .code |
| 8530 | deny senders = \N^.*this.*@example\.com$\N : \ |
| 8531 | \N^\d{8}.+@spamhaus.example$\N : ... |
| 8532 | .endd |
| 8533 | The &`\N`& sequences are removed by the expansion, so these items do indeed |
| 8534 | start with &"^"& by the time they are being interpreted as address patterns. |
| 8535 | |
| 8536 | .next |
| 8537 | .cindex "address list" "lookup for complete address" |
| 8538 | Complete addresses can be looked up by using a pattern that starts with a |
| 8539 | lookup type terminated by a semicolon, followed by the data for the lookup. For |
| 8540 | example: |
| 8541 | .code |
| 8542 | deny senders = cdb;/etc/blocked.senders : \ |
| 8543 | mysql;select address from blocked where \ |
| 8544 | address='${quote_mysql:$sender_address}' |
| 8545 | .endd |
| 8546 | Both query-style and single-key lookup types can be used. For a single-key |
| 8547 | lookup type, Exim uses the complete address as the key. However, empty keys are |
| 8548 | not supported for single-key lookups, so a match against the empty address |
| 8549 | always fails. This restriction does not apply to query-style lookups. |
| 8550 | |
| 8551 | Partial matching for single-key lookups (section &<<SECTpartiallookup>>&) |
| 8552 | cannot be used, and is ignored if specified, with an entry being written to the |
| 8553 | panic log. |
| 8554 | .cindex "*@ with single-key lookup" |
| 8555 | However, you can configure lookup defaults, as described in section |
| 8556 | &<<SECTdefaultvaluelookups>>&, but this is useful only for the &"*@"& type of |
| 8557 | default. For example, with this lookup: |
| 8558 | .code |
| 8559 | accept senders = lsearch*@;/some/file |
| 8560 | .endd |
| 8561 | the file could contains lines like this: |
| 8562 | .code |
| 8563 | user1@domain1.example |
| 8564 | *@domain2.example |
| 8565 | .endd |
| 8566 | and for the sender address &'nimrod@jaeger.example'&, the sequence of keys |
| 8567 | that are tried is: |
| 8568 | .code |
| 8569 | nimrod@jaeger.example |
| 8570 | *@jaeger.example |
| 8571 | * |
| 8572 | .endd |
| 8573 | &*Warning 1*&: Do not include a line keyed by &"*"& in the file, because that |
| 8574 | would mean that every address matches, thus rendering the test useless. |
| 8575 | |
| 8576 | &*Warning 2*&: Do not confuse these two kinds of item: |
| 8577 | .code |
| 8578 | deny recipients = dbm*@;/some/file |
| 8579 | deny recipients = *@dbm;/some/file |
| 8580 | .endd |
| 8581 | The first does a whole address lookup, with defaulting, as just described, |
| 8582 | because it starts with a lookup type. The second matches the local part and |
| 8583 | domain independently, as described in a bullet point below. |
| 8584 | .endlist |
| 8585 | |
| 8586 | |
| 8587 | The following kinds of address list pattern can match only non-empty addresses. |
| 8588 | If the subject address is empty, a match against any of these pattern types |
| 8589 | always fails. |
| 8590 | |
| 8591 | |
| 8592 | .ilist |
| 8593 | .cindex "@@ with single-key lookup" |
| 8594 | .cindex "address list" "@@ lookup type" |
| 8595 | .cindex "address list" "split local part and domain" |
| 8596 | If a pattern starts with &"@@"& followed by a single-key lookup item |
| 8597 | (for example, &`@@lsearch;/some/file`&), the address that is being checked is |
| 8598 | split into a local part and a domain. The domain is looked up in the file. If |
| 8599 | it is not found, there is no match. If it is found, the data that is looked up |
| 8600 | from the file is treated as a colon-separated list of local part patterns, each |
| 8601 | of which is matched against the subject local part in turn. |
| 8602 | |
| 8603 | .cindex "asterisk" "in address list" |
| 8604 | The lookup may be a partial one, and/or one involving a search for a default |
| 8605 | keyed by &"*"& (see section &<<SECTdefaultvaluelookups>>&). The local part |
| 8606 | patterns that are looked up can be regular expressions or begin with &"*"&, or |
| 8607 | even be further lookups. They may also be independently negated. For example, |
| 8608 | with |
| 8609 | .code |
| 8610 | deny senders = @@dbm;/etc/reject-by-domain |
| 8611 | .endd |
| 8612 | the data from which the DBM file is built could contain lines like |
| 8613 | .code |
| 8614 | baddomain.com: !postmaster : * |
| 8615 | .endd |
| 8616 | to reject all senders except &%postmaster%& from that domain. |
| 8617 | |
| 8618 | .cindex "local part" "starting with !" |
| 8619 | If a local part that actually begins with an exclamation mark is required, it |
| 8620 | has to be specified using a regular expression. In &(lsearch)& files, an entry |
| 8621 | may be split over several lines by indenting the second and subsequent lines, |
| 8622 | but the separating colon must still be included at line breaks. White space |
| 8623 | surrounding the colons is ignored. For example: |
| 8624 | .code |
| 8625 | aol.com: spammer1 : spammer2 : ^[0-9]+$ : |
| 8626 | spammer3 : spammer4 |
| 8627 | .endd |
| 8628 | As in all colon-separated lists in Exim, a colon can be included in an item by |
| 8629 | doubling. |
| 8630 | |
| 8631 | If the last item in the list starts with a right angle-bracket, the remainder |
| 8632 | of the item is taken as a new key to look up in order to obtain a continuation |
| 8633 | list of local parts. The new key can be any sequence of characters. Thus one |
| 8634 | might have entries like |
| 8635 | .code |
| 8636 | aol.com: spammer1 : spammer 2 : >* |
| 8637 | xyz.com: spammer3 : >* |
| 8638 | *: ^\d{8}$ |
| 8639 | .endd |
| 8640 | in a file that was searched with &%@@dbm*%&, to specify a match for 8-digit |
| 8641 | local parts for all domains, in addition to the specific local parts listed for |
| 8642 | each domain. Of course, using this feature costs another lookup each time a |
| 8643 | chain is followed, but the effort needed to maintain the data is reduced. |
| 8644 | |
| 8645 | .cindex "loop" "in lookups" |
| 8646 | It is possible to construct loops using this facility, and in order to catch |
| 8647 | them, the chains may be no more than fifty items long. |
| 8648 | |
| 8649 | .next |
| 8650 | The @@<&'lookup'&> style of item can also be used with a query-style |
| 8651 | lookup, but in this case, the chaining facility is not available. The lookup |
| 8652 | can only return a single list of local parts. |
| 8653 | .endlist |
| 8654 | |
| 8655 | &*Warning*&: There is an important difference between the address list items |
| 8656 | in these two examples: |
| 8657 | .code |
| 8658 | senders = +my_list |
| 8659 | senders = *@+my_list |
| 8660 | .endd |
| 8661 | In the first one, &`my_list`& is a named address list, whereas in the second |
| 8662 | example it is a named domain list. |
| 8663 | |
| 8664 | |
| 8665 | |
| 8666 | |
| 8667 | .section "Case of letters in address lists" "SECTcasletadd" |
| 8668 | .cindex "case of local parts" |
| 8669 | .cindex "address list" "case forcing" |
| 8670 | .cindex "case forcing in address lists" |
| 8671 | Domains in email addresses are always handled caselessly, but for local parts |
| 8672 | case may be significant on some systems (see &%caseful_local_part%& for how |
| 8673 | Exim deals with this when routing addresses). However, RFC 2505 (&'Anti-Spam |
| 8674 | Recommendations for SMTP MTAs'&) suggests that matching of addresses to |
| 8675 | blocking lists should be done in a case-independent manner. Since most address |
| 8676 | lists in Exim are used for this kind of control, Exim attempts to do this by |
| 8677 | default. |
| 8678 | |
| 8679 | The domain portion of an address is always lowercased before matching it to an |
| 8680 | address list. The local part is lowercased by default, and any string |
| 8681 | comparisons that take place are done caselessly. This means that the data in |
| 8682 | the address list itself, in files included as plain file names, and in any file |
| 8683 | that is looked up using the &"@@"& mechanism, can be in any case. However, the |
| 8684 | keys in files that are looked up by a search type other than &(lsearch)& (which |
| 8685 | works caselessly) must be in lower case, because these lookups are not |
| 8686 | case-independent. |
| 8687 | |
| 8688 | .cindex "&`+caseful`&" |
| 8689 | To allow for the possibility of caseful address list matching, if an item in |
| 8690 | an address list is the string &"+caseful"&, the original case of the local |
| 8691 | part is restored for any comparisons that follow, and string comparisons are no |
| 8692 | longer case-independent. This does not affect the domain, which remains in |
| 8693 | lower case. However, although independent matches on the domain alone are still |
| 8694 | performed caselessly, regular expressions that match against an entire address |
| 8695 | become case-sensitive after &"+caseful"& has been seen. |
| 8696 | |
| 8697 | |
| 8698 | |
| 8699 | .section "Local part lists" "SECTlocparlis" |
| 8700 | .cindex "list" "local part list" |
| 8701 | .cindex "local part" "list" |
| 8702 | Case-sensitivity in local part lists is handled in the same way as for address |
| 8703 | lists, as just described. The &"+caseful"& item can be used if required. In a |
| 8704 | setting of the &%local_parts%& option in a router with &%caseful_local_part%& |
| 8705 | set false, the subject is lowercased and the matching is initially |
| 8706 | case-insensitive. In this case, &"+caseful"& will restore case-sensitive |
| 8707 | matching in the local part list, but not elsewhere in the router. If |
| 8708 | &%caseful_local_part%& is set true in a router, matching in the &%local_parts%& |
| 8709 | option is case-sensitive from the start. |
| 8710 | |
| 8711 | If a local part list is indirected to a file (see section &<<SECTfilnamlis>>&), |
| 8712 | comments are handled in the same way as address lists &-- they are recognized |
| 8713 | only if the # is preceded by white space or the start of the line. |
| 8714 | Otherwise, local part lists are matched in the same way as domain lists, except |
| 8715 | that the special items that refer to the local host (&`@`&, &`@[]`&, |
| 8716 | &`@mx_any`&, &`@mx_primary`&, and &`@mx_secondary`&) are not recognized. |
| 8717 | Refer to section &<<SECTdomainlist>>& for details of the other available item |
| 8718 | types. |
| 8719 | .ecindex IIDdohoadli |
| 8720 | |
| 8721 | |
| 8722 | |
| 8723 | |
| 8724 | . //////////////////////////////////////////////////////////////////////////// |
| 8725 | . //////////////////////////////////////////////////////////////////////////// |
| 8726 | |
| 8727 | .chapter "String expansions" "CHAPexpand" |
| 8728 | .scindex IIDstrexp "expansion" "of strings" |
| 8729 | Many strings in Exim's run time configuration are expanded before use. Some of |
| 8730 | them are expanded every time they are used; others are expanded only once. |
| 8731 | |
| 8732 | When a string is being expanded it is copied verbatim from left to right except |
| 8733 | when a dollar or backslash character is encountered. A dollar specifies the |
| 8734 | start of a portion of the string that is interpreted and replaced as described |
| 8735 | below in section &<<SECTexpansionitems>>& onwards. Backslash is used as an |
| 8736 | escape character, as described in the following section. |
| 8737 | |
| 8738 | Whether a string is expanded depends upon the context. Usually this is solely |
| 8739 | dependent upon the option for which a value is sought; in this documentation, |
| 8740 | options for which string expansion is performed are marked with † after |
| 8741 | the data type. ACL rules always expand strings. A couple of expansion |
| 8742 | conditions do not expand some of the brace-delimited branches, for security |
| 8743 | reasons. |
| 8744 | |
| 8745 | |
| 8746 | |
| 8747 | .section "Literal text in expanded strings" "SECTlittext" |
| 8748 | .cindex "expansion" "including literal text" |
| 8749 | An uninterpreted dollar can be included in an expanded string by putting a |
| 8750 | backslash in front of it. A backslash can be used to prevent any special |
| 8751 | character being treated specially in an expansion, including backslash itself. |
| 8752 | If the string appears in quotes in the configuration file, two backslashes are |
| 8753 | required because the quotes themselves cause interpretation of backslashes when |
| 8754 | the string is read in (see section &<<SECTstrings>>&). |
| 8755 | |
| 8756 | .cindex "expansion" "non-expandable substrings" |
| 8757 | A portion of the string can specified as non-expandable by placing it between |
| 8758 | two occurrences of &`\N`&. This is particularly useful for protecting regular |
| 8759 | expressions, which often contain backslashes and dollar signs. For example: |
| 8760 | .code |
| 8761 | deny senders = \N^\d{8}[a-z]@some\.site\.example$\N |
| 8762 | .endd |
| 8763 | On encountering the first &`\N`&, the expander copies subsequent characters |
| 8764 | without interpretation until it reaches the next &`\N`& or the end of the |
| 8765 | string. |
| 8766 | |
| 8767 | |
| 8768 | |
| 8769 | .section "Character escape sequences in expanded strings" "SECID82" |
| 8770 | .cindex "expansion" "escape sequences" |
| 8771 | A backslash followed by one of the letters &"n"&, &"r"&, or &"t"& in an |
| 8772 | expanded string is recognized as an escape sequence for the character newline, |
| 8773 | carriage return, or tab, respectively. A backslash followed by up to three |
| 8774 | octal digits is recognized as an octal encoding for a single character, and a |
| 8775 | backslash followed by &"x"& and up to two hexadecimal digits is a hexadecimal |
| 8776 | encoding. |
| 8777 | |
| 8778 | These escape sequences are also recognized in quoted strings when they are read |
| 8779 | in. Their interpretation in expansions as well is useful for unquoted strings, |
| 8780 | and for other cases such as looked-up strings that are then expanded. |
| 8781 | |
| 8782 | |
| 8783 | .section "Testing string expansions" "SECID83" |
| 8784 | .cindex "expansion" "testing" |
| 8785 | .cindex "testing" "string expansion" |
| 8786 | .oindex "&%-be%&" |
| 8787 | Many expansions can be tested by calling Exim with the &%-be%& option. This |
| 8788 | takes the command arguments, or lines from the standard input if there are no |
| 8789 | arguments, runs them through the string expansion code, and writes the results |
| 8790 | to the standard output. Variables based on configuration values are set up, but |
| 8791 | since no message is being processed, variables such as &$local_part$& have no |
| 8792 | value. Nevertheless the &%-be%& option can be useful for checking out file and |
| 8793 | database lookups, and the use of expansion operators such as &%sg%&, &%substr%& |
| 8794 | and &%nhash%&. |
| 8795 | |
| 8796 | Exim gives up its root privilege when it is called with the &%-be%& option, and |
| 8797 | instead runs under the uid and gid it was called with, to prevent users from |
| 8798 | using &%-be%& for reading files to which they do not have access. |
| 8799 | |
| 8800 | .oindex "&%-bem%&" |
| 8801 | If you want to test expansions that include variables whose values are taken |
| 8802 | from a message, there are two other options that can be used. The &%-bem%& |
| 8803 | option is like &%-be%& except that it is followed by a file name. The file is |
| 8804 | read as a message before doing the test expansions. For example: |
| 8805 | .code |
| 8806 | exim -bem /tmp/test.message '$h_subject:' |
| 8807 | .endd |
| 8808 | The &%-Mset%& option is used in conjunction with &%-be%& and is followed by an |
| 8809 | Exim message identifier. For example: |
| 8810 | .code |
| 8811 | exim -be -Mset 1GrA8W-0004WS-LQ '$recipients' |
| 8812 | .endd |
| 8813 | This loads the message from Exim's spool before doing the test expansions, and |
| 8814 | is therefore restricted to admin users. |
| 8815 | |
| 8816 | |
| 8817 | .section "Forced expansion failure" "SECTforexpfai" |
| 8818 | .cindex "expansion" "forced failure" |
| 8819 | A number of expansions that are described in the following section have |
| 8820 | alternative &"true"& and &"false"& substrings, enclosed in brace characters |
| 8821 | (which are sometimes called &"curly brackets"&). Which of the two strings is |
| 8822 | used depends on some condition that is evaluated as part of the expansion. If, |
| 8823 | instead of a &"false"& substring, the word &"fail"& is used (not in braces), |
| 8824 | the entire string expansion fails in a way that can be detected by the code |
| 8825 | that requested the expansion. This is called &"forced expansion failure"&, and |
| 8826 | its consequences depend on the circumstances. In some cases it is no different |
| 8827 | from any other expansion failure, but in others a different action may be |
| 8828 | taken. Such variations are mentioned in the documentation of the option that is |
| 8829 | being expanded. |
| 8830 | |
| 8831 | |
| 8832 | |
| 8833 | |
| 8834 | .section "Expansion items" "SECTexpansionitems" |
| 8835 | The following items are recognized in expanded strings. White space may be used |
| 8836 | between sub-items that are keywords or substrings enclosed in braces inside an |
| 8837 | outer set of braces, to improve readability. &*Warning*&: Within braces, |
| 8838 | white space is significant. |
| 8839 | |
| 8840 | .vlist |
| 8841 | .vitem &*$*&<&'variable&~name'&>&~or&~&*${*&<&'variable&~name'&>&*}*& |
| 8842 | .cindex "expansion" "variables" |
| 8843 | Substitute the contents of the named variable, for example: |
| 8844 | .code |
| 8845 | $local_part |
| 8846 | ${domain} |
| 8847 | .endd |
| 8848 | The second form can be used to separate the name from subsequent alphanumeric |
| 8849 | characters. This form (using braces) is available only for variables; it does |
| 8850 | &'not'& apply to message headers. The names of the variables are given in |
| 8851 | section &<<SECTexpvar>>& below. If the name of a non-existent variable is |
| 8852 | given, the expansion fails. |
| 8853 | |
| 8854 | .vitem &*${*&<&'op'&>&*:*&<&'string'&>&*}*& |
| 8855 | .cindex "expansion" "operators" |
| 8856 | The string is first itself expanded, and then the operation specified by |
| 8857 | <&'op'&> is applied to it. For example: |
| 8858 | .code |
| 8859 | ${lc:$local_part} |
| 8860 | .endd |
| 8861 | The string starts with the first character after the colon, which may be |
| 8862 | leading white space. A list of operators is given in section &<<SECTexpop>>& |
| 8863 | below. The operator notation is used for simple expansion items that have just |
| 8864 | one argument, because it reduces the number of braces and therefore makes the |
| 8865 | string easier to understand. |
| 8866 | |
| 8867 | .vitem &*$bheader_*&<&'header&~name'&>&*:*&&~or&~&*$bh_*&<&'header&~name'&>&*:*& |
| 8868 | This item inserts &"basic"& header lines. It is described with the &%header%& |
| 8869 | expansion item below. |
| 8870 | |
| 8871 | |
| 8872 | .vitem "&*${acl{*&<&'name'&>&*}{*&<&'arg'&>&*}...}*&" |
| 8873 | .cindex "expansion" "calling an acl" |
| 8874 | .cindex "&%acl%&" "call from expansion" |
| 8875 | The name and zero to nine argument strings are first expanded separately. The expanded |
| 8876 | arguments are assigned to the variables &$acl_arg1$& to &$acl_arg9$& in order. |
| 8877 | Any unused are made empty. The variable &$acl_narg$& is set to the number of |
| 8878 | arguments. The named ACL (see chapter &<<CHAPACL>>&) is called |
| 8879 | and may use the variables; if another acl expansion is used the values |
| 8880 | are restored after it returns. If the ACL sets |
| 8881 | a value using a "message =" modifier and returns accept or deny, the value becomes |
| 8882 | the result of the expansion. |
| 8883 | If no message is set and the ACL returns accept or deny |
| 8884 | the expansion result is an empty string. |
| 8885 | If the ACL returns defer the result is a forced-fail. Otherwise the expansion fails. |
| 8886 | |
| 8887 | |
| 8888 | .new |
| 8889 | .vitem "&*${certextract{*&<&'field'&>&*}{*&<&'certificate'&>&*}&&& |
| 8890 | {*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&" |
| 8891 | .cindex "expansion" "extracting cerificate fields" |
| 8892 | .cindex "&%certextract%&" "certificate fields" |
| 8893 | .cindex "certificate" "extracting fields" |
| 8894 | The <&'certificate'&> must be a variable of type certificate. |
| 8895 | The field name is expanded and used to retrive the relevant field from |
| 8896 | the certificate. Supported fields are: |
| 8897 | .display |
| 8898 | &`version `& |
| 8899 | &`serial_number `& |
| 8900 | &`subject `& RFC4514 DN |
| 8901 | &`issuer `& RFC4514 DN |
| 8902 | &`notbefore `& time |
| 8903 | &`notafter `& time |
| 8904 | &`sig_algorithm `& |
| 8905 | &`signature `& |
| 8906 | &`subj_altname `& tagged list |
| 8907 | &`ocsp_uri `& list |
| 8908 | &`crl_uri `& list |
| 8909 | .endd |
| 8910 | If the field is found, |
| 8911 | <&'string2'&> is expanded, and replaces the whole item; |
| 8912 | otherwise <&'string3'&> is used. During the expansion of <&'string2'&> the |
| 8913 | variable &$value$& contains the value that has been extracted. Afterwards, it |
| 8914 | is restored to any previous value it might have had. |
| 8915 | |
| 8916 | If {<&'string3'&>} is omitted, the item is replaced by an empty string if the |
| 8917 | key is not found. If {<&'string2'&>} is also omitted, the value that was |
| 8918 | extracted is used. |
| 8919 | |
| 8920 | Some field names take optional modifiers, appended and separated by commas. |
| 8921 | |
| 8922 | The field selectors marked as "RFC4514" above |
| 8923 | output a Distinguished Name string which is |
| 8924 | not quite |
| 8925 | parseable by Exim as a comma-separated tagged list |
| 8926 | (the exceptions being elements containin commas). |
| 8927 | RDN elements of a single type may be selected by |
| 8928 | a modifier of the type label; if so the expansion |
| 8929 | result is a list (newline-separated by default). |
| 8930 | The separator may be changed by another modifer of |
| 8931 | a right angle-bracket followed immediately by the new separator. |
| 8932 | Recognised RDN type labels include "CN", "O", "OU" and "DC". |
| 8933 | |
| 8934 | The field selectors marked as "time" above |
| 8935 | may output a number of seconds since epoch |
| 8936 | if the modifier "int" is used. |
| 8937 | |
| 8938 | The field selectors marked as "list" above return a list, |
| 8939 | newline-separated by default, |
| 8940 | (embedded separator characters in elements are doubled). |
| 8941 | The separator may be changed by a modifier of |
| 8942 | a right angle-bracket followed immediately by the new separator. |
| 8943 | |
| 8944 | The field selectors marked as "tagged" above |
| 8945 | prefix each list element with a type string and an equals sign. |
| 8946 | Elements of only one type may be selected by a modifier |
| 8947 | which is one of "dns", "uri" or "mail"; |
| 8948 | if so the elenment tags are omitted. |
| 8949 | |
| 8950 | If not otherwise noted field values are presented in human-readable form. |
| 8951 | .wen |
| 8952 | |
| 8953 | .vitem "&*${dlfunc{*&<&'file'&>&*}{*&<&'function'&>&*}{*&<&'arg'&>&*}&&& |
| 8954 | {*&<&'arg'&>&*}...}*&" |
| 8955 | .cindex &%dlfunc%& |
| 8956 | This expansion dynamically loads and then calls a locally-written C function. |
| 8957 | This functionality is available only if Exim is compiled with |
| 8958 | .code |
| 8959 | EXPAND_DLFUNC=yes |
| 8960 | .endd |
| 8961 | set in &_Local/Makefile_&. Once loaded, Exim remembers the dynamically loaded |
| 8962 | object so that it doesn't reload the same object file in the same Exim process |
| 8963 | (but of course Exim does start new processes frequently). |
| 8964 | |
| 8965 | There may be from zero to eight arguments to the function. When compiling |
| 8966 | a local function that is to be called in this way, &_local_scan.h_& should be |
| 8967 | included. The Exim variables and functions that are defined by that API |
| 8968 | are also available for dynamically loaded functions. The function itself |
| 8969 | must have the following type: |
| 8970 | .code |
| 8971 | int dlfunction(uschar **yield, int argc, uschar *argv[]) |
| 8972 | .endd |
| 8973 | Where &`uschar`& is a typedef for &`unsigned char`& in &_local_scan.h_&. The |
| 8974 | function should return one of the following values: |
| 8975 | |
| 8976 | &`OK`&: Success. The string that is placed in the variable &'yield'& is put |
| 8977 | into the expanded string that is being built. |
| 8978 | |
| 8979 | &`FAIL`&: A non-forced expansion failure occurs, with the error message taken |
| 8980 | from &'yield'&, if it is set. |
| 8981 | |
| 8982 | &`FAIL_FORCED`&: A forced expansion failure occurs, with the error message |
| 8983 | taken from &'yield'& if it is set. |
| 8984 | |
| 8985 | &`ERROR`&: Same as &`FAIL`&, except that a panic log entry is written. |
| 8986 | |
| 8987 | When compiling a function that is to be used in this way with gcc, |
| 8988 | you need to add &%-shared%& to the gcc command. Also, in the Exim build-time |
| 8989 | configuration, you must add &%-export-dynamic%& to EXTRALIBS. |
| 8990 | |
| 8991 | .vitem "&*${extract{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}&&& |
| 8992 | {*&<&'string3'&>&*}}*&" |
| 8993 | .cindex "expansion" "extracting substrings by key" |
| 8994 | .cindex "&%extract%&" "substrings by key" |
| 8995 | The key and <&'string1'&> are first expanded separately. Leading and trailing |
| 8996 | white space is removed from the key (but not from any of the strings). The key |
| 8997 | must not consist entirely of digits. The expanded <&'string1'&> must be of the |
| 8998 | form: |
| 8999 | .display |
| 9000 | <&'key1'&> = <&'value1'&> <&'key2'&> = <&'value2'&> ... |
| 9001 | .endd |
| 9002 | .vindex "&$value$&" |
| 9003 | where the equals signs and spaces (but not both) are optional. If any of the |
| 9004 | values contain white space, they must be enclosed in double quotes, and any |
| 9005 | values that are enclosed in double quotes are subject to escape processing as |
| 9006 | described in section &<<SECTstrings>>&. The expanded <&'string1'&> is searched |
| 9007 | for the value that corresponds to the key. The search is case-insensitive. If |
| 9008 | the key is found, <&'string2'&> is expanded, and replaces the whole item; |
| 9009 | otherwise <&'string3'&> is used. During the expansion of <&'string2'&> the |
| 9010 | variable &$value$& contains the value that has been extracted. Afterwards, it |
| 9011 | is restored to any previous value it might have had. |
| 9012 | |
| 9013 | If {<&'string3'&>} is omitted, the item is replaced by an empty string if the |
| 9014 | key is not found. If {<&'string2'&>} is also omitted, the value that was |
| 9015 | extracted is used. Thus, for example, these two expansions are identical, and |
| 9016 | yield &"2001"&: |
| 9017 | .code |
| 9018 | ${extract{gid}{uid=1984 gid=2001}} |
| 9019 | ${extract{gid}{uid=1984 gid=2001}{$value}} |
| 9020 | .endd |
| 9021 | Instead of {<&'string3'&>} the word &"fail"& (not in curly brackets) can |
| 9022 | appear, for example: |
| 9023 | .code |
| 9024 | ${extract{Z}{A=... B=...}{$value} fail } |
| 9025 | .endd |
| 9026 | This forces an expansion failure (see section &<<SECTforexpfai>>&); |
| 9027 | {<&'string2'&>} must be present for &"fail"& to be recognized. |
| 9028 | |
| 9029 | |
| 9030 | .vitem "&*${extract{*&<&'number'&>&*}{*&<&'separators'&>&*}&&& |
| 9031 | {*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&" |
| 9032 | .cindex "expansion" "extracting substrings by number" |
| 9033 | .cindex "&%extract%&" "substrings by number" |
| 9034 | The <&'number'&> argument must consist entirely of decimal digits, |
| 9035 | apart from leading and trailing white space, which is ignored. |
| 9036 | This is what distinguishes this form of &%extract%& from the previous kind. It |
| 9037 | behaves in the same way, except that, instead of extracting a named field, it |
| 9038 | extracts from <&'string1'&> the field whose number is given as the first |
| 9039 | argument. You can use &$value$& in <&'string2'&> or &`fail`& instead of |
| 9040 | <&'string3'&> as before. |
| 9041 | |
| 9042 | The fields in the string are separated by any one of the characters in the |
| 9043 | separator string. These may include space or tab characters. |
| 9044 | The first field is numbered one. If the number is negative, the fields are |
| 9045 | counted from the end of the string, with the rightmost one numbered -1. If the |
| 9046 | number given is zero, the entire string is returned. If the modulus of the |
| 9047 | number is greater than the number of fields in the string, the result is the |
| 9048 | expansion of <&'string3'&>, or the empty string if <&'string3'&> is not |
| 9049 | provided. For example: |
| 9050 | .code |
| 9051 | ${extract{2}{:}{x:42:99:& Mailer::/bin/bash}} |
| 9052 | .endd |
| 9053 | yields &"42"&, and |
| 9054 | .code |
| 9055 | ${extract{-4}{:}{x:42:99:& Mailer::/bin/bash}} |
| 9056 | .endd |
| 9057 | yields &"99"&. Two successive separators mean that the field between them is |
| 9058 | empty (for example, the fifth field above). |
| 9059 | |
| 9060 | |
| 9061 | .vitem &*${filter{*&<&'string'&>&*}{*&<&'condition'&>&*}}*& |
| 9062 | .cindex "list" "selecting by condition" |
| 9063 | .cindex "expansion" "selecting from list by condition" |
| 9064 | .vindex "&$item$&" |
| 9065 | After expansion, <&'string'&> is interpreted as a list, colon-separated by |
| 9066 | default, but the separator can be changed in the usual way. For each item |
| 9067 | in this list, its value is place in &$item$&, and then the condition is |
| 9068 | evaluated. If the condition is true, &$item$& is added to the output as an |
| 9069 | item in a new list; if the condition is false, the item is discarded. The |
| 9070 | separator used for the output list is the same as the one used for the |
| 9071 | input, but a separator setting is not included in the output. For example: |
| 9072 | .code |
| 9073 | ${filter{a:b:c}{!eq{$item}{b}} |
| 9074 | .endd |
| 9075 | yields &`a:c`&. At the end of the expansion, the value of &$item$& is restored |
| 9076 | to what it was before. See also the &*map*& and &*reduce*& expansion items. |
| 9077 | |
| 9078 | |
| 9079 | .vitem &*${hash{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*& |
| 9080 | .cindex "hash function" "textual" |
| 9081 | .cindex "expansion" "textual hash" |
| 9082 | This is a textual hashing function, and was the first to be implemented in |
| 9083 | early versions of Exim. In current releases, there are other hashing functions |
| 9084 | (numeric, MD5, and SHA-1), which are described below. |
| 9085 | |
| 9086 | The first two strings, after expansion, must be numbers. Call them <&'m'&> and |
| 9087 | <&'n'&>. If you are using fixed values for these numbers, that is, if |
| 9088 | <&'string1'&> and <&'string2'&> do not change when they are expanded, you can |
| 9089 | use the simpler operator notation that avoids some of the braces: |
| 9090 | .code |
| 9091 | ${hash_<n>_<m>:<string>} |
| 9092 | .endd |
| 9093 | The second number is optional (in both notations). If <&'n'&> is greater than |
| 9094 | or equal to the length of the string, the expansion item returns the string. |
| 9095 | Otherwise it computes a new string of length <&'n'&> by applying a hashing |
| 9096 | function to the string. The new string consists of characters taken from the |
| 9097 | first <&'m'&> characters of the string |
| 9098 | .code |
| 9099 | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQWRSTUVWXYZ0123456789 |
| 9100 | .endd |
| 9101 | If <&'m'&> is not present the value 26 is used, so that only lower case |
| 9102 | letters appear. For example: |
| 9103 | .display |
| 9104 | &`$hash{3}{monty}} `& yields &`jmg`& |
| 9105 | &`$hash{5}{monty}} `& yields &`monty`& |
| 9106 | &`$hash{4}{62}{monty python}}`& yields &`fbWx`& |
| 9107 | .endd |
| 9108 | |
| 9109 | .vitem "&*$header_*&<&'header&~name'&>&*:*&&~or&~&&& |
| 9110 | &*$h_*&<&'header&~name'&>&*:*&" &&& |
| 9111 | "&*$bheader_*&<&'header&~name'&>&*:*&&~or&~&&& |
| 9112 | &*$bh_*&<&'header&~name'&>&*:*&" &&& |
| 9113 | "&*$rheader_*&<&'header&~name'&>&*:*&&~or&~&&& |
| 9114 | &*$rh_*&<&'header&~name'&>&*:*&" |
| 9115 | .cindex "expansion" "header insertion" |
| 9116 | .vindex "&$header_$&" |
| 9117 | .vindex "&$bheader_$&" |
| 9118 | .vindex "&$rheader_$&" |
| 9119 | .cindex "header lines" "in expansion strings" |
| 9120 | .cindex "header lines" "character sets" |
| 9121 | .cindex "header lines" "decoding" |
| 9122 | Substitute the contents of the named message header line, for example |
| 9123 | .code |
| 9124 | $header_reply-to: |
| 9125 | .endd |
| 9126 | The newline that terminates a header line is not included in the expansion, but |
| 9127 | internal newlines (caused by splitting the header line over several physical |
| 9128 | lines) may be present. |
| 9129 | |
| 9130 | The difference between &%rheader%&, &%bheader%&, and &%header%& is in the way |
| 9131 | the data in the header line is interpreted. |
| 9132 | |
| 9133 | .ilist |
| 9134 | .cindex "white space" "in header lines" |
| 9135 | &%rheader%& gives the original &"raw"& content of the header line, with no |
| 9136 | processing at all, and without the removal of leading and trailing white space. |
| 9137 | |
| 9138 | .next |
| 9139 | .cindex "base64 encoding" "in header lines" |
| 9140 | &%bheader%& removes leading and trailing white space, and then decodes base64 |
| 9141 | or quoted-printable MIME &"words"& within the header text, but does no |
| 9142 | character set translation. If decoding of what looks superficially like a MIME |
| 9143 | &"word"& fails, the raw string is returned. If decoding |
| 9144 | .cindex "binary zero" "in header line" |
| 9145 | produces a binary zero character, it is replaced by a question mark &-- this is |
| 9146 | what Exim does for binary zeros that are actually received in header lines. |
| 9147 | |
| 9148 | .next |
| 9149 | &%header%& tries to translate the string as decoded by &%bheader%& to a |
| 9150 | standard character set. This is an attempt to produce the same string as would |
| 9151 | be displayed on a user's MUA. If translation fails, the &%bheader%& string is |
| 9152 | returned. Translation is attempted only on operating systems that support the |
| 9153 | &[iconv()]& function. This is indicated by the compile-time macro HAVE_ICONV in |
| 9154 | a system Makefile or in &_Local/Makefile_&. |
| 9155 | .endlist ilist |
| 9156 | |
| 9157 | In a filter file, the target character set for &%header%& can be specified by a |
| 9158 | command of the following form: |
| 9159 | .code |
| 9160 | headers charset "UTF-8" |
| 9161 | .endd |
| 9162 | This command affects all references to &$h_$& (or &$header_$&) expansions in |
| 9163 | subsequently obeyed filter commands. In the absence of this command, the target |
| 9164 | character set in a filter is taken from the setting of the &%headers_charset%& |
| 9165 | option in the runtime configuration. The value of this option defaults to the |
| 9166 | value of HEADERS_CHARSET in &_Local/Makefile_&. The ultimate default is |
| 9167 | ISO-8859-1. |
| 9168 | |
| 9169 | Header names follow the syntax of RFC 2822, which states that they may contain |
| 9170 | any printing characters except space and colon. Consequently, curly brackets |
| 9171 | &'do not'& terminate header names, and should not be used to enclose them as |
| 9172 | if they were variables. Attempting to do so causes a syntax error. |
| 9173 | |
| 9174 | Only header lines that are common to all copies of a message are visible to |
| 9175 | this mechanism. These are the original header lines that are received with the |
| 9176 | message, and any that are added by an ACL statement or by a system |
| 9177 | filter. Header lines that are added to a particular copy of a message by a |
| 9178 | router or transport are not accessible. |
| 9179 | |
| 9180 | For incoming SMTP messages, no header lines are visible in ACLs that are obeyed |
| 9181 | before the DATA ACL, because the header structure is not set up until the |
| 9182 | message is received. Header lines that are added in a RCPT ACL (for example) |
| 9183 | are saved until the message's incoming header lines are available, at which |
| 9184 | point they are added. When a DATA ACL is running, however, header lines added |
| 9185 | by earlier ACLs are visible. |
| 9186 | |
| 9187 | Upper case and lower case letters are synonymous in header names. If the |
| 9188 | following character is white space, the terminating colon may be omitted, but |
| 9189 | this is not recommended, because you may then forget it when it is needed. When |
| 9190 | white space terminates the header name, it is included in the expanded string. |
| 9191 | If the message does not contain the given header, the expansion item is |
| 9192 | replaced by an empty string. (See the &%def%& condition in section |
| 9193 | &<<SECTexpcond>>& for a means of testing for the existence of a header.) |
| 9194 | |
| 9195 | If there is more than one header with the same name, they are all concatenated |
| 9196 | to form the substitution string, up to a maximum length of 64K. Unless |
| 9197 | &%rheader%& is being used, leading and trailing white space is removed from |
| 9198 | each header before concatenation, and a completely empty header is ignored. A |
| 9199 | newline character is then inserted between non-empty headers, but there is no |
| 9200 | newline at the very end. For the &%header%& and &%bheader%& expansion, for |
| 9201 | those headers that contain lists of addresses, a comma is also inserted at the |
| 9202 | junctions between headers. This does not happen for the &%rheader%& expansion. |
| 9203 | |
| 9204 | |
| 9205 | .vitem &*${hmac{*&<&'hashname'&>&*}{*&<&'secret'&>&*}{*&<&'string'&>&*}}*& |
| 9206 | .cindex "expansion" "hmac hashing" |
| 9207 | .cindex &%hmac%& |
| 9208 | This function uses cryptographic hashing (either MD5 or SHA-1) to convert a |
| 9209 | shared secret and some text into a message authentication code, as specified in |
| 9210 | RFC 2104. This differs from &`${md5:secret_text...}`& or |
| 9211 | &`${sha1:secret_text...}`& in that the hmac step adds a signature to the |
| 9212 | cryptographic hash, allowing for authentication that is not possible with MD5 |
| 9213 | or SHA-1 alone. The hash name must expand to either &`md5`& or &`sha1`& at |
| 9214 | present. For example: |
| 9215 | .code |
| 9216 | ${hmac{md5}{somesecret}{$primary_hostname $tod_log}} |
| 9217 | .endd |
| 9218 | For the hostname &'mail.example.com'& and time 2002-10-17 11:30:59, this |
| 9219 | produces: |
| 9220 | .code |
| 9221 | dd97e3ba5d1a61b5006108f8c8252953 |
| 9222 | .endd |
| 9223 | As an example of how this might be used, you might put in the main part of |
| 9224 | an Exim configuration: |
| 9225 | .code |
| 9226 | SPAMSCAN_SECRET=cohgheeLei2thahw |
| 9227 | .endd |
| 9228 | In a router or a transport you could then have: |
| 9229 | .code |
| 9230 | headers_add = \ |
| 9231 | X-Spam-Scanned: ${primary_hostname} ${message_exim_id} \ |
| 9232 | ${hmac{md5}{SPAMSCAN_SECRET}\ |
| 9233 | {${primary_hostname},${message_exim_id},$h_message-id:}} |
| 9234 | .endd |
| 9235 | Then given a message, you can check where it was scanned by looking at the |
| 9236 | &'X-Spam-Scanned:'& header line. If you know the secret, you can check that |
| 9237 | this header line is authentic by recomputing the authentication code from the |
| 9238 | host name, message ID and the &'Message-id:'& header line. This can be done |
| 9239 | using Exim's &%-be%& option, or by other means, for example by using the |
| 9240 | &'hmac_md5_hex()'& function in Perl. |
| 9241 | |
| 9242 | |
| 9243 | .vitem &*${if&~*&<&'condition'&>&*&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}}*& |
| 9244 | .cindex "expansion" "conditional" |
| 9245 | .cindex "&%if%&, expansion item" |
| 9246 | If <&'condition'&> is true, <&'string1'&> is expanded and replaces the whole |
| 9247 | item; otherwise <&'string2'&> is used. The available conditions are described |
| 9248 | in section &<<SECTexpcond>>& below. For example: |
| 9249 | .code |
| 9250 | ${if eq {$local_part}{postmaster} {yes}{no} } |
| 9251 | .endd |
| 9252 | The second string need not be present; if it is not and the condition is not |
| 9253 | true, the item is replaced with nothing. Alternatively, the word &"fail"& may |
| 9254 | be present instead of the second string (without any curly brackets). In this |
| 9255 | case, the expansion is forced to fail if the condition is not true (see section |
| 9256 | &<<SECTforexpfai>>&). |
| 9257 | |
| 9258 | If both strings are omitted, the result is the string &`true`& if the condition |
| 9259 | is true, and the empty string if the condition is false. This makes it less |
| 9260 | cumbersome to write custom ACL and router conditions. For example, instead of |
| 9261 | .code |
| 9262 | condition = ${if >{$acl_m4}{3}{true}{false}} |
| 9263 | .endd |
| 9264 | you can use |
| 9265 | .code |
| 9266 | condition = ${if >{$acl_m4}{3}} |
| 9267 | .endd |
| 9268 | |
| 9269 | .vitem &*${length{*&<&'string1'&>&*}{*&<&'string2'&>&*}}*& |
| 9270 | .cindex "expansion" "string truncation" |
| 9271 | .cindex "&%length%& expansion item" |
| 9272 | The &%length%& item is used to extract the initial portion of a string. Both |
| 9273 | strings are expanded, and the first one must yield a number, <&'n'&>, say. If |
| 9274 | you are using a fixed value for the number, that is, if <&'string1'&> does not |
| 9275 | change when expanded, you can use the simpler operator notation that avoids |
| 9276 | some of the braces: |
| 9277 | .code |
| 9278 | ${length_<n>:<string>} |
| 9279 | .endd |
| 9280 | The result of this item is either the first <&'n'&> characters or the whole |
| 9281 | of <&'string2'&>, whichever is the shorter. Do not confuse &%length%& with |
| 9282 | &%strlen%&, which gives the length of a string. |
| 9283 | |
| 9284 | |
| 9285 | .vitem "&*${listextract{*&<&'number'&>&*}&&& |
| 9286 | {*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&" |
| 9287 | .cindex "expansion" "extracting list elements by number" |
| 9288 | .cindex "&%listextract%&" "extract list elements by number" |
| 9289 | .cindex "list" "extracting elements by number" |
| 9290 | The <&'number'&> argument must consist entirely of decimal digits, |
| 9291 | apart from an optional leading minus, |
| 9292 | and leading and trailing white space (which is ignored). |
| 9293 | |
| 9294 | After expansion, <&'string1'&> is interpreted as a list, colon-separated by |
| 9295 | default, but the separator can be changed in the usual way. |
| 9296 | |
| 9297 | The first field of the list is numbered one. |
| 9298 | If the number is negative, the fields are |
| 9299 | counted from the end of the list, with the rightmost one numbered -1. |
| 9300 | The numbered element of the list is extracted and placed in &$value$&, |
| 9301 | then <&'string2'&> is expanded as the result. |
| 9302 | |
| 9303 | If the modulus of the |
| 9304 | number is zero or greater than the number of fields in the string, |
| 9305 | the result is the expansion of <&'string3'&>. |
| 9306 | |
| 9307 | For example: |
| 9308 | .code |
| 9309 | ${listextract{2}{x:42:99}} |
| 9310 | .endd |
| 9311 | yields &"42"&, and |
| 9312 | .code |
| 9313 | ${listextract{-3}{<, x,42,99,& Mailer,,/bin/bash}{result: $value}} |
| 9314 | .endd |
| 9315 | yields &"result: 99"&. |
| 9316 | |
| 9317 | If {<&'string3'&>} is omitted, an empty string is used for string3. |
| 9318 | If {<&'string2'&>} is also omitted, the value that was |
| 9319 | extracted is used. |
| 9320 | You can use &`fail`& instead of {<&'string3'&>} as in a string extract. |
| 9321 | |
| 9322 | |
| 9323 | .vitem "&*${lookup{*&<&'key'&>&*}&~*&<&'search&~type'&>&*&~&&& |
| 9324 | {*&<&'file'&>&*}&~{*&<&'string1'&>&*}&~{*&<&'string2'&>&*}}*&" |
| 9325 | This is the first of one of two different types of lookup item, which are both |
| 9326 | described in the next item. |
| 9327 | |
| 9328 | .vitem "&*${lookup&~*&<&'search&~type'&>&*&~{*&<&'query'&>&*}&~&&& |
| 9329 | {*&<&'string1'&>&*}&~{*&<&'string2'&>&*}}*&" |
| 9330 | .cindex "expansion" "lookup in" |
| 9331 | .cindex "file" "lookups" |
| 9332 | .cindex "lookup" "in expanded string" |
| 9333 | The two forms of lookup item specify data lookups in files and databases, as |
| 9334 | discussed in chapter &<<CHAPfdlookup>>&. The first form is used for single-key |
| 9335 | lookups, and the second is used for query-style lookups. The <&'key'&>, |
| 9336 | <&'file'&>, and <&'query'&> strings are expanded before use. |
| 9337 | |
| 9338 | If there is any white space in a lookup item which is part of a filter command, |
| 9339 | a retry or rewrite rule, a routing rule for the &(manualroute)& router, or any |
| 9340 | other place where white space is significant, the lookup item must be enclosed |
| 9341 | in double quotes. The use of data lookups in users' filter files may be locked |
| 9342 | out by the system administrator. |
| 9343 | |
| 9344 | .vindex "&$value$&" |
| 9345 | If the lookup succeeds, <&'string1'&> is expanded and replaces the entire item. |
| 9346 | During its expansion, the variable &$value$& contains the data returned by the |
| 9347 | lookup. Afterwards it reverts to the value it had previously (at the outer |
| 9348 | level it is empty). If the lookup fails, <&'string2'&> is expanded and replaces |
| 9349 | the entire item. If {<&'string2'&>} is omitted, the replacement is the empty |
| 9350 | string on failure. If <&'string2'&> is provided, it can itself be a nested |
| 9351 | lookup, thus providing a mechanism for looking up a default value when the |
| 9352 | original lookup fails. |
| 9353 | |
| 9354 | If a nested lookup is used as part of <&'string1'&>, &$value$& contains the |
| 9355 | data for the outer lookup while the parameters of the second lookup are |
| 9356 | expanded, and also while <&'string2'&> of the second lookup is expanded, should |
| 9357 | the second lookup fail. Instead of {<&'string2'&>} the word &"fail"& can |
| 9358 | appear, and in this case, if the lookup fails, the entire expansion is forced |
| 9359 | to fail (see section &<<SECTforexpfai>>&). If both {<&'string1'&>} and |
| 9360 | {<&'string2'&>} are omitted, the result is the looked up value in the case of a |
| 9361 | successful lookup, and nothing in the case of failure. |
| 9362 | |
| 9363 | For single-key lookups, the string &"partial"& is permitted to precede the |
| 9364 | search type in order to do partial matching, and * or *@ may follow a search |
| 9365 | type to request default lookups if the key does not match (see sections |
| 9366 | &<<SECTdefaultvaluelookups>>& and &<<SECTpartiallookup>>& for details). |
| 9367 | |
| 9368 | .cindex "numerical variables (&$1$& &$2$& etc)" "in lookup expansion" |
| 9369 | If a partial search is used, the variables &$1$& and &$2$& contain the wild |
| 9370 | and non-wild parts of the key during the expansion of the replacement text. |
| 9371 | They return to their previous values at the end of the lookup item. |
| 9372 | |
| 9373 | This example looks up the postmaster alias in the conventional alias file: |
| 9374 | .code |
| 9375 | ${lookup {postmaster} lsearch {/etc/aliases} {$value}} |
| 9376 | .endd |
| 9377 | This example uses NIS+ to look up the full name of the user corresponding to |
| 9378 | the local part of an address, forcing the expansion to fail if it is not found: |
| 9379 | .code |
| 9380 | ${lookup nisplus {[name=$local_part],passwd.org_dir:gcos} \ |
| 9381 | {$value}fail} |
| 9382 | .endd |
| 9383 | |
| 9384 | |
| 9385 | .vitem &*${map{*&<&'string1'&>&*}{*&<&'string2'&>&*}}*& |
| 9386 | .cindex "expansion" "list creation" |
| 9387 | .vindex "&$item$&" |
| 9388 | After expansion, <&'string1'&> is interpreted as a list, colon-separated by |
| 9389 | default, but the separator can be changed in the usual way. For each item |
| 9390 | in this list, its value is place in &$item$&, and then <&'string2'&> is |
| 9391 | expanded and added to the output as an item in a new list. The separator used |
| 9392 | for the output list is the same as the one used for the input, but a separator |
| 9393 | setting is not included in the output. For example: |
| 9394 | .code |
| 9395 | ${map{a:b:c}{[$item]}} ${map{<- x-y-z}{($item)}} |
| 9396 | .endd |
| 9397 | expands to &`[a]:[b]:[c] (x)-(y)-(z)`&. At the end of the expansion, the |
| 9398 | value of &$item$& is restored to what it was before. See also the &*filter*& |
| 9399 | and &*reduce*& expansion items. |
| 9400 | |
| 9401 | .vitem &*${nhash{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*& |
| 9402 | .cindex "expansion" "numeric hash" |
| 9403 | .cindex "hash function" "numeric" |
| 9404 | The three strings are expanded; the first two must yield numbers. Call them |
| 9405 | <&'n'&> and <&'m'&>. If you are using fixed values for these numbers, that is, |
| 9406 | if <&'string1'&> and <&'string2'&> do not change when they are expanded, you |
| 9407 | can use the simpler operator notation that avoids some of the braces: |
| 9408 | .code |
| 9409 | ${nhash_<n>_<m>:<string>} |
| 9410 | .endd |
| 9411 | The second number is optional (in both notations). If there is only one number, |
| 9412 | the result is a number in the range 0&--<&'n'&>-1. Otherwise, the string is |
| 9413 | processed by a div/mod hash function that returns two numbers, separated by a |
| 9414 | slash, in the ranges 0 to <&'n'&>-1 and 0 to <&'m'&>-1, respectively. For |
| 9415 | example, |
| 9416 | .code |
| 9417 | ${nhash{8}{64}{supercalifragilisticexpialidocious}} |
| 9418 | .endd |
| 9419 | returns the string &"6/33"&. |
| 9420 | |
| 9421 | |
| 9422 | |
| 9423 | .vitem &*${perl{*&<&'subroutine'&>&*}{*&<&'arg'&>&*}{*&<&'arg'&>&*}...}*& |
| 9424 | .cindex "Perl" "use in expanded string" |
| 9425 | .cindex "expansion" "calling Perl from" |
| 9426 | This item is available only if Exim has been built to include an embedded Perl |
| 9427 | interpreter. The subroutine name and the arguments are first separately |
| 9428 | expanded, and then the Perl subroutine is called with those arguments. No |
| 9429 | additional arguments need be given; the maximum number permitted, including the |
| 9430 | name of the subroutine, is nine. |
| 9431 | |
| 9432 | The return value of the subroutine is inserted into the expanded string, unless |
| 9433 | the return value is &%undef%&. In that case, the expansion fails in the same |
| 9434 | way as an explicit &"fail"& on a lookup item. The return value is a scalar. |
| 9435 | Whatever you return is evaluated in a scalar context. For example, if you |
| 9436 | return the name of a Perl vector, the return value is the size of the vector, |
| 9437 | not its contents. |
| 9438 | |
| 9439 | If the subroutine exits by calling Perl's &%die%& function, the expansion fails |
| 9440 | with the error message that was passed to &%die%&. More details of the embedded |
| 9441 | Perl facility are given in chapter &<<CHAPperl>>&. |
| 9442 | |
| 9443 | The &(redirect)& router has an option called &%forbid_filter_perl%& which locks |
| 9444 | out the use of this expansion item in filter files. |
| 9445 | |
| 9446 | |
| 9447 | .vitem &*${prvs{*&<&'address'&>&*}{*&<&'secret'&>&*}{*&<&'keynumber'&>&*}}*& |
| 9448 | .cindex "&%prvs%& expansion item" |
| 9449 | The first argument is a complete email address and the second is secret |
| 9450 | keystring. The third argument, specifying a key number, is optional. If absent, |
| 9451 | it defaults to 0. The result of the expansion is a prvs-signed email address, |
| 9452 | to be typically used with the &%return_path%& option on an &(smtp)& transport |
| 9453 | as part of a bounce address tag validation (BATV) scheme. For more discussion |
| 9454 | and an example, see section &<<SECTverifyPRVS>>&. |
| 9455 | |
| 9456 | .vitem "&*${prvscheck{*&<&'address'&>&*}{*&<&'secret'&>&*}&&& |
| 9457 | {*&<&'string'&>&*}}*&" |
| 9458 | .cindex "&%prvscheck%& expansion item" |
| 9459 | This expansion item is the complement of the &%prvs%& item. It is used for |
| 9460 | checking prvs-signed addresses. If the expansion of the first argument does not |
| 9461 | yield a syntactically valid prvs-signed address, the whole item expands to the |
| 9462 | empty string. When the first argument does expand to a syntactically valid |
| 9463 | prvs-signed address, the second argument is expanded, with the prvs-decoded |
| 9464 | version of the address and the key number extracted from the address in the |
| 9465 | variables &$prvscheck_address$& and &$prvscheck_keynum$&, respectively. |
| 9466 | |
| 9467 | These two variables can be used in the expansion of the second argument to |
| 9468 | retrieve the secret. The validity of the prvs-signed address is then checked |
| 9469 | against the secret. The result is stored in the variable &$prvscheck_result$&, |
| 9470 | which is empty for failure or &"1"& for success. |
| 9471 | |
| 9472 | The third argument is optional; if it is missing, it defaults to an empty |
| 9473 | string. This argument is now expanded. If the result is an empty string, the |
| 9474 | result of the expansion is the decoded version of the address. This is the case |
| 9475 | whether or not the signature was valid. Otherwise, the result of the expansion |
| 9476 | is the expansion of the third argument. |
| 9477 | |
| 9478 | All three variables can be used in the expansion of the third argument. |
| 9479 | However, once the expansion is complete, only &$prvscheck_result$& remains set. |
| 9480 | For more discussion and an example, see section &<<SECTverifyPRVS>>&. |
| 9481 | |
| 9482 | .vitem &*${readfile{*&<&'file&~name'&>&*}{*&<&'eol&~string'&>&*}}*& |
| 9483 | .cindex "expansion" "inserting an entire file" |
| 9484 | .cindex "file" "inserting into expansion" |
| 9485 | .cindex "&%readfile%& expansion item" |
| 9486 | The file name and end-of-line string are first expanded separately. The file is |
| 9487 | then read, and its contents replace the entire item. All newline characters in |
| 9488 | the file are replaced by the end-of-line string if it is present. Otherwise, |
| 9489 | newlines are left in the string. |
| 9490 | String expansion is not applied to the contents of the file. If you want this, |
| 9491 | you must wrap the item in an &%expand%& operator. If the file cannot be read, |
| 9492 | the string expansion fails. |
| 9493 | |
| 9494 | The &(redirect)& router has an option called &%forbid_filter_readfile%& which |
| 9495 | locks out the use of this expansion item in filter files. |
| 9496 | |
| 9497 | |
| 9498 | |
| 9499 | .vitem "&*${readsocket{*&<&'name'&>&*}{*&<&'request'&>&*}&&& |
| 9500 | {*&<&'timeout'&>&*}{*&<&'eol&~string'&>&*}{*&<&'fail&~string'&>&*}}*&" |
| 9501 | .cindex "expansion" "inserting from a socket" |
| 9502 | .cindex "socket, use of in expansion" |
| 9503 | .cindex "&%readsocket%& expansion item" |
| 9504 | This item inserts data from a Unix domain or Internet socket into the expanded |
| 9505 | string. The minimal way of using it uses just two arguments, as in these |
| 9506 | examples: |
| 9507 | .code |
| 9508 | ${readsocket{/socket/name}{request string}} |
| 9509 | ${readsocket{inet:some.host:1234}{request string}} |
| 9510 | .endd |
| 9511 | For a Unix domain socket, the first substring must be the path to the socket. |
| 9512 | For an Internet socket, the first substring must contain &`inet:`& followed by |
| 9513 | a host name or IP address, followed by a colon and a port, which can be a |
| 9514 | number or the name of a TCP port in &_/etc/services_&. An IP address may |
| 9515 | optionally be enclosed in square brackets. This is best for IPv6 addresses. For |
| 9516 | example: |
| 9517 | .code |
| 9518 | ${readsocket{inet:[::1]:1234}{request string}} |
| 9519 | .endd |
| 9520 | Only a single host name may be given, but if looking it up yields more than |
| 9521 | one IP address, they are each tried in turn until a connection is made. For |
| 9522 | both kinds of socket, Exim makes a connection, writes the request string |
| 9523 | (unless it is an empty string) and reads from the socket until an end-of-file |
| 9524 | is read. A timeout of 5 seconds is applied. Additional, optional arguments |
| 9525 | extend what can be done. Firstly, you can vary the timeout. For example: |
| 9526 | .code |
| 9527 | ${readsocket{/socket/name}{request string}{3s}} |
| 9528 | .endd |
| 9529 | A fourth argument allows you to change any newlines that are in the data |
| 9530 | that is read, in the same way as for &%readfile%& (see above). This example |
| 9531 | turns them into spaces: |
| 9532 | .code |
| 9533 | ${readsocket{inet:127.0.0.1:3294}{request string}{3s}{ }} |
| 9534 | .endd |
| 9535 | As with all expansions, the substrings are expanded before the processing |
| 9536 | happens. Errors in these sub-expansions cause the expansion to fail. In |
| 9537 | addition, the following errors can occur: |
| 9538 | |
| 9539 | .ilist |
| 9540 | Failure to create a socket file descriptor; |
| 9541 | .next |
| 9542 | Failure to connect the socket; |
| 9543 | .next |
| 9544 | Failure to write the request string; |
| 9545 | .next |
| 9546 | Timeout on reading from the socket. |
| 9547 | .endlist |
| 9548 | |
| 9549 | By default, any of these errors causes the expansion to fail. However, if |
| 9550 | you supply a fifth substring, it is expanded and used when any of the above |
| 9551 | errors occurs. For example: |
| 9552 | .code |
| 9553 | ${readsocket{/socket/name}{request string}{3s}{\n}\ |
| 9554 | {socket failure}} |
| 9555 | .endd |
| 9556 | You can test for the existence of a Unix domain socket by wrapping this |
| 9557 | expansion in &`${if exists`&, but there is a race condition between that test |
| 9558 | and the actual opening of the socket, so it is safer to use the fifth argument |
| 9559 | if you want to be absolutely sure of avoiding an expansion error for a |
| 9560 | non-existent Unix domain socket, or a failure to connect to an Internet socket. |
| 9561 | |
| 9562 | The &(redirect)& router has an option called &%forbid_filter_readsocket%& which |
| 9563 | locks out the use of this expansion item in filter files. |
| 9564 | |
| 9565 | |
| 9566 | .vitem &*${reduce{*&<&'string1'&>}{<&'string2'&>&*}{*&<&'string3'&>&*}}*& |
| 9567 | .cindex "expansion" "reducing a list to a scalar" |
| 9568 | .cindex "list" "reducing to a scalar" |
| 9569 | .vindex "&$value$&" |
| 9570 | .vindex "&$item$&" |
| 9571 | This operation reduces a list to a single, scalar string. After expansion, |
| 9572 | <&'string1'&> is interpreted as a list, colon-separated by default, but the |
| 9573 | separator can be changed in the usual way. Then <&'string2'&> is expanded and |
| 9574 | assigned to the &$value$& variable. After this, each item in the <&'string1'&> |
| 9575 | list is assigned to &$item$& in turn, and <&'string3'&> is expanded for each of |
| 9576 | them. The result of that expansion is assigned to &$value$& before the next |
| 9577 | iteration. When the end of the list is reached, the final value of &$value$& is |
| 9578 | added to the expansion output. The &*reduce*& expansion item can be used in a |
| 9579 | number of ways. For example, to add up a list of numbers: |
| 9580 | .code |
| 9581 | ${reduce {<, 1,2,3}{0}{${eval:$value+$item}}} |
| 9582 | .endd |
| 9583 | The result of that expansion would be &`6`&. The maximum of a list of numbers |
| 9584 | can be found: |
| 9585 | .code |
| 9586 | ${reduce {3:0:9:4:6}{0}{${if >{$item}{$value}{$item}{$value}}}} |
| 9587 | .endd |
| 9588 | At the end of a &*reduce*& expansion, the values of &$item$& and &$value$& are |
| 9589 | restored to what they were before. See also the &*filter*& and &*map*& |
| 9590 | expansion items. |
| 9591 | |
| 9592 | .vitem &*$rheader_*&<&'header&~name'&>&*:*&&~or&~&*$rh_*&<&'header&~name'&>&*:*& |
| 9593 | This item inserts &"raw"& header lines. It is described with the &%header%& |
| 9594 | expansion item above. |
| 9595 | |
| 9596 | .vitem "&*${run{*&<&'command'&>&*&~*&<&'args'&>&*}{*&<&'string1'&>&*}&&& |
| 9597 | {*&<&'string2'&>&*}}*&" |
| 9598 | .cindex "expansion" "running a command" |
| 9599 | .cindex "&%run%& expansion item" |
| 9600 | The command and its arguments are first expanded separately, and then the |
| 9601 | command is run in a separate process, but under the same uid and gid. As in |
| 9602 | other command executions from Exim, a shell is not used by default. If you want |
| 9603 | a shell, you must explicitly code it. |
| 9604 | |
| 9605 | The standard input for the command exists, but is empty. The standard output |
| 9606 | and standard error are set to the same file descriptor. |
| 9607 | .cindex "return code" "from &%run%& expansion" |
| 9608 | .vindex "&$value$&" |
| 9609 | If the command succeeds (gives a zero return code) <&'string1'&> is expanded |
| 9610 | and replaces the entire item; during this expansion, the standard output/error |
| 9611 | from the command is in the variable &$value$&. If the command fails, |
| 9612 | <&'string2'&>, if present, is expanded and used. Once again, during the |
| 9613 | expansion, the standard output/error from the command is in the variable |
| 9614 | &$value$&. |
| 9615 | |
| 9616 | If <&'string2'&> is absent, the result is empty. Alternatively, <&'string2'&> |
| 9617 | can be the word &"fail"& (not in braces) to force expansion failure if the |
| 9618 | command does not succeed. If both strings are omitted, the result is contents |
| 9619 | of the standard output/error on success, and nothing on failure. |
| 9620 | |
| 9621 | .vindex "&$run_in_acl$&" |
| 9622 | The standard output/error of the command is put in the variable &$value$&. |
| 9623 | In this ACL example, the output of a command is logged for the admin to |
| 9624 | troubleshoot: |
| 9625 | .code |
| 9626 | warn condition = ${run{/usr/bin/id}{yes}{no}} |
| 9627 | log_message = Output of id: $value |
| 9628 | .endd |
| 9629 | If the command requires shell idioms, such as the > redirect operator, the |
| 9630 | shell must be invoked directly, such as with: |
| 9631 | .code |
| 9632 | ${run{/bin/bash -c "/usr/bin/id >/tmp/id"}{yes}{yes}} |
| 9633 | .endd |
| 9634 | |
| 9635 | .vindex "&$runrc$&" |
| 9636 | The return code from the command is put in the variable &$runrc$&, and this |
| 9637 | remains set afterwards, so in a filter file you can do things like this: |
| 9638 | .code |
| 9639 | if "${run{x y z}{}}$runrc" is 1 then ... |
| 9640 | elif $runrc is 2 then ... |
| 9641 | ... |
| 9642 | endif |
| 9643 | .endd |
| 9644 | If execution of the command fails (for example, the command does not exist), |
| 9645 | the return code is 127 &-- the same code that shells use for non-existent |
| 9646 | commands. |
| 9647 | |
| 9648 | &*Warning*&: In a router or transport, you cannot assume the order in which |
| 9649 | option values are expanded, except for those preconditions whose order of |
| 9650 | testing is documented. Therefore, you cannot reliably expect to set &$runrc$& |
| 9651 | by the expansion of one option, and use it in another. |
| 9652 | |
| 9653 | The &(redirect)& router has an option called &%forbid_filter_run%& which locks |
| 9654 | out the use of this expansion item in filter files. |
| 9655 | |
| 9656 | |
| 9657 | .vitem &*${sg{*&<&'subject'&>&*}{*&<&'regex'&>&*}{*&<&'replacement'&>&*}}*& |
| 9658 | .cindex "expansion" "string substitution" |
| 9659 | .cindex "&%sg%& expansion item" |
| 9660 | This item works like Perl's substitution operator (s) with the global (/g) |
| 9661 | option; hence its name. However, unlike the Perl equivalent, Exim does not |
| 9662 | modify the subject string; instead it returns the modified string for insertion |
| 9663 | into the overall expansion. The item takes three arguments: the subject string, |
| 9664 | a regular expression, and a substitution string. For example: |
| 9665 | .code |
| 9666 | ${sg{abcdefabcdef}{abc}{xyz}} |
| 9667 | .endd |
| 9668 | yields &"xyzdefxyzdef"&. Because all three arguments are expanded before use, |
| 9669 | if any $ or \ characters are required in the regular expression or in the |
| 9670 | substitution string, they have to be escaped. For example: |
| 9671 | .code |
| 9672 | ${sg{abcdef}{^(...)(...)\$}{\$2\$1}} |
| 9673 | .endd |
| 9674 | yields &"defabc"&, and |
| 9675 | .code |
| 9676 | ${sg{1=A 4=D 3=C}{\N(\d+)=\N}{K\$1=}} |
| 9677 | .endd |
| 9678 | yields &"K1=A K4=D K3=C"&. Note the use of &`\N`& to protect the contents of |
| 9679 | the regular expression from string expansion. |
| 9680 | |
| 9681 | |
| 9682 | |
| 9683 | .vitem &*${substr{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*& |
| 9684 | .cindex "&%substr%& expansion item" |
| 9685 | .cindex "substring extraction" |
| 9686 | .cindex "expansion" "substring extraction" |
| 9687 | The three strings are expanded; the first two must yield numbers. Call them |
| 9688 | <&'n'&> and <&'m'&>. If you are using fixed values for these numbers, that is, |
| 9689 | if <&'string1'&> and <&'string2'&> do not change when they are expanded, you |
| 9690 | can use the simpler operator notation that avoids some of the braces: |
| 9691 | .code |
| 9692 | ${substr_<n>_<m>:<string>} |
| 9693 | .endd |
| 9694 | The second number is optional (in both notations). |
| 9695 | If it is absent in the simpler format, the preceding underscore must also be |
| 9696 | omitted. |
| 9697 | |
| 9698 | The &%substr%& item can be used to extract more general substrings than |
| 9699 | &%length%&. The first number, <&'n'&>, is a starting offset, and <&'m'&> is the |
| 9700 | length required. For example |
| 9701 | .code |
| 9702 | ${substr{3}{2}{$local_part}} |
| 9703 | .endd |
| 9704 | If the starting offset is greater than the string length the result is the |
| 9705 | null string; if the length plus starting offset is greater than the string |
| 9706 | length, the result is the right-hand part of the string, starting from the |
| 9707 | given offset. The first character in the string has offset zero. |
| 9708 | |
| 9709 | The &%substr%& expansion item can take negative offset values to count |
| 9710 | from the right-hand end of its operand. The last character is offset -1, the |
| 9711 | second-last is offset -2, and so on. Thus, for example, |
| 9712 | .code |
| 9713 | ${substr{-5}{2}{1234567}} |
| 9714 | .endd |
| 9715 | yields &"34"&. If the absolute value of a negative offset is greater than the |
| 9716 | length of the string, the substring starts at the beginning of the string, and |
| 9717 | the length is reduced by the amount of overshoot. Thus, for example, |
| 9718 | .code |
| 9719 | ${substr{-5}{2}{12}} |
| 9720 | .endd |
| 9721 | yields an empty string, but |
| 9722 | .code |
| 9723 | ${substr{-3}{2}{12}} |
| 9724 | .endd |
| 9725 | yields &"1"&. |
| 9726 | |
| 9727 | When the second number is omitted from &%substr%&, the remainder of the string |
| 9728 | is taken if the offset is positive. If it is negative, all characters in the |
| 9729 | string preceding the offset point are taken. For example, an offset of -1 and |
| 9730 | no length, as in these semantically identical examples: |
| 9731 | .code |
| 9732 | ${substr_-1:abcde} |
| 9733 | ${substr{-1}{abcde}} |
| 9734 | .endd |
| 9735 | yields all but the last character of the string, that is, &"abcd"&. |
| 9736 | |
| 9737 | |
| 9738 | |
| 9739 | .vitem "&*${tr{*&<&'subject'&>&*}{*&<&'characters'&>&*}&&& |
| 9740 | {*&<&'replacements'&>&*}}*&" |
| 9741 | .cindex "expansion" "character translation" |
| 9742 | .cindex "&%tr%& expansion item" |
| 9743 | This item does single-character translation on its subject string. The second |
| 9744 | argument is a list of characters to be translated in the subject string. Each |
| 9745 | matching character is replaced by the corresponding character from the |
| 9746 | replacement list. For example |
| 9747 | .code |
| 9748 | ${tr{abcdea}{ac}{13}} |
| 9749 | .endd |
| 9750 | yields &`1b3de1`&. If there are duplicates in the second character string, the |
| 9751 | last occurrence is used. If the third string is shorter than the second, its |
| 9752 | last character is replicated. However, if it is empty, no translation takes |
| 9753 | place. |
| 9754 | .endlist |
| 9755 | |
| 9756 | |
| 9757 | |
| 9758 | .section "Expansion operators" "SECTexpop" |
| 9759 | .cindex "expansion" "operators" |
| 9760 | For expansion items that perform transformations on a single argument string, |
| 9761 | the &"operator"& notation is used because it is simpler and uses fewer braces. |
| 9762 | The substring is first expanded before the operation is applied to it. The |
| 9763 | following operations can be performed: |
| 9764 | |
| 9765 | .vlist |
| 9766 | .vitem &*${address:*&<&'string'&>&*}*& |
| 9767 | .cindex "expansion" "RFC 2822 address handling" |
| 9768 | .cindex "&%address%& expansion item" |
| 9769 | The string is interpreted as an RFC 2822 address, as it might appear in a |
| 9770 | header line, and the effective address is extracted from it. If the string does |
| 9771 | not parse successfully, the result is empty. |
| 9772 | |
| 9773 | |
| 9774 | .vitem &*${addresses:*&<&'string'&>&*}*& |
| 9775 | .cindex "expansion" "RFC 2822 address handling" |
| 9776 | .cindex "&%addresses%& expansion item" |
| 9777 | The string (after expansion) is interpreted as a list of addresses in RFC |
| 9778 | 2822 format, such as can be found in a &'To:'& or &'Cc:'& header line. The |
| 9779 | operative address (&'local-part@domain'&) is extracted from each item, and the |
| 9780 | result of the expansion is a colon-separated list, with appropriate |
| 9781 | doubling of colons should any happen to be present in the email addresses. |
| 9782 | Syntactically invalid RFC2822 address items are omitted from the output. |
| 9783 | |
| 9784 | It is possible to specify a character other than colon for the output |
| 9785 | separator by starting the string with > followed by the new separator |
| 9786 | character. For example: |
| 9787 | .code |
| 9788 | ${addresses:>& Chief <ceo@up.stairs>, sec@base.ment (dogsbody)} |
| 9789 | .endd |
| 9790 | expands to &`ceo@up.stairs&&sec@base.ment`&. Compare the &*address*& (singular) |
| 9791 | expansion item, which extracts the working address from a single RFC2822 |
| 9792 | address. See the &*filter*&, &*map*&, and &*reduce*& items for ways of |
| 9793 | processing lists. |
| 9794 | |
| 9795 | To clarify "list of addresses in RFC 2822 format" mentioned above, Exim follows |
| 9796 | a strict interpretation of header line formatting. Exim parses the bare, |
| 9797 | unquoted portion of an email address and if it finds a comma, treats it as an |
| 9798 | email address seperator. For the example header line: |
| 9799 | .code |
| 9800 | From: =?iso-8859-2?Q?Last=2C_First?= <user@example.com> |
| 9801 | .endd |
| 9802 | The first example below demonstrates that Q-encoded email addresses are parsed |
| 9803 | properly if it is given the raw header (in this example, &`$rheader_from:`&). |
| 9804 | It does not see the comma because it's still encoded as "=2C". The second |
| 9805 | example below is passed the contents of &`$header_from:`&, meaning it gets |
| 9806 | de-mimed. Exim sees the decoded "," so it treats it as &*two*& email addresses. |
| 9807 | The third example shows that the presence of a comma is skipped when it is |
| 9808 | quoted. |
| 9809 | .code |
| 9810 | # exim -be '${addresses:From: \ |
| 9811 | =?iso-8859-2?Q?Last=2C_First?= <user@example.com>}' |
| 9812 | user@example.com |
| 9813 | # exim -be '${addresses:From: Last, First <user@example.com>}' |
| 9814 | Last:user@example.com |
| 9815 | # exim -be '${addresses:From: "Last, First" <user@example.com>}' |
| 9816 | user@example.com |
| 9817 | .endd |
| 9818 | |
| 9819 | .vitem &*${base62:*&<&'digits'&>&*}*& |
| 9820 | .cindex "&%base62%& expansion item" |
| 9821 | .cindex "expansion" "conversion to base 62" |
| 9822 | The string must consist entirely of decimal digits. The number is converted to |
| 9823 | base 62 and output as a string of six characters, including leading zeros. In |
| 9824 | the few operating environments where Exim uses base 36 instead of base 62 for |
| 9825 | its message identifiers (because those systems do not have case-sensitive file |
| 9826 | names), base 36 is used by this operator, despite its name. &*Note*&: Just to |
| 9827 | be absolutely clear: this is &'not'& base64 encoding. |
| 9828 | |
| 9829 | .vitem &*${base62d:*&<&'base-62&~digits'&>&*}*& |
| 9830 | .cindex "&%base62d%& expansion item" |
| 9831 | .cindex "expansion" "conversion to base 62" |
| 9832 | The string must consist entirely of base-62 digits, or, in operating |
| 9833 | environments where Exim uses base 36 instead of base 62 for its message |
| 9834 | identifiers, base-36 digits. The number is converted to decimal and output as a |
| 9835 | string. |
| 9836 | |
| 9837 | |
| 9838 | .vitem &*${domain:*&<&'string'&>&*}*& |
| 9839 | .cindex "domain" "extraction" |
| 9840 | .cindex "expansion" "domain extraction" |
| 9841 | The string is interpreted as an RFC 2822 address and the domain is extracted |
| 9842 | from it. If the string does not parse successfully, the result is empty. |
| 9843 | |
| 9844 | |
| 9845 | .vitem &*${escape:*&<&'string'&>&*}*& |
| 9846 | .cindex "expansion" "escaping non-printing characters" |
| 9847 | .cindex "&%escape%& expansion item" |
| 9848 | If the string contains any non-printing characters, they are converted to |
| 9849 | escape sequences starting with a backslash. Whether characters with the most |
| 9850 | significant bit set (so-called &"8-bit characters"&) count as printing or not |
| 9851 | is controlled by the &%print_topbitchars%& option. |
| 9852 | |
| 9853 | |
| 9854 | .vitem &*${eval:*&<&'string'&>&*}*&&~and&~&*${eval10:*&<&'string'&>&*}*& |
| 9855 | .cindex "expansion" "expression evaluation" |
| 9856 | .cindex "expansion" "arithmetic expression" |
| 9857 | .cindex "&%eval%& expansion item" |
| 9858 | These items supports simple arithmetic and bitwise logical operations in |
| 9859 | expansion strings. The string (after expansion) must be a conventional |
| 9860 | arithmetic expression, but it is limited to basic arithmetic operators, bitwise |
| 9861 | logical operators, and parentheses. All operations are carried out using |
| 9862 | integer arithmetic. The operator priorities are as follows (the same as in the |
| 9863 | C programming language): |
| 9864 | .table2 70pt 300pt |
| 9865 | .irow &'highest:'& "not (~), negate (-)" |
| 9866 | .irow "" "multiply (*), divide (/), remainder (%)" |
| 9867 | .irow "" "plus (+), minus (-)" |
| 9868 | .irow "" "shift-left (<<), shift-right (>>)" |
| 9869 | .irow "" "and (&&)" |
| 9870 | .irow "" "xor (^)" |
| 9871 | .irow &'lowest:'& "or (|)" |
| 9872 | .endtable |
| 9873 | Binary operators with the same priority are evaluated from left to right. White |
| 9874 | space is permitted before or after operators. |
| 9875 | |
| 9876 | For &%eval%&, numbers may be decimal, octal (starting with &"0"&) or |
| 9877 | hexadecimal (starting with &"0x"&). For &%eval10%&, all numbers are taken as |
| 9878 | decimal, even if they start with a leading zero; hexadecimal numbers are not |
| 9879 | permitted. This can be useful when processing numbers extracted from dates or |
| 9880 | times, which often do have leading zeros. |
| 9881 | |
| 9882 | A number may be followed by &"K"&, &"M"& or &"G"& to multiply it by 1024, 1024*1024 |
| 9883 | or 1024*1024*1024, |
| 9884 | respectively. Negative numbers are supported. The result of the computation is |
| 9885 | a decimal representation of the answer (without &"K"&, &"M"& or &"G"&). For example: |
| 9886 | |
| 9887 | .display |
| 9888 | &`${eval:1+1} `& yields 2 |
| 9889 | &`${eval:1+2*3} `& yields 7 |
| 9890 | &`${eval:(1+2)*3} `& yields 9 |
| 9891 | &`${eval:2+42%5} `& yields 4 |
| 9892 | &`${eval:0xc&5} `& yields 4 |
| 9893 | &`${eval:0xc|5} `& yields 13 |
| 9894 | &`${eval:0xc^5} `& yields 9 |
| 9895 | &`${eval:0xc>>1} `& yields 6 |
| 9896 | &`${eval:0xc<<1} `& yields 24 |
| 9897 | &`${eval:~255&0x1234} `& yields 4608 |
| 9898 | &`${eval:-(~255&0x1234)} `& yields -4608 |
| 9899 | .endd |
| 9900 | |
| 9901 | As a more realistic example, in an ACL you might have |
| 9902 | .code |
| 9903 | deny message = Too many bad recipients |
| 9904 | condition = \ |
| 9905 | ${if and { \ |
| 9906 | {>{$rcpt_count}{10}} \ |
| 9907 | { \ |
| 9908 | < \ |
| 9909 | {$recipients_count} \ |
| 9910 | {${eval:$rcpt_count/2}} \ |
| 9911 | } \ |
| 9912 | }{yes}{no}} |
| 9913 | .endd |
| 9914 | The condition is true if there have been more than 10 RCPT commands and |
| 9915 | fewer than half of them have resulted in a valid recipient. |
| 9916 | |
| 9917 | |
| 9918 | .vitem &*${expand:*&<&'string'&>&*}*& |
| 9919 | .cindex "expansion" "re-expansion of substring" |
| 9920 | The &%expand%& operator causes a string to be expanded for a second time. For |
| 9921 | example, |
| 9922 | .code |
| 9923 | ${expand:${lookup{$domain}dbm{/some/file}{$value}}} |
| 9924 | .endd |
| 9925 | first looks up a string in a file while expanding the operand for &%expand%&, |
| 9926 | and then re-expands what it has found. |
| 9927 | |
| 9928 | |
| 9929 | .vitem &*${from_utf8:*&<&'string'&>&*}*& |
| 9930 | .cindex "Unicode" |
| 9931 | .cindex "UTF-8" "conversion from" |
| 9932 | .cindex "expansion" "UTF-8 conversion" |
| 9933 | .cindex "&%from_utf8%& expansion item" |
| 9934 | The world is slowly moving towards Unicode, although there are no standards for |
| 9935 | email yet. However, other applications (including some databases) are starting |
| 9936 | to store data in Unicode, using UTF-8 encoding. This operator converts from a |
| 9937 | UTF-8 string to an ISO-8859-1 string. UTF-8 code values greater than 255 are |
| 9938 | converted to underscores. The input must be a valid UTF-8 string. If it is not, |
| 9939 | the result is an undefined sequence of bytes. |
| 9940 | |
| 9941 | Unicode code points with values less than 256 are compatible with ASCII and |
| 9942 | ISO-8859-1 (also known as Latin-1). |
| 9943 | For example, character 169 is the copyright symbol in both cases, though the |
| 9944 | way it is encoded is different. In UTF-8, more than one byte is needed for |
| 9945 | characters with code values greater than 127, whereas ISO-8859-1 is a |
| 9946 | single-byte encoding (but thereby limited to 256 characters). This makes |
| 9947 | translation from UTF-8 to ISO-8859-1 straightforward. |
| 9948 | |
| 9949 | |
| 9950 | .vitem &*${hash_*&<&'n'&>&*_*&<&'m'&>&*:*&<&'string'&>&*}*& |
| 9951 | .cindex "hash function" "textual" |
| 9952 | .cindex "expansion" "textual hash" |
| 9953 | The &%hash%& operator is a simpler interface to the hashing function that can |
| 9954 | be used when the two parameters are fixed numbers (as opposed to strings that |
| 9955 | change when expanded). The effect is the same as |
| 9956 | .code |
| 9957 | ${hash{<n>}{<m>}{<string>}} |
| 9958 | .endd |
| 9959 | See the description of the general &%hash%& item above for details. The |
| 9960 | abbreviation &%h%& can be used when &%hash%& is used as an operator. |
| 9961 | |
| 9962 | |
| 9963 | |
| 9964 | .vitem &*${hex2b64:*&<&'hexstring'&>&*}*& |
| 9965 | .cindex "base64 encoding" "conversion from hex" |
| 9966 | .cindex "expansion" "hex to base64" |
| 9967 | .cindex "&%hex2b64%& expansion item" |
| 9968 | This operator converts a hex string into one that is base64 encoded. This can |
| 9969 | be useful for processing the output of the MD5 and SHA-1 hashing functions. |
| 9970 | |
| 9971 | |
| 9972 | |
| 9973 | .vitem &*${hexquote:*&<&'string'&>&*}*& |
| 9974 | .cindex "quoting" "hex-encoded unprintable characters" |
| 9975 | .cindex "&%hexquote%& expansion item" |
| 9976 | This operator converts non-printable characters in a string into a hex |
| 9977 | escape form. Byte values between 33 (!) and 126 (~) inclusive are left |
| 9978 | as is, and other byte values are converted to &`\xNN`&, for example a |
| 9979 | byte value 127 is converted to &`\x7f`&. |
| 9980 | |
| 9981 | |
| 9982 | .vitem &*${lc:*&<&'string'&>&*}*& |
| 9983 | .cindex "case forcing in strings" |
| 9984 | .cindex "string" "case forcing" |
| 9985 | .cindex "lower casing" |
| 9986 | .cindex "expansion" "case forcing" |
| 9987 | .cindex "&%lc%& expansion item" |
| 9988 | This forces the letters in the string into lower-case, for example: |
| 9989 | .code |
| 9990 | ${lc:$local_part} |
| 9991 | .endd |
| 9992 | |
| 9993 | .vitem &*${length_*&<&'number'&>&*:*&<&'string'&>&*}*& |
| 9994 | .cindex "expansion" "string truncation" |
| 9995 | .cindex "&%length%& expansion item" |
| 9996 | The &%length%& operator is a simpler interface to the &%length%& function that |
| 9997 | can be used when the parameter is a fixed number (as opposed to a string that |
| 9998 | changes when expanded). The effect is the same as |
| 9999 | .code |
| 10000 | ${length{<number>}{<string>}} |
| 10001 | .endd |
| 10002 | See the description of the general &%length%& item above for details. Note that |
| 10003 | &%length%& is not the same as &%strlen%&. The abbreviation &%l%& can be used |
| 10004 | when &%length%& is used as an operator. |
| 10005 | |
| 10006 | |
| 10007 | .vitem &*${listcount:*&<&'string'&>&*}*& |
| 10008 | .cindex "expansion" "list item count" |
| 10009 | .cindex "list" "item count" |
| 10010 | .cindex "list" "count of items" |
| 10011 | .cindex "&%listcount%& expansion item" |
| 10012 | The string is interpreted as a list and the number of items is returned. |
| 10013 | |
| 10014 | |
| 10015 | .vitem &*${listnamed:*&<&'name'&>&*}*&&~and&~&*${listnamed_*&<&'type'&>&*:*&<&'name'&>&*}*& |
| 10016 | .cindex "expansion" "named list" |
| 10017 | .cindex "&%listnamed%& expansion item" |
| 10018 | The name is interpreted as a named list and the content of the list is returned, |
| 10019 | expanding any referenced lists, re-quoting as needed for colon-separation. |
| 10020 | If the optional type is given it must be one of "a", "d", "h" or "l" |
| 10021 | and selects address-, domain-, host- or localpart- lists to search among respectively. |
| 10022 | Otherwise all types are searched in an undefined order and the first |
| 10023 | matching list is returned. |
| 10024 | |
| 10025 | |
| 10026 | .vitem &*${local_part:*&<&'string'&>&*}*& |
| 10027 | .cindex "expansion" "local part extraction" |
| 10028 | .cindex "&%local_part%& expansion item" |
| 10029 | The string is interpreted as an RFC 2822 address and the local part is |
| 10030 | extracted from it. If the string does not parse successfully, the result is |
| 10031 | empty. |
| 10032 | |
| 10033 | |
| 10034 | .vitem &*${mask:*&<&'IP&~address'&>&*/*&<&'bit&~count'&>&*}*& |
| 10035 | .cindex "masked IP address" |
| 10036 | .cindex "IP address" "masking" |
| 10037 | .cindex "CIDR notation" |
| 10038 | .cindex "expansion" "IP address masking" |
| 10039 | .cindex "&%mask%& expansion item" |
| 10040 | If the form of the string to be operated on is not an IP address followed by a |
| 10041 | slash and an integer (that is, a network address in CIDR notation), the |
| 10042 | expansion fails. Otherwise, this operator converts the IP address to binary, |
| 10043 | masks off the least significant bits according to the bit count, and converts |
| 10044 | the result back to text, with mask appended. For example, |
| 10045 | .code |
| 10046 | ${mask:10.111.131.206/28} |
| 10047 | .endd |
| 10048 | returns the string &"10.111.131.192/28"&. Since this operation is expected to |
| 10049 | be mostly used for looking up masked addresses in files, the result for an IPv6 |
| 10050 | address uses dots to separate components instead of colons, because colon |
| 10051 | terminates a key string in lsearch files. So, for example, |
| 10052 | .code |
| 10053 | ${mask:3ffe:ffff:836f:0a00:000a:0800:200a:c031/99} |
| 10054 | .endd |
| 10055 | returns the string |
| 10056 | .code |
| 10057 | 3ffe.ffff.836f.0a00.000a.0800.2000.0000/99 |
| 10058 | .endd |
| 10059 | Letters in IPv6 addresses are always output in lower case. |
| 10060 | |
| 10061 | |
| 10062 | .vitem &*${md5:*&<&'string'&>&*}*& |
| 10063 | .cindex "MD5 hash" |
| 10064 | .cindex "expansion" "MD5 hash" |
| 10065 | .cindex "certificate fingerprint" |
| 10066 | .cindex "&%md5%& expansion item" |
| 10067 | The &%md5%& operator computes the MD5 hash value of the string, and returns it |
| 10068 | as a 32-digit hexadecimal number, in which any letters are in lower case. |
| 10069 | |
| 10070 | |
| 10071 | .vitem &*${nhash_*&<&'n'&>&*_*&<&'m'&>&*:*&<&'string'&>&*}*& |
| 10072 | .cindex "expansion" "numeric hash" |
| 10073 | .cindex "hash function" "numeric" |
| 10074 | The &%nhash%& operator is a simpler interface to the numeric hashing function |
| 10075 | that can be used when the two parameters are fixed numbers (as opposed to |
| 10076 | strings that change when expanded). The effect is the same as |
| 10077 | .code |
| 10078 | ${nhash{<n>}{<m>}{<string>}} |
| 10079 | .endd |
| 10080 | See the description of the general &%nhash%& item above for details. |
| 10081 | |
| 10082 | |
| 10083 | .vitem &*${quote:*&<&'string'&>&*}*& |
| 10084 | .cindex "quoting" "in string expansions" |
| 10085 | .cindex "expansion" "quoting" |
| 10086 | .cindex "&%quote%& expansion item" |
| 10087 | The &%quote%& operator puts its argument into double quotes if it |
| 10088 | is an empty string or |
| 10089 | contains anything other than letters, digits, underscores, dots, and hyphens. |
| 10090 | Any occurrences of double quotes and backslashes are escaped with a backslash. |
| 10091 | Newlines and carriage returns are converted to &`\n`& and &`\r`&, |
| 10092 | respectively For example, |
| 10093 | .code |
| 10094 | ${quote:ab"*"cd} |
| 10095 | .endd |
| 10096 | becomes |
| 10097 | .code |
| 10098 | "ab\"*\"cd" |
| 10099 | .endd |
| 10100 | The place where this is useful is when the argument is a substitution from a |
| 10101 | variable or a message header. |
| 10102 | |
| 10103 | .vitem &*${quote_local_part:*&<&'string'&>&*}*& |
| 10104 | .cindex "&%quote_local_part%& expansion item" |
| 10105 | This operator is like &%quote%&, except that it quotes the string only if |
| 10106 | required to do so by the rules of RFC 2822 for quoting local parts. For |
| 10107 | example, a plus sign would not cause quoting (but it would for &%quote%&). |
| 10108 | If you are creating a new email address from the contents of &$local_part$& |
| 10109 | (or any other unknown data), you should always use this operator. |
| 10110 | |
| 10111 | |
| 10112 | .vitem &*${quote_*&<&'lookup-type'&>&*:*&<&'string'&>&*}*& |
| 10113 | .cindex "quoting" "lookup-specific" |
| 10114 | This operator applies lookup-specific quoting rules to the string. Each |
| 10115 | query-style lookup type has its own quoting rules which are described with |
| 10116 | the lookups in chapter &<<CHAPfdlookup>>&. For example, |
| 10117 | .code |
| 10118 | ${quote_ldap:two * two} |
| 10119 | .endd |
| 10120 | returns |
| 10121 | .code |
| 10122 | two%20%5C2A%20two |
| 10123 | .endd |
| 10124 | For single-key lookup types, no quoting is ever necessary and this operator |
| 10125 | yields an unchanged string. |
| 10126 | |
| 10127 | |
| 10128 | .vitem &*${randint:*&<&'n'&>&*}*& |
| 10129 | .cindex "random number" |
| 10130 | This operator returns a somewhat random number which is less than the |
| 10131 | supplied number and is at least 0. The quality of this randomness depends |
| 10132 | on how Exim was built; the values are not suitable for keying material. |
| 10133 | If Exim is linked against OpenSSL then RAND_pseudo_bytes() is used. |
| 10134 | If Exim is linked against GnuTLS then gnutls_rnd(GNUTLS_RND_NONCE) is used, |
| 10135 | for versions of GnuTLS with that function. |
| 10136 | Otherwise, the implementation may be arc4random(), random() seeded by |
| 10137 | srandomdev() or srandom(), or a custom implementation even weaker than |
| 10138 | random(). |
| 10139 | |
| 10140 | |
| 10141 | .vitem &*${reverse_ip:*&<&'ipaddr'&>&*}*& |
| 10142 | .cindex "expansion" "IP address" |
| 10143 | This operator reverses an IP address; for IPv4 addresses, the result is in |
| 10144 | dotted-quad decimal form, while for IPv6 addreses the result is in |
| 10145 | dotted-nibble hexadecimal form. In both cases, this is the "natural" form |
| 10146 | for DNS. For example, |
| 10147 | .code |
| 10148 | ${reverse_ip:192.0.2.4} |
| 10149 | ${reverse_ip:2001:0db8:c42:9:1:abcd:192.0.2.127} |
| 10150 | .endd |
| 10151 | returns |
| 10152 | .code |
| 10153 | 4.2.0.192 |
| 10154 | f.7.2.0.0.0.0.c.d.c.b.a.1.0.0.0.9.0.0.0.2.4.c.0.8.b.d.0.1.0.0.2 |
| 10155 | .endd |
| 10156 | |
| 10157 | |
| 10158 | .vitem &*${rfc2047:*&<&'string'&>&*}*& |
| 10159 | .cindex "expansion" "RFC 2047" |
| 10160 | .cindex "RFC 2047" "expansion operator" |
| 10161 | .cindex "&%rfc2047%& expansion item" |
| 10162 | This operator encodes text according to the rules of RFC 2047. This is an |
| 10163 | encoding that is used in header lines to encode non-ASCII characters. It is |
| 10164 | assumed that the input string is in the encoding specified by the |
| 10165 | &%headers_charset%& option, which defaults to ISO-8859-1. If the string |
| 10166 | contains only characters in the range 33&--126, and no instances of the |
| 10167 | characters |
| 10168 | .code |
| 10169 | ? = ( ) < > @ , ; : \ " . [ ] _ |
| 10170 | .endd |
| 10171 | it is not modified. Otherwise, the result is the RFC 2047 encoding of the |
| 10172 | string, using as many &"encoded words"& as necessary to encode all the |
| 10173 | characters. |
| 10174 | |
| 10175 | |
| 10176 | .vitem &*${rfc2047d:*&<&'string'&>&*}*& |
| 10177 | .cindex "expansion" "RFC 2047" |
| 10178 | .cindex "RFC 2047" "decoding" |
| 10179 | .cindex "&%rfc2047d%& expansion item" |
| 10180 | This operator decodes strings that are encoded as per RFC 2047. Binary zero |
| 10181 | bytes are replaced by question marks. Characters are converted into the |
| 10182 | character set defined by &%headers_charset%&. Overlong RFC 2047 &"words"& are |
| 10183 | not recognized unless &%check_rfc2047_length%& is set false. |
| 10184 | |
| 10185 | &*Note*&: If you use &%$header%&_&'xxx'&&*:*& (or &%$h%&_&'xxx'&&*:*&) to |
| 10186 | access a header line, RFC 2047 decoding is done automatically. You do not need |
| 10187 | to use this operator as well. |
| 10188 | |
| 10189 | |
| 10190 | |
| 10191 | .vitem &*${rxquote:*&<&'string'&>&*}*& |
| 10192 | .cindex "quoting" "in regular expressions" |
| 10193 | .cindex "regular expressions" "quoting" |
| 10194 | .cindex "&%rxquote%& expansion item" |
| 10195 | The &%rxquote%& operator inserts a backslash before any non-alphanumeric |
| 10196 | characters in its argument. This is useful when substituting the values of |
| 10197 | variables or headers inside regular expressions. |
| 10198 | |
| 10199 | |
| 10200 | .vitem &*${sha1:*&<&'string'&>&*}*& |
| 10201 | .cindex "SHA-1 hash" |
| 10202 | .cindex "expansion" "SHA-1 hashing" |
| 10203 | .cindex "certificate fingerprint" |
| 10204 | .cindex "&%sha2%& expansion item" |
| 10205 | The &%sha1%& operator computes the SHA-1 hash value of the string, and returns |
| 10206 | it as a 40-digit hexadecimal number, in which any letters are in upper case. |
| 10207 | |
| 10208 | |
| 10209 | .vitem &*${sha256:*&<&'certificate'&>&*}*& |
| 10210 | .cindex "SHA-256 hash" |
| 10211 | .cindex "certificate fingerprint" |
| 10212 | .cindex "expansion" "SHA-256 hashing" |
| 10213 | .cindex "&%sha256%& expansion item" |
| 10214 | The &%sha256%& operator computes the SHA-256 hash fingerprint of the |
| 10215 | certificate, |
| 10216 | and returns |
| 10217 | it as a 64-digit hexadecimal number, in which any letters are in upper case. |
| 10218 | Only arguments which are a single variable of certificate type are supported. |
| 10219 | |
| 10220 | |
| 10221 | .vitem &*${stat:*&<&'string'&>&*}*& |
| 10222 | .cindex "expansion" "statting a file" |
| 10223 | .cindex "file" "extracting characteristics" |
| 10224 | .cindex "&%stat%& expansion item" |
| 10225 | The string, after expansion, must be a file path. A call to the &[stat()]& |
| 10226 | function is made for this path. If &[stat()]& fails, an error occurs and the |
| 10227 | expansion fails. If it succeeds, the data from the stat replaces the item, as a |
| 10228 | series of <&'name'&>=<&'value'&> pairs, where the values are all numerical, |
| 10229 | except for the value of &"smode"&. The names are: &"mode"& (giving the mode as |
| 10230 | a 4-digit octal number), &"smode"& (giving the mode in symbolic format as a |
| 10231 | 10-character string, as for the &'ls'& command), &"inode"&, &"device"&, |
| 10232 | &"links"&, &"uid"&, &"gid"&, &"size"&, &"atime"&, &"mtime"&, and &"ctime"&. You |
| 10233 | can extract individual fields using the &%extract%& expansion item. |
| 10234 | |
| 10235 | The use of the &%stat%& expansion in users' filter files can be locked out by |
| 10236 | the system administrator. &*Warning*&: The file size may be incorrect on 32-bit |
| 10237 | systems for files larger than 2GB. |
| 10238 | |
| 10239 | .vitem &*${str2b64:*&<&'string'&>&*}*& |
| 10240 | .cindex "expansion" "base64 encoding" |
| 10241 | .cindex "base64 encoding" "in string expansion" |
| 10242 | .cindex "&%str2b64%& expansion item" |
| 10243 | This operator converts a string into one that is base64 encoded. |
| 10244 | |
| 10245 | |
| 10246 | |
| 10247 | .vitem &*${strlen:*&<&'string'&>&*}*& |
| 10248 | .cindex "expansion" "string length" |
| 10249 | .cindex "string" "length in expansion" |
| 10250 | .cindex "&%strlen%& expansion item" |
| 10251 | The item is replace by the length of the expanded string, expressed as a |
| 10252 | decimal number. &*Note*&: Do not confuse &%strlen%& with &%length%&. |
| 10253 | |
| 10254 | |
| 10255 | .vitem &*${substr_*&<&'start'&>&*_*&<&'length'&>&*:*&<&'string'&>&*}*& |
| 10256 | .cindex "&%substr%& expansion item" |
| 10257 | .cindex "substring extraction" |
| 10258 | .cindex "expansion" "substring expansion" |
| 10259 | The &%substr%& operator is a simpler interface to the &%substr%& function that |
| 10260 | can be used when the two parameters are fixed numbers (as opposed to strings |
| 10261 | that change when expanded). The effect is the same as |
| 10262 | .code |
| 10263 | ${substr{<start>}{<length>}{<string>}} |
| 10264 | .endd |
| 10265 | See the description of the general &%substr%& item above for details. The |
| 10266 | abbreviation &%s%& can be used when &%substr%& is used as an operator. |
| 10267 | |
| 10268 | .vitem &*${time_eval:*&<&'string'&>&*}*& |
| 10269 | .cindex "&%time_eval%& expansion item" |
| 10270 | .cindex "time interval" "decoding" |
| 10271 | This item converts an Exim time interval such as &`2d4h5m`& into a number of |
| 10272 | seconds. |
| 10273 | |
| 10274 | .vitem &*${time_interval:*&<&'string'&>&*}*& |
| 10275 | .cindex "&%time_interval%& expansion item" |
| 10276 | .cindex "time interval" "formatting" |
| 10277 | The argument (after sub-expansion) must be a sequence of decimal digits that |
| 10278 | represents an interval of time as a number of seconds. It is converted into a |
| 10279 | number of larger units and output in Exim's normal time format, for example, |
| 10280 | &`1w3d4h2m6s`&. |
| 10281 | |
| 10282 | .vitem &*${uc:*&<&'string'&>&*}*& |
| 10283 | .cindex "case forcing in strings" |
| 10284 | .cindex "string" "case forcing" |
| 10285 | .cindex "upper casing" |
| 10286 | .cindex "expansion" "case forcing" |
| 10287 | .cindex "&%uc%& expansion item" |
| 10288 | This forces the letters in the string into upper-case. |
| 10289 | |
| 10290 | .vitem &*${utf8clean:*&<&'string'&>&*}*& |
| 10291 | .cindex "correction of invalid utf-8 sequences in strings" |
| 10292 | .cindex "utf-8" "utf-8 sequences" |
| 10293 | .cindex "incorrect utf-8" |
| 10294 | .cindex "expansion" "utf-8 forcing" |
| 10295 | .cindex "&%utf8clean%& expansion item" |
| 10296 | This replaces any invalid utf-8 sequence in the string by the character &`?`&. |
| 10297 | .endlist |
| 10298 | |
| 10299 | |
| 10300 | |
| 10301 | |
| 10302 | |
| 10303 | |
| 10304 | .section "Expansion conditions" "SECTexpcond" |
| 10305 | .scindex IIDexpcond "expansion" "conditions" |
| 10306 | The following conditions are available for testing by the &%${if%& construct |
| 10307 | while expanding strings: |
| 10308 | |
| 10309 | .vlist |
| 10310 | .vitem &*!*&<&'condition'&> |
| 10311 | .cindex "expansion" "negating a condition" |
| 10312 | .cindex "negation" "in expansion condition" |
| 10313 | Preceding any condition with an exclamation mark negates the result of the |
| 10314 | condition. |
| 10315 | |
| 10316 | .vitem <&'symbolic&~operator'&>&~&*{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
| 10317 | .cindex "numeric comparison" |
| 10318 | .cindex "expansion" "numeric comparison" |
| 10319 | There are a number of symbolic operators for doing numeric comparisons. They |
| 10320 | are: |
| 10321 | .display |
| 10322 | &`= `& equal |
| 10323 | &`== `& equal |
| 10324 | &`> `& greater |
| 10325 | &`>= `& greater or equal |
| 10326 | &`< `& less |
| 10327 | &`<= `& less or equal |
| 10328 | .endd |
| 10329 | For example: |
| 10330 | .code |
| 10331 | ${if >{$message_size}{10M} ... |
| 10332 | .endd |
| 10333 | Note that the general negation operator provides for inequality testing. The |
| 10334 | two strings must take the form of optionally signed decimal integers, |
| 10335 | optionally followed by one of the letters &"K"&, &"M"& or &"G"& (in either upper or |
| 10336 | lower case), signifying multiplication by 1024, 1024*1024 or 1024*1024*1024, respectively. |
| 10337 | As a special case, the numerical value of an empty string is taken as |
| 10338 | zero. |
| 10339 | |
| 10340 | In all cases, a relative comparator OP is testing if <&'string1'&> OP |
| 10341 | <&'string2'&>; the above example is checking if &$message_size$& is larger than |
| 10342 | 10M, not if 10M is larger than &$message_size$&. |
| 10343 | |
| 10344 | |
| 10345 | .vitem &*acl&~{{*&<&'name'&>&*}{*&<&'arg1'&>&*}&&& |
| 10346 | {*&<&'arg2'&>&*}...}*& |
| 10347 | .cindex "expansion" "calling an acl" |
| 10348 | .cindex "&%acl%&" "expansion condition" |
| 10349 | The name and zero to nine argument strings are first expanded separately. The expanded |
| 10350 | arguments are assigned to the variables &$acl_arg1$& to &$acl_arg9$& in order. |
| 10351 | Any unused are made empty. The variable &$acl_narg$& is set to the number of |
| 10352 | arguments. The named ACL (see chapter &<<CHAPACL>>&) is called |
| 10353 | and may use the variables; if another acl expansion is used the values |
| 10354 | are restored after it returns. If the ACL sets |
| 10355 | a value using a "message =" modifier the variable $value becomes |
| 10356 | the result of the expansion, otherwise it is empty. |
| 10357 | If the ACL returns accept the condition is true; if deny, false. |
| 10358 | If the ACL returns defer the result is a forced-fail. |
| 10359 | |
| 10360 | .vitem &*bool&~{*&<&'string'&>&*}*& |
| 10361 | .cindex "expansion" "boolean parsing" |
| 10362 | .cindex "&%bool%& expansion condition" |
| 10363 | This condition turns a string holding a true or false representation into |
| 10364 | a boolean state. It parses &"true"&, &"false"&, &"yes"& and &"no"& |
| 10365 | (case-insensitively); also integer numbers map to true if non-zero, |
| 10366 | false if zero. |
| 10367 | An empty string is treated as false. |
| 10368 | Leading and trailing whitespace is ignored; |
| 10369 | thus a string consisting only of whitespace is false. |
| 10370 | All other string values will result in expansion failure. |
| 10371 | |
| 10372 | When combined with ACL variables, this expansion condition will let you |
| 10373 | make decisions in one place and act on those decisions in another place. |
| 10374 | For example: |
| 10375 | .code |
| 10376 | ${if bool{$acl_m_privileged_sender} ... |
| 10377 | .endd |
| 10378 | |
| 10379 | |
| 10380 | .vitem &*bool_lax&~{*&<&'string'&>&*}*& |
| 10381 | .cindex "expansion" "boolean parsing" |
| 10382 | .cindex "&%bool_lax%& expansion condition" |
| 10383 | Like &%bool%&, this condition turns a string into a boolean state. But |
| 10384 | where &%bool%& accepts a strict set of strings, &%bool_lax%& uses the same |
| 10385 | loose definition that the Router &%condition%& option uses. The empty string |
| 10386 | and the values &"false"&, &"no"& and &"0"& map to false, all others map to |
| 10387 | true. Leading and trailing whitespace is ignored. |
| 10388 | |
| 10389 | Note that where &"bool{00}"& is false, &"bool_lax{00}"& is true. |
| 10390 | |
| 10391 | .vitem &*crypteq&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
| 10392 | .cindex "expansion" "encrypted comparison" |
| 10393 | .cindex "encrypted strings, comparing" |
| 10394 | .cindex "&%crypteq%& expansion condition" |
| 10395 | This condition is included in the Exim binary if it is built to support any |
| 10396 | authentication mechanisms (see chapter &<<CHAPSMTPAUTH>>&). Otherwise, it is |
| 10397 | necessary to define SUPPORT_CRYPTEQ in &_Local/Makefile_& to get &%crypteq%& |
| 10398 | included in the binary. |
| 10399 | |
| 10400 | The &%crypteq%& condition has two arguments. The first is encrypted and |
| 10401 | compared against the second, which is already encrypted. The second string may |
| 10402 | be in the LDAP form for storing encrypted strings, which starts with the |
| 10403 | encryption type in curly brackets, followed by the data. If the second string |
| 10404 | does not begin with &"{"& it is assumed to be encrypted with &[crypt()]& or |
| 10405 | &[crypt16()]& (see below), since such strings cannot begin with &"{"&. |
| 10406 | Typically this will be a field from a password file. An example of an encrypted |
| 10407 | string in LDAP form is: |
| 10408 | .code |
| 10409 | {md5}CY9rzUYh03PK3k6DJie09g== |
| 10410 | .endd |
| 10411 | If such a string appears directly in an expansion, the curly brackets have to |
| 10412 | be quoted, because they are part of the expansion syntax. For example: |
| 10413 | .code |
| 10414 | ${if crypteq {test}{\{md5\}CY9rzUYh03PK3k6DJie09g==}{yes}{no}} |
| 10415 | .endd |
| 10416 | The following encryption types (whose names are matched case-independently) are |
| 10417 | supported: |
| 10418 | |
| 10419 | .ilist |
| 10420 | .cindex "MD5 hash" |
| 10421 | .cindex "base64 encoding" "in encrypted password" |
| 10422 | &%{md5}%& computes the MD5 digest of the first string, and expresses this as |
| 10423 | printable characters to compare with the remainder of the second string. If the |
| 10424 | length of the comparison string is 24, Exim assumes that it is base64 encoded |
| 10425 | (as in the above example). If the length is 32, Exim assumes that it is a |
| 10426 | hexadecimal encoding of the MD5 digest. If the length not 24 or 32, the |
| 10427 | comparison fails. |
| 10428 | |
| 10429 | .next |
| 10430 | .cindex "SHA-1 hash" |
| 10431 | &%{sha1}%& computes the SHA-1 digest of the first string, and expresses this as |
| 10432 | printable characters to compare with the remainder of the second string. If the |
| 10433 | length of the comparison string is 28, Exim assumes that it is base64 encoded. |
| 10434 | If the length is 40, Exim assumes that it is a hexadecimal encoding of the |
| 10435 | SHA-1 digest. If the length is not 28 or 40, the comparison fails. |
| 10436 | |
| 10437 | .next |
| 10438 | .cindex "&[crypt()]&" |
| 10439 | &%{crypt}%& calls the &[crypt()]& function, which traditionally used to use |
| 10440 | only the first eight characters of the password. However, in modern operating |
| 10441 | systems this is no longer true, and in many cases the entire password is used, |
| 10442 | whatever its length. |
| 10443 | |
| 10444 | .next |
| 10445 | .cindex "&[crypt16()]&" |
| 10446 | &%{crypt16}%& calls the &[crypt16()]& function, which was originally created to |
| 10447 | use up to 16 characters of the password in some operating systems. Again, in |
| 10448 | modern operating systems, more characters may be used. |
| 10449 | .endlist |
| 10450 | Exim has its own version of &[crypt16()]&, which is just a double call to |
| 10451 | &[crypt()]&. For operating systems that have their own version, setting |
| 10452 | HAVE_CRYPT16 in &_Local/Makefile_& when building Exim causes it to use the |
| 10453 | operating system version instead of its own. This option is set by default in |
| 10454 | the OS-dependent &_Makefile_& for those operating systems that are known to |
| 10455 | support &[crypt16()]&. |
| 10456 | |
| 10457 | Some years after Exim's &[crypt16()]& was implemented, a user discovered that |
| 10458 | it was not using the same algorithm as some operating systems' versions. It |
| 10459 | turns out that as well as &[crypt16()]& there is a function called |
| 10460 | &[bigcrypt()]& in some operating systems. This may or may not use the same |
| 10461 | algorithm, and both of them may be different to Exim's built-in &[crypt16()]&. |
| 10462 | |
| 10463 | However, since there is now a move away from the traditional &[crypt()]& |
| 10464 | functions towards using SHA1 and other algorithms, tidying up this area of |
| 10465 | Exim is seen as very low priority. |
| 10466 | |
| 10467 | If you do not put a encryption type (in curly brackets) in a &%crypteq%& |
| 10468 | comparison, the default is usually either &`{crypt}`& or &`{crypt16}`&, as |
| 10469 | determined by the setting of DEFAULT_CRYPT in &_Local/Makefile_&. The default |
| 10470 | default is &`{crypt}`&. Whatever the default, you can always use either |
| 10471 | function by specifying it explicitly in curly brackets. |
| 10472 | |
| 10473 | .vitem &*def:*&<&'variable&~name'&> |
| 10474 | .cindex "expansion" "checking for empty variable" |
| 10475 | .cindex "&%def%& expansion condition" |
| 10476 | The &%def%& condition must be followed by the name of one of the expansion |
| 10477 | variables defined in section &<<SECTexpvar>>&. The condition is true if the |
| 10478 | variable does not contain the empty string. For example: |
| 10479 | .code |
| 10480 | ${if def:sender_ident {from $sender_ident}} |
| 10481 | .endd |
| 10482 | Note that the variable name is given without a leading &%$%& character. If the |
| 10483 | variable does not exist, the expansion fails. |
| 10484 | |
| 10485 | .vitem "&*def:header_*&<&'header&~name'&>&*:*&&~&~or&~&&& |
| 10486 | &~&*def:h_*&<&'header&~name'&>&*:*&" |
| 10487 | .cindex "expansion" "checking header line existence" |
| 10488 | This condition is true if a message is being processed and the named header |
| 10489 | exists in the message. For example, |
| 10490 | .code |
| 10491 | ${if def:header_reply-to:{$h_reply-to:}{$h_from:}} |
| 10492 | .endd |
| 10493 | &*Note*&: No &%$%& appears before &%header_%& or &%h_%& in the condition, and |
| 10494 | the header name must be terminated by a colon if white space does not follow. |
| 10495 | |
| 10496 | .vitem &*eq&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&& |
| 10497 | &*eqi&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
| 10498 | .cindex "string" "comparison" |
| 10499 | .cindex "expansion" "string comparison" |
| 10500 | .cindex "&%eq%& expansion condition" |
| 10501 | .cindex "&%eqi%& expansion condition" |
| 10502 | The two substrings are first expanded. The condition is true if the two |
| 10503 | resulting strings are identical. For &%eq%& the comparison includes the case of |
| 10504 | letters, whereas for &%eqi%& the comparison is case-independent. |
| 10505 | |
| 10506 | .vitem &*exists&~{*&<&'file&~name'&>&*}*& |
| 10507 | .cindex "expansion" "file existence test" |
| 10508 | .cindex "file" "existence test" |
| 10509 | .cindex "&%exists%&, expansion condition" |
| 10510 | The substring is first expanded and then interpreted as an absolute path. The |
| 10511 | condition is true if the named file (or directory) exists. The existence test |
| 10512 | is done by calling the &[stat()]& function. The use of the &%exists%& test in |
| 10513 | users' filter files may be locked out by the system administrator. |
| 10514 | |
| 10515 | .vitem &*first_delivery*& |
| 10516 | .cindex "delivery" "first" |
| 10517 | .cindex "first delivery" |
| 10518 | .cindex "expansion" "first delivery test" |
| 10519 | .cindex "&%first_delivery%& expansion condition" |
| 10520 | This condition, which has no data, is true during a message's first delivery |
| 10521 | attempt. It is false during any subsequent delivery attempts. |
| 10522 | |
| 10523 | |
| 10524 | .vitem "&*forall{*&<&'a list'&>&*}{*&<&'a condition'&>&*}*&" &&& |
| 10525 | "&*forany{*&<&'a list'&>&*}{*&<&'a condition'&>&*}*&" |
| 10526 | .cindex "list" "iterative conditions" |
| 10527 | .cindex "expansion" "&*forall*& condition" |
| 10528 | .cindex "expansion" "&*forany*& condition" |
| 10529 | .vindex "&$item$&" |
| 10530 | These conditions iterate over a list. The first argument is expanded to form |
| 10531 | the list. By default, the list separator is a colon, but it can be changed by |
| 10532 | the normal method. The second argument is interpreted as a condition that is to |
| 10533 | be applied to each item in the list in turn. During the interpretation of the |
| 10534 | condition, the current list item is placed in a variable called &$item$&. |
| 10535 | .ilist |
| 10536 | For &*forany*&, interpretation stops if the condition is true for any item, and |
| 10537 | the result of the whole condition is true. If the condition is false for all |
| 10538 | items in the list, the overall condition is false. |
| 10539 | .next |
| 10540 | For &*forall*&, interpretation stops if the condition is false for any item, |
| 10541 | and the result of the whole condition is false. If the condition is true for |
| 10542 | all items in the list, the overall condition is true. |
| 10543 | .endlist |
| 10544 | Note that negation of &*forany*& means that the condition must be false for all |
| 10545 | items for the overall condition to succeed, and negation of &*forall*& means |
| 10546 | that the condition must be false for at least one item. In this example, the |
| 10547 | list separator is changed to a comma: |
| 10548 | .code |
| 10549 | ${if forany{<, $recipients}{match{$item}{^user3@}}{yes}{no}} |
| 10550 | .endd |
| 10551 | The value of &$item$& is saved and restored while &*forany*& or &*forall*& is |
| 10552 | being processed, to enable these expansion items to be nested. |
| 10553 | |
| 10554 | To scan a named list, expand it with the &*listnamed*& operator. |
| 10555 | |
| 10556 | |
| 10557 | .vitem &*ge&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&& |
| 10558 | &*gei&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
| 10559 | .cindex "string" "comparison" |
| 10560 | .cindex "expansion" "string comparison" |
| 10561 | .cindex "&%ge%& expansion condition" |
| 10562 | .cindex "&%gei%& expansion condition" |
| 10563 | The two substrings are first expanded. The condition is true if the first |
| 10564 | string is lexically greater than or equal to the second string. For &%ge%& the |
| 10565 | comparison includes the case of letters, whereas for &%gei%& the comparison is |
| 10566 | case-independent. |
| 10567 | |
| 10568 | .vitem &*gt&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&& |
| 10569 | &*gti&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
| 10570 | .cindex "string" "comparison" |
| 10571 | .cindex "expansion" "string comparison" |
| 10572 | .cindex "&%gt%& expansion condition" |
| 10573 | .cindex "&%gti%& expansion condition" |
| 10574 | The two substrings are first expanded. The condition is true if the first |
| 10575 | string is lexically greater than the second string. For &%gt%& the comparison |
| 10576 | includes the case of letters, whereas for &%gti%& the comparison is |
| 10577 | case-independent. |
| 10578 | |
| 10579 | .vitem &*inlist&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&& |
| 10580 | &*inlisti&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
| 10581 | .cindex "string" "comparison" |
| 10582 | .cindex "list" "iterative conditions" |
| 10583 | Both strings are expanded; the second string is treated as a list of simple |
| 10584 | strings; if the first string is a member of the second, then the condition |
| 10585 | is true. |
| 10586 | |
| 10587 | These are simpler to use versions of the more powerful &*forany*& condition. |
| 10588 | Examples, and the &*forany*& equivalents: |
| 10589 | .code |
| 10590 | ${if inlist{needle}{foo:needle:bar}} |
| 10591 | ${if forany{foo:needle:bar}{eq{$item}{needle}}} |
| 10592 | ${if inlisti{Needle}{fOo:NeeDLE:bAr}} |
| 10593 | ${if forany{fOo:NeeDLE:bAr}{eqi{$item}{Needle}}} |
| 10594 | .endd |
| 10595 | |
| 10596 | .vitem &*isip&~{*&<&'string'&>&*}*& &&& |
| 10597 | &*isip4&~{*&<&'string'&>&*}*& &&& |
| 10598 | &*isip6&~{*&<&'string'&>&*}*& |
| 10599 | .cindex "IP address" "testing string format" |
| 10600 | .cindex "string" "testing for IP address" |
| 10601 | .cindex "&%isip%& expansion condition" |
| 10602 | .cindex "&%isip4%& expansion condition" |
| 10603 | .cindex "&%isip6%& expansion condition" |
| 10604 | The substring is first expanded, and then tested to see if it has the form of |
| 10605 | an IP address. Both IPv4 and IPv6 addresses are valid for &%isip%&, whereas |
| 10606 | &%isip4%& and &%isip6%& test specifically for IPv4 or IPv6 addresses. |
| 10607 | |
| 10608 | For an IPv4 address, the test is for four dot-separated components, each of |
| 10609 | which consists of from one to three digits. For an IPv6 address, up to eight |
| 10610 | colon-separated components are permitted, each containing from one to four |
| 10611 | hexadecimal digits. There may be fewer than eight components if an empty |
| 10612 | component (adjacent colons) is present. Only one empty component is permitted. |
| 10613 | |
| 10614 | &*Note*&: The checks are just on the form of the address; actual numerical |
| 10615 | values are not considered. Thus, for example, 999.999.999.999 passes the IPv4 |
| 10616 | check. The main use of these tests is to distinguish between IP addresses and |
| 10617 | host names, or between IPv4 and IPv6 addresses. For example, you could use |
| 10618 | .code |
| 10619 | ${if isip4{$sender_host_address}... |
| 10620 | .endd |
| 10621 | to test which IP version an incoming SMTP connection is using. |
| 10622 | |
| 10623 | .vitem &*ldapauth&~{*&<&'ldap&~query'&>&*}*& |
| 10624 | .cindex "LDAP" "use for authentication" |
| 10625 | .cindex "expansion" "LDAP authentication test" |
| 10626 | .cindex "&%ldapauth%& expansion condition" |
| 10627 | This condition supports user authentication using LDAP. See section |
| 10628 | &<<SECTldap>>& for details of how to use LDAP in lookups and the syntax of |
| 10629 | queries. For this use, the query must contain a user name and password. The |
| 10630 | query itself is not used, and can be empty. The condition is true if the |
| 10631 | password is not empty, and the user name and password are accepted by the LDAP |
| 10632 | server. An empty password is rejected without calling LDAP because LDAP binds |
| 10633 | with an empty password are considered anonymous regardless of the username, and |
| 10634 | will succeed in most configurations. See chapter &<<CHAPSMTPAUTH>>& for details |
| 10635 | of SMTP authentication, and chapter &<<CHAPplaintext>>& for an example of how |
| 10636 | this can be used. |
| 10637 | |
| 10638 | |
| 10639 | .vitem &*le&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&& |
| 10640 | &*lei&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
| 10641 | .cindex "string" "comparison" |
| 10642 | .cindex "expansion" "string comparison" |
| 10643 | .cindex "&%le%& expansion condition" |
| 10644 | .cindex "&%lei%& expansion condition" |
| 10645 | The two substrings are first expanded. The condition is true if the first |
| 10646 | string is lexically less than or equal to the second string. For &%le%& the |
| 10647 | comparison includes the case of letters, whereas for &%lei%& the comparison is |
| 10648 | case-independent. |
| 10649 | |
| 10650 | .vitem &*lt&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&& |
| 10651 | &*lti&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
| 10652 | .cindex "string" "comparison" |
| 10653 | .cindex "expansion" "string comparison" |
| 10654 | .cindex "&%lt%& expansion condition" |
| 10655 | .cindex "&%lti%& expansion condition" |
| 10656 | The two substrings are first expanded. The condition is true if the first |
| 10657 | string is lexically less than the second string. For &%lt%& the comparison |
| 10658 | includes the case of letters, whereas for &%lti%& the comparison is |
| 10659 | case-independent. |
| 10660 | |
| 10661 | |
| 10662 | .vitem &*match&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
| 10663 | .cindex "expansion" "regular expression comparison" |
| 10664 | .cindex "regular expressions" "match in expanded string" |
| 10665 | .cindex "&%match%& expansion condition" |
| 10666 | The two substrings are first expanded. The second is then treated as a regular |
| 10667 | expression and applied to the first. Because of the pre-expansion, if the |
| 10668 | regular expression contains dollar, or backslash characters, they must be |
| 10669 | escaped. Care must also be taken if the regular expression contains braces |
| 10670 | (curly brackets). A closing brace must be escaped so that it is not taken as a |
| 10671 | premature termination of <&'string2'&>. The easiest approach is to use the |
| 10672 | &`\N`& feature to disable expansion of the regular expression. |
| 10673 | For example, |
| 10674 | .code |
| 10675 | ${if match {$local_part}{\N^\d{3}\N} ... |
| 10676 | .endd |
| 10677 | If the whole expansion string is in double quotes, further escaping of |
| 10678 | backslashes is also required. |
| 10679 | |
| 10680 | The condition is true if the regular expression match succeeds. |
| 10681 | The regular expression is not required to begin with a circumflex |
| 10682 | metacharacter, but if there is no circumflex, the expression is not anchored, |
| 10683 | and it may match anywhere in the subject, not just at the start. If you want |
| 10684 | the pattern to match at the end of the subject, you must include the &`$`& |
| 10685 | metacharacter at an appropriate point. |
| 10686 | |
| 10687 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &%if%& expansion" |
| 10688 | At the start of an &%if%& expansion the values of the numeric variable |
| 10689 | substitutions &$1$& etc. are remembered. Obeying a &%match%& condition that |
| 10690 | succeeds causes them to be reset to the substrings of that condition and they |
| 10691 | will have these values during the expansion of the success string. At the end |
| 10692 | of the &%if%& expansion, the previous values are restored. After testing a |
| 10693 | combination of conditions using &%or%&, the subsequent values of the numeric |
| 10694 | variables are those of the condition that succeeded. |
| 10695 | |
| 10696 | .vitem &*match_address&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
| 10697 | .cindex "&%match_address%& expansion condition" |
| 10698 | See &*match_local_part*&. |
| 10699 | |
| 10700 | .vitem &*match_domain&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
| 10701 | .cindex "&%match_domain%& expansion condition" |
| 10702 | See &*match_local_part*&. |
| 10703 | |
| 10704 | .vitem &*match_ip&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
| 10705 | .cindex "&%match_ip%& expansion condition" |
| 10706 | This condition matches an IP address to a list of IP address patterns. It must |
| 10707 | be followed by two argument strings. The first (after expansion) must be an IP |
| 10708 | address or an empty string. The second (not expanded) is a restricted host |
| 10709 | list that can match only an IP address, not a host name. For example: |
| 10710 | .code |
| 10711 | ${if match_ip{$sender_host_address}{1.2.3.4:5.6.7.8}{...}{...}} |
| 10712 | .endd |
| 10713 | The specific types of host list item that are permitted in the list are: |
| 10714 | |
| 10715 | .ilist |
| 10716 | An IP address, optionally with a CIDR mask. |
| 10717 | .next |
| 10718 | A single asterisk, which matches any IP address. |
| 10719 | .next |
| 10720 | An empty item, which matches only if the IP address is empty. This could be |
| 10721 | useful for testing for a locally submitted message or one from specific hosts |
| 10722 | in a single test such as |
| 10723 | . ==== As this is a nested list, any displays it contains must be indented |
| 10724 | . ==== as otherwise they are too far to the left. This comment applies to |
| 10725 | . ==== the use of xmlto plus fop. There's no problem when formatting with |
| 10726 | . ==== sdop, with or without the extra indent. |
| 10727 | .code |
| 10728 | ${if match_ip{$sender_host_address}{:4.3.2.1:...}{...}{...}} |
| 10729 | .endd |
| 10730 | where the first item in the list is the empty string. |
| 10731 | .next |
| 10732 | The item @[] matches any of the local host's interface addresses. |
| 10733 | .next |
| 10734 | Single-key lookups are assumed to be like &"net-"& style lookups in host lists, |
| 10735 | even if &`net-`& is not specified. There is never any attempt to turn the IP |
| 10736 | address into a host name. The most common type of linear search for |
| 10737 | &*match_ip*& is likely to be &*iplsearch*&, in which the file can contain CIDR |
| 10738 | masks. For example: |
| 10739 | .code |
| 10740 | ${if match_ip{$sender_host_address}{iplsearch;/some/file}... |
| 10741 | .endd |
| 10742 | It is of course possible to use other kinds of lookup, and in such a case, you |
| 10743 | do need to specify the &`net-`& prefix if you want to specify a specific |
| 10744 | address mask, for example: |
| 10745 | .code |
| 10746 | ${if match_ip{$sender_host_address}{net24-dbm;/some/file}... |
| 10747 | .endd |
| 10748 | However, unless you are combining a &%match_ip%& condition with others, it is |
| 10749 | just as easy to use the fact that a lookup is itself a condition, and write: |
| 10750 | .code |
| 10751 | ${lookup{${mask:$sender_host_address/24}}dbm{/a/file}... |
| 10752 | .endd |
| 10753 | .endlist ilist |
| 10754 | |
| 10755 | Note that <&'string2'&> is not itself subject to string expansion, unless |
| 10756 | Exim was built with the EXPAND_LISTMATCH_RHS option. |
| 10757 | |
| 10758 | Consult section &<<SECThoslispatip>>& for further details of these patterns. |
| 10759 | |
| 10760 | .vitem &*match_local_part&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
| 10761 | .cindex "domain list" "in expansion condition" |
| 10762 | .cindex "address list" "in expansion condition" |
| 10763 | .cindex "local part" "list, in expansion condition" |
| 10764 | .cindex "&%match_local_part%& expansion condition" |
| 10765 | This condition, together with &%match_address%& and &%match_domain%&, make it |
| 10766 | possible to test domain, address, and local part lists within expansions. Each |
| 10767 | condition requires two arguments: an item and a list to match. A trivial |
| 10768 | example is: |
| 10769 | .code |
| 10770 | ${if match_domain{a.b.c}{x.y.z:a.b.c:p.q.r}{yes}{no}} |
| 10771 | .endd |
| 10772 | In each case, the second argument may contain any of the allowable items for a |
| 10773 | list of the appropriate type. Also, because the second argument (after |
| 10774 | expansion) is a standard form of list, it is possible to refer to a named list. |
| 10775 | Thus, you can use conditions like this: |
| 10776 | .code |
| 10777 | ${if match_domain{$domain}{+local_domains}{... |
| 10778 | .endd |
| 10779 | .cindex "&`+caseful`&" |
| 10780 | For address lists, the matching starts off caselessly, but the &`+caseful`& |
| 10781 | item can be used, as in all address lists, to cause subsequent items to |
| 10782 | have their local parts matched casefully. Domains are always matched |
| 10783 | caselessly. |
| 10784 | |
| 10785 | Note that <&'string2'&> is not itself subject to string expansion, unless |
| 10786 | Exim was built with the EXPAND_LISTMATCH_RHS option. |
| 10787 | |
| 10788 | &*Note*&: Host lists are &'not'& supported in this way. This is because |
| 10789 | hosts have two identities: a name and an IP address, and it is not clear |
| 10790 | how to specify cleanly how such a test would work. However, IP addresses can be |
| 10791 | matched using &%match_ip%&. |
| 10792 | |
| 10793 | .vitem &*pam&~{*&<&'string1'&>&*:*&<&'string2'&>&*:...}*& |
| 10794 | .cindex "PAM authentication" |
| 10795 | .cindex "AUTH" "with PAM" |
| 10796 | .cindex "Solaris" "PAM support" |
| 10797 | .cindex "expansion" "PAM authentication test" |
| 10798 | .cindex "&%pam%& expansion condition" |
| 10799 | &'Pluggable Authentication Modules'& |
| 10800 | (&url(http://www.kernel.org/pub/linux/libs/pam/)) are a facility that is |
| 10801 | available in the latest releases of Solaris and in some GNU/Linux |
| 10802 | distributions. The Exim support, which is intended for use in conjunction with |
| 10803 | the SMTP AUTH command, is available only if Exim is compiled with |
| 10804 | .code |
| 10805 | SUPPORT_PAM=yes |
| 10806 | .endd |
| 10807 | in &_Local/Makefile_&. You probably need to add &%-lpam%& to EXTRALIBS, and |
| 10808 | in some releases of GNU/Linux &%-ldl%& is also needed. |
| 10809 | |
| 10810 | The argument string is first expanded, and the result must be a |
| 10811 | colon-separated list of strings. Leading and trailing white space is ignored. |
| 10812 | The PAM module is initialized with the service name &"exim"& and the user name |
| 10813 | taken from the first item in the colon-separated data string (<&'string1'&>). |
| 10814 | The remaining items in the data string are passed over in response to requests |
| 10815 | from the authentication function. In the simple case there will only be one |
| 10816 | request, for a password, so the data consists of just two strings. |
| 10817 | |
| 10818 | There can be problems if any of the strings are permitted to contain colon |
| 10819 | characters. In the usual way, these have to be doubled to avoid being taken as |
| 10820 | separators. If the data is being inserted from a variable, the &%sg%& expansion |
| 10821 | item can be used to double any existing colons. For example, the configuration |
| 10822 | of a LOGIN authenticator might contain this setting: |
| 10823 | .code |
| 10824 | server_condition = ${if pam{$auth1:${sg{$auth2}{:}{::}}}} |
| 10825 | .endd |
| 10826 | For a PLAIN authenticator you could use: |
| 10827 | .code |
| 10828 | server_condition = ${if pam{$auth2:${sg{$auth3}{:}{::}}}} |
| 10829 | .endd |
| 10830 | In some operating systems, PAM authentication can be done only from a process |
| 10831 | running as root. Since Exim is running as the Exim user when receiving |
| 10832 | messages, this means that PAM cannot be used directly in those systems. |
| 10833 | A patched version of the &'pam_unix'& module that comes with the |
| 10834 | Linux PAM package is available from &url(http://www.e-admin.de/pam_exim/). |
| 10835 | The patched module allows one special uid/gid combination, in addition to root, |
| 10836 | to authenticate. If you build the patched module to allow the Exim user and |
| 10837 | group, PAM can then be used from an Exim authenticator. |
| 10838 | |
| 10839 | |
| 10840 | .vitem &*pwcheck&~{*&<&'string1'&>&*:*&<&'string2'&>&*}*& |
| 10841 | .cindex "&'pwcheck'& daemon" |
| 10842 | .cindex "Cyrus" |
| 10843 | .cindex "expansion" "&'pwcheck'& authentication test" |
| 10844 | .cindex "&%pwcheck%& expansion condition" |
| 10845 | This condition supports user authentication using the Cyrus &'pwcheck'& daemon. |
| 10846 | This is one way of making it possible for passwords to be checked by a process |
| 10847 | that is not running as root. &*Note*&: The use of &'pwcheck'& is now |
| 10848 | deprecated. Its replacement is &'saslauthd'& (see below). |
| 10849 | |
| 10850 | The pwcheck support is not included in Exim by default. You need to specify |
| 10851 | the location of the pwcheck daemon's socket in &_Local/Makefile_& before |
| 10852 | building Exim. For example: |
| 10853 | .code |
| 10854 | CYRUS_PWCHECK_SOCKET=/var/pwcheck/pwcheck |
| 10855 | .endd |
| 10856 | You do not need to install the full Cyrus software suite in order to use |
| 10857 | the pwcheck daemon. You can compile and install just the daemon alone |
| 10858 | from the Cyrus SASL library. Ensure that &'exim'& is the only user that has |
| 10859 | access to the &_/var/pwcheck_& directory. |
| 10860 | |
| 10861 | The &%pwcheck%& condition takes one argument, which must be the user name and |
| 10862 | password, separated by a colon. For example, in a LOGIN authenticator |
| 10863 | configuration, you might have this: |
| 10864 | .code |
| 10865 | server_condition = ${if pwcheck{$auth1:$auth2}} |
| 10866 | .endd |
| 10867 | Again, for a PLAIN authenticator configuration, this would be: |
| 10868 | .code |
| 10869 | server_condition = ${if pwcheck{$auth2:$auth3}} |
| 10870 | .endd |
| 10871 | .vitem &*queue_running*& |
| 10872 | .cindex "queue runner" "detecting when delivering from" |
| 10873 | .cindex "expansion" "queue runner test" |
| 10874 | .cindex "&%queue_running%& expansion condition" |
| 10875 | This condition, which has no data, is true during delivery attempts that are |
| 10876 | initiated by queue runner processes, and false otherwise. |
| 10877 | |
| 10878 | |
| 10879 | .vitem &*radius&~{*&<&'authentication&~string'&>&*}*& |
| 10880 | .cindex "Radius" |
| 10881 | .cindex "expansion" "Radius authentication" |
| 10882 | .cindex "&%radius%& expansion condition" |
| 10883 | Radius authentication (RFC 2865) is supported in a similar way to PAM. You must |
| 10884 | set RADIUS_CONFIG_FILE in &_Local/Makefile_& to specify the location of |
| 10885 | the Radius client configuration file in order to build Exim with Radius |
| 10886 | support. |
| 10887 | |
| 10888 | With just that one setting, Exim expects to be linked with the &%radiusclient%& |
| 10889 | library, using the original API. If you are using release 0.4.0 or later of |
| 10890 | this library, you need to set |
| 10891 | .code |
| 10892 | RADIUS_LIB_TYPE=RADIUSCLIENTNEW |
| 10893 | .endd |
| 10894 | in &_Local/Makefile_& when building Exim. You can also link Exim with the |
| 10895 | &%libradius%& library that comes with FreeBSD. To do this, set |
| 10896 | .code |
| 10897 | RADIUS_LIB_TYPE=RADLIB |
| 10898 | .endd |
| 10899 | in &_Local/Makefile_&, in addition to setting RADIUS_CONFIGURE_FILE. |
| 10900 | You may also have to supply a suitable setting in EXTRALIBS so that the |
| 10901 | Radius library can be found when Exim is linked. |
| 10902 | |
| 10903 | The string specified by RADIUS_CONFIG_FILE is expanded and passed to the |
| 10904 | Radius client library, which calls the Radius server. The condition is true if |
| 10905 | the authentication is successful. For example: |
| 10906 | .code |
| 10907 | server_condition = ${if radius{<arguments>}} |
| 10908 | .endd |
| 10909 | |
| 10910 | |
| 10911 | .vitem "&*saslauthd&~{{*&<&'user'&>&*}{*&<&'password'&>&*}&&& |
| 10912 | {*&<&'service'&>&*}{*&<&'realm'&>&*}}*&" |
| 10913 | .cindex "&'saslauthd'& daemon" |
| 10914 | .cindex "Cyrus" |
| 10915 | .cindex "expansion" "&'saslauthd'& authentication test" |
| 10916 | .cindex "&%saslauthd%& expansion condition" |
| 10917 | This condition supports user authentication using the Cyrus &'saslauthd'& |
| 10918 | daemon. This replaces the older &'pwcheck'& daemon, which is now deprecated. |
| 10919 | Using this daemon is one way of making it possible for passwords to be checked |
| 10920 | by a process that is not running as root. |
| 10921 | |
| 10922 | The saslauthd support is not included in Exim by default. You need to specify |
| 10923 | the location of the saslauthd daemon's socket in &_Local/Makefile_& before |
| 10924 | building Exim. For example: |
| 10925 | .code |
| 10926 | CYRUS_SASLAUTHD_SOCKET=/var/state/saslauthd/mux |
| 10927 | .endd |
| 10928 | You do not need to install the full Cyrus software suite in order to use |
| 10929 | the saslauthd daemon. You can compile and install just the daemon alone |
| 10930 | from the Cyrus SASL library. |
| 10931 | |
| 10932 | Up to four arguments can be supplied to the &%saslauthd%& condition, but only |
| 10933 | two are mandatory. For example: |
| 10934 | .code |
| 10935 | server_condition = ${if saslauthd{{$auth1}{$auth2}}} |
| 10936 | .endd |
| 10937 | The service and the realm are optional (which is why the arguments are enclosed |
| 10938 | in their own set of braces). For details of the meaning of the service and |
| 10939 | realm, and how to run the daemon, consult the Cyrus documentation. |
| 10940 | .endlist vlist |
| 10941 | |
| 10942 | |
| 10943 | |
| 10944 | .section "Combining expansion conditions" "SECID84" |
| 10945 | .cindex "expansion" "combining conditions" |
| 10946 | Several conditions can be tested at once by combining them using the &%and%& |
| 10947 | and &%or%& combination conditions. Note that &%and%& and &%or%& are complete |
| 10948 | conditions on their own, and precede their lists of sub-conditions. Each |
| 10949 | sub-condition must be enclosed in braces within the overall braces that contain |
| 10950 | the list. No repetition of &%if%& is used. |
| 10951 | |
| 10952 | |
| 10953 | .vlist |
| 10954 | .vitem &*or&~{{*&<&'cond1'&>&*}{*&<&'cond2'&>&*}...}*& |
| 10955 | .cindex "&""or""& expansion condition" |
| 10956 | .cindex "expansion" "&""or""& of conditions" |
| 10957 | The sub-conditions are evaluated from left to right. The condition is true if |
| 10958 | any one of the sub-conditions is true. |
| 10959 | For example, |
| 10960 | .code |
| 10961 | ${if or {{eq{$local_part}{spqr}}{eq{$domain}{testing.com}}}... |
| 10962 | .endd |
| 10963 | When a true sub-condition is found, the following ones are parsed but not |
| 10964 | evaluated. If there are several &"match"& sub-conditions the values of the |
| 10965 | numeric variables afterwards are taken from the first one that succeeds. |
| 10966 | |
| 10967 | .vitem &*and&~{{*&<&'cond1'&>&*}{*&<&'cond2'&>&*}...}*& |
| 10968 | .cindex "&""and""& expansion condition" |
| 10969 | .cindex "expansion" "&""and""& of conditions" |
| 10970 | The sub-conditions are evaluated from left to right. The condition is true if |
| 10971 | all of the sub-conditions are true. If there are several &"match"& |
| 10972 | sub-conditions, the values of the numeric variables afterwards are taken from |
| 10973 | the last one. When a false sub-condition is found, the following ones are |
| 10974 | parsed but not evaluated. |
| 10975 | .endlist |
| 10976 | .ecindex IIDexpcond |
| 10977 | |
| 10978 | |
| 10979 | |
| 10980 | |
| 10981 | .section "Expansion variables" "SECTexpvar" |
| 10982 | .cindex "expansion" "variables, list of" |
| 10983 | This section contains an alphabetical list of all the expansion variables. Some |
| 10984 | of them are available only when Exim is compiled with specific options such as |
| 10985 | support for TLS or the content scanning extension. |
| 10986 | |
| 10987 | .vlist |
| 10988 | .vitem "&$0$&, &$1$&, etc" |
| 10989 | .cindex "numerical variables (&$1$& &$2$& etc)" |
| 10990 | When a &%match%& expansion condition succeeds, these variables contain the |
| 10991 | captured substrings identified by the regular expression during subsequent |
| 10992 | processing of the success string of the containing &%if%& expansion item. |
| 10993 | However, they do not retain their values afterwards; in fact, their previous |
| 10994 | values are restored at the end of processing an &%if%& item. The numerical |
| 10995 | variables may also be set externally by some other matching process which |
| 10996 | precedes the expansion of the string. For example, the commands available in |
| 10997 | Exim filter files include an &%if%& command with its own regular expression |
| 10998 | matching condition. |
| 10999 | |
| 11000 | .vitem "&$acl_c...$&" |
| 11001 | Values can be placed in these variables by the &%set%& modifier in an ACL. They |
| 11002 | can be given any name that starts with &$acl_c$& and is at least six characters |
| 11003 | long, but the sixth character must be either a digit or an underscore. For |
| 11004 | example: &$acl_c5$&, &$acl_c_mycount$&. The values of the &$acl_c...$& |
| 11005 | variables persist throughout the lifetime of an SMTP connection. They can be |
| 11006 | used to pass information between ACLs and between different invocations of the |
| 11007 | same ACL. When a message is received, the values of these variables are saved |
| 11008 | with the message, and can be accessed by filters, routers, and transports |
| 11009 | during subsequent delivery. |
| 11010 | |
| 11011 | .vitem "&$acl_m...$&" |
| 11012 | These variables are like the &$acl_c...$& variables, except that their values |
| 11013 | are reset after a message has been received. Thus, if several messages are |
| 11014 | received in one SMTP connection, &$acl_m...$& values are not passed on from one |
| 11015 | message to the next, as &$acl_c...$& values are. The &$acl_m...$& variables are |
| 11016 | also reset by MAIL, RSET, EHLO, HELO, and after starting a TLS session. When a |
| 11017 | message is received, the values of these variables are saved with the message, |
| 11018 | and can be accessed by filters, routers, and transports during subsequent |
| 11019 | delivery. |
| 11020 | |
| 11021 | .vitem &$acl_verify_message$& |
| 11022 | .vindex "&$acl_verify_message$&" |
| 11023 | After an address verification has failed, this variable contains the failure |
| 11024 | message. It retains its value for use in subsequent modifiers. The message can |
| 11025 | be preserved by coding like this: |
| 11026 | .code |
| 11027 | warn !verify = sender |
| 11028 | set acl_m0 = $acl_verify_message |
| 11029 | .endd |
| 11030 | You can use &$acl_verify_message$& during the expansion of the &%message%& or |
| 11031 | &%log_message%& modifiers, to include information about the verification |
| 11032 | failure. |
| 11033 | |
| 11034 | .vitem &$address_data$& |
| 11035 | .vindex "&$address_data$&" |
| 11036 | This variable is set by means of the &%address_data%& option in routers. The |
| 11037 | value then remains with the address while it is processed by subsequent routers |
| 11038 | and eventually a transport. If the transport is handling multiple addresses, |
| 11039 | the value from the first address is used. See chapter &<<CHAProutergeneric>>& |
| 11040 | for more details. &*Note*&: The contents of &$address_data$& are visible in |
| 11041 | user filter files. |
| 11042 | |
| 11043 | If &$address_data$& is set when the routers are called from an ACL to verify |
| 11044 | a recipient address, the final value is still in the variable for subsequent |
| 11045 | conditions and modifiers of the ACL statement. If routing the address caused it |
| 11046 | to be redirected to just one address, the child address is also routed as part |
| 11047 | of the verification, and in this case the final value of &$address_data$& is |
| 11048 | from the child's routing. |
| 11049 | |
| 11050 | If &$address_data$& is set when the routers are called from an ACL to verify a |
| 11051 | sender address, the final value is also preserved, but this time in |
| 11052 | &$sender_address_data$&, to distinguish it from data from a recipient |
| 11053 | address. |
| 11054 | |
| 11055 | In both cases (recipient and sender verification), the value does not persist |
| 11056 | after the end of the current ACL statement. If you want to preserve |
| 11057 | these values for longer, you can save them in ACL variables. |
| 11058 | |
| 11059 | .vitem &$address_file$& |
| 11060 | .vindex "&$address_file$&" |
| 11061 | When, as a result of aliasing, forwarding, or filtering, a message is directed |
| 11062 | to a specific file, this variable holds the name of the file when the transport |
| 11063 | is running. At other times, the variable is empty. For example, using the |
| 11064 | default configuration, if user &%r2d2%& has a &_.forward_& file containing |
| 11065 | .code |
| 11066 | /home/r2d2/savemail |
| 11067 | .endd |
| 11068 | then when the &(address_file)& transport is running, &$address_file$& |
| 11069 | contains the text string &`/home/r2d2/savemail`&. |
| 11070 | .cindex "Sieve filter" "value of &$address_file$&" |
| 11071 | For Sieve filters, the value may be &"inbox"& or a relative folder name. It is |
| 11072 | then up to the transport configuration to generate an appropriate absolute path |
| 11073 | to the relevant file. |
| 11074 | |
| 11075 | .vitem &$address_pipe$& |
| 11076 | .vindex "&$address_pipe$&" |
| 11077 | When, as a result of aliasing or forwarding, a message is directed to a pipe, |
| 11078 | this variable holds the pipe command when the transport is running. |
| 11079 | |
| 11080 | .vitem "&$auth1$& &-- &$auth3$&" |
| 11081 | .vindex "&$auth1$&, &$auth2$&, etc" |
| 11082 | These variables are used in SMTP authenticators (see chapters |
| 11083 | &<<CHAPplaintext>>&&--&<<CHAPspa>>&). Elsewhere, they are empty. |
| 11084 | |
| 11085 | .vitem &$authenticated_id$& |
| 11086 | .cindex "authentication" "id" |
| 11087 | .vindex "&$authenticated_id$&" |
| 11088 | When a server successfully authenticates a client it may be configured to |
| 11089 | preserve some of the authentication information in the variable |
| 11090 | &$authenticated_id$& (see chapter &<<CHAPSMTPAUTH>>&). For example, a |
| 11091 | user/password authenticator configuration might preserve the user name for use |
| 11092 | in the routers. Note that this is not the same information that is saved in |
| 11093 | &$sender_host_authenticated$&. |
| 11094 | When a message is submitted locally (that is, not over a TCP connection) |
| 11095 | the value of &$authenticated_id$& is normally the login name of the calling |
| 11096 | process. However, a trusted user can override this by means of the &%-oMai%& |
| 11097 | command line option. |
| 11098 | |
| 11099 | .vitem &$authenticated_fail_id$& |
| 11100 | .cindex "authentication" "fail" "id" |
| 11101 | .vindex "&$authenticated_fail_id$&" |
| 11102 | When an authentication attempt fails, the variable &$authenticated_fail_id$& |
| 11103 | will contain the failed authentication id. If more than one authentication |
| 11104 | id is attempted, it will contain only the last one. The variable is |
| 11105 | available for processing in the ACL's, generally the quit or notquit ACL. |
| 11106 | A message to a local recipient could still be accepted without requiring |
| 11107 | authentication, which means this variable could also be visible in all of |
| 11108 | the ACL's as well. |
| 11109 | |
| 11110 | |
| 11111 | .vitem &$authenticated_sender$& |
| 11112 | .cindex "sender" "authenticated" |
| 11113 | .cindex "authentication" "sender" |
| 11114 | .cindex "AUTH" "on MAIL command" |
| 11115 | .vindex "&$authenticated_sender$&" |
| 11116 | When acting as a server, Exim takes note of the AUTH= parameter on an incoming |
| 11117 | SMTP MAIL command if it believes the sender is sufficiently trusted, as |
| 11118 | described in section &<<SECTauthparamail>>&. Unless the data is the string |
| 11119 | &"<>"&, it is set as the authenticated sender of the message, and the value is |
| 11120 | available during delivery in the &$authenticated_sender$& variable. If the |
| 11121 | sender is not trusted, Exim accepts the syntax of AUTH=, but ignores the data. |
| 11122 | |
| 11123 | .vindex "&$qualify_domain$&" |
| 11124 | When a message is submitted locally (that is, not over a TCP connection), the |
| 11125 | value of &$authenticated_sender$& is an address constructed from the login |
| 11126 | name of the calling process and &$qualify_domain$&, except that a trusted user |
| 11127 | can override this by means of the &%-oMas%& command line option. |
| 11128 | |
| 11129 | |
| 11130 | .vitem &$authentication_failed$& |
| 11131 | .cindex "authentication" "failure" |
| 11132 | .vindex "&$authentication_failed$&" |
| 11133 | This variable is set to &"1"& in an Exim server if a client issues an AUTH |
| 11134 | command that does not succeed. Otherwise it is set to &"0"&. This makes it |
| 11135 | possible to distinguish between &"did not try to authenticate"& |
| 11136 | (&$sender_host_authenticated$& is empty and &$authentication_failed$& is set to |
| 11137 | &"0"&) and &"tried to authenticate but failed"& (&$sender_host_authenticated$& |
| 11138 | is empty and &$authentication_failed$& is set to &"1"&). Failure includes any |
| 11139 | negative response to an AUTH command, including (for example) an attempt to use |
| 11140 | an undefined mechanism. |
| 11141 | |
| 11142 | .vitem &$av_failed$& |
| 11143 | .cindex "content scanning" "AV scanner failure" |
| 11144 | This variable is available when Exim is compiled with the content-scanning |
| 11145 | extension. It is set to &"0"& by default, but will be set to &"1"& if any |
| 11146 | problem occurs with the virus scanner (specified by &%av_scanner%&) during |
| 11147 | the ACL malware condition. |
| 11148 | |
| 11149 | .vitem &$body_linecount$& |
| 11150 | .cindex "message body" "line count" |
| 11151 | .cindex "body of message" "line count" |
| 11152 | .vindex "&$body_linecount$&" |
| 11153 | When a message is being received or delivered, this variable contains the |
| 11154 | number of lines in the message's body. See also &$message_linecount$&. |
| 11155 | |
| 11156 | .vitem &$body_zerocount$& |
| 11157 | .cindex "message body" "binary zero count" |
| 11158 | .cindex "body of message" "binary zero count" |
| 11159 | .cindex "binary zero" "in message body" |
| 11160 | .vindex "&$body_zerocount$&" |
| 11161 | When a message is being received or delivered, this variable contains the |
| 11162 | number of binary zero bytes (ASCII NULs) in the message's body. |
| 11163 | |
| 11164 | .vitem &$bounce_recipient$& |
| 11165 | .vindex "&$bounce_recipient$&" |
| 11166 | This is set to the recipient address of a bounce message while Exim is creating |
| 11167 | it. It is useful if a customized bounce message text file is in use (see |
| 11168 | chapter &<<CHAPemsgcust>>&). |
| 11169 | |
| 11170 | .vitem &$bounce_return_size_limit$& |
| 11171 | .vindex "&$bounce_return_size_limit$&" |
| 11172 | This contains the value set in the &%bounce_return_size_limit%& option, rounded |
| 11173 | up to a multiple of 1000. It is useful when a customized error message text |
| 11174 | file is in use (see chapter &<<CHAPemsgcust>>&). |
| 11175 | |
| 11176 | .vitem &$caller_gid$& |
| 11177 | .cindex "gid (group id)" "caller" |
| 11178 | .vindex "&$caller_gid$&" |
| 11179 | The real group id under which the process that called Exim was running. This is |
| 11180 | not the same as the group id of the originator of a message (see |
| 11181 | &$originator_gid$&). If Exim re-execs itself, this variable in the new |
| 11182 | incarnation normally contains the Exim gid. |
| 11183 | |
| 11184 | .vitem &$caller_uid$& |
| 11185 | .cindex "uid (user id)" "caller" |
| 11186 | .vindex "&$caller_uid$&" |
| 11187 | The real user id under which the process that called Exim was running. This is |
| 11188 | not the same as the user id of the originator of a message (see |
| 11189 | &$originator_uid$&). If Exim re-execs itself, this variable in the new |
| 11190 | incarnation normally contains the Exim uid. |
| 11191 | |
| 11192 | .vitem &$compile_date$& |
| 11193 | .vindex "&$compile_date$&" |
| 11194 | The date on which the Exim binary was compiled. |
| 11195 | |
| 11196 | .vitem &$compile_number$& |
| 11197 | .vindex "&$compile_number$&" |
| 11198 | The building process for Exim keeps a count of the number |
| 11199 | of times it has been compiled. This serves to distinguish different |
| 11200 | compilations of the same version of the program. |
| 11201 | |
| 11202 | .vitem &$demime_errorlevel$& |
| 11203 | .vindex "&$demime_errorlevel$&" |
| 11204 | This variable is available when Exim is compiled with |
| 11205 | the content-scanning extension and the obsolete &%demime%& condition. For |
| 11206 | details, see section &<<SECTdemimecond>>&. |
| 11207 | |
| 11208 | .vitem &$demime_reason$& |
| 11209 | .vindex "&$demime_reason$&" |
| 11210 | This variable is available when Exim is compiled with the |
| 11211 | content-scanning extension and the obsolete &%demime%& condition. For details, |
| 11212 | see section &<<SECTdemimecond>>&. |
| 11213 | |
| 11214 | .vitem &$dnslist_domain$& &&& |
| 11215 | &$dnslist_matched$& &&& |
| 11216 | &$dnslist_text$& &&& |
| 11217 | &$dnslist_value$& |
| 11218 | .vindex "&$dnslist_domain$&" |
| 11219 | .vindex "&$dnslist_matched$&" |
| 11220 | .vindex "&$dnslist_text$&" |
| 11221 | .vindex "&$dnslist_value$&" |
| 11222 | .cindex "black list (DNS)" |
| 11223 | When a DNS (black) list lookup succeeds, these variables are set to contain |
| 11224 | the following data from the lookup: the list's domain name, the key that was |
| 11225 | looked up, the contents of any associated TXT record, and the value from the |
| 11226 | main A record. See section &<<SECID204>>& for more details. |
| 11227 | |
| 11228 | .vitem &$domain$& |
| 11229 | .vindex "&$domain$&" |
| 11230 | When an address is being routed, or delivered on its own, this variable |
| 11231 | contains the domain. Uppercase letters in the domain are converted into lower |
| 11232 | case for &$domain$&. |
| 11233 | |
| 11234 | Global address rewriting happens when a message is received, so the value of |
| 11235 | &$domain$& during routing and delivery is the value after rewriting. &$domain$& |
| 11236 | is set during user filtering, but not during system filtering, because a |
| 11237 | message may have many recipients and the system filter is called just once. |
| 11238 | |
| 11239 | When more than one address is being delivered at once (for example, several |
| 11240 | RCPT commands in one SMTP delivery), &$domain$& is set only if they all |
| 11241 | have the same domain. Transports can be restricted to handling only one domain |
| 11242 | at a time if the value of &$domain$& is required at transport time &-- this is |
| 11243 | the default for local transports. For further details of the environment in |
| 11244 | which local transports are run, see chapter &<<CHAPenvironment>>&. |
| 11245 | |
| 11246 | .oindex "&%delay_warning_condition%&" |
| 11247 | At the end of a delivery, if all deferred addresses have the same domain, it is |
| 11248 | set in &$domain$& during the expansion of &%delay_warning_condition%&. |
| 11249 | |
| 11250 | The &$domain$& variable is also used in some other circumstances: |
| 11251 | |
| 11252 | .ilist |
| 11253 | When an ACL is running for a RCPT command, &$domain$& contains the domain of |
| 11254 | the recipient address. The domain of the &'sender'& address is in |
| 11255 | &$sender_address_domain$& at both MAIL time and at RCPT time. &$domain$& is not |
| 11256 | normally set during the running of the MAIL ACL. However, if the sender address |
| 11257 | is verified with a callout during the MAIL ACL, the sender domain is placed in |
| 11258 | &$domain$& during the expansions of &%hosts%&, &%interface%&, and &%port%& in |
| 11259 | the &(smtp)& transport. |
| 11260 | |
| 11261 | .next |
| 11262 | When a rewrite item is being processed (see chapter &<<CHAPrewrite>>&), |
| 11263 | &$domain$& contains the domain portion of the address that is being rewritten; |
| 11264 | it can be used in the expansion of the replacement address, for example, to |
| 11265 | rewrite domains by file lookup. |
| 11266 | |
| 11267 | .next |
| 11268 | With one important exception, whenever a domain list is being scanned, |
| 11269 | &$domain$& contains the subject domain. &*Exception*&: When a domain list in |
| 11270 | a &%sender_domains%& condition in an ACL is being processed, the subject domain |
| 11271 | is in &$sender_address_domain$& and not in &$domain$&. It works this way so |
| 11272 | that, in a RCPT ACL, the sender domain list can be dependent on the |
| 11273 | recipient domain (which is what is in &$domain$& at this time). |
| 11274 | |
| 11275 | .next |
| 11276 | .cindex "ETRN" "value of &$domain$&" |
| 11277 | .oindex "&%smtp_etrn_command%&" |
| 11278 | When the &%smtp_etrn_command%& option is being expanded, &$domain$& contains |
| 11279 | the complete argument of the ETRN command (see section &<<SECTETRN>>&). |
| 11280 | .endlist |
| 11281 | |
| 11282 | |
| 11283 | .vitem &$domain_data$& |
| 11284 | .vindex "&$domain_data$&" |
| 11285 | When the &%domains%& option on a router matches a domain by |
| 11286 | means of a lookup, the data read by the lookup is available during the running |
| 11287 | of the router as &$domain_data$&. In addition, if the driver routes the |
| 11288 | address to a transport, the value is available in that transport. If the |
| 11289 | transport is handling multiple addresses, the value from the first address is |
| 11290 | used. |
| 11291 | |
| 11292 | &$domain_data$& is also set when the &%domains%& condition in an ACL matches a |
| 11293 | domain by means of a lookup. The data read by the lookup is available during |
| 11294 | the rest of the ACL statement. In all other situations, this variable expands |
| 11295 | to nothing. |
| 11296 | |
| 11297 | .vitem &$exim_gid$& |
| 11298 | .vindex "&$exim_gid$&" |
| 11299 | This variable contains the numerical value of the Exim group id. |
| 11300 | |
| 11301 | .vitem &$exim_path$& |
| 11302 | .vindex "&$exim_path$&" |
| 11303 | This variable contains the path to the Exim binary. |
| 11304 | |
| 11305 | .vitem &$exim_uid$& |
| 11306 | .vindex "&$exim_uid$&" |
| 11307 | This variable contains the numerical value of the Exim user id. |
| 11308 | |
| 11309 | .vitem &$found_extension$& |
| 11310 | .vindex "&$found_extension$&" |
| 11311 | This variable is available when Exim is compiled with the |
| 11312 | content-scanning extension and the obsolete &%demime%& condition. For details, |
| 11313 | see section &<<SECTdemimecond>>&. |
| 11314 | |
| 11315 | .vitem &$header_$&<&'name'&> |
| 11316 | This is not strictly an expansion variable. It is expansion syntax for |
| 11317 | inserting the message header line with the given name. Note that the name must |
| 11318 | be terminated by colon or white space, because it may contain a wide variety of |
| 11319 | characters. Note also that braces must &'not'& be used. |
| 11320 | |
| 11321 | .vitem &$headers_added$& |
| 11322 | .vindex "&$headers_added$&" |
| 11323 | Within an ACL this variable contains the headers added so far by |
| 11324 | the ACL modifier add_header (section &<<SECTaddheadacl>>&). |
| 11325 | The headers are a newline-separated list. |
| 11326 | |
| 11327 | .vitem &$home$& |
| 11328 | .vindex "&$home$&" |
| 11329 | When the &%check_local_user%& option is set for a router, the user's home |
| 11330 | directory is placed in &$home$& when the check succeeds. In particular, this |
| 11331 | means it is set during the running of users' filter files. A router may also |
| 11332 | explicitly set a home directory for use by a transport; this can be overridden |
| 11333 | by a setting on the transport itself. |
| 11334 | |
| 11335 | When running a filter test via the &%-bf%& option, &$home$& is set to the value |
| 11336 | of the environment variable HOME. |
| 11337 | |
| 11338 | .vitem &$host$& |
| 11339 | .vindex "&$host$&" |
| 11340 | If a router assigns an address to a transport (any transport), and passes a |
| 11341 | list of hosts with the address, the value of &$host$& when the transport starts |
| 11342 | to run is the name of the first host on the list. Note that this applies both |
| 11343 | to local and remote transports. |
| 11344 | |
| 11345 | .cindex "transport" "filter" |
| 11346 | .cindex "filter" "transport filter" |
| 11347 | For the &(smtp)& transport, if there is more than one host, the value of |
| 11348 | &$host$& changes as the transport works its way through the list. In |
| 11349 | particular, when the &(smtp)& transport is expanding its options for encryption |
| 11350 | using TLS, or for specifying a transport filter (see chapter |
| 11351 | &<<CHAPtransportgeneric>>&), &$host$& contains the name of the host to which it |
| 11352 | is connected. |
| 11353 | |
| 11354 | When used in the client part of an authenticator configuration (see chapter |
| 11355 | &<<CHAPSMTPAUTH>>&), &$host$& contains the name of the server to which the |
| 11356 | client is connected. |
| 11357 | |
| 11358 | |
| 11359 | .vitem &$host_address$& |
| 11360 | .vindex "&$host_address$&" |
| 11361 | This variable is set to the remote host's IP address whenever &$host$& is set |
| 11362 | for a remote connection. It is also set to the IP address that is being checked |
| 11363 | when the &%ignore_target_hosts%& option is being processed. |
| 11364 | |
| 11365 | .vitem &$host_data$& |
| 11366 | .vindex "&$host_data$&" |
| 11367 | If a &%hosts%& condition in an ACL is satisfied by means of a lookup, the |
| 11368 | result of the lookup is made available in the &$host_data$& variable. This |
| 11369 | allows you, for example, to do things like this: |
| 11370 | .code |
| 11371 | deny hosts = net-lsearch;/some/file |
| 11372 | message = $host_data |
| 11373 | .endd |
| 11374 | .vitem &$host_lookup_deferred$& |
| 11375 | .cindex "host name" "lookup, failure of" |
| 11376 | .vindex "&$host_lookup_deferred$&" |
| 11377 | This variable normally contains &"0"&, as does &$host_lookup_failed$&. When a |
| 11378 | message comes from a remote host and there is an attempt to look up the host's |
| 11379 | name from its IP address, and the attempt is not successful, one of these |
| 11380 | variables is set to &"1"&. |
| 11381 | |
| 11382 | .ilist |
| 11383 | If the lookup receives a definite negative response (for example, a DNS lookup |
| 11384 | succeeded, but no records were found), &$host_lookup_failed$& is set to &"1"&. |
| 11385 | |
| 11386 | .next |
| 11387 | If there is any kind of problem during the lookup, such that Exim cannot |
| 11388 | tell whether or not the host name is defined (for example, a timeout for a DNS |
| 11389 | lookup), &$host_lookup_deferred$& is set to &"1"&. |
| 11390 | .endlist ilist |
| 11391 | |
| 11392 | Looking up a host's name from its IP address consists of more than just a |
| 11393 | single reverse lookup. Exim checks that a forward lookup of at least one of the |
| 11394 | names it receives from a reverse lookup yields the original IP address. If this |
| 11395 | is not the case, Exim does not accept the looked up name(s), and |
| 11396 | &$host_lookup_failed$& is set to &"1"&. Thus, being able to find a name from an |
| 11397 | IP address (for example, the existence of a PTR record in the DNS) is not |
| 11398 | sufficient on its own for the success of a host name lookup. If the reverse |
| 11399 | lookup succeeds, but there is a lookup problem such as a timeout when checking |
| 11400 | the result, the name is not accepted, and &$host_lookup_deferred$& is set to |
| 11401 | &"1"&. See also &$sender_host_name$&. |
| 11402 | |
| 11403 | .vitem &$host_lookup_failed$& |
| 11404 | .vindex "&$host_lookup_failed$&" |
| 11405 | See &$host_lookup_deferred$&. |
| 11406 | |
| 11407 | |
| 11408 | .vitem &$inode$& |
| 11409 | .vindex "&$inode$&" |
| 11410 | The only time this variable is set is while expanding the &%directory_file%& |
| 11411 | option in the &(appendfile)& transport. The variable contains the inode number |
| 11412 | of the temporary file which is about to be renamed. It can be used to construct |
| 11413 | a unique name for the file. |
| 11414 | |
| 11415 | .vitem &$interface_address$& |
| 11416 | .vindex "&$interface_address$&" |
| 11417 | This is an obsolete name for &$received_ip_address$&. |
| 11418 | |
| 11419 | .vitem &$interface_port$& |
| 11420 | .vindex "&$interface_port$&" |
| 11421 | This is an obsolete name for &$received_port$&. |
| 11422 | |
| 11423 | .vitem &$item$& |
| 11424 | .vindex "&$item$&" |
| 11425 | This variable is used during the expansion of &*forall*& and &*forany*& |
| 11426 | conditions (see section &<<SECTexpcond>>&), and &*filter*&, &*map*&, and |
| 11427 | &*reduce*& items (see section &<<SECTexpcond>>&). In other circumstances, it is |
| 11428 | empty. |
| 11429 | |
| 11430 | .vitem &$ldap_dn$& |
| 11431 | .vindex "&$ldap_dn$&" |
| 11432 | This variable, which is available only when Exim is compiled with LDAP support, |
| 11433 | contains the DN from the last entry in the most recently successful LDAP |
| 11434 | lookup. |
| 11435 | |
| 11436 | .vitem &$load_average$& |
| 11437 | .vindex "&$load_average$&" |
| 11438 | This variable contains the system load average, multiplied by 1000 so that it |
| 11439 | is an integer. For example, if the load average is 0.21, the value of the |
| 11440 | variable is 210. The value is recomputed every time the variable is referenced. |
| 11441 | |
| 11442 | .vitem &$local_part$& |
| 11443 | .vindex "&$local_part$&" |
| 11444 | When an address is being routed, or delivered on its own, this |
| 11445 | variable contains the local part. When a number of addresses are being |
| 11446 | delivered together (for example, multiple RCPT commands in an SMTP |
| 11447 | session), &$local_part$& is not set. |
| 11448 | |
| 11449 | Global address rewriting happens when a message is received, so the value of |
| 11450 | &$local_part$& during routing and delivery is the value after rewriting. |
| 11451 | &$local_part$& is set during user filtering, but not during system filtering, |
| 11452 | because a message may have many recipients and the system filter is called just |
| 11453 | once. |
| 11454 | |
| 11455 | .vindex "&$local_part_prefix$&" |
| 11456 | .vindex "&$local_part_suffix$&" |
| 11457 | If a local part prefix or suffix has been recognized, it is not included in the |
| 11458 | value of &$local_part$& during routing and subsequent delivery. The values of |
| 11459 | any prefix or suffix are in &$local_part_prefix$& and |
| 11460 | &$local_part_suffix$&, respectively. |
| 11461 | |
| 11462 | When a message is being delivered to a file, pipe, or autoreply transport as a |
| 11463 | result of aliasing or forwarding, &$local_part$& is set to the local part of |
| 11464 | the parent address, not to the file name or command (see &$address_file$& and |
| 11465 | &$address_pipe$&). |
| 11466 | |
| 11467 | When an ACL is running for a RCPT command, &$local_part$& contains the |
| 11468 | local part of the recipient address. |
| 11469 | |
| 11470 | When a rewrite item is being processed (see chapter &<<CHAPrewrite>>&), |
| 11471 | &$local_part$& contains the local part of the address that is being rewritten; |
| 11472 | it can be used in the expansion of the replacement address, for example. |
| 11473 | |
| 11474 | In all cases, all quoting is removed from the local part. For example, for both |
| 11475 | the addresses |
| 11476 | .code |
| 11477 | "abc:xyz"@test.example |
| 11478 | abc\:xyz@test.example |
| 11479 | .endd |
| 11480 | the value of &$local_part$& is |
| 11481 | .code |
| 11482 | abc:xyz |
| 11483 | .endd |
| 11484 | If you use &$local_part$& to create another address, you should always wrap it |
| 11485 | inside a quoting operator. For example, in a &(redirect)& router you could |
| 11486 | have: |
| 11487 | .code |
| 11488 | data = ${quote_local_part:$local_part}@new.domain.example |
| 11489 | .endd |
| 11490 | &*Note*&: The value of &$local_part$& is normally lower cased. If you want |
| 11491 | to process local parts in a case-dependent manner in a router, you can set the |
| 11492 | &%caseful_local_part%& option (see chapter &<<CHAProutergeneric>>&). |
| 11493 | |
| 11494 | .vitem &$local_part_data$& |
| 11495 | .vindex "&$local_part_data$&" |
| 11496 | When the &%local_parts%& option on a router matches a local part by means of a |
| 11497 | lookup, the data read by the lookup is available during the running of the |
| 11498 | router as &$local_part_data$&. In addition, if the driver routes the address |
| 11499 | to a transport, the value is available in that transport. If the transport is |
| 11500 | handling multiple addresses, the value from the first address is used. |
| 11501 | |
| 11502 | &$local_part_data$& is also set when the &%local_parts%& condition in an ACL |
| 11503 | matches a local part by means of a lookup. The data read by the lookup is |
| 11504 | available during the rest of the ACL statement. In all other situations, this |
| 11505 | variable expands to nothing. |
| 11506 | |
| 11507 | .vitem &$local_part_prefix$& |
| 11508 | .vindex "&$local_part_prefix$&" |
| 11509 | When an address is being routed or delivered, and a |
| 11510 | specific prefix for the local part was recognized, it is available in this |
| 11511 | variable, having been removed from &$local_part$&. |
| 11512 | |
| 11513 | .vitem &$local_part_suffix$& |
| 11514 | .vindex "&$local_part_suffix$&" |
| 11515 | When an address is being routed or delivered, and a |
| 11516 | specific suffix for the local part was recognized, it is available in this |
| 11517 | variable, having been removed from &$local_part$&. |
| 11518 | |
| 11519 | .vitem &$local_scan_data$& |
| 11520 | .vindex "&$local_scan_data$&" |
| 11521 | This variable contains the text returned by the &[local_scan()]& function when |
| 11522 | a message is received. See chapter &<<CHAPlocalscan>>& for more details. |
| 11523 | |
| 11524 | .vitem &$local_user_gid$& |
| 11525 | .vindex "&$local_user_gid$&" |
| 11526 | See &$local_user_uid$&. |
| 11527 | |
| 11528 | .vitem &$local_user_uid$& |
| 11529 | .vindex "&$local_user_uid$&" |
| 11530 | This variable and &$local_user_gid$& are set to the uid and gid after the |
| 11531 | &%check_local_user%& router precondition succeeds. This means that their values |
| 11532 | are available for the remaining preconditions (&%senders%&, &%require_files%&, |
| 11533 | and &%condition%&), for the &%address_data%& expansion, and for any |
| 11534 | router-specific expansions. At all other times, the values in these variables |
| 11535 | are &`(uid_t)(-1)`& and &`(gid_t)(-1)`&, respectively. |
| 11536 | |
| 11537 | .vitem &$localhost_number$& |
| 11538 | .vindex "&$localhost_number$&" |
| 11539 | This contains the expanded value of the |
| 11540 | &%localhost_number%& option. The expansion happens after the main options have |
| 11541 | been read. |
| 11542 | |
| 11543 | .vitem &$log_inodes$& |
| 11544 | .vindex "&$log_inodes$&" |
| 11545 | The number of free inodes in the disk partition where Exim's |
| 11546 | log files are being written. The value is recalculated whenever the variable is |
| 11547 | referenced. If the relevant file system does not have the concept of inodes, |
| 11548 | the value of is -1. See also the &%check_log_inodes%& option. |
| 11549 | |
| 11550 | .vitem &$log_space$& |
| 11551 | .vindex "&$log_space$&" |
| 11552 | The amount of free space (as a number of kilobytes) in the disk |
| 11553 | partition where Exim's log files are being written. The value is recalculated |
| 11554 | whenever the variable is referenced. If the operating system does not have the |
| 11555 | ability to find the amount of free space (only true for experimental systems), |
| 11556 | the space value is -1. See also the &%check_log_space%& option. |
| 11557 | |
| 11558 | |
| 11559 | .new |
| 11560 | .vitem &$lookup_dnssec_authenticated$& |
| 11561 | .vindex "&$lookup_dnssec_authenticated$&" |
| 11562 | This variable is set after a DNS lookup done by |
| 11563 | a dnsdb lookup expansion, dnslookup router or smtp transport. |
| 11564 | It will be empty if &(DNSSEC)& was not requested, |
| 11565 | &"no"& if the result was not labelled as authenticated data |
| 11566 | and &"yes"& if it was. |
| 11567 | .wen |
| 11568 | |
| 11569 | .vitem &$mailstore_basename$& |
| 11570 | .vindex "&$mailstore_basename$&" |
| 11571 | This variable is set only when doing deliveries in &"mailstore"& format in the |
| 11572 | &(appendfile)& transport. During the expansion of the &%mailstore_prefix%&, |
| 11573 | &%mailstore_suffix%&, &%message_prefix%&, and &%message_suffix%& options, it |
| 11574 | contains the basename of the files that are being written, that is, the name |
| 11575 | without the &".tmp"&, &".env"&, or &".msg"& suffix. At all other times, this |
| 11576 | variable is empty. |
| 11577 | |
| 11578 | .vitem &$malware_name$& |
| 11579 | .vindex "&$malware_name$&" |
| 11580 | This variable is available when Exim is compiled with the |
| 11581 | content-scanning extension. It is set to the name of the virus that was found |
| 11582 | when the ACL &%malware%& condition is true (see section &<<SECTscanvirus>>&). |
| 11583 | |
| 11584 | .vitem &$max_received_linelength$& |
| 11585 | .vindex "&$max_received_linelength$&" |
| 11586 | .cindex "maximum" "line length" |
| 11587 | .cindex "line length" "maximum" |
| 11588 | This variable contains the number of bytes in the longest line that was |
| 11589 | received as part of the message, not counting the line termination |
| 11590 | character(s). |
| 11591 | |
| 11592 | .vitem &$message_age$& |
| 11593 | .cindex "message" "age of" |
| 11594 | .vindex "&$message_age$&" |
| 11595 | This variable is set at the start of a delivery attempt to contain the number |
| 11596 | of seconds since the message was received. It does not change during a single |
| 11597 | delivery attempt. |
| 11598 | |
| 11599 | .vitem &$message_body$& |
| 11600 | .cindex "body of message" "expansion variable" |
| 11601 | .cindex "message body" "in expansion" |
| 11602 | .cindex "binary zero" "in message body" |
| 11603 | .vindex "&$message_body$&" |
| 11604 | .oindex "&%message_body_visible%&" |
| 11605 | This variable contains the initial portion of a message's body while it is |
| 11606 | being delivered, and is intended mainly for use in filter files. The maximum |
| 11607 | number of characters of the body that are put into the variable is set by the |
| 11608 | &%message_body_visible%& configuration option; the default is 500. |
| 11609 | |
| 11610 | .oindex "&%message_body_newlines%&" |
| 11611 | By default, newlines are converted into spaces in &$message_body$&, to make it |
| 11612 | easier to search for phrases that might be split over a line break. However, |
| 11613 | this can be disabled by setting &%message_body_newlines%& to be true. Binary |
| 11614 | zeros are always converted into spaces. |
| 11615 | |
| 11616 | .vitem &$message_body_end$& |
| 11617 | .cindex "body of message" "expansion variable" |
| 11618 | .cindex "message body" "in expansion" |
| 11619 | .vindex "&$message_body_end$&" |
| 11620 | This variable contains the final portion of a message's |
| 11621 | body while it is being delivered. The format and maximum size are as for |
| 11622 | &$message_body$&. |
| 11623 | |
| 11624 | .vitem &$message_body_size$& |
| 11625 | .cindex "body of message" "size" |
| 11626 | .cindex "message body" "size" |
| 11627 | .vindex "&$message_body_size$&" |
| 11628 | When a message is being delivered, this variable contains the size of the body |
| 11629 | in bytes. The count starts from the character after the blank line that |
| 11630 | separates the body from the header. Newlines are included in the count. See |
| 11631 | also &$message_size$&, &$body_linecount$&, and &$body_zerocount$&. |
| 11632 | |
| 11633 | .vitem &$message_exim_id$& |
| 11634 | .vindex "&$message_exim_id$&" |
| 11635 | When a message is being received or delivered, this variable contains the |
| 11636 | unique message id that is generated and used by Exim to identify the message. |
| 11637 | An id is not created for a message until after its header has been successfully |
| 11638 | received. &*Note*&: This is &'not'& the contents of the &'Message-ID:'& header |
| 11639 | line; it is the local id that Exim assigns to the message, for example: |
| 11640 | &`1BXTIK-0001yO-VA`&. |
| 11641 | |
| 11642 | .vitem &$message_headers$& |
| 11643 | .vindex &$message_headers$& |
| 11644 | This variable contains a concatenation of all the header lines when a message |
| 11645 | is being processed, except for lines added by routers or transports. The header |
| 11646 | lines are separated by newline characters. Their contents are decoded in the |
| 11647 | same way as a header line that is inserted by &%bheader%&. |
| 11648 | |
| 11649 | .vitem &$message_headers_raw$& |
| 11650 | .vindex &$message_headers_raw$& |
| 11651 | This variable is like &$message_headers$& except that no processing of the |
| 11652 | contents of header lines is done. |
| 11653 | |
| 11654 | .vitem &$message_id$& |
| 11655 | This is an old name for &$message_exim_id$&, which is now deprecated. |
| 11656 | |
| 11657 | .vitem &$message_linecount$& |
| 11658 | .vindex "&$message_linecount$&" |
| 11659 | This variable contains the total number of lines in the header and body of the |
| 11660 | message. Compare &$body_linecount$&, which is the count for the body only. |
| 11661 | During the DATA and content-scanning ACLs, &$message_linecount$& contains the |
| 11662 | number of lines received. Before delivery happens (that is, before filters, |
| 11663 | routers, and transports run) the count is increased to include the |
| 11664 | &'Received:'& header line that Exim standardly adds, and also any other header |
| 11665 | lines that are added by ACLs. The blank line that separates the message header |
| 11666 | from the body is not counted. |
| 11667 | |
| 11668 | As with the special case of &$message_size$&, during the expansion of the |
| 11669 | appendfile transport's maildir_tag option in maildir format, the value of |
| 11670 | &$message_linecount$& is the precise size of the number of newlines in the |
| 11671 | file that has been written (minus one for the blank line between the |
| 11672 | header and the body). |
| 11673 | |
| 11674 | Here is an example of the use of this variable in a DATA ACL: |
| 11675 | .code |
| 11676 | deny message = Too many lines in message header |
| 11677 | condition = \ |
| 11678 | ${if <{250}{${eval:$message_linecount - $body_linecount}}} |
| 11679 | .endd |
| 11680 | In the MAIL and RCPT ACLs, the value is zero because at that stage the |
| 11681 | message has not yet been received. |
| 11682 | |
| 11683 | .vitem &$message_size$& |
| 11684 | .cindex "size" "of message" |
| 11685 | .cindex "message" "size" |
| 11686 | .vindex "&$message_size$&" |
| 11687 | When a message is being processed, this variable contains its size in bytes. In |
| 11688 | most cases, the size includes those headers that were received with the |
| 11689 | message, but not those (such as &'Envelope-to:'&) that are added to individual |
| 11690 | deliveries as they are written. However, there is one special case: during the |
| 11691 | expansion of the &%maildir_tag%& option in the &(appendfile)& transport while |
| 11692 | doing a delivery in maildir format, the value of &$message_size$& is the |
| 11693 | precise size of the file that has been written. See also |
| 11694 | &$message_body_size$&, &$body_linecount$&, and &$body_zerocount$&. |
| 11695 | |
| 11696 | .cindex "RCPT" "value of &$message_size$&" |
| 11697 | While running a per message ACL (mail/rcpt/predata), &$message_size$& |
| 11698 | contains the size supplied on the MAIL command, or -1 if no size was given. The |
| 11699 | value may not, of course, be truthful. |
| 11700 | |
| 11701 | .vitem &$mime_$&&'xxx'& |
| 11702 | A number of variables whose names start with &$mime$& are |
| 11703 | available when Exim is compiled with the content-scanning extension. For |
| 11704 | details, see section &<<SECTscanmimepart>>&. |
| 11705 | |
| 11706 | .vitem "&$n0$& &-- &$n9$&" |
| 11707 | These variables are counters that can be incremented by means |
| 11708 | of the &%add%& command in filter files. |
| 11709 | |
| 11710 | .vitem &$original_domain$& |
| 11711 | .vindex "&$domain$&" |
| 11712 | .vindex "&$original_domain$&" |
| 11713 | When a top-level address is being processed for delivery, this contains the |
| 11714 | same value as &$domain$&. However, if a &"child"& address (for example, |
| 11715 | generated by an alias, forward, or filter file) is being processed, this |
| 11716 | variable contains the domain of the original address (lower cased). This |
| 11717 | differs from &$parent_domain$& only when there is more than one level of |
| 11718 | aliasing or forwarding. When more than one address is being delivered in a |
| 11719 | single transport run, &$original_domain$& is not set. |
| 11720 | |
| 11721 | If a new address is created by means of a &%deliver%& command in a system |
| 11722 | filter, it is set up with an artificial &"parent"& address. This has the local |
| 11723 | part &'system-filter'& and the default qualify domain. |
| 11724 | |
| 11725 | .vitem &$original_local_part$& |
| 11726 | .vindex "&$local_part$&" |
| 11727 | .vindex "&$original_local_part$&" |
| 11728 | When a top-level address is being processed for delivery, this contains the |
| 11729 | same value as &$local_part$&, unless a prefix or suffix was removed from the |
| 11730 | local part, because &$original_local_part$& always contains the full local |
| 11731 | part. When a &"child"& address (for example, generated by an alias, forward, or |
| 11732 | filter file) is being processed, this variable contains the full local part of |
| 11733 | the original address. |
| 11734 | |
| 11735 | If the router that did the redirection processed the local part |
| 11736 | case-insensitively, the value in &$original_local_part$& is in lower case. |
| 11737 | This variable differs from &$parent_local_part$& only when there is more than |
| 11738 | one level of aliasing or forwarding. When more than one address is being |
| 11739 | delivered in a single transport run, &$original_local_part$& is not set. |
| 11740 | |
| 11741 | If a new address is created by means of a &%deliver%& command in a system |
| 11742 | filter, it is set up with an artificial &"parent"& address. This has the local |
| 11743 | part &'system-filter'& and the default qualify domain. |
| 11744 | |
| 11745 | .vitem &$originator_gid$& |
| 11746 | .cindex "gid (group id)" "of originating user" |
| 11747 | .cindex "sender" "gid" |
| 11748 | .vindex "&$caller_gid$&" |
| 11749 | .vindex "&$originator_gid$&" |
| 11750 | This variable contains the value of &$caller_gid$& that was set when the |
| 11751 | message was received. For messages received via the command line, this is the |
| 11752 | gid of the sending user. For messages received by SMTP over TCP/IP, this is |
| 11753 | normally the gid of the Exim user. |
| 11754 | |
| 11755 | .vitem &$originator_uid$& |
| 11756 | .cindex "uid (user id)" "of originating user" |
| 11757 | .cindex "sender" "uid" |
| 11758 | .vindex "&$caller_uid$&" |
| 11759 | .vindex "&$originaltor_uid$&" |
| 11760 | The value of &$caller_uid$& that was set when the message was received. For |
| 11761 | messages received via the command line, this is the uid of the sending user. |
| 11762 | For messages received by SMTP over TCP/IP, this is normally the uid of the Exim |
| 11763 | user. |
| 11764 | |
| 11765 | .vitem &$parent_domain$& |
| 11766 | .vindex "&$parent_domain$&" |
| 11767 | This variable is similar to &$original_domain$& (see |
| 11768 | above), except that it refers to the immediately preceding parent address. |
| 11769 | |
| 11770 | .vitem &$parent_local_part$& |
| 11771 | .vindex "&$parent_local_part$&" |
| 11772 | This variable is similar to &$original_local_part$& |
| 11773 | (see above), except that it refers to the immediately preceding parent address. |
| 11774 | |
| 11775 | .vitem &$pid$& |
| 11776 | .cindex "pid (process id)" "of current process" |
| 11777 | .vindex "&$pid$&" |
| 11778 | This variable contains the current process id. |
| 11779 | |
| 11780 | .vitem &$pipe_addresses$& |
| 11781 | .cindex "filter" "transport filter" |
| 11782 | .cindex "transport" "filter" |
| 11783 | .vindex "&$pipe_addresses$&" |
| 11784 | This is not an expansion variable, but is mentioned here because the string |
| 11785 | &`$pipe_addresses`& is handled specially in the command specification for the |
| 11786 | &(pipe)& transport (chapter &<<CHAPpipetransport>>&) and in transport filters |
| 11787 | (described under &%transport_filter%& in chapter &<<CHAPtransportgeneric>>&). |
| 11788 | It cannot be used in general expansion strings, and provokes an &"unknown |
| 11789 | variable"& error if encountered. |
| 11790 | |
| 11791 | .vitem &$primary_hostname$& |
| 11792 | .vindex "&$primary_hostname$&" |
| 11793 | This variable contains the value set by &%primary_hostname%& in the |
| 11794 | configuration file, or read by the &[uname()]& function. If &[uname()]& returns |
| 11795 | a single-component name, Exim calls &[gethostbyname()]& (or |
| 11796 | &[getipnodebyname()]& where available) in an attempt to acquire a fully |
| 11797 | qualified host name. See also &$smtp_active_hostname$&. |
| 11798 | |
| 11799 | |
| 11800 | .vitem &$prvscheck_address$& |
| 11801 | This variable is used in conjunction with the &%prvscheck%& expansion item, |
| 11802 | which is described in sections &<<SECTexpansionitems>>& and |
| 11803 | &<<SECTverifyPRVS>>&. |
| 11804 | |
| 11805 | .vitem &$prvscheck_keynum$& |
| 11806 | This variable is used in conjunction with the &%prvscheck%& expansion item, |
| 11807 | which is described in sections &<<SECTexpansionitems>>& and |
| 11808 | &<<SECTverifyPRVS>>&. |
| 11809 | |
| 11810 | .vitem &$prvscheck_result$& |
| 11811 | This variable is used in conjunction with the &%prvscheck%& expansion item, |
| 11812 | which is described in sections &<<SECTexpansionitems>>& and |
| 11813 | &<<SECTverifyPRVS>>&. |
| 11814 | |
| 11815 | .vitem &$qualify_domain$& |
| 11816 | .vindex "&$qualify_domain$&" |
| 11817 | The value set for the &%qualify_domain%& option in the configuration file. |
| 11818 | |
| 11819 | .vitem &$qualify_recipient$& |
| 11820 | .vindex "&$qualify_recipient$&" |
| 11821 | The value set for the &%qualify_recipient%& option in the configuration file, |
| 11822 | or if not set, the value of &$qualify_domain$&. |
| 11823 | |
| 11824 | .vitem &$rcpt_count$& |
| 11825 | .vindex "&$rcpt_count$&" |
| 11826 | When a message is being received by SMTP, this variable contains the number of |
| 11827 | RCPT commands received for the current message. If this variable is used in a |
| 11828 | RCPT ACL, its value includes the current command. |
| 11829 | |
| 11830 | .vitem &$rcpt_defer_count$& |
| 11831 | .vindex "&$rcpt_defer_count$&" |
| 11832 | .cindex "4&'xx'& responses" "count of" |
| 11833 | When a message is being received by SMTP, this variable contains the number of |
| 11834 | RCPT commands in the current message that have previously been rejected with a |
| 11835 | temporary (4&'xx'&) response. |
| 11836 | |
| 11837 | .vitem &$rcpt_fail_count$& |
| 11838 | .vindex "&$rcpt_fail_count$&" |
| 11839 | When a message is being received by SMTP, this variable contains the number of |
| 11840 | RCPT commands in the current message that have previously been rejected with a |
| 11841 | permanent (5&'xx'&) response. |
| 11842 | |
| 11843 | .vitem &$received_count$& |
| 11844 | .vindex "&$received_count$&" |
| 11845 | This variable contains the number of &'Received:'& header lines in the message, |
| 11846 | including the one added by Exim (so its value is always greater than zero). It |
| 11847 | is available in the DATA ACL, the non-SMTP ACL, and while routing and |
| 11848 | delivering. |
| 11849 | |
| 11850 | .vitem &$received_for$& |
| 11851 | .vindex "&$received_for$&" |
| 11852 | If there is only a single recipient address in an incoming message, this |
| 11853 | variable contains that address when the &'Received:'& header line is being |
| 11854 | built. The value is copied after recipient rewriting has happened, but before |
| 11855 | the &[local_scan()]& function is run. |
| 11856 | |
| 11857 | .vitem &$received_ip_address$& |
| 11858 | .vindex "&$received_ip_address$&" |
| 11859 | As soon as an Exim server starts processing an incoming TCP/IP connection, this |
| 11860 | variable is set to the address of the local IP interface, and &$received_port$& |
| 11861 | is set to the local port number. (The remote IP address and port are in |
| 11862 | &$sender_host_address$& and &$sender_host_port$&.) When testing with &%-bh%&, |
| 11863 | the port value is -1 unless it has been set using the &%-oMi%& command line |
| 11864 | option. |
| 11865 | |
| 11866 | As well as being useful in ACLs (including the &"connect"& ACL), these variable |
| 11867 | could be used, for example, to make the file name for a TLS certificate depend |
| 11868 | on which interface and/or port is being used for the incoming connection. The |
| 11869 | values of &$received_ip_address$& and &$received_port$& are saved with any |
| 11870 | messages that are received, thus making these variables available at delivery |
| 11871 | time. |
| 11872 | |
| 11873 | &*Note:*& There are no equivalent variables for outgoing connections, because |
| 11874 | the values are unknown (unless they are explicitly set by options of the |
| 11875 | &(smtp)& transport). |
| 11876 | |
| 11877 | .vitem &$received_port$& |
| 11878 | .vindex "&$received_port$&" |
| 11879 | See &$received_ip_address$&. |
| 11880 | |
| 11881 | .vitem &$received_protocol$& |
| 11882 | .vindex "&$received_protocol$&" |
| 11883 | When a message is being processed, this variable contains the name of the |
| 11884 | protocol by which it was received. Most of the names used by Exim are defined |
| 11885 | by RFCs 821, 2821, and 3848. They start with &"smtp"& (the client used HELO) or |
| 11886 | &"esmtp"& (the client used EHLO). This can be followed by &"s"& for secure |
| 11887 | (encrypted) and/or &"a"& for authenticated. Thus, for example, if the protocol |
| 11888 | is set to &"esmtpsa"&, the message was received over an encrypted SMTP |
| 11889 | connection and the client was successfully authenticated. |
| 11890 | |
| 11891 | Exim uses the protocol name &"smtps"& for the case when encryption is |
| 11892 | automatically set up on connection without the use of STARTTLS (see |
| 11893 | &%tls_on_connect_ports%&), and the client uses HELO to initiate the |
| 11894 | encrypted SMTP session. The name &"smtps"& is also used for the rare situation |
| 11895 | where the client initially uses EHLO, sets up an encrypted connection using |
| 11896 | STARTTLS, and then uses HELO afterwards. |
| 11897 | |
| 11898 | The &%-oMr%& option provides a way of specifying a custom protocol name for |
| 11899 | messages that are injected locally by trusted callers. This is commonly used to |
| 11900 | identify messages that are being re-injected after some kind of scanning. |
| 11901 | |
| 11902 | .vitem &$received_time$& |
| 11903 | .vindex "&$received_time$&" |
| 11904 | This variable contains the date and time when the current message was received, |
| 11905 | as a number of seconds since the start of the Unix epoch. |
| 11906 | |
| 11907 | .vitem &$recipient_data$& |
| 11908 | .vindex "&$recipient_data$&" |
| 11909 | This variable is set after an indexing lookup success in an ACL &%recipients%& |
| 11910 | condition. It contains the data from the lookup, and the value remains set |
| 11911 | until the next &%recipients%& test. Thus, you can do things like this: |
| 11912 | .display |
| 11913 | &`require recipients = cdb*@;/some/file`& |
| 11914 | &`deny `&&'some further test involving'& &`$recipient_data`& |
| 11915 | .endd |
| 11916 | &*Warning*&: This variable is set only when a lookup is used as an indexing |
| 11917 | method in the address list, using the semicolon syntax as in the example above. |
| 11918 | The variable is not set for a lookup that is used as part of the string |
| 11919 | expansion that all such lists undergo before being interpreted. |
| 11920 | |
| 11921 | .vitem &$recipient_verify_failure$& |
| 11922 | .vindex "&$recipient_verify_failure$&" |
| 11923 | In an ACL, when a recipient verification fails, this variable contains |
| 11924 | information about the failure. It is set to one of the following words: |
| 11925 | |
| 11926 | .ilist |
| 11927 | &"qualify"&: The address was unqualified (no domain), and the message |
| 11928 | was neither local nor came from an exempted host. |
| 11929 | |
| 11930 | .next |
| 11931 | &"route"&: Routing failed. |
| 11932 | |
| 11933 | .next |
| 11934 | &"mail"&: Routing succeeded, and a callout was attempted; rejection occurred at |
| 11935 | or before the MAIL command (that is, on initial connection, HELO, or |
| 11936 | MAIL). |
| 11937 | |
| 11938 | .next |
| 11939 | &"recipient"&: The RCPT command in a callout was rejected. |
| 11940 | .next |
| 11941 | |
| 11942 | &"postmaster"&: The postmaster check in a callout was rejected. |
| 11943 | .endlist |
| 11944 | |
| 11945 | The main use of this variable is expected to be to distinguish between |
| 11946 | rejections of MAIL and rejections of RCPT. |
| 11947 | |
| 11948 | .vitem &$recipients$& |
| 11949 | .vindex "&$recipients$&" |
| 11950 | This variable contains a list of envelope recipients for a message. A comma and |
| 11951 | a space separate the addresses in the replacement text. However, the variable |
| 11952 | is not generally available, to prevent exposure of Bcc recipients in |
| 11953 | unprivileged users' filter files. You can use &$recipients$& only in these |
| 11954 | cases: |
| 11955 | |
| 11956 | .olist |
| 11957 | In a system filter file. |
| 11958 | .next |
| 11959 | In the ACLs associated with the DATA command and with non-SMTP messages, that |
| 11960 | is, the ACLs defined by &%acl_smtp_predata%&, &%acl_smtp_data%&, |
| 11961 | &%acl_smtp_mime%&, &%acl_not_smtp_start%&, &%acl_not_smtp%&, and |
| 11962 | &%acl_not_smtp_mime%&. |
| 11963 | .next |
| 11964 | From within a &[local_scan()]& function. |
| 11965 | .endlist |
| 11966 | |
| 11967 | |
| 11968 | .vitem &$recipients_count$& |
| 11969 | .vindex "&$recipients_count$&" |
| 11970 | When a message is being processed, this variable contains the number of |
| 11971 | envelope recipients that came with the message. Duplicates are not excluded |
| 11972 | from the count. While a message is being received over SMTP, the number |
| 11973 | increases for each accepted recipient. It can be referenced in an ACL. |
| 11974 | |
| 11975 | |
| 11976 | .vitem &$regex_match_string$& |
| 11977 | .vindex "&$regex_match_string$&" |
| 11978 | This variable is set to contain the matching regular expression after a |
| 11979 | &%regex%& ACL condition has matched (see section &<<SECTscanregex>>&). |
| 11980 | |
| 11981 | |
| 11982 | .vitem &$reply_address$& |
| 11983 | .vindex "&$reply_address$&" |
| 11984 | When a message is being processed, this variable contains the contents of the |
| 11985 | &'Reply-To:'& header line if one exists and it is not empty, or otherwise the |
| 11986 | contents of the &'From:'& header line. Apart from the removal of leading |
| 11987 | white space, the value is not processed in any way. In particular, no RFC 2047 |
| 11988 | decoding or character code translation takes place. |
| 11989 | |
| 11990 | .vitem &$return_path$& |
| 11991 | .vindex "&$return_path$&" |
| 11992 | When a message is being delivered, this variable contains the return path &-- |
| 11993 | the sender field that will be sent as part of the envelope. It is not enclosed |
| 11994 | in <> characters. At the start of routing an address, &$return_path$& has the |
| 11995 | same value as &$sender_address$&, but if, for example, an incoming message to a |
| 11996 | mailing list has been expanded by a router which specifies a different address |
| 11997 | for bounce messages, &$return_path$& subsequently contains the new bounce |
| 11998 | address, whereas &$sender_address$& always contains the original sender address |
| 11999 | that was received with the message. In other words, &$sender_address$& contains |
| 12000 | the incoming envelope sender, and &$return_path$& contains the outgoing |
| 12001 | envelope sender. |
| 12002 | |
| 12003 | .vitem &$return_size_limit$& |
| 12004 | .vindex "&$return_size_limit$&" |
| 12005 | This is an obsolete name for &$bounce_return_size_limit$&. |
| 12006 | |
| 12007 | .vitem &$router_name$& |
| 12008 | .cindex "router" "name" |
| 12009 | .cindex "name" "of router" |
| 12010 | .vindex "&$router_name$&" |
| 12011 | During the running of a router this variable contains its name. |
| 12012 | |
| 12013 | .vitem &$runrc$& |
| 12014 | .cindex "return code" "from &%run%& expansion" |
| 12015 | .vindex "&$runrc$&" |
| 12016 | This variable contains the return code from a command that is run by the |
| 12017 | &%${run...}%& expansion item. &*Warning*&: In a router or transport, you cannot |
| 12018 | assume the order in which option values are expanded, except for those |
| 12019 | preconditions whose order of testing is documented. Therefore, you cannot |
| 12020 | reliably expect to set &$runrc$& by the expansion of one option, and use it in |
| 12021 | another. |
| 12022 | |
| 12023 | .vitem &$self_hostname$& |
| 12024 | .oindex "&%self%&" "value of host name" |
| 12025 | .vindex "&$self_hostname$&" |
| 12026 | When an address is routed to a supposedly remote host that turns out to be the |
| 12027 | local host, what happens is controlled by the &%self%& generic router option. |
| 12028 | One of its values causes the address to be passed to another router. When this |
| 12029 | happens, &$self_hostname$& is set to the name of the local host that the |
| 12030 | original router encountered. In other circumstances its contents are null. |
| 12031 | |
| 12032 | .vitem &$sender_address$& |
| 12033 | .vindex "&$sender_address$&" |
| 12034 | When a message is being processed, this variable contains the sender's address |
| 12035 | that was received in the message's envelope. The case of letters in the address |
| 12036 | is retained, in both the local part and the domain. For bounce messages, the |
| 12037 | value of this variable is the empty string. See also &$return_path$&. |
| 12038 | |
| 12039 | .vitem &$sender_address_data$& |
| 12040 | .vindex "&$address_data$&" |
| 12041 | .vindex "&$sender_address_data$&" |
| 12042 | If &$address_data$& is set when the routers are called from an ACL to verify a |
| 12043 | sender address, the final value is preserved in &$sender_address_data$&, to |
| 12044 | distinguish it from data from a recipient address. The value does not persist |
| 12045 | after the end of the current ACL statement. If you want to preserve it for |
| 12046 | longer, you can save it in an ACL variable. |
| 12047 | |
| 12048 | .vitem &$sender_address_domain$& |
| 12049 | .vindex "&$sender_address_domain$&" |
| 12050 | The domain portion of &$sender_address$&. |
| 12051 | |
| 12052 | .vitem &$sender_address_local_part$& |
| 12053 | .vindex "&$sender_address_local_part$&" |
| 12054 | The local part portion of &$sender_address$&. |
| 12055 | |
| 12056 | .vitem &$sender_data$& |
| 12057 | .vindex "&$sender_data$&" |
| 12058 | This variable is set after a lookup success in an ACL &%senders%& condition or |
| 12059 | in a router &%senders%& option. It contains the data from the lookup, and the |
| 12060 | value remains set until the next &%senders%& test. Thus, you can do things like |
| 12061 | this: |
| 12062 | .display |
| 12063 | &`require senders = cdb*@;/some/file`& |
| 12064 | &`deny `&&'some further test involving'& &`$sender_data`& |
| 12065 | .endd |
| 12066 | &*Warning*&: This variable is set only when a lookup is used as an indexing |
| 12067 | method in the address list, using the semicolon syntax as in the example above. |
| 12068 | The variable is not set for a lookup that is used as part of the string |
| 12069 | expansion that all such lists undergo before being interpreted. |
| 12070 | |
| 12071 | .vitem &$sender_fullhost$& |
| 12072 | .vindex "&$sender_fullhost$&" |
| 12073 | When a message is received from a remote host, this variable contains the host |
| 12074 | name and IP address in a single string. It ends with the IP address in square |
| 12075 | brackets, followed by a colon and a port number if the logging of ports is |
| 12076 | enabled. The format of the rest of the string depends on whether the host |
| 12077 | issued a HELO or EHLO SMTP command, and whether the host name was verified by |
| 12078 | looking up its IP address. (Looking up the IP address can be forced by the |
| 12079 | &%host_lookup%& option, independent of verification.) A plain host name at the |
| 12080 | start of the string is a verified host name; if this is not present, |
| 12081 | verification either failed or was not requested. A host name in parentheses is |
| 12082 | the argument of a HELO or EHLO command. This is omitted if it is identical to |
| 12083 | the verified host name or to the host's IP address in square brackets. |
| 12084 | |
| 12085 | .vitem &$sender_helo_name$& |
| 12086 | .vindex "&$sender_helo_name$&" |
| 12087 | When a message is received from a remote host that has issued a HELO or EHLO |
| 12088 | command, the argument of that command is placed in this variable. It is also |
| 12089 | set if HELO or EHLO is used when a message is received using SMTP locally via |
| 12090 | the &%-bs%& or &%-bS%& options. |
| 12091 | |
| 12092 | .vitem &$sender_host_address$& |
| 12093 | .vindex "&$sender_host_address$&" |
| 12094 | When a message is received from a remote host, this variable contains that |
| 12095 | host's IP address. For locally submitted messages, it is empty. |
| 12096 | |
| 12097 | .vitem &$sender_host_authenticated$& |
| 12098 | .vindex "&$sender_host_authenticated$&" |
| 12099 | This variable contains the name (not the public name) of the authenticator |
| 12100 | driver that successfully authenticated the client from which the message was |
| 12101 | received. It is empty if there was no successful authentication. See also |
| 12102 | &$authenticated_id$&. |
| 12103 | |
| 12104 | .vitem &$sender_host_dnssec$& |
| 12105 | .vindex "&$sender_host_dnssec$&" |
| 12106 | If an attempt to populate &$sender_host_name$& has been made |
| 12107 | (by reference, &%hosts_lookup%& or |
| 12108 | otherwise) then this boolean will have been set true if, and only if, the |
| 12109 | resolver library states that the reverse DNS was authenticated data. At all |
| 12110 | other times, this variable is false. |
| 12111 | |
| 12112 | It is likely that you will need to coerce DNSSEC support on in the resolver |
| 12113 | library, by setting: |
| 12114 | .code |
| 12115 | dns_dnssec_ok = 1 |
| 12116 | .endd |
| 12117 | |
| 12118 | Exim does not perform DNSSEC validation itself, instead leaving that to a |
| 12119 | validating resolver (eg, unbound, or bind with suitable configuration). |
| 12120 | |
| 12121 | Exim does not (currently) check to see if the forward DNS was also secured |
| 12122 | with DNSSEC, only the reverse DNS. |
| 12123 | |
| 12124 | If you have changed &%host_lookup_order%& so that &`bydns`& is not the first |
| 12125 | mechanism in the list, then this variable will be false. |
| 12126 | |
| 12127 | |
| 12128 | .vitem &$sender_host_name$& |
| 12129 | .vindex "&$sender_host_name$&" |
| 12130 | When a message is received from a remote host, this variable contains the |
| 12131 | host's name as obtained by looking up its IP address. For messages received by |
| 12132 | other means, this variable is empty. |
| 12133 | |
| 12134 | .vindex "&$host_lookup_failed$&" |
| 12135 | If the host name has not previously been looked up, a reference to |
| 12136 | &$sender_host_name$& triggers a lookup (for messages from remote hosts). |
| 12137 | A looked up name is accepted only if it leads back to the original IP address |
| 12138 | via a forward lookup. If either the reverse or the forward lookup fails to find |
| 12139 | any data, or if the forward lookup does not yield the original IP address, |
| 12140 | &$sender_host_name$& remains empty, and &$host_lookup_failed$& is set to &"1"&. |
| 12141 | |
| 12142 | .vindex "&$host_lookup_deferred$&" |
| 12143 | However, if either of the lookups cannot be completed (for example, there is a |
| 12144 | DNS timeout), &$host_lookup_deferred$& is set to &"1"&, and |
| 12145 | &$host_lookup_failed$& remains set to &"0"&. |
| 12146 | |
| 12147 | Once &$host_lookup_failed$& is set to &"1"&, Exim does not try to look up the |
| 12148 | host name again if there is a subsequent reference to &$sender_host_name$& |
| 12149 | in the same Exim process, but it does try again if &$host_lookup_deferred$& |
| 12150 | is set to &"1"&. |
| 12151 | |
| 12152 | Exim does not automatically look up every calling host's name. If you want |
| 12153 | maximum efficiency, you should arrange your configuration so that it avoids |
| 12154 | these lookups altogether. The lookup happens only if one or more of the |
| 12155 | following are true: |
| 12156 | |
| 12157 | .ilist |
| 12158 | A string containing &$sender_host_name$& is expanded. |
| 12159 | .next |
| 12160 | The calling host matches the list in &%host_lookup%&. In the default |
| 12161 | configuration, this option is set to *, so it must be changed if lookups are |
| 12162 | to be avoided. (In the code, the default for &%host_lookup%& is unset.) |
| 12163 | .next |
| 12164 | Exim needs the host name in order to test an item in a host list. The items |
| 12165 | that require this are described in sections &<<SECThoslispatnam>>& and |
| 12166 | &<<SECThoslispatnamsk>>&. |
| 12167 | .next |
| 12168 | The calling host matches &%helo_try_verify_hosts%& or &%helo_verify_hosts%&. |
| 12169 | In this case, the host name is required to compare with the name quoted in any |
| 12170 | EHLO or HELO commands that the client issues. |
| 12171 | .next |
| 12172 | The remote host issues a EHLO or HELO command that quotes one of the |
| 12173 | domains in &%helo_lookup_domains%&. The default value of this option is |
| 12174 | . ==== As this is a nested list, any displays it contains must be indented |
| 12175 | . ==== as otherwise they are too far to the left. |
| 12176 | .code |
| 12177 | helo_lookup_domains = @ : @[] |
| 12178 | .endd |
| 12179 | which causes a lookup if a remote host (incorrectly) gives the server's name or |
| 12180 | IP address in an EHLO or HELO command. |
| 12181 | .endlist |
| 12182 | |
| 12183 | |
| 12184 | .vitem &$sender_host_port$& |
| 12185 | .vindex "&$sender_host_port$&" |
| 12186 | When a message is received from a remote host, this variable contains the port |
| 12187 | number that was used on the remote host. |
| 12188 | |
| 12189 | .vitem &$sender_ident$& |
| 12190 | .vindex "&$sender_ident$&" |
| 12191 | When a message is received from a remote host, this variable contains the |
| 12192 | identification received in response to an RFC 1413 request. When a message has |
| 12193 | been received locally, this variable contains the login name of the user that |
| 12194 | called Exim. |
| 12195 | |
| 12196 | .vitem &$sender_rate_$&&'xxx'& |
| 12197 | A number of variables whose names begin &$sender_rate_$& are set as part of the |
| 12198 | &%ratelimit%& ACL condition. Details are given in section |
| 12199 | &<<SECTratelimiting>>&. |
| 12200 | |
| 12201 | .vitem &$sender_rcvhost$& |
| 12202 | .cindex "DNS" "reverse lookup" |
| 12203 | .cindex "reverse DNS lookup" |
| 12204 | .vindex "&$sender_rcvhost$&" |
| 12205 | This is provided specifically for use in &'Received:'& headers. It starts with |
| 12206 | either the verified host name (as obtained from a reverse DNS lookup) or, if |
| 12207 | there is no verified host name, the IP address in square brackets. After that |
| 12208 | there may be text in parentheses. When the first item is a verified host name, |
| 12209 | the first thing in the parentheses is the IP address in square brackets, |
| 12210 | followed by a colon and a port number if port logging is enabled. When the |
| 12211 | first item is an IP address, the port is recorded as &"port=&'xxxx'&"& inside |
| 12212 | the parentheses. |
| 12213 | |
| 12214 | There may also be items of the form &"helo=&'xxxx'&"& if HELO or EHLO |
| 12215 | was used and its argument was not identical to the real host name or IP |
| 12216 | address, and &"ident=&'xxxx'&"& if an RFC 1413 ident string is available. If |
| 12217 | all three items are present in the parentheses, a newline and tab are inserted |
| 12218 | into the string, to improve the formatting of the &'Received:'& header. |
| 12219 | |
| 12220 | .vitem &$sender_verify_failure$& |
| 12221 | .vindex "&$sender_verify_failure$&" |
| 12222 | In an ACL, when a sender verification fails, this variable contains information |
| 12223 | about the failure. The details are the same as for |
| 12224 | &$recipient_verify_failure$&. |
| 12225 | |
| 12226 | .vitem &$sending_ip_address$& |
| 12227 | .vindex "&$sending_ip_address$&" |
| 12228 | This variable is set whenever an outgoing SMTP connection to another host has |
| 12229 | been set up. It contains the IP address of the local interface that is being |
| 12230 | used. This is useful if a host that has more than one IP address wants to take |
| 12231 | on different personalities depending on which one is being used. For incoming |
| 12232 | connections, see &$received_ip_address$&. |
| 12233 | |
| 12234 | .vitem &$sending_port$& |
| 12235 | .vindex "&$sending_port$&" |
| 12236 | This variable is set whenever an outgoing SMTP connection to another host has |
| 12237 | been set up. It contains the local port that is being used. For incoming |
| 12238 | connections, see &$received_port$&. |
| 12239 | |
| 12240 | .vitem &$smtp_active_hostname$& |
| 12241 | .vindex "&$smtp_active_hostname$&" |
| 12242 | During an incoming SMTP session, this variable contains the value of the active |
| 12243 | host name, as specified by the &%smtp_active_hostname%& option. The value of |
| 12244 | &$smtp_active_hostname$& is saved with any message that is received, so its |
| 12245 | value can be consulted during routing and delivery. |
| 12246 | |
| 12247 | .vitem &$smtp_command$& |
| 12248 | .vindex "&$smtp_command$&" |
| 12249 | During the processing of an incoming SMTP command, this variable contains the |
| 12250 | entire command. This makes it possible to distinguish between HELO and EHLO in |
| 12251 | the HELO ACL, and also to distinguish between commands such as these: |
| 12252 | .code |
| 12253 | MAIL FROM:<> |
| 12254 | MAIL FROM: <> |
| 12255 | .endd |
| 12256 | For a MAIL command, extra parameters such as SIZE can be inspected. For a RCPT |
| 12257 | command, the address in &$smtp_command$& is the original address before any |
| 12258 | rewriting, whereas the values in &$local_part$& and &$domain$& are taken from |
| 12259 | the address after SMTP-time rewriting. |
| 12260 | |
| 12261 | .vitem &$smtp_command_argument$& |
| 12262 | .cindex "SMTP" "command, argument for" |
| 12263 | .vindex "&$smtp_command_argument$&" |
| 12264 | While an ACL is running to check an SMTP command, this variable contains the |
| 12265 | argument, that is, the text that follows the command name, with leading white |
| 12266 | space removed. Following the introduction of &$smtp_command$&, this variable is |
| 12267 | somewhat redundant, but is retained for backwards compatibility. |
| 12268 | |
| 12269 | .vitem &$smtp_count_at_connection_start$& |
| 12270 | .vindex "&$smtp_count_at_connection_start$&" |
| 12271 | This variable is set greater than zero only in processes spawned by the Exim |
| 12272 | daemon for handling incoming SMTP connections. The name is deliberately long, |
| 12273 | in order to emphasize what the contents are. When the daemon accepts a new |
| 12274 | connection, it increments this variable. A copy of the variable is passed to |
| 12275 | the child process that handles the connection, but its value is fixed, and |
| 12276 | never changes. It is only an approximation of how many incoming connections |
| 12277 | there actually are, because many other connections may come and go while a |
| 12278 | single connection is being processed. When a child process terminates, the |
| 12279 | daemon decrements its copy of the variable. |
| 12280 | |
| 12281 | .vitem "&$sn0$& &-- &$sn9$&" |
| 12282 | These variables are copies of the values of the &$n0$& &-- &$n9$& accumulators |
| 12283 | that were current at the end of the system filter file. This allows a system |
| 12284 | filter file to set values that can be tested in users' filter files. For |
| 12285 | example, a system filter could set a value indicating how likely it is that a |
| 12286 | message is junk mail. |
| 12287 | |
| 12288 | .vitem &$spam_$&&'xxx'& |
| 12289 | A number of variables whose names start with &$spam$& are available when Exim |
| 12290 | is compiled with the content-scanning extension. For details, see section |
| 12291 | &<<SECTscanspamass>>&. |
| 12292 | |
| 12293 | |
| 12294 | .vitem &$spool_directory$& |
| 12295 | .vindex "&$spool_directory$&" |
| 12296 | The name of Exim's spool directory. |
| 12297 | |
| 12298 | .vitem &$spool_inodes$& |
| 12299 | .vindex "&$spool_inodes$&" |
| 12300 | The number of free inodes in the disk partition where Exim's spool files are |
| 12301 | being written. The value is recalculated whenever the variable is referenced. |
| 12302 | If the relevant file system does not have the concept of inodes, the value of |
| 12303 | is -1. See also the &%check_spool_inodes%& option. |
| 12304 | |
| 12305 | .vitem &$spool_space$& |
| 12306 | .vindex "&$spool_space$&" |
| 12307 | The amount of free space (as a number of kilobytes) in the disk partition where |
| 12308 | Exim's spool files are being written. The value is recalculated whenever the |
| 12309 | variable is referenced. If the operating system does not have the ability to |
| 12310 | find the amount of free space (only true for experimental systems), the space |
| 12311 | value is -1. For example, to check in an ACL that there is at least 50 |
| 12312 | megabytes free on the spool, you could write: |
| 12313 | .code |
| 12314 | condition = ${if > {$spool_space}{50000}} |
| 12315 | .endd |
| 12316 | See also the &%check_spool_space%& option. |
| 12317 | |
| 12318 | |
| 12319 | .vitem &$thisaddress$& |
| 12320 | .vindex "&$thisaddress$&" |
| 12321 | This variable is set only during the processing of the &%foranyaddress%& |
| 12322 | command in a filter file. Its use is explained in the description of that |
| 12323 | command, which can be found in the separate document entitled &'Exim's |
| 12324 | interfaces to mail filtering'&. |
| 12325 | |
| 12326 | .vitem &$tls_in_bits$& |
| 12327 | .vindex "&$tls_in_bits$&" |
| 12328 | Contains an approximation of the TLS cipher's bit-strength |
| 12329 | on the inbound connection; the meaning of |
| 12330 | this depends upon the TLS implementation used. |
| 12331 | If TLS has not been negotiated, the value will be 0. |
| 12332 | The value of this is automatically fed into the Cyrus SASL authenticator |
| 12333 | when acting as a server, to specify the "external SSF" (a SASL term). |
| 12334 | |
| 12335 | The deprecated &$tls_bits$& variable refers to the inbound side |
| 12336 | except when used in the context of an outbound SMTP delivery, when it refers to |
| 12337 | the outbound. |
| 12338 | |
| 12339 | .vitem &$tls_out_bits$& |
| 12340 | .vindex "&$tls_out_bits$&" |
| 12341 | Contains an approximation of the TLS cipher's bit-strength |
| 12342 | on an outbound SMTP connection; the meaning of |
| 12343 | this depends upon the TLS implementation used. |
| 12344 | If TLS has not been negotiated, the value will be 0. |
| 12345 | |
| 12346 | .new |
| 12347 | .vitem &$tls_in_ourcert$& |
| 12348 | .vindex "&$tls_in_ourcert$&" |
| 12349 | This variable refers to the certificate presented to the peer of an |
| 12350 | inbound connection when the message was received. |
| 12351 | It is only useful as the argument of a |
| 12352 | &%certextract%& expansion item, &%md5%& or &%sha1%& operator, |
| 12353 | or a &%def%& condition. |
| 12354 | .wen |
| 12355 | |
| 12356 | .new |
| 12357 | .vitem &$tls_in_peercert$& |
| 12358 | .vindex "&$tls_in_peercert$&" |
| 12359 | This variable refers to the certificate presented by the peer of an |
| 12360 | inbound connection when the message was received. |
| 12361 | It is only useful as the argument of a |
| 12362 | &%certextract%& expansion item, &%md5%& or &%sha1%& operator, |
| 12363 | or a &%def%& condition. |
| 12364 | .wen |
| 12365 | |
| 12366 | .new |
| 12367 | .vitem &$tls_out_ourcert$& |
| 12368 | .vindex "&$tls_out_ourcert$&" |
| 12369 | This variable refers to the certificate presented to the peer of an |
| 12370 | outbound connection. It is only useful as the argument of a |
| 12371 | &%certextract%& expansion item, &%md5%& or &%sha1%& operator, |
| 12372 | or a &%def%& condition. |
| 12373 | .wen |
| 12374 | |
| 12375 | .new |
| 12376 | .vitem &$tls_out_peercert$& |
| 12377 | .vindex "&$tls_out_peercert$&" |
| 12378 | This variable refers to the certificate presented by the peer of an |
| 12379 | outbound connection. It is only useful as the argument of a |
| 12380 | &%certextract%& expansion item, &%md5%& or &%sha1%& operator, |
| 12381 | or a &%def%& condition. |
| 12382 | .wen |
| 12383 | |
| 12384 | .vitem &$tls_in_certificate_verified$& |
| 12385 | .vindex "&$tls_in_certificate_verified$&" |
| 12386 | This variable is set to &"1"& if a TLS certificate was verified when the |
| 12387 | message was received, and &"0"& otherwise. |
| 12388 | |
| 12389 | The deprecated &$tls_certificate_verfied$& variable refers to the inbound side |
| 12390 | except when used in the context of an outbound SMTP delivery, when it refers to |
| 12391 | the outbound. |
| 12392 | |
| 12393 | .vitem &$tls_out_certificate_verified$& |
| 12394 | .vindex "&$tls_out_certificate_verified$&" |
| 12395 | This variable is set to &"1"& if a TLS certificate was verified when an |
| 12396 | outbound SMTP connection was made, |
| 12397 | and &"0"& otherwise. |
| 12398 | |
| 12399 | .vitem &$tls_in_cipher$& |
| 12400 | .vindex "&$tls_in_cipher$&" |
| 12401 | .vindex "&$tls_cipher$&" |
| 12402 | When a message is received from a remote host over an encrypted SMTP |
| 12403 | connection, this variable is set to the cipher suite that was negotiated, for |
| 12404 | example DES-CBC3-SHA. In other circumstances, in particular, for message |
| 12405 | received over unencrypted connections, the variable is empty. Testing |
| 12406 | &$tls_cipher$& for emptiness is one way of distinguishing between encrypted and |
| 12407 | non-encrypted connections during ACL processing. |
| 12408 | |
| 12409 | The deprecated &$tls_cipher$& variable is the same as &$tls_in_cipher$& during message reception, |
| 12410 | but in the context of an outward SMTP delivery taking place via the &(smtp)& transport |
| 12411 | becomes the same as &$tls_out_cipher$&. |
| 12412 | |
| 12413 | .vitem &$tls_out_cipher$& |
| 12414 | .vindex "&$tls_out_cipher$&" |
| 12415 | This variable is |
| 12416 | cleared before any outgoing SMTP connection is made, |
| 12417 | and then set to the outgoing cipher suite if one is negotiated. See chapter |
| 12418 | &<<CHAPTLS>>& for details of TLS support and chapter &<<CHAPsmtptrans>>& for |
| 12419 | details of the &(smtp)& transport. |
| 12420 | |
| 12421 | .vitem &$tls_in_peerdn$& |
| 12422 | .vindex "&$tls_in_peerdn$&" |
| 12423 | .vindex "&$tls_peerdn$&" |
| 12424 | When a message is received from a remote host over an encrypted SMTP |
| 12425 | connection, and Exim is configured to request a certificate from the client, |
| 12426 | the value of the Distinguished Name of the certificate is made available in the |
| 12427 | &$tls_in_peerdn$& during subsequent processing. |
| 12428 | |
| 12429 | The deprecated &$tls_peerdn$& variable refers to the inbound side |
| 12430 | except when used in the context of an outbound SMTP delivery, when it refers to |
| 12431 | the outbound. |
| 12432 | |
| 12433 | .vitem &$tls_out_peerdn$& |
| 12434 | .vindex "&$tls_out_peerdn$&" |
| 12435 | When a message is being delivered to a remote host over an encrypted SMTP |
| 12436 | connection, and Exim is configured to request a certificate from the server, |
| 12437 | the value of the Distinguished Name of the certificate is made available in the |
| 12438 | &$tls_out_peerdn$& during subsequent processing. |
| 12439 | |
| 12440 | .vitem &$tls_in_sni$& |
| 12441 | .vindex "&$tls_in_sni$&" |
| 12442 | .vindex "&$tls_sni$&" |
| 12443 | .cindex "TLS" "Server Name Indication" |
| 12444 | When a TLS session is being established, if the client sends the Server |
| 12445 | Name Indication extension, the value will be placed in this variable. |
| 12446 | If the variable appears in &%tls_certificate%& then this option and |
| 12447 | some others, described in &<<SECTtlssni>>&, |
| 12448 | will be re-expanded early in the TLS session, to permit |
| 12449 | a different certificate to be presented (and optionally a different key to be |
| 12450 | used) to the client, based upon the value of the SNI extension. |
| 12451 | |
| 12452 | The deprecated &$tls_sni$& variable refers to the inbound side |
| 12453 | except when used in the context of an outbound SMTP delivery, when it refers to |
| 12454 | the outbound. |
| 12455 | |
| 12456 | .vitem &$tls_out_sni$& |
| 12457 | .vindex "&$tls_out_sni$&" |
| 12458 | .cindex "TLS" "Server Name Indication" |
| 12459 | During outbound |
| 12460 | SMTP deliveries, this variable reflects the value of the &%tls_sni%& option on |
| 12461 | the transport. |
| 12462 | |
| 12463 | .vitem &$tod_bsdinbox$& |
| 12464 | .vindex "&$tod_bsdinbox$&" |
| 12465 | The time of day and the date, in the format required for BSD-style mailbox |
| 12466 | files, for example: Thu Oct 17 17:14:09 1995. |
| 12467 | |
| 12468 | .vitem &$tod_epoch$& |
| 12469 | .vindex "&$tod_epoch$&" |
| 12470 | The time and date as a number of seconds since the start of the Unix epoch. |
| 12471 | |
| 12472 | .vitem &$tod_epoch_l$& |
| 12473 | .vindex "&$tod_epoch_l$&" |
| 12474 | The time and date as a number of microseconds since the start of the Unix epoch. |
| 12475 | |
| 12476 | .vitem &$tod_full$& |
| 12477 | .vindex "&$tod_full$&" |
| 12478 | A full version of the time and date, for example: Wed, 16 Oct 1995 09:51:40 |
| 12479 | +0100. The timezone is always given as a numerical offset from UTC, with |
| 12480 | positive values used for timezones that are ahead (east) of UTC, and negative |
| 12481 | values for those that are behind (west). |
| 12482 | |
| 12483 | .vitem &$tod_log$& |
| 12484 | .vindex "&$tod_log$&" |
| 12485 | The time and date in the format used for writing Exim's log files, for example: |
| 12486 | 1995-10-12 15:32:29, but without a timezone. |
| 12487 | |
| 12488 | .vitem &$tod_logfile$& |
| 12489 | .vindex "&$tod_logfile$&" |
| 12490 | This variable contains the date in the format yyyymmdd. This is the format that |
| 12491 | is used for datestamping log files when &%log_file_path%& contains the &`%D`& |
| 12492 | flag. |
| 12493 | |
| 12494 | .vitem &$tod_zone$& |
| 12495 | .vindex "&$tod_zone$&" |
| 12496 | This variable contains the numerical value of the local timezone, for example: |
| 12497 | -0500. |
| 12498 | |
| 12499 | .vitem &$tod_zulu$& |
| 12500 | .vindex "&$tod_zulu$&" |
| 12501 | This variable contains the UTC date and time in &"Zulu"& format, as specified |
| 12502 | by ISO 8601, for example: 20030221154023Z. |
| 12503 | |
| 12504 | .vitem &$transport_name$& |
| 12505 | .cindex "transport" "name" |
| 12506 | .cindex "name" "of transport" |
| 12507 | .vindex "&$transport_name$&" |
| 12508 | During the running of a transport, this variable contains its name. |
| 12509 | |
| 12510 | .vitem &$value$& |
| 12511 | .vindex "&$value$&" |
| 12512 | This variable contains the result of an expansion lookup, extraction operation, |
| 12513 | or external command, as described above. It is also used during a |
| 12514 | &*reduce*& expansion. |
| 12515 | |
| 12516 | .vitem &$version_number$& |
| 12517 | .vindex "&$version_number$&" |
| 12518 | The version number of Exim. |
| 12519 | |
| 12520 | .vitem &$warn_message_delay$& |
| 12521 | .vindex "&$warn_message_delay$&" |
| 12522 | This variable is set only during the creation of a message warning about a |
| 12523 | delivery delay. Details of its use are explained in section &<<SECTcustwarn>>&. |
| 12524 | |
| 12525 | .vitem &$warn_message_recipients$& |
| 12526 | .vindex "&$warn_message_recipients$&" |
| 12527 | This variable is set only during the creation of a message warning about a |
| 12528 | delivery delay. Details of its use are explained in section &<<SECTcustwarn>>&. |
| 12529 | .endlist |
| 12530 | .ecindex IIDstrexp |
| 12531 | |
| 12532 | |
| 12533 | |
| 12534 | . //////////////////////////////////////////////////////////////////////////// |
| 12535 | . //////////////////////////////////////////////////////////////////////////// |
| 12536 | |
| 12537 | .chapter "Embedded Perl" "CHAPperl" |
| 12538 | .scindex IIDperl "Perl" "calling from Exim" |
| 12539 | Exim can be built to include an embedded Perl interpreter. When this is done, |
| 12540 | Perl subroutines can be called as part of the string expansion process. To make |
| 12541 | use of the Perl support, you need version 5.004 or later of Perl installed on |
| 12542 | your system. To include the embedded interpreter in the Exim binary, include |
| 12543 | the line |
| 12544 | .code |
| 12545 | EXIM_PERL = perl.o |
| 12546 | .endd |
| 12547 | in your &_Local/Makefile_& and then build Exim in the normal way. |
| 12548 | |
| 12549 | |
| 12550 | .section "Setting up so Perl can be used" "SECID85" |
| 12551 | .oindex "&%perl_startup%&" |
| 12552 | Access to Perl subroutines is via a global configuration option called |
| 12553 | &%perl_startup%& and an expansion string operator &%${perl ...}%&. If there is |
| 12554 | no &%perl_startup%& option in the Exim configuration file then no Perl |
| 12555 | interpreter is started and there is almost no overhead for Exim (since none of |
| 12556 | the Perl library will be paged in unless used). If there is a &%perl_startup%& |
| 12557 | option then the associated value is taken to be Perl code which is executed in |
| 12558 | a newly created Perl interpreter. |
| 12559 | |
| 12560 | The value of &%perl_startup%& is not expanded in the Exim sense, so you do not |
| 12561 | need backslashes before any characters to escape special meanings. The option |
| 12562 | should usually be something like |
| 12563 | .code |
| 12564 | perl_startup = do '/etc/exim.pl' |
| 12565 | .endd |
| 12566 | where &_/etc/exim.pl_& is Perl code which defines any subroutines you want to |
| 12567 | use from Exim. Exim can be configured either to start up a Perl interpreter as |
| 12568 | soon as it is entered, or to wait until the first time it is needed. Starting |
| 12569 | the interpreter at the beginning ensures that it is done while Exim still has |
| 12570 | its setuid privilege, but can impose an unnecessary overhead if Perl is not in |
| 12571 | fact used in a particular run. Also, note that this does not mean that Exim is |
| 12572 | necessarily running as root when Perl is called at a later time. By default, |
| 12573 | the interpreter is started only when it is needed, but this can be changed in |
| 12574 | two ways: |
| 12575 | |
| 12576 | .ilist |
| 12577 | .oindex "&%perl_at_start%&" |
| 12578 | Setting &%perl_at_start%& (a boolean option) in the configuration requests |
| 12579 | a startup when Exim is entered. |
| 12580 | .next |
| 12581 | The command line option &%-ps%& also requests a startup when Exim is entered, |
| 12582 | overriding the setting of &%perl_at_start%&. |
| 12583 | .endlist |
| 12584 | |
| 12585 | There is also a command line option &%-pd%& (for delay) which suppresses the |
| 12586 | initial startup, even if &%perl_at_start%& is set. |
| 12587 | |
| 12588 | |
| 12589 | .section "Calling Perl subroutines" "SECID86" |
| 12590 | When the configuration file includes a &%perl_startup%& option you can make use |
| 12591 | of the string expansion item to call the Perl subroutines that are defined |
| 12592 | by the &%perl_startup%& code. The operator is used in any of the following |
| 12593 | forms: |
| 12594 | .code |
| 12595 | ${perl{foo}} |
| 12596 | ${perl{foo}{argument}} |
| 12597 | ${perl{foo}{argument1}{argument2} ... } |
| 12598 | .endd |
| 12599 | which calls the subroutine &%foo%& with the given arguments. A maximum of eight |
| 12600 | arguments may be passed. Passing more than this results in an expansion failure |
| 12601 | with an error message of the form |
| 12602 | .code |
| 12603 | Too many arguments passed to Perl subroutine "foo" (max is 8) |
| 12604 | .endd |
| 12605 | The return value of the Perl subroutine is evaluated in a scalar context before |
| 12606 | it is passed back to Exim to be inserted into the expanded string. If the |
| 12607 | return value is &'undef'&, the expansion is forced to fail in the same way as |
| 12608 | an explicit &"fail"& on an &%if%& or &%lookup%& item. If the subroutine aborts |
| 12609 | by obeying Perl's &%die%& function, the expansion fails with the error message |
| 12610 | that was passed to &%die%&. |
| 12611 | |
| 12612 | |
| 12613 | .section "Calling Exim functions from Perl" "SECID87" |
| 12614 | Within any Perl code called from Exim, the function &'Exim::expand_string()'& |
| 12615 | is available to call back into Exim's string expansion function. For example, |
| 12616 | the Perl code |
| 12617 | .code |
| 12618 | my $lp = Exim::expand_string('$local_part'); |
| 12619 | .endd |
| 12620 | makes the current Exim &$local_part$& available in the Perl variable &$lp$&. |
| 12621 | Note those are single quotes and not double quotes to protect against |
| 12622 | &$local_part$& being interpolated as a Perl variable. |
| 12623 | |
| 12624 | If the string expansion is forced to fail by a &"fail"& item, the result of |
| 12625 | &'Exim::expand_string()'& is &%undef%&. If there is a syntax error in the |
| 12626 | expansion string, the Perl call from the original expansion string fails with |
| 12627 | an appropriate error message, in the same way as if &%die%& were used. |
| 12628 | |
| 12629 | .cindex "debugging" "from embedded Perl" |
| 12630 | .cindex "log" "writing from embedded Perl" |
| 12631 | Two other Exim functions are available for use from within Perl code. |
| 12632 | &'Exim::debug_write()'& writes a string to the standard error stream if Exim's |
| 12633 | debugging is enabled. If you want a newline at the end, you must supply it. |
| 12634 | &'Exim::log_write()'& writes a string to Exim's main log, adding a leading |
| 12635 | timestamp. In this case, you should not supply a terminating newline. |
| 12636 | |
| 12637 | |
| 12638 | .section "Use of standard output and error by Perl" "SECID88" |
| 12639 | .cindex "Perl" "standard output and error" |
| 12640 | You should not write to the standard error or output streams from within your |
| 12641 | Perl code, as it is not defined how these are set up. In versions of Exim |
| 12642 | before 4.50, it is possible for the standard output or error to refer to the |
| 12643 | SMTP connection during message reception via the daemon. Writing to this stream |
| 12644 | is certain to cause chaos. From Exim 4.50 onwards, the standard output and |
| 12645 | error streams are connected to &_/dev/null_& in the daemon. The chaos is |
| 12646 | avoided, but the output is lost. |
| 12647 | |
| 12648 | .cindex "Perl" "use of &%warn%&" |
| 12649 | The Perl &%warn%& statement writes to the standard error stream by default. |
| 12650 | Calls to &%warn%& may be embedded in Perl modules that you use, but over which |
| 12651 | you have no control. When Exim starts up the Perl interpreter, it arranges for |
| 12652 | output from the &%warn%& statement to be written to the Exim main log. You can |
| 12653 | change this by including appropriate Perl magic somewhere in your Perl code. |
| 12654 | For example, to discard &%warn%& output completely, you need this: |
| 12655 | .code |
| 12656 | $SIG{__WARN__} = sub { }; |
| 12657 | .endd |
| 12658 | Whenever a &%warn%& is obeyed, the anonymous subroutine is called. In this |
| 12659 | example, the code for the subroutine is empty, so it does nothing, but you can |
| 12660 | include any Perl code that you like. The text of the &%warn%& message is passed |
| 12661 | as the first subroutine argument. |
| 12662 | .ecindex IIDperl |
| 12663 | |
| 12664 | |
| 12665 | . //////////////////////////////////////////////////////////////////////////// |
| 12666 | . //////////////////////////////////////////////////////////////////////////// |
| 12667 | |
| 12668 | .chapter "Starting the daemon and the use of network interfaces" &&& |
| 12669 | "CHAPinterfaces" &&& |
| 12670 | "Starting the daemon" |
| 12671 | .cindex "daemon" "starting" |
| 12672 | .cindex "interface" "listening" |
| 12673 | .cindex "network interface" |
| 12674 | .cindex "interface" "network" |
| 12675 | .cindex "IP address" "for listening" |
| 12676 | .cindex "daemon" "listening IP addresses" |
| 12677 | .cindex "TCP/IP" "setting listening interfaces" |
| 12678 | .cindex "TCP/IP" "setting listening ports" |
| 12679 | A host that is connected to a TCP/IP network may have one or more physical |
| 12680 | hardware network interfaces. Each of these interfaces may be configured as one |
| 12681 | or more &"logical"& interfaces, which are the entities that a program actually |
| 12682 | works with. Each of these logical interfaces is associated with an IP address. |
| 12683 | In addition, TCP/IP software supports &"loopback"& interfaces (127.0.0.1 in |
| 12684 | IPv4 and ::1 in IPv6), which do not use any physical hardware. Exim requires |
| 12685 | knowledge about the host's interfaces for use in three different circumstances: |
| 12686 | |
| 12687 | .olist |
| 12688 | When a listening daemon is started, Exim needs to know which interfaces |
| 12689 | and ports to listen on. |
| 12690 | .next |
| 12691 | When Exim is routing an address, it needs to know which IP addresses |
| 12692 | are associated with local interfaces. This is required for the correct |
| 12693 | processing of MX lists by removing the local host and others with the |
| 12694 | same or higher priority values. Also, Exim needs to detect cases |
| 12695 | when an address is routed to an IP address that in fact belongs to the |
| 12696 | local host. Unless the &%self%& router option or the &%allow_localhost%& |
| 12697 | option of the smtp transport is set (as appropriate), this is treated |
| 12698 | as an error situation. |
| 12699 | .next |
| 12700 | When Exim connects to a remote host, it may need to know which interface to use |
| 12701 | for the outgoing connection. |
| 12702 | .endlist |
| 12703 | |
| 12704 | |
| 12705 | Exim's default behaviour is likely to be appropriate in the vast majority |
| 12706 | of cases. If your host has only one interface, and you want all its IP |
| 12707 | addresses to be treated in the same way, and you are using only the |
| 12708 | standard SMTP port, you should not need to take any special action. The |
| 12709 | rest of this chapter does not apply to you. |
| 12710 | |
| 12711 | In a more complicated situation you may want to listen only on certain |
| 12712 | interfaces, or on different ports, and for this reason there are a number of |
| 12713 | options that can be used to influence Exim's behaviour. The rest of this |
| 12714 | chapter describes how they operate. |
| 12715 | |
| 12716 | When a message is received over TCP/IP, the interface and port that were |
| 12717 | actually used are set in &$received_ip_address$& and &$received_port$&. |
| 12718 | |
| 12719 | |
| 12720 | |
| 12721 | .section "Starting a listening daemon" "SECID89" |
| 12722 | When a listening daemon is started (by means of the &%-bd%& command line |
| 12723 | option), the interfaces and ports on which it listens are controlled by the |
| 12724 | following options: |
| 12725 | |
| 12726 | .ilist |
| 12727 | &%daemon_smtp_ports%& contains a list of default ports |
| 12728 | or service names. |
| 12729 | (For backward compatibility, this option can also be specified in the singular.) |
| 12730 | .next |
| 12731 | &%local_interfaces%& contains list of interface IP addresses on which to |
| 12732 | listen. Each item may optionally also specify a port. |
| 12733 | .endlist |
| 12734 | |
| 12735 | The default list separator in both cases is a colon, but this can be changed as |
| 12736 | described in section &<<SECTlistconstruct>>&. When IPv6 addresses are involved, |
| 12737 | it is usually best to change the separator to avoid having to double all the |
| 12738 | colons. For example: |
| 12739 | .code |
| 12740 | local_interfaces = <; 127.0.0.1 ; \ |
| 12741 | 192.168.23.65 ; \ |
| 12742 | ::1 ; \ |
| 12743 | 3ffe:ffff:836f::fe86:a061 |
| 12744 | .endd |
| 12745 | There are two different formats for specifying a port along with an IP address |
| 12746 | in &%local_interfaces%&: |
| 12747 | |
| 12748 | .olist |
| 12749 | The port is added onto the address with a dot separator. For example, to listen |
| 12750 | on port 1234 on two different IP addresses: |
| 12751 | .code |
| 12752 | local_interfaces = <; 192.168.23.65.1234 ; \ |
| 12753 | 3ffe:ffff:836f::fe86:a061.1234 |
| 12754 | .endd |
| 12755 | .next |
| 12756 | The IP address is enclosed in square brackets, and the port is added |
| 12757 | with a colon separator, for example: |
| 12758 | .code |
| 12759 | local_interfaces = <; [192.168.23.65]:1234 ; \ |
| 12760 | [3ffe:ffff:836f::fe86:a061]:1234 |
| 12761 | .endd |
| 12762 | .endlist |
| 12763 | |
| 12764 | When a port is not specified, the value of &%daemon_smtp_ports%& is used. The |
| 12765 | default setting contains just one port: |
| 12766 | .code |
| 12767 | daemon_smtp_ports = smtp |
| 12768 | .endd |
| 12769 | If more than one port is listed, each interface that does not have its own port |
| 12770 | specified listens on all of them. Ports that are listed in |
| 12771 | &%daemon_smtp_ports%& can be identified either by name (defined in |
| 12772 | &_/etc/services_&) or by number. However, when ports are given with individual |
| 12773 | IP addresses in &%local_interfaces%&, only numbers (not names) can be used. |
| 12774 | |
| 12775 | |
| 12776 | |
| 12777 | .section "Special IP listening addresses" "SECID90" |
| 12778 | The addresses 0.0.0.0 and ::0 are treated specially. They are interpreted |
| 12779 | as &"all IPv4 interfaces"& and &"all IPv6 interfaces"&, respectively. In each |
| 12780 | case, Exim tells the TCP/IP stack to &"listen on all IPv&'x'& interfaces"& |
| 12781 | instead of setting up separate listening sockets for each interface. The |
| 12782 | default value of &%local_interfaces%& is |
| 12783 | .code |
| 12784 | local_interfaces = 0.0.0.0 |
| 12785 | .endd |
| 12786 | when Exim is built without IPv6 support; otherwise it is: |
| 12787 | .code |
| 12788 | local_interfaces = <; ::0 ; 0.0.0.0 |
| 12789 | .endd |
| 12790 | Thus, by default, Exim listens on all available interfaces, on the SMTP port. |
| 12791 | |
| 12792 | |
| 12793 | |
| 12794 | .section "Overriding local_interfaces and daemon_smtp_ports" "SECID91" |
| 12795 | The &%-oX%& command line option can be used to override the values of |
| 12796 | &%daemon_smtp_ports%& and/or &%local_interfaces%& for a particular daemon |
| 12797 | instance. Another way of doing this would be to use macros and the &%-D%& |
| 12798 | option. However, &%-oX%& can be used by any admin user, whereas modification of |
| 12799 | the runtime configuration by &%-D%& is allowed only when the caller is root or |
| 12800 | exim. |
| 12801 | |
| 12802 | The value of &%-oX%& is a list of items. The default colon separator can be |
| 12803 | changed in the usual way if required. If there are any items that do not |
| 12804 | contain dots or colons (that is, are not IP addresses), the value of |
| 12805 | &%daemon_smtp_ports%& is replaced by the list of those items. If there are any |
| 12806 | items that do contain dots or colons, the value of &%local_interfaces%& is |
| 12807 | replaced by those items. Thus, for example, |
| 12808 | .code |
| 12809 | -oX 1225 |
| 12810 | .endd |
| 12811 | overrides &%daemon_smtp_ports%&, but leaves &%local_interfaces%& unchanged, |
| 12812 | whereas |
| 12813 | .code |
| 12814 | -oX 192.168.34.5.1125 |
| 12815 | .endd |
| 12816 | overrides &%local_interfaces%&, leaving &%daemon_smtp_ports%& unchanged. |
| 12817 | (However, since &%local_interfaces%& now contains no items without ports, the |
| 12818 | value of &%daemon_smtp_ports%& is no longer relevant in this example.) |
| 12819 | |
| 12820 | |
| 12821 | |
| 12822 | .section "Support for the obsolete SSMTP (or SMTPS) protocol" "SECTsupobssmt" |
| 12823 | .cindex "ssmtp protocol" |
| 12824 | .cindex "smtps protocol" |
| 12825 | .cindex "SMTP" "ssmtp protocol" |
| 12826 | .cindex "SMTP" "smtps protocol" |
| 12827 | Exim supports the obsolete SSMTP protocol (also known as SMTPS) that was used |
| 12828 | before the STARTTLS command was standardized for SMTP. Some legacy clients |
| 12829 | still use this protocol. If the &%tls_on_connect_ports%& option is set to a |
| 12830 | list of port numbers or service names, |
| 12831 | connections to those ports must use SSMTP. The most |
| 12832 | common use of this option is expected to be |
| 12833 | .code |
| 12834 | tls_on_connect_ports = 465 |
| 12835 | .endd |
| 12836 | because 465 is the usual port number used by the legacy clients. There is also |
| 12837 | a command line option &%-tls-on-connect%&, which forces all ports to behave in |
| 12838 | this way when a daemon is started. |
| 12839 | |
| 12840 | &*Warning*&: Setting &%tls_on_connect_ports%& does not of itself cause the |
| 12841 | daemon to listen on those ports. You must still specify them in |
| 12842 | &%daemon_smtp_ports%&, &%local_interfaces%&, or the &%-oX%& option. (This is |
| 12843 | because &%tls_on_connect_ports%& applies to &%inetd%& connections as well as to |
| 12844 | connections via the daemon.) |
| 12845 | |
| 12846 | |
| 12847 | |
| 12848 | |
| 12849 | .section "IPv6 address scopes" "SECID92" |
| 12850 | .cindex "IPv6" "address scopes" |
| 12851 | IPv6 addresses have &"scopes"&, and a host with multiple hardware interfaces |
| 12852 | can, in principle, have the same link-local IPv6 address on different |
| 12853 | interfaces. Thus, additional information is needed, over and above the IP |
| 12854 | address, to distinguish individual interfaces. A convention of using a |
| 12855 | percent sign followed by something (often the interface name) has been |
| 12856 | adopted in some cases, leading to addresses like this: |
| 12857 | .code |
| 12858 | fe80::202:b3ff:fe03:45c1%eth0 |
| 12859 | .endd |
| 12860 | To accommodate this usage, a percent sign followed by an arbitrary string is |
| 12861 | allowed at the end of an IPv6 address. By default, Exim calls &[getaddrinfo()]& |
| 12862 | to convert a textual IPv6 address for actual use. This function recognizes the |
| 12863 | percent convention in operating systems that support it, and it processes the |
| 12864 | address appropriately. Unfortunately, some older libraries have problems with |
| 12865 | &[getaddrinfo()]&. If |
| 12866 | .code |
| 12867 | IPV6_USE_INET_PTON=yes |
| 12868 | .endd |
| 12869 | is set in &_Local/Makefile_& (or an OS-dependent Makefile) when Exim is built, |
| 12870 | Exim uses &'inet_pton()'& to convert a textual IPv6 address for actual use, |
| 12871 | instead of &[getaddrinfo()]&. (Before version 4.14, it always used this |
| 12872 | function.) Of course, this means that the additional functionality of |
| 12873 | &[getaddrinfo()]& &-- recognizing scoped addresses &-- is lost. |
| 12874 | |
| 12875 | .section "Disabling IPv6" "SECID93" |
| 12876 | .cindex "IPv6" "disabling" |
| 12877 | Sometimes it happens that an Exim binary that was compiled with IPv6 support is |
| 12878 | run on a host whose kernel does not support IPv6. The binary will fall back to |
| 12879 | using IPv4, but it may waste resources looking up AAAA records, and trying to |
| 12880 | connect to IPv6 addresses, causing delays to mail delivery. If you set the |
| 12881 | .oindex "&%disable_ipv6%&" |
| 12882 | &%disable_ipv6%& option true, even if the Exim binary has IPv6 support, no IPv6 |
| 12883 | activities take place. AAAA records are never looked up, and any IPv6 addresses |
| 12884 | that are listed in &%local_interfaces%&, data for the &(manualroute)& router, |
| 12885 | etc. are ignored. If IP literals are enabled, the &(ipliteral)& router declines |
| 12886 | to handle IPv6 literal addresses. |
| 12887 | |
| 12888 | On the other hand, when IPv6 is in use, there may be times when you want to |
| 12889 | disable it for certain hosts or domains. You can use the &%dns_ipv4_lookup%& |
| 12890 | option to globally suppress the lookup of AAAA records for specified domains, |
| 12891 | and you can use the &%ignore_target_hosts%& generic router option to ignore |
| 12892 | IPv6 addresses in an individual router. |
| 12893 | |
| 12894 | |
| 12895 | |
| 12896 | .section "Examples of starting a listening daemon" "SECID94" |
| 12897 | The default case in an IPv6 environment is |
| 12898 | .code |
| 12899 | daemon_smtp_ports = smtp |
| 12900 | local_interfaces = <; ::0 ; 0.0.0.0 |
| 12901 | .endd |
| 12902 | This specifies listening on the smtp port on all IPv6 and IPv4 interfaces. |
| 12903 | Either one or two sockets may be used, depending on the characteristics of |
| 12904 | the TCP/IP stack. (This is complicated and messy; for more information, |
| 12905 | read the comments in the &_daemon.c_& source file.) |
| 12906 | |
| 12907 | To specify listening on ports 25 and 26 on all interfaces: |
| 12908 | .code |
| 12909 | daemon_smtp_ports = 25 : 26 |
| 12910 | .endd |
| 12911 | (leaving &%local_interfaces%& at the default setting) or, more explicitly: |
| 12912 | .code |
| 12913 | local_interfaces = <; ::0.25 ; ::0.26 \ |
| 12914 | 0.0.0.0.25 ; 0.0.0.0.26 |
| 12915 | .endd |
| 12916 | To listen on the default port on all IPv4 interfaces, and on port 26 on the |
| 12917 | IPv4 loopback address only: |
| 12918 | .code |
| 12919 | local_interfaces = 0.0.0.0 : 127.0.0.1.26 |
| 12920 | .endd |
| 12921 | To specify listening on the default port on specific interfaces only: |
| 12922 | .code |
| 12923 | local_interfaces = 10.0.0.67 : 192.168.34.67 |
| 12924 | .endd |
| 12925 | &*Warning*&: Such a setting excludes listening on the loopback interfaces. |
| 12926 | |
| 12927 | |
| 12928 | |
| 12929 | .section "Recognizing the local host" "SECTreclocipadd" |
| 12930 | The &%local_interfaces%& option is also used when Exim needs to determine |
| 12931 | whether or not an IP address refers to the local host. That is, the IP |
| 12932 | addresses of all the interfaces on which a daemon is listening are always |
| 12933 | treated as local. |
| 12934 | |
| 12935 | For this usage, port numbers in &%local_interfaces%& are ignored. If either of |
| 12936 | the items 0.0.0.0 or ::0 are encountered, Exim gets a complete list of |
| 12937 | available interfaces from the operating system, and extracts the relevant |
| 12938 | (that is, IPv4 or IPv6) addresses to use for checking. |
| 12939 | |
| 12940 | Some systems set up large numbers of virtual interfaces in order to provide |
| 12941 | many virtual web servers. In this situation, you may want to listen for |
| 12942 | email on only a few of the available interfaces, but nevertheless treat all |
| 12943 | interfaces as local when routing. You can do this by setting |
| 12944 | &%extra_local_interfaces%& to a list of IP addresses, possibly including the |
| 12945 | &"all"& wildcard values. These addresses are recognized as local, but are not |
| 12946 | used for listening. Consider this example: |
| 12947 | .code |
| 12948 | local_interfaces = <; 127.0.0.1 ; ::1 ; \ |
| 12949 | 192.168.53.235 ; \ |
| 12950 | 3ffe:2101:12:1:a00:20ff:fe86:a061 |
| 12951 | |
| 12952 | extra_local_interfaces = <; ::0 ; 0.0.0.0 |
| 12953 | .endd |
| 12954 | The daemon listens on the loopback interfaces and just one IPv4 and one IPv6 |
| 12955 | address, but all available interface addresses are treated as local when |
| 12956 | Exim is routing. |
| 12957 | |
| 12958 | In some environments the local host name may be in an MX list, but with an IP |
| 12959 | address that is not assigned to any local interface. In other cases it may be |
| 12960 | desirable to treat other host names as if they referred to the local host. Both |
| 12961 | these cases can be handled by setting the &%hosts_treat_as_local%& option. |
| 12962 | This contains host names rather than IP addresses. When a host is referenced |
| 12963 | during routing, either via an MX record or directly, it is treated as the local |
| 12964 | host if its name matches &%hosts_treat_as_local%&, or if any of its IP |
| 12965 | addresses match &%local_interfaces%& or &%extra_local_interfaces%&. |
| 12966 | |
| 12967 | |
| 12968 | |
| 12969 | .section "Delivering to a remote host" "SECID95" |
| 12970 | Delivery to a remote host is handled by the smtp transport. By default, it |
| 12971 | allows the system's TCP/IP functions to choose which interface to use (if |
| 12972 | there is more than one) when connecting to a remote host. However, the |
| 12973 | &%interface%& option can be set to specify which interface is used. See the |
| 12974 | description of the smtp transport in chapter &<<CHAPsmtptrans>>& for more |
| 12975 | details. |
| 12976 | |
| 12977 | |
| 12978 | |
| 12979 | |
| 12980 | . //////////////////////////////////////////////////////////////////////////// |
| 12981 | . //////////////////////////////////////////////////////////////////////////// |
| 12982 | |
| 12983 | .chapter "Main configuration" "CHAPmainconfig" |
| 12984 | .scindex IIDconfima "configuration file" "main section" |
| 12985 | .scindex IIDmaiconf "main configuration" |
| 12986 | The first part of the run time configuration file contains three types of item: |
| 12987 | |
| 12988 | .ilist |
| 12989 | Macro definitions: These lines start with an upper case letter. See section |
| 12990 | &<<SECTmacrodefs>>& for details of macro processing. |
| 12991 | .next |
| 12992 | Named list definitions: These lines start with one of the words &"domainlist"&, |
| 12993 | &"hostlist"&, &"addresslist"&, or &"localpartlist"&. Their use is described in |
| 12994 | section &<<SECTnamedlists>>&. |
| 12995 | .next |
| 12996 | Main configuration settings: Each setting occupies one line of the file |
| 12997 | (with possible continuations). If any setting is preceded by the word |
| 12998 | &"hide"&, the &%-bP%& command line option displays its value to admin users |
| 12999 | only. See section &<<SECTcos>>& for a description of the syntax of these option |
| 13000 | settings. |
| 13001 | .endlist |
| 13002 | |
| 13003 | This chapter specifies all the main configuration options, along with their |
| 13004 | types and default values. For ease of finding a particular option, they appear |
| 13005 | in alphabetical order in section &<<SECTalomo>>& below. However, because there |
| 13006 | are now so many options, they are first listed briefly in functional groups, as |
| 13007 | an aid to finding the name of the option you are looking for. Some options are |
| 13008 | listed in more than one group. |
| 13009 | |
| 13010 | .section "Miscellaneous" "SECID96" |
| 13011 | .table2 |
| 13012 | .row &%bi_command%& "to run for &%-bi%& command line option" |
| 13013 | .row &%disable_ipv6%& "do no IPv6 processing" |
| 13014 | .row &%keep_malformed%& "for broken files &-- should not happen" |
| 13015 | .row &%localhost_number%& "for unique message ids in clusters" |
| 13016 | .row &%message_body_newlines%& "retain newlines in &$message_body$&" |
| 13017 | .row &%message_body_visible%& "how much to show in &$message_body$&" |
| 13018 | .row &%mua_wrapper%& "run in &""MUA wrapper""& mode" |
| 13019 | .row &%print_topbitchars%& "top-bit characters are printing" |
| 13020 | .row &%timezone%& "force time zone" |
| 13021 | .endtable |
| 13022 | |
| 13023 | |
| 13024 | .section "Exim parameters" "SECID97" |
| 13025 | .table2 |
| 13026 | .row &%exim_group%& "override compiled-in value" |
| 13027 | .row &%exim_path%& "override compiled-in value" |
| 13028 | .row &%exim_user%& "override compiled-in value" |
| 13029 | .row &%primary_hostname%& "default from &[uname()]&" |
| 13030 | .row &%split_spool_directory%& "use multiple directories" |
| 13031 | .row &%spool_directory%& "override compiled-in value" |
| 13032 | .endtable |
| 13033 | |
| 13034 | |
| 13035 | |
| 13036 | .section "Privilege controls" "SECID98" |
| 13037 | .table2 |
| 13038 | .row &%admin_groups%& "groups that are Exim admin users" |
| 13039 | .row &%deliver_drop_privilege%& "drop root for delivery processes" |
| 13040 | .row &%local_from_check%& "insert &'Sender:'& if necessary" |
| 13041 | .row &%local_from_prefix%& "for testing &'From:'& for local sender" |
| 13042 | .row &%local_from_suffix%& "for testing &'From:'& for local sender" |
| 13043 | .row &%local_sender_retain%& "keep &'Sender:'& from untrusted user" |
| 13044 | .row &%never_users%& "do not run deliveries as these" |
| 13045 | .row &%prod_requires_admin%& "forced delivery requires admin user" |
| 13046 | .row &%queue_list_requires_admin%& "queue listing requires admin user" |
| 13047 | .row &%trusted_groups%& "groups that are trusted" |
| 13048 | .row &%trusted_users%& "users that are trusted" |
| 13049 | .endtable |
| 13050 | |
| 13051 | |
| 13052 | |
| 13053 | .section "Logging" "SECID99" |
| 13054 | .table2 |
| 13055 | .row &%hosts_connection_nolog%& "exemption from connect logging" |
| 13056 | .row &%log_file_path%& "override compiled-in value" |
| 13057 | .row &%log_selector%& "set/unset optional logging" |
| 13058 | .row &%log_timezone%& "add timezone to log lines" |
| 13059 | .row &%message_logs%& "create per-message logs" |
| 13060 | .row &%preserve_message_logs%& "after message completion" |
| 13061 | .row &%process_log_path%& "for SIGUSR1 and &'exiwhat'&" |
| 13062 | .row &%syslog_duplication%& "controls duplicate log lines on syslog" |
| 13063 | .row &%syslog_facility%& "set syslog &""facility""& field" |
| 13064 | .row &%syslog_processname%& "set syslog &""ident""& field" |
| 13065 | .row &%syslog_timestamp%& "timestamp syslog lines" |
| 13066 | .row &%write_rejectlog%& "control use of message log" |
| 13067 | .endtable |
| 13068 | |
| 13069 | |
| 13070 | |
| 13071 | .section "Frozen messages" "SECID100" |
| 13072 | .table2 |
| 13073 | .row &%auto_thaw%& "sets time for retrying frozen messages" |
| 13074 | .row &%freeze_tell%& "send message when freezing" |
| 13075 | .row &%move_frozen_messages%& "to another directory" |
| 13076 | .row &%timeout_frozen_after%& "keep frozen messages only so long" |
| 13077 | .endtable |
| 13078 | |
| 13079 | |
| 13080 | |
| 13081 | .section "Data lookups" "SECID101" |
| 13082 | .table2 |
| 13083 | .row &%ibase_servers%& "InterBase servers" |
| 13084 | .row &%ldap_ca_cert_dir%& "dir of CA certs to verify LDAP server's" |
| 13085 | .row &%ldap_ca_cert_file%& "file of CA certs to verify LDAP server's" |
| 13086 | .row &%ldap_cert_file%& "client cert file for LDAP" |
| 13087 | .row &%ldap_cert_key%& "client key file for LDAP" |
| 13088 | .row &%ldap_cipher_suite%& "TLS negotiation preference control" |
| 13089 | .row &%ldap_default_servers%& "used if no server in query" |
| 13090 | .row &%ldap_require_cert%& "action to take without LDAP server cert" |
| 13091 | .row &%ldap_start_tls%& "require TLS within LDAP" |
| 13092 | .row &%ldap_version%& "set protocol version" |
| 13093 | .row &%lookup_open_max%& "lookup files held open" |
| 13094 | .row &%mysql_servers%& "default MySQL servers" |
| 13095 | .row &%oracle_servers%& "Oracle servers" |
| 13096 | .row &%pgsql_servers%& "default PostgreSQL servers" |
| 13097 | .row &%sqlite_lock_timeout%& "as it says" |
| 13098 | .endtable |
| 13099 | |
| 13100 | |
| 13101 | |
| 13102 | .section "Message ids" "SECID102" |
| 13103 | .table2 |
| 13104 | .row &%message_id_header_domain%& "used to build &'Message-ID:'& header" |
| 13105 | .row &%message_id_header_text%& "ditto" |
| 13106 | .endtable |
| 13107 | |
| 13108 | |
| 13109 | |
| 13110 | .section "Embedded Perl Startup" "SECID103" |
| 13111 | .table2 |
| 13112 | .row &%perl_at_start%& "always start the interpreter" |
| 13113 | .row &%perl_startup%& "code to obey when starting Perl" |
| 13114 | .endtable |
| 13115 | |
| 13116 | |
| 13117 | |
| 13118 | .section "Daemon" "SECID104" |
| 13119 | .table2 |
| 13120 | .row &%daemon_smtp_ports%& "default ports" |
| 13121 | .row &%daemon_startup_retries%& "number of times to retry" |
| 13122 | .row &%daemon_startup_sleep%& "time to sleep between tries" |
| 13123 | .row &%extra_local_interfaces%& "not necessarily listened on" |
| 13124 | .row &%local_interfaces%& "on which to listen, with optional ports" |
| 13125 | .row &%pid_file_path%& "override compiled-in value" |
| 13126 | .row &%queue_run_max%& "maximum simultaneous queue runners" |
| 13127 | .endtable |
| 13128 | |
| 13129 | |
| 13130 | |
| 13131 | .section "Resource control" "SECID105" |
| 13132 | .table2 |
| 13133 | .row &%check_log_inodes%& "before accepting a message" |
| 13134 | .row &%check_log_space%& "before accepting a message" |
| 13135 | .row &%check_spool_inodes%& "before accepting a message" |
| 13136 | .row &%check_spool_space%& "before accepting a message" |
| 13137 | .row &%deliver_queue_load_max%& "no queue deliveries if load high" |
| 13138 | .row &%queue_only_load%& "queue incoming if load high" |
| 13139 | .row &%queue_only_load_latch%& "don't re-evaluate load for each message" |
| 13140 | .row &%queue_run_max%& "maximum simultaneous queue runners" |
| 13141 | .row &%remote_max_parallel%& "parallel SMTP delivery per message" |
| 13142 | .row &%smtp_accept_max%& "simultaneous incoming connections" |
| 13143 | .row &%smtp_accept_max_nonmail%& "non-mail commands" |
| 13144 | .row &%smtp_accept_max_nonmail_hosts%& "hosts to which the limit applies" |
| 13145 | .row &%smtp_accept_max_per_connection%& "messages per connection" |
| 13146 | .row &%smtp_accept_max_per_host%& "connections from one host" |
| 13147 | .row &%smtp_accept_queue%& "queue mail if more connections" |
| 13148 | .row &%smtp_accept_queue_per_connection%& "queue if more messages per &&& |
| 13149 | connection" |
| 13150 | .row &%smtp_accept_reserve%& "only reserve hosts if more connections" |
| 13151 | .row &%smtp_check_spool_space%& "from SIZE on MAIL command" |
| 13152 | .row &%smtp_connect_backlog%& "passed to TCP/IP stack" |
| 13153 | .row &%smtp_load_reserve%& "SMTP from reserved hosts if load high" |
| 13154 | .row &%smtp_reserve_hosts%& "these are the reserve hosts" |
| 13155 | .endtable |
| 13156 | |
| 13157 | |
| 13158 | |
| 13159 | .section "Policy controls" "SECID106" |
| 13160 | .table2 |
| 13161 | .row &%acl_not_smtp%& "ACL for non-SMTP messages" |
| 13162 | .row &%acl_not_smtp_mime%& "ACL for non-SMTP MIME parts" |
| 13163 | .row &%acl_not_smtp_start%& "ACL for start of non-SMTP message" |
| 13164 | .row &%acl_smtp_auth%& "ACL for AUTH" |
| 13165 | .row &%acl_smtp_connect%& "ACL for connection" |
| 13166 | .row &%acl_smtp_data%& "ACL for DATA" |
| 13167 | .row &%acl_smtp_data_prdr%& "ACL for DATA, per-recipient" |
| 13168 | .row &%acl_smtp_dkim%& "ACL for DKIM verification" |
| 13169 | .row &%acl_smtp_etrn%& "ACL for ETRN" |
| 13170 | .row &%acl_smtp_expn%& "ACL for EXPN" |
| 13171 | .row &%acl_smtp_helo%& "ACL for EHLO or HELO" |
| 13172 | .row &%acl_smtp_mail%& "ACL for MAIL" |
| 13173 | .row &%acl_smtp_mailauth%& "ACL for AUTH on MAIL command" |
| 13174 | .row &%acl_smtp_mime%& "ACL for MIME parts" |
| 13175 | .row &%acl_smtp_predata%& "ACL for start of data" |
| 13176 | .row &%acl_smtp_quit%& "ACL for QUIT" |
| 13177 | .row &%acl_smtp_rcpt%& "ACL for RCPT" |
| 13178 | .row &%acl_smtp_starttls%& "ACL for STARTTLS" |
| 13179 | .row &%acl_smtp_vrfy%& "ACL for VRFY" |
| 13180 | .row &%av_scanner%& "specify virus scanner" |
| 13181 | .row &%check_rfc2047_length%& "check length of RFC 2047 &""encoded &&& |
| 13182 | words""&" |
| 13183 | .row &%dns_csa_search_limit%& "control CSA parent search depth" |
| 13184 | .row &%dns_csa_use_reverse%& "en/disable CSA IP reverse search" |
| 13185 | .row &%header_maxsize%& "total size of message header" |
| 13186 | .row &%header_line_maxsize%& "individual header line limit" |
| 13187 | .row &%helo_accept_junk_hosts%& "allow syntactic junk from these hosts" |
| 13188 | .row &%helo_allow_chars%& "allow illegal chars in HELO names" |
| 13189 | .row &%helo_lookup_domains%& "lookup hostname for these HELO names" |
| 13190 | .row &%helo_try_verify_hosts%& "HELO soft-checked for these hosts" |
| 13191 | .row &%helo_verify_hosts%& "HELO hard-checked for these hosts" |
| 13192 | .row &%host_lookup%& "host name looked up for these hosts" |
| 13193 | .row &%host_lookup_order%& "order of DNS and local name lookups" |
| 13194 | .row &%host_reject_connection%& "reject connection from these hosts" |
| 13195 | .row &%hosts_treat_as_local%& "useful in some cluster configurations" |
| 13196 | .row &%local_scan_timeout%& "timeout for &[local_scan()]&" |
| 13197 | .row &%message_size_limit%& "for all messages" |
| 13198 | .row &%percent_hack_domains%& "recognize %-hack for these domains" |
| 13199 | .row &%spamd_address%& "set interface to SpamAssassin" |
| 13200 | .row &%strict_acl_vars%& "object to unset ACL variables" |
| 13201 | .endtable |
| 13202 | |
| 13203 | |
| 13204 | |
| 13205 | .section "Callout cache" "SECID107" |
| 13206 | .table2 |
| 13207 | .row &%callout_domain_negative_expire%& "timeout for negative domain cache &&& |
| 13208 | item" |
| 13209 | .row &%callout_domain_positive_expire%& "timeout for positive domain cache &&& |
| 13210 | item" |
| 13211 | .row &%callout_negative_expire%& "timeout for negative address cache item" |
| 13212 | .row &%callout_positive_expire%& "timeout for positive address cache item" |
| 13213 | .row &%callout_random_local_part%& "string to use for &""random""& testing" |
| 13214 | .endtable |
| 13215 | |
| 13216 | |
| 13217 | |
| 13218 | .section "TLS" "SECID108" |
| 13219 | .table2 |
| 13220 | .row &%gnutls_compat_mode%& "use GnuTLS compatibility mode" |
| 13221 | .row &%gnutls_allow_auto_pkcs11%& "allow GnuTLS to autoload PKCS11 modules" |
| 13222 | .row &%openssl_options%& "adjust OpenSSL compatibility options" |
| 13223 | .row &%tls_advertise_hosts%& "advertise TLS to these hosts" |
| 13224 | .row &%tls_certificate%& "location of server certificate" |
| 13225 | .row &%tls_crl%& "certificate revocation list" |
| 13226 | .row &%tls_dh_max_bits%& "clamp D-H bit count suggestion" |
| 13227 | .row &%tls_dhparam%& "DH parameters for server" |
| 13228 | .row &%tls_ocsp_file%& "location of server certificate status proof" |
| 13229 | .row &%tls_on_connect_ports%& "specify SSMTP (SMTPS) ports" |
| 13230 | .row &%tls_privatekey%& "location of server private key" |
| 13231 | .row &%tls_remember_esmtp%& "don't reset after starting TLS" |
| 13232 | .row &%tls_require_ciphers%& "specify acceptable ciphers" |
| 13233 | .row &%tls_try_verify_hosts%& "try to verify client certificate" |
| 13234 | .row &%tls_verify_certificates%& "expected client certificates" |
| 13235 | .row &%tls_verify_hosts%& "insist on client certificate verify" |
| 13236 | .endtable |
| 13237 | |
| 13238 | |
| 13239 | |
| 13240 | .section "Local user handling" "SECID109" |
| 13241 | .table2 |
| 13242 | .row &%finduser_retries%& "useful in NIS environments" |
| 13243 | .row &%gecos_name%& "used when creating &'Sender:'&" |
| 13244 | .row &%gecos_pattern%& "ditto" |
| 13245 | .row &%max_username_length%& "for systems that truncate" |
| 13246 | .row &%unknown_login%& "used when no login name found" |
| 13247 | .row &%unknown_username%& "ditto" |
| 13248 | .row &%uucp_from_pattern%& "for recognizing &""From ""& lines" |
| 13249 | .row &%uucp_from_sender%& "ditto" |
| 13250 | .endtable |
| 13251 | |
| 13252 | |
| 13253 | |
| 13254 | .section "All incoming messages (SMTP and non-SMTP)" "SECID110" |
| 13255 | .table2 |
| 13256 | .row &%header_maxsize%& "total size of message header" |
| 13257 | .row &%header_line_maxsize%& "individual header line limit" |
| 13258 | .row &%message_size_limit%& "applies to all messages" |
| 13259 | .row &%percent_hack_domains%& "recognize %-hack for these domains" |
| 13260 | .row &%received_header_text%& "expanded to make &'Received:'&" |
| 13261 | .row &%received_headers_max%& "for mail loop detection" |
| 13262 | .row &%recipients_max%& "limit per message" |
| 13263 | .row &%recipients_max_reject%& "permanently reject excess recipients" |
| 13264 | .endtable |
| 13265 | |
| 13266 | |
| 13267 | |
| 13268 | |
| 13269 | .section "Non-SMTP incoming messages" "SECID111" |
| 13270 | .table2 |
| 13271 | .row &%receive_timeout%& "for non-SMTP messages" |
| 13272 | .endtable |
| 13273 | |
| 13274 | |
| 13275 | |
| 13276 | |
| 13277 | |
| 13278 | .section "Incoming SMTP messages" "SECID112" |
| 13279 | See also the &'Policy controls'& section above. |
| 13280 | |
| 13281 | .table2 |
| 13282 | .row &%host_lookup%& "host name looked up for these hosts" |
| 13283 | .row &%host_lookup_order%& "order of DNS and local name lookups" |
| 13284 | .row &%recipient_unqualified_hosts%& "may send unqualified recipients" |
| 13285 | .row &%rfc1413_hosts%& "make ident calls to these hosts" |
| 13286 | .row &%rfc1413_query_timeout%& "zero disables ident calls" |
| 13287 | .row &%sender_unqualified_hosts%& "may send unqualified senders" |
| 13288 | .row &%smtp_accept_keepalive%& "some TCP/IP magic" |
| 13289 | .row &%smtp_accept_max%& "simultaneous incoming connections" |
| 13290 | .row &%smtp_accept_max_nonmail%& "non-mail commands" |
| 13291 | .row &%smtp_accept_max_nonmail_hosts%& "hosts to which the limit applies" |
| 13292 | .row &%smtp_accept_max_per_connection%& "messages per connection" |
| 13293 | .row &%smtp_accept_max_per_host%& "connections from one host" |
| 13294 | .row &%smtp_accept_queue%& "queue mail if more connections" |
| 13295 | .row &%smtp_accept_queue_per_connection%& "queue if more messages per &&& |
| 13296 | connection" |
| 13297 | .row &%smtp_accept_reserve%& "only reserve hosts if more connections" |
| 13298 | .row &%smtp_active_hostname%& "host name to use in messages" |
| 13299 | .row &%smtp_banner%& "text for welcome banner" |
| 13300 | .row &%smtp_check_spool_space%& "from SIZE on MAIL command" |
| 13301 | .row &%smtp_connect_backlog%& "passed to TCP/IP stack" |
| 13302 | .row &%smtp_enforce_sync%& "of SMTP command/responses" |
| 13303 | .row &%smtp_etrn_command%& "what to run for ETRN" |
| 13304 | .row &%smtp_etrn_serialize%& "only one at once" |
| 13305 | .row &%smtp_load_reserve%& "only reserve hosts if this load" |
| 13306 | .row &%smtp_max_unknown_commands%& "before dropping connection" |
| 13307 | .row &%smtp_ratelimit_hosts%& "apply ratelimiting to these hosts" |
| 13308 | .row &%smtp_ratelimit_mail%& "ratelimit for MAIL commands" |
| 13309 | .row &%smtp_ratelimit_rcpt%& "ratelimit for RCPT commands" |
| 13310 | .row &%smtp_receive_timeout%& "per command or data line" |
| 13311 | .row &%smtp_reserve_hosts%& "these are the reserve hosts" |
| 13312 | .row &%smtp_return_error_details%& "give detail on rejections" |
| 13313 | .endtable |
| 13314 | |
| 13315 | |
| 13316 | |
| 13317 | .section "SMTP extensions" "SECID113" |
| 13318 | .table2 |
| 13319 | .row &%accept_8bitmime%& "advertise 8BITMIME" |
| 13320 | .row &%auth_advertise_hosts%& "advertise AUTH to these hosts" |
| 13321 | .row &%ignore_fromline_hosts%& "allow &""From ""& from these hosts" |
| 13322 | .row &%ignore_fromline_local%& "allow &""From ""& from local SMTP" |
| 13323 | .row &%pipelining_advertise_hosts%& "advertise pipelining to these hosts" |
| 13324 | .row &%prdr_enable%& "advertise PRDR to all hosts" |
| 13325 | .row &%tls_advertise_hosts%& "advertise TLS to these hosts" |
| 13326 | .endtable |
| 13327 | |
| 13328 | |
| 13329 | |
| 13330 | .section "Processing messages" "SECID114" |
| 13331 | .table2 |
| 13332 | .row &%allow_domain_literals%& "recognize domain literal syntax" |
| 13333 | .row &%allow_mx_to_ip%& "allow MX to point to IP address" |
| 13334 | .row &%allow_utf8_domains%& "in addresses" |
| 13335 | .row &%check_rfc2047_length%& "check length of RFC 2047 &""encoded &&& |
| 13336 | words""&" |
| 13337 | .row &%delivery_date_remove%& "from incoming messages" |
| 13338 | .row &%envelope_to_remove%& "from incoming messages" |
| 13339 | .row &%extract_addresses_remove_arguments%& "affects &%-t%& processing" |
| 13340 | .row &%headers_charset%& "default for translations" |
| 13341 | .row &%qualify_domain%& "default for senders" |
| 13342 | .row &%qualify_recipient%& "default for recipients" |
| 13343 | .row &%return_path_remove%& "from incoming messages" |
| 13344 | .row &%strip_excess_angle_brackets%& "in addresses" |
| 13345 | .row &%strip_trailing_dot%& "at end of addresses" |
| 13346 | .row &%untrusted_set_sender%& "untrusted can set envelope sender" |
| 13347 | .endtable |
| 13348 | |
| 13349 | |
| 13350 | |
| 13351 | .section "System filter" "SECID115" |
| 13352 | .table2 |
| 13353 | .row &%system_filter%& "locate system filter" |
| 13354 | .row &%system_filter_directory_transport%& "transport for delivery to a &&& |
| 13355 | directory" |
| 13356 | .row &%system_filter_file_transport%& "transport for delivery to a file" |
| 13357 | .row &%system_filter_group%& "group for filter running" |
| 13358 | .row &%system_filter_pipe_transport%& "transport for delivery to a pipe" |
| 13359 | .row &%system_filter_reply_transport%& "transport for autoreply delivery" |
| 13360 | .row &%system_filter_user%& "user for filter running" |
| 13361 | .endtable |
| 13362 | |
| 13363 | |
| 13364 | |
| 13365 | .section "Routing and delivery" "SECID116" |
| 13366 | .table2 |
| 13367 | .row &%disable_ipv6%& "do no IPv6 processing" |
| 13368 | .row &%dns_again_means_nonexist%& "for broken domains" |
| 13369 | .row &%dns_check_names_pattern%& "pre-DNS syntax check" |
| 13370 | .row &%dns_dnssec_ok%& "parameter for resolver" |
| 13371 | .row &%dns_ipv4_lookup%& "only v4 lookup for these domains" |
| 13372 | .row &%dns_retrans%& "parameter for resolver" |
| 13373 | .row &%dns_retry%& "parameter for resolver" |
| 13374 | .row &%dns_use_edns0%& "parameter for resolver" |
| 13375 | .row &%hold_domains%& "hold delivery for these domains" |
| 13376 | .row &%local_interfaces%& "for routing checks" |
| 13377 | .row &%queue_domains%& "no immediate delivery for these" |
| 13378 | .row &%queue_only%& "no immediate delivery at all" |
| 13379 | .row &%queue_only_file%& "no immediate delivery if file exists" |
| 13380 | .row &%queue_only_load%& "no immediate delivery if load is high" |
| 13381 | .row &%queue_only_load_latch%& "don't re-evaluate load for each message" |
| 13382 | .row &%queue_only_override%& "allow command line to override" |
| 13383 | .row &%queue_run_in_order%& "order of arrival" |
| 13384 | .row &%queue_run_max%& "of simultaneous queue runners" |
| 13385 | .row &%queue_smtp_domains%& "no immediate SMTP delivery for these" |
| 13386 | .row &%remote_max_parallel%& "parallel SMTP delivery per message" |
| 13387 | .row &%remote_sort_domains%& "order of remote deliveries" |
| 13388 | .row &%retry_data_expire%& "timeout for retry data" |
| 13389 | .row &%retry_interval_max%& "safety net for retry rules" |
| 13390 | .endtable |
| 13391 | |
| 13392 | |
| 13393 | |
| 13394 | .section "Bounce and warning messages" "SECID117" |
| 13395 | .table2 |
| 13396 | .row &%bounce_message_file%& "content of bounce" |
| 13397 | .row &%bounce_message_text%& "content of bounce" |
| 13398 | .row &%bounce_return_body%& "include body if returning message" |
| 13399 | .row &%bounce_return_message%& "include original message in bounce" |
| 13400 | .row &%bounce_return_size_limit%& "limit on returned message" |
| 13401 | .row &%bounce_sender_authentication%& "send authenticated sender with bounce" |
| 13402 | .row &%dsn_from%& "set &'From:'& contents in bounces" |
| 13403 | .row &%errors_copy%& "copy bounce messages" |
| 13404 | .row &%errors_reply_to%& "&'Reply-to:'& in bounces" |
| 13405 | .row &%delay_warning%& "time schedule" |
| 13406 | .row &%delay_warning_condition%& "condition for warning messages" |
| 13407 | .row &%ignore_bounce_errors_after%& "discard undeliverable bounces" |
| 13408 | .row &%smtp_return_error_details%& "give detail on rejections" |
| 13409 | .row &%warn_message_file%& "content of warning message" |
| 13410 | .endtable |
| 13411 | |
| 13412 | |
| 13413 | |
| 13414 | .section "Alphabetical list of main options" "SECTalomo" |
| 13415 | Those options that undergo string expansion before use are marked with |
| 13416 | †. |
| 13417 | |
| 13418 | .option accept_8bitmime main boolean true |
| 13419 | .cindex "8BITMIME" |
| 13420 | .cindex "8-bit characters" |
| 13421 | .cindex "log" "selectors" |
| 13422 | .cindex "log" "8BITMIME" |
| 13423 | This option causes Exim to send 8BITMIME in its response to an SMTP |
| 13424 | EHLO command, and to accept the BODY= parameter on MAIL commands. |
| 13425 | However, though Exim is 8-bit clean, it is not a protocol converter, and it |
| 13426 | takes no steps to do anything special with messages received by this route. |
| 13427 | |
| 13428 | Historically Exim kept this option off by default, but the maintainers |
| 13429 | feel that in today's Internet, this causes more problems than it solves. |
| 13430 | It now defaults to true. |
| 13431 | A more detailed analysis of the issues is provided by Dan Bernstein: |
| 13432 | .display |
| 13433 | &url(http://cr.yp.to/smtp/8bitmime.html) |
| 13434 | .endd |
| 13435 | |
| 13436 | To log received 8BITMIME status use |
| 13437 | .code |
| 13438 | log_selector = +8bitmime |
| 13439 | .endd |
| 13440 | |
| 13441 | .option acl_not_smtp main string&!! unset |
| 13442 | .cindex "&ACL;" "for non-SMTP messages" |
| 13443 | .cindex "non-SMTP messages" "ACLs for" |
| 13444 | This option defines the ACL that is run when a non-SMTP message has been |
| 13445 | read and is on the point of being accepted. See chapter &<<CHAPACL>>& for |
| 13446 | further details. |
| 13447 | |
| 13448 | .option acl_not_smtp_mime main string&!! unset |
| 13449 | This option defines the ACL that is run for individual MIME parts of non-SMTP |
| 13450 | messages. It operates in exactly the same way as &%acl_smtp_mime%& operates for |
| 13451 | SMTP messages. |
| 13452 | |
| 13453 | .option acl_not_smtp_start main string&!! unset |
| 13454 | .cindex "&ACL;" "at start of non-SMTP message" |
| 13455 | .cindex "non-SMTP messages" "ACLs for" |
| 13456 | This option defines the ACL that is run before Exim starts reading a |
| 13457 | non-SMTP message. See chapter &<<CHAPACL>>& for further details. |
| 13458 | |
| 13459 | .option acl_smtp_auth main string&!! unset |
| 13460 | .cindex "&ACL;" "setting up for SMTP commands" |
| 13461 | .cindex "AUTH" "ACL for" |
| 13462 | This option defines the ACL that is run when an SMTP AUTH command is |
| 13463 | received. See chapter &<<CHAPACL>>& for further details. |
| 13464 | |
| 13465 | .option acl_smtp_connect main string&!! unset |
| 13466 | .cindex "&ACL;" "on SMTP connection" |
| 13467 | This option defines the ACL that is run when an SMTP connection is received. |
| 13468 | See chapter &<<CHAPACL>>& for further details. |
| 13469 | |
| 13470 | .option acl_smtp_data main string&!! unset |
| 13471 | .cindex "DATA" "ACL for" |
| 13472 | This option defines the ACL that is run after an SMTP DATA command has been |
| 13473 | processed and the message itself has been received, but before the final |
| 13474 | acknowledgment is sent. See chapter &<<CHAPACL>>& for further details. |
| 13475 | |
| 13476 | .option acl_smtp_data_prdr main string&!! unset |
| 13477 | .cindex "DATA" "ACL for" |
| 13478 | .cindex "&ACL;" "PRDR-related" |
| 13479 | .cindex "&ACL;" "per-user data processing" |
| 13480 | This option defines the ACL that, |
| 13481 | if the PRDR feature has been negotiated, |
| 13482 | is run for each recipient after an SMTP DATA command has been |
| 13483 | processed and the message itself has been received, but before the |
| 13484 | acknowledgment is sent. See chapter &<<CHAPACL>>& for further details. |
| 13485 | |
| 13486 | .option acl_smtp_etrn main string&!! unset |
| 13487 | .cindex "ETRN" "ACL for" |
| 13488 | This option defines the ACL that is run when an SMTP ETRN command is |
| 13489 | received. See chapter &<<CHAPACL>>& for further details. |
| 13490 | |
| 13491 | .option acl_smtp_expn main string&!! unset |
| 13492 | .cindex "EXPN" "ACL for" |
| 13493 | This option defines the ACL that is run when an SMTP EXPN command is |
| 13494 | received. See chapter &<<CHAPACL>>& for further details. |
| 13495 | |
| 13496 | .option acl_smtp_helo main string&!! unset |
| 13497 | .cindex "EHLO" "ACL for" |
| 13498 | .cindex "HELO" "ACL for" |
| 13499 | This option defines the ACL that is run when an SMTP EHLO or HELO |
| 13500 | command is received. See chapter &<<CHAPACL>>& for further details. |
| 13501 | |
| 13502 | |
| 13503 | .option acl_smtp_mail main string&!! unset |
| 13504 | .cindex "MAIL" "ACL for" |
| 13505 | This option defines the ACL that is run when an SMTP MAIL command is |
| 13506 | received. See chapter &<<CHAPACL>>& for further details. |
| 13507 | |
| 13508 | .option acl_smtp_mailauth main string&!! unset |
| 13509 | .cindex "AUTH" "on MAIL command" |
| 13510 | This option defines the ACL that is run when there is an AUTH parameter on |
| 13511 | a MAIL command. See chapter &<<CHAPACL>>& for details of ACLs, and chapter |
| 13512 | &<<CHAPSMTPAUTH>>& for details of authentication. |
| 13513 | |
| 13514 | .option acl_smtp_mime main string&!! unset |
| 13515 | .cindex "MIME content scanning" "ACL for" |
| 13516 | This option is available when Exim is built with the content-scanning |
| 13517 | extension. It defines the ACL that is run for each MIME part in a message. See |
| 13518 | section &<<SECTscanmimepart>>& for details. |
| 13519 | |
| 13520 | .option acl_smtp_predata main string&!! unset |
| 13521 | This option defines the ACL that is run when an SMTP DATA command is |
| 13522 | received, before the message itself is received. See chapter &<<CHAPACL>>& for |
| 13523 | further details. |
| 13524 | |
| 13525 | .option acl_smtp_quit main string&!! unset |
| 13526 | .cindex "QUIT, ACL for" |
| 13527 | This option defines the ACL that is run when an SMTP QUIT command is |
| 13528 | received. See chapter &<<CHAPACL>>& for further details. |
| 13529 | |
| 13530 | .option acl_smtp_rcpt main string&!! unset |
| 13531 | .cindex "RCPT" "ACL for" |
| 13532 | This option defines the ACL that is run when an SMTP RCPT command is |
| 13533 | received. See chapter &<<CHAPACL>>& for further details. |
| 13534 | |
| 13535 | .option acl_smtp_starttls main string&!! unset |
| 13536 | .cindex "STARTTLS, ACL for" |
| 13537 | This option defines the ACL that is run when an SMTP STARTTLS command is |
| 13538 | received. See chapter &<<CHAPACL>>& for further details. |
| 13539 | |
| 13540 | .option acl_smtp_vrfy main string&!! unset |
| 13541 | .cindex "VRFY" "ACL for" |
| 13542 | This option defines the ACL that is run when an SMTP VRFY command is |
| 13543 | received. See chapter &<<CHAPACL>>& for further details. |
| 13544 | |
| 13545 | .option admin_groups main "string list&!!" unset |
| 13546 | .cindex "admin user" |
| 13547 | This option is expanded just once, at the start of Exim's processing. If the |
| 13548 | current group or any of the supplementary groups of an Exim caller is in this |
| 13549 | colon-separated list, the caller has admin privileges. If all your system |
| 13550 | programmers are in a specific group, for example, you can give them all Exim |
| 13551 | admin privileges by putting that group in &%admin_groups%&. However, this does |
| 13552 | not permit them to read Exim's spool files (whose group owner is the Exim gid). |
| 13553 | To permit this, you have to add individuals to the Exim group. |
| 13554 | |
| 13555 | .option allow_domain_literals main boolean false |
| 13556 | .cindex "domain literal" |
| 13557 | If this option is set, the RFC 2822 domain literal format is permitted in |
| 13558 | email addresses. The option is not set by default, because the domain literal |
| 13559 | format is not normally required these days, and few people know about it. It |
| 13560 | has, however, been exploited by mail abusers. |
| 13561 | |
| 13562 | Unfortunately, it seems that some DNS black list maintainers are using this |
| 13563 | format to report black listing to postmasters. If you want to accept messages |
| 13564 | addressed to your hosts by IP address, you need to set |
| 13565 | &%allow_domain_literals%& true, and also to add &`@[]`& to the list of local |
| 13566 | domains (defined in the named domain list &%local_domains%& in the default |
| 13567 | configuration). This &"magic string"& matches the domain literal form of all |
| 13568 | the local host's IP addresses. |
| 13569 | |
| 13570 | |
| 13571 | .option allow_mx_to_ip main boolean false |
| 13572 | .cindex "MX record" "pointing to IP address" |
| 13573 | It appears that more and more DNS zone administrators are breaking the rules |
| 13574 | and putting domain names that look like IP addresses on the right hand side of |
| 13575 | MX records. Exim follows the rules and rejects this, giving an error message |
| 13576 | that explains the mis-configuration. However, some other MTAs support this |
| 13577 | practice, so to avoid &"Why can't Exim do this?"& complaints, |
| 13578 | &%allow_mx_to_ip%& exists, in order to enable this heinous activity. It is not |
| 13579 | recommended, except when you have no other choice. |
| 13580 | |
| 13581 | .option allow_utf8_domains main boolean false |
| 13582 | .cindex "domain" "UTF-8 characters in" |
| 13583 | .cindex "UTF-8" "in domain name" |
| 13584 | Lots of discussion is going on about internationalized domain names. One |
| 13585 | camp is strongly in favour of just using UTF-8 characters, and it seems |
| 13586 | that at least two other MTAs permit this. This option allows Exim users to |
| 13587 | experiment if they wish. |
| 13588 | |
| 13589 | If it is set true, Exim's domain parsing function allows valid |
| 13590 | UTF-8 multicharacters to appear in domain name components, in addition to |
| 13591 | letters, digits, and hyphens. However, just setting this option is not |
| 13592 | enough; if you want to look up these domain names in the DNS, you must also |
| 13593 | adjust the value of &%dns_check_names_pattern%& to match the extended form. A |
| 13594 | suitable setting is: |
| 13595 | .code |
| 13596 | dns_check_names_pattern = (?i)^(?>(?(1)\.|())[a-z0-9\xc0-\xff]\ |
| 13597 | (?>[-a-z0-9\x80-\xff]*[a-z0-9\x80-\xbf])?)+$ |
| 13598 | .endd |
| 13599 | Alternatively, you can just disable this feature by setting |
| 13600 | .code |
| 13601 | dns_check_names_pattern = |
| 13602 | .endd |
| 13603 | That is, set the option to an empty string so that no check is done. |
| 13604 | |
| 13605 | |
| 13606 | .option auth_advertise_hosts main "host list&!!" * |
| 13607 | .cindex "authentication" "advertising" |
| 13608 | .cindex "AUTH" "advertising" |
| 13609 | If any server authentication mechanisms are configured, Exim advertises them in |
| 13610 | response to an EHLO command only if the calling host matches this list. |
| 13611 | Otherwise, Exim does not advertise AUTH. |
| 13612 | Exim does not accept AUTH commands from clients to which it has not |
| 13613 | advertised the availability of AUTH. The advertising of individual |
| 13614 | authentication mechanisms can be controlled by the use of the |
| 13615 | &%server_advertise_condition%& generic authenticator option on the individual |
| 13616 | authenticators. See chapter &<<CHAPSMTPAUTH>>& for further details. |
| 13617 | |
| 13618 | Certain mail clients (for example, Netscape) require the user to provide a name |
| 13619 | and password for authentication if AUTH is advertised, even though it may |
| 13620 | not be needed (the host may accept messages from hosts on its local LAN without |
| 13621 | authentication, for example). The &%auth_advertise_hosts%& option can be used |
| 13622 | to make these clients more friendly by excluding them from the set of hosts to |
| 13623 | which Exim advertises AUTH. |
| 13624 | |
| 13625 | .cindex "AUTH" "advertising when encrypted" |
| 13626 | If you want to advertise the availability of AUTH only when the connection |
| 13627 | is encrypted using TLS, you can make use of the fact that the value of this |
| 13628 | option is expanded, with a setting like this: |
| 13629 | .code |
| 13630 | auth_advertise_hosts = ${if eq{$tls_in_cipher}{}{}{*}} |
| 13631 | .endd |
| 13632 | .vindex "&$tls_in_cipher$&" |
| 13633 | If &$tls_in_cipher$& is empty, the session is not encrypted, and the result of |
| 13634 | the expansion is empty, thus matching no hosts. Otherwise, the result of the |
| 13635 | expansion is *, which matches all hosts. |
| 13636 | |
| 13637 | |
| 13638 | .option auto_thaw main time 0s |
| 13639 | .cindex "thawing messages" |
| 13640 | .cindex "unfreezing messages" |
| 13641 | If this option is set to a time greater than zero, a queue runner will try a |
| 13642 | new delivery attempt on any frozen message, other than a bounce message, if |
| 13643 | this much time has passed since it was frozen. This may result in the message |
| 13644 | being re-frozen if nothing has changed since the last attempt. It is a way of |
| 13645 | saying &"keep on trying, even though there are big problems"&. |
| 13646 | |
| 13647 | &*Note*&: This is an old option, which predates &%timeout_frozen_after%& and |
| 13648 | &%ignore_bounce_errors_after%&. It is retained for compatibility, but it is not |
| 13649 | thought to be very useful any more, and its use should probably be avoided. |
| 13650 | |
| 13651 | |
| 13652 | .option av_scanner main string "see below" |
| 13653 | This option is available if Exim is built with the content-scanning extension. |
| 13654 | It specifies which anti-virus scanner to use. The default value is: |
| 13655 | .code |
| 13656 | sophie:/var/run/sophie |
| 13657 | .endd |
| 13658 | If the value of &%av_scanner%& starts with a dollar character, it is expanded |
| 13659 | before use. See section &<<SECTscanvirus>>& for further details. |
| 13660 | |
| 13661 | |
| 13662 | .option bi_command main string unset |
| 13663 | .oindex "&%-bi%&" |
| 13664 | This option supplies the name of a command that is run when Exim is called with |
| 13665 | the &%-bi%& option (see chapter &<<CHAPcommandline>>&). The string value is |
| 13666 | just the command name, it is not a complete command line. If an argument is |
| 13667 | required, it must come from the &%-oA%& command line option. |
| 13668 | |
| 13669 | |
| 13670 | .option bounce_message_file main string unset |
| 13671 | .cindex "bounce message" "customizing" |
| 13672 | .cindex "customizing" "bounce message" |
| 13673 | This option defines a template file containing paragraphs of text to be used |
| 13674 | for constructing bounce messages. Details of the file's contents are given in |
| 13675 | chapter &<<CHAPemsgcust>>&. See also &%warn_message_file%&. |
| 13676 | |
| 13677 | |
| 13678 | .option bounce_message_text main string unset |
| 13679 | When this option is set, its contents are included in the default bounce |
| 13680 | message immediately after &"This message was created automatically by mail |
| 13681 | delivery software."& It is not used if &%bounce_message_file%& is set. |
| 13682 | |
| 13683 | .option bounce_return_body main boolean true |
| 13684 | .cindex "bounce message" "including body" |
| 13685 | This option controls whether the body of an incoming message is included in a |
| 13686 | bounce message when &%bounce_return_message%& is true. The default setting |
| 13687 | causes the entire message, both header and body, to be returned (subject to the |
| 13688 | value of &%bounce_return_size_limit%&). If this option is false, only the |
| 13689 | message header is included. In the case of a non-SMTP message containing an |
| 13690 | error that is detected during reception, only those header lines preceding the |
| 13691 | point at which the error was detected are returned. |
| 13692 | .cindex "bounce message" "including original" |
| 13693 | |
| 13694 | .option bounce_return_message main boolean true |
| 13695 | If this option is set false, none of the original message is included in |
| 13696 | bounce messages generated by Exim. See also &%bounce_return_size_limit%& and |
| 13697 | &%bounce_return_body%&. |
| 13698 | |
| 13699 | |
| 13700 | .option bounce_return_size_limit main integer 100K |
| 13701 | .cindex "size" "of bounce, limit" |
| 13702 | .cindex "bounce message" "size limit" |
| 13703 | .cindex "limit" "bounce message size" |
| 13704 | This option sets a limit in bytes on the size of messages that are returned to |
| 13705 | senders as part of bounce messages when &%bounce_return_message%& is true. The |
| 13706 | limit should be less than the value of the global &%message_size_limit%& and of |
| 13707 | any &%message_size_limit%& settings on transports, to allow for the bounce text |
| 13708 | that Exim generates. If this option is set to zero there is no limit. |
| 13709 | |
| 13710 | When the body of any message that is to be included in a bounce message is |
| 13711 | greater than the limit, it is truncated, and a comment pointing this out is |
| 13712 | added at the top. The actual cutoff may be greater than the value given, owing |
| 13713 | to the use of buffering for transferring the message in chunks (typically 8K in |
| 13714 | size). The idea is to save bandwidth on those undeliverable 15-megabyte |
| 13715 | messages. |
| 13716 | |
| 13717 | .option bounce_sender_authentication main string unset |
| 13718 | .cindex "bounce message" "sender authentication" |
| 13719 | .cindex "authentication" "bounce message" |
| 13720 | .cindex "AUTH" "on bounce message" |
| 13721 | This option provides an authenticated sender address that is sent with any |
| 13722 | bounce messages generated by Exim that are sent over an authenticated SMTP |
| 13723 | connection. A typical setting might be: |
| 13724 | .code |
| 13725 | bounce_sender_authentication = mailer-daemon@my.domain.example |
| 13726 | .endd |
| 13727 | which would cause bounce messages to be sent using the SMTP command: |
| 13728 | .code |
| 13729 | MAIL FROM:<> AUTH=mailer-daemon@my.domain.example |
| 13730 | .endd |
| 13731 | The value of &%bounce_sender_authentication%& must always be a complete email |
| 13732 | address. |
| 13733 | |
| 13734 | .option callout_domain_negative_expire main time 3h |
| 13735 | .cindex "caching" "callout timeouts" |
| 13736 | .cindex "callout" "caching timeouts" |
| 13737 | This option specifies the expiry time for negative callout cache data for a |
| 13738 | domain. See section &<<SECTcallver>>& for details of callout verification, and |
| 13739 | section &<<SECTcallvercache>>& for details of the caching. |
| 13740 | |
| 13741 | |
| 13742 | .option callout_domain_positive_expire main time 7d |
| 13743 | This option specifies the expiry time for positive callout cache data for a |
| 13744 | domain. See section &<<SECTcallver>>& for details of callout verification, and |
| 13745 | section &<<SECTcallvercache>>& for details of the caching. |
| 13746 | |
| 13747 | |
| 13748 | .option callout_negative_expire main time 2h |
| 13749 | This option specifies the expiry time for negative callout cache data for an |
| 13750 | address. See section &<<SECTcallver>>& for details of callout verification, and |
| 13751 | section &<<SECTcallvercache>>& for details of the caching. |
| 13752 | |
| 13753 | |
| 13754 | .option callout_positive_expire main time 24h |
| 13755 | This option specifies the expiry time for positive callout cache data for an |
| 13756 | address. See section &<<SECTcallver>>& for details of callout verification, and |
| 13757 | section &<<SECTcallvercache>>& for details of the caching. |
| 13758 | |
| 13759 | |
| 13760 | .option callout_random_local_part main string&!! "see below" |
| 13761 | This option defines the &"random"& local part that can be used as part of |
| 13762 | callout verification. The default value is |
| 13763 | .code |
| 13764 | $primary_hostname-$tod_epoch-testing |
| 13765 | .endd |
| 13766 | See section &<<CALLaddparcall>>& for details of how this value is used. |
| 13767 | |
| 13768 | |
| 13769 | .option check_log_inodes main integer 0 |
| 13770 | See &%check_spool_space%& below. |
| 13771 | |
| 13772 | |
| 13773 | .option check_log_space main integer 0 |
| 13774 | See &%check_spool_space%& below. |
| 13775 | |
| 13776 | .oindex "&%check_rfc2047_length%&" |
| 13777 | .cindex "RFC 2047" "disabling length check" |
| 13778 | .option check_rfc2047_length main boolean true |
| 13779 | RFC 2047 defines a way of encoding non-ASCII characters in headers using a |
| 13780 | system of &"encoded words"&. The RFC specifies a maximum length for an encoded |
| 13781 | word; strings to be encoded that exceed this length are supposed to use |
| 13782 | multiple encoded words. By default, Exim does not recognize encoded words that |
| 13783 | exceed the maximum length. However, it seems that some software, in violation |
| 13784 | of the RFC, generates overlong encoded words. If &%check_rfc2047_length%& is |
| 13785 | set false, Exim recognizes encoded words of any length. |
| 13786 | |
| 13787 | |
| 13788 | .option check_spool_inodes main integer 0 |
| 13789 | See &%check_spool_space%& below. |
| 13790 | |
| 13791 | |
| 13792 | .option check_spool_space main integer 0 |
| 13793 | .cindex "checking disk space" |
| 13794 | .cindex "disk space, checking" |
| 13795 | .cindex "spool directory" "checking space" |
| 13796 | The four &%check_...%& options allow for checking of disk resources before a |
| 13797 | message is accepted. |
| 13798 | |
| 13799 | .vindex "&$log_inodes$&" |
| 13800 | .vindex "&$log_space$&" |
| 13801 | .vindex "&$spool_inodes$&" |
| 13802 | .vindex "&$spool_space$&" |
| 13803 | When any of these options are set, they apply to all incoming messages. If you |
| 13804 | want to apply different checks to different kinds of message, you can do so by |
| 13805 | testing the variables &$log_inodes$&, &$log_space$&, &$spool_inodes$&, and |
| 13806 | &$spool_space$& in an ACL with appropriate additional conditions. |
| 13807 | |
| 13808 | |
| 13809 | &%check_spool_space%& and &%check_spool_inodes%& check the spool partition if |
| 13810 | either value is greater than zero, for example: |
| 13811 | .code |
| 13812 | check_spool_space = 10M |
| 13813 | check_spool_inodes = 100 |
| 13814 | .endd |
| 13815 | The spool partition is the one that contains the directory defined by |
| 13816 | SPOOL_DIRECTORY in &_Local/Makefile_&. It is used for holding messages in |
| 13817 | transit. |
| 13818 | |
| 13819 | &%check_log_space%& and &%check_log_inodes%& check the partition in which log |
| 13820 | files are written if either is greater than zero. These should be set only if |
| 13821 | &%log_file_path%& and &%spool_directory%& refer to different partitions. |
| 13822 | |
| 13823 | If there is less space or fewer inodes than requested, Exim refuses to accept |
| 13824 | incoming mail. In the case of SMTP input this is done by giving a 452 temporary |
| 13825 | error response to the MAIL command. If ESMTP is in use and there was a |
| 13826 | SIZE parameter on the MAIL command, its value is added to the |
| 13827 | &%check_spool_space%& value, and the check is performed even if |
| 13828 | &%check_spool_space%& is zero, unless &%no_smtp_check_spool_space%& is set. |
| 13829 | |
| 13830 | The values for &%check_spool_space%& and &%check_log_space%& are held as a |
| 13831 | number of kilobytes. If a non-multiple of 1024 is specified, it is rounded up. |
| 13832 | |
| 13833 | For non-SMTP input and for batched SMTP input, the test is done at start-up; on |
| 13834 | failure a message is written to stderr and Exim exits with a non-zero code, as |
| 13835 | it obviously cannot send an error message of any kind. |
| 13836 | |
| 13837 | .option daemon_smtp_ports main string &`smtp`& |
| 13838 | .cindex "port" "for daemon" |
| 13839 | .cindex "TCP/IP" "setting listening ports" |
| 13840 | This option specifies one or more default SMTP ports on which the Exim daemon |
| 13841 | listens. See chapter &<<CHAPinterfaces>>& for details of how it is used. For |
| 13842 | backward compatibility, &%daemon_smtp_port%& (singular) is a synonym. |
| 13843 | |
| 13844 | .option daemon_startup_retries main integer 9 |
| 13845 | .cindex "daemon startup, retrying" |
| 13846 | This option, along with &%daemon_startup_sleep%&, controls the retrying done by |
| 13847 | the daemon at startup when it cannot immediately bind a listening socket |
| 13848 | (typically because the socket is already in use): &%daemon_startup_retries%& |
| 13849 | defines the number of retries after the first failure, and |
| 13850 | &%daemon_startup_sleep%& defines the length of time to wait between retries. |
| 13851 | |
| 13852 | .option daemon_startup_sleep main time 30s |
| 13853 | See &%daemon_startup_retries%&. |
| 13854 | |
| 13855 | .option delay_warning main "time list" 24h |
| 13856 | .cindex "warning of delay" |
| 13857 | .cindex "delay warning, specifying" |
| 13858 | When a message is delayed, Exim sends a warning message to the sender at |
| 13859 | intervals specified by this option. The data is a colon-separated list of times |
| 13860 | after which to send warning messages. If the value of the option is an empty |
| 13861 | string or a zero time, no warnings are sent. Up to 10 times may be given. If a |
| 13862 | message has been on the queue for longer than the last time, the last interval |
| 13863 | between the times is used to compute subsequent warning times. For example, |
| 13864 | with |
| 13865 | .code |
| 13866 | delay_warning = 4h:8h:24h |
| 13867 | .endd |
| 13868 | the first message is sent after 4 hours, the second after 8 hours, and |
| 13869 | the third one after 24 hours. After that, messages are sent every 16 hours, |
| 13870 | because that is the interval between the last two times on the list. If you set |
| 13871 | just one time, it specifies the repeat interval. For example, with: |
| 13872 | .code |
| 13873 | delay_warning = 6h |
| 13874 | .endd |
| 13875 | messages are repeated every six hours. To stop warnings after a given time, set |
| 13876 | a very large time at the end of the list. For example: |
| 13877 | .code |
| 13878 | delay_warning = 2h:12h:99d |
| 13879 | .endd |
| 13880 | Note that the option is only evaluated at the time a delivery attempt fails, |
| 13881 | which depends on retry and queue-runner configuration. |
| 13882 | Typically retries will be configured more frequently than warning messages. |
| 13883 | |
| 13884 | .option delay_warning_condition main string&!! "see below" |
| 13885 | .vindex "&$domain$&" |
| 13886 | The string is expanded at the time a warning message might be sent. If all the |
| 13887 | deferred addresses have the same domain, it is set in &$domain$& during the |
| 13888 | expansion. Otherwise &$domain$& is empty. If the result of the expansion is a |
| 13889 | forced failure, an empty string, or a string matching any of &"0"&, &"no"& or |
| 13890 | &"false"& (the comparison being done caselessly) then the warning message is |
| 13891 | not sent. The default is: |
| 13892 | .code |
| 13893 | delay_warning_condition = ${if or {\ |
| 13894 | { !eq{$h_list-id:$h_list-post:$h_list-subscribe:}{} }\ |
| 13895 | { match{$h_precedence:}{(?i)bulk|list|junk} }\ |
| 13896 | { match{$h_auto-submitted:}{(?i)auto-generated|auto-replied} }\ |
| 13897 | } {no}{yes}} |
| 13898 | .endd |
| 13899 | This suppresses the sending of warnings for messages that contain &'List-ID:'&, |
| 13900 | &'List-Post:'&, or &'List-Subscribe:'& headers, or have &"bulk"&, &"list"& or |
| 13901 | &"junk"& in a &'Precedence:'& header, or have &"auto-generated"& or |
| 13902 | &"auto-replied"& in an &'Auto-Submitted:'& header. |
| 13903 | |
| 13904 | .option deliver_drop_privilege main boolean false |
| 13905 | .cindex "unprivileged delivery" |
| 13906 | .cindex "delivery" "unprivileged" |
| 13907 | If this option is set true, Exim drops its root privilege at the start of a |
| 13908 | delivery process, and runs as the Exim user throughout. This severely restricts |
| 13909 | the kinds of local delivery that are possible, but is viable in certain types |
| 13910 | of configuration. There is a discussion about the use of root privilege in |
| 13911 | chapter &<<CHAPsecurity>>&. |
| 13912 | |
| 13913 | .option deliver_queue_load_max main fixed-point unset |
| 13914 | .cindex "load average" |
| 13915 | .cindex "queue runner" "abandoning" |
| 13916 | When this option is set, a queue run is abandoned if the system load average |
| 13917 | becomes greater than the value of the option. The option has no effect on |
| 13918 | ancient operating systems on which Exim cannot determine the load average. |
| 13919 | See also &%queue_only_load%& and &%smtp_load_reserve%&. |
| 13920 | |
| 13921 | |
| 13922 | .option delivery_date_remove main boolean true |
| 13923 | .cindex "&'Delivery-date:'& header line" |
| 13924 | Exim's transports have an option for adding a &'Delivery-date:'& header to a |
| 13925 | message when it is delivered, in exactly the same way as &'Return-path:'& is |
| 13926 | handled. &'Delivery-date:'& records the actual time of delivery. Such headers |
| 13927 | should not be present in incoming messages, and this option causes them to be |
| 13928 | removed at the time the message is received, to avoid any problems that might |
| 13929 | occur when a delivered message is subsequently sent on to some other recipient. |
| 13930 | |
| 13931 | .option disable_fsync main boolean false |
| 13932 | .cindex "&[fsync()]&, disabling" |
| 13933 | This option is available only if Exim was built with the compile-time option |
| 13934 | ENABLE_DISABLE_FSYNC. When this is not set, a reference to &%disable_fsync%& in |
| 13935 | a runtime configuration generates an &"unknown option"& error. You should not |
| 13936 | build Exim with ENABLE_DISABLE_FSYNC or set &%disable_fsync%& unless you |
| 13937 | really, really, really understand what you are doing. &'No pre-compiled |
| 13938 | distributions of Exim should ever make this option available.'& |
| 13939 | |
| 13940 | When &%disable_fsync%& is set true, Exim no longer calls &[fsync()]& to force |
| 13941 | updated files' data to be written to disc before continuing. Unexpected events |
| 13942 | such as crashes and power outages may cause data to be lost or scrambled. |
| 13943 | Here be Dragons. &*Beware.*& |
| 13944 | |
| 13945 | |
| 13946 | .option disable_ipv6 main boolean false |
| 13947 | .cindex "IPv6" "disabling" |
| 13948 | If this option is set true, even if the Exim binary has IPv6 support, no IPv6 |
| 13949 | activities take place. AAAA records are never looked up, and any IPv6 addresses |
| 13950 | that are listed in &%local_interfaces%&, data for the &%manualroute%& router, |
| 13951 | etc. are ignored. If IP literals are enabled, the &(ipliteral)& router declines |
| 13952 | to handle IPv6 literal addresses. |
| 13953 | |
| 13954 | |
| 13955 | .option dns_again_means_nonexist main "domain list&!!" unset |
| 13956 | .cindex "DNS" "&""try again""& response; overriding" |
| 13957 | DNS lookups give a &"try again"& response for the DNS errors |
| 13958 | &"non-authoritative host not found"& and &"SERVERFAIL"&. This can cause Exim to |
| 13959 | keep trying to deliver a message, or to give repeated temporary errors to |
| 13960 | incoming mail. Sometimes the effect is caused by a badly set up name server and |
| 13961 | may persist for a long time. If a domain which exhibits this problem matches |
| 13962 | anything in &%dns_again_means_nonexist%&, it is treated as if it did not exist. |
| 13963 | This option should be used with care. You can make it apply to reverse lookups |
| 13964 | by a setting such as this: |
| 13965 | .code |
| 13966 | dns_again_means_nonexist = *.in-addr.arpa |
| 13967 | .endd |
| 13968 | This option applies to all DNS lookups that Exim does. It also applies when the |
| 13969 | &[gethostbyname()]& or &[getipnodebyname()]& functions give temporary errors, |
| 13970 | since these are most likely to be caused by DNS lookup problems. The |
| 13971 | &(dnslookup)& router has some options of its own for controlling what happens |
| 13972 | when lookups for MX or SRV records give temporary errors. These more specific |
| 13973 | options are applied after this global option. |
| 13974 | |
| 13975 | .option dns_check_names_pattern main string "see below" |
| 13976 | .cindex "DNS" "pre-check of name syntax" |
| 13977 | When this option is set to a non-empty string, it causes Exim to check domain |
| 13978 | names for characters that are not allowed in host names before handing them to |
| 13979 | the DNS resolver, because some resolvers give temporary errors for names that |
| 13980 | contain unusual characters. If a domain name contains any unwanted characters, |
| 13981 | a &"not found"& result is forced, and the resolver is not called. The check is |
| 13982 | done by matching the domain name against a regular expression, which is the |
| 13983 | value of this option. The default pattern is |
| 13984 | .code |
| 13985 | dns_check_names_pattern = \ |
| 13986 | (?i)^(?>(?(1)\.|())[^\W_](?>[a-z0-9/-]*[^\W_])?)+$ |
| 13987 | .endd |
| 13988 | which permits only letters, digits, slashes, and hyphens in components, but |
| 13989 | they must start and end with a letter or digit. Slashes are not, in fact, |
| 13990 | permitted in host names, but they are found in certain NS records (which can be |
| 13991 | accessed in Exim by using a &%dnsdb%& lookup). If you set |
| 13992 | &%allow_utf8_domains%&, you must modify this pattern, or set the option to an |
| 13993 | empty string. |
| 13994 | |
| 13995 | .option dns_csa_search_limit main integer 5 |
| 13996 | This option controls the depth of parental searching for CSA SRV records in the |
| 13997 | DNS, as described in more detail in section &<<SECTverifyCSA>>&. |
| 13998 | |
| 13999 | .option dns_csa_use_reverse main boolean true |
| 14000 | This option controls whether or not an IP address, given as a CSA domain, is |
| 14001 | reversed and looked up in the reverse DNS, as described in more detail in |
| 14002 | section &<<SECTverifyCSA>>&. |
| 14003 | |
| 14004 | |
| 14005 | .option dns_dnssec_ok main integer -1 |
| 14006 | .cindex "DNS" "resolver options" |
| 14007 | .cindex "DNS" "DNSSEC" |
| 14008 | If this option is set to a non-negative number then Exim will initialise the |
| 14009 | DNS resolver library to either use or not use DNSSEC, overriding the system |
| 14010 | default. A value of 0 coerces DNSSEC off, a value of 1 coerces DNSSEC on. |
| 14011 | |
| 14012 | If the resolver library does not support DNSSEC then this option has no effect. |
| 14013 | |
| 14014 | |
| 14015 | .option dns_ipv4_lookup main "domain list&!!" unset |
| 14016 | .cindex "IPv6" "DNS lookup for AAAA records" |
| 14017 | .cindex "DNS" "IPv6 lookup for AAAA records" |
| 14018 | When Exim is compiled with IPv6 support and &%disable_ipv6%& is not set, it |
| 14019 | looks for IPv6 address records (AAAA records) as well as IPv4 address records |
| 14020 | (A records) when trying to find IP addresses for hosts, unless the host's |
| 14021 | domain matches this list. |
| 14022 | |
| 14023 | This is a fudge to help with name servers that give big delays or otherwise do |
| 14024 | not work for the AAAA record type. In due course, when the world's name |
| 14025 | servers have all been upgraded, there should be no need for this option. |
| 14026 | |
| 14027 | |
| 14028 | .option dns_retrans main time 0s |
| 14029 | .cindex "DNS" "resolver options" |
| 14030 | The options &%dns_retrans%& and &%dns_retry%& can be used to set the |
| 14031 | retransmission and retry parameters for DNS lookups. Values of zero (the |
| 14032 | defaults) leave the system default settings unchanged. The first value is the |
| 14033 | time between retries, and the second is the number of retries. It isn't |
| 14034 | totally clear exactly how these settings affect the total time a DNS lookup may |
| 14035 | take. I haven't found any documentation about timeouts on DNS lookups; these |
| 14036 | parameter values are available in the external resolver interface structure, |
| 14037 | but nowhere does it seem to describe how they are used or what you might want |
| 14038 | to set in them. |
| 14039 | |
| 14040 | |
| 14041 | .option dns_retry main integer 0 |
| 14042 | See &%dns_retrans%& above. |
| 14043 | |
| 14044 | |
| 14045 | .option dns_use_edns0 main integer -1 |
| 14046 | .cindex "DNS" "resolver options" |
| 14047 | .cindex "DNS" "EDNS0" |
| 14048 | If this option is set to a non-negative number then Exim will initialise the |
| 14049 | DNS resolver library to either use or not use EDNS0 extensions, overriding |
| 14050 | the system default. A value of 0 coerces EDNS0 off, a value of 1 coerces EDNS0 |
| 14051 | on. |
| 14052 | |
| 14053 | If the resolver library does not support EDNS0 then this option has no effect. |
| 14054 | |
| 14055 | |
| 14056 | .option drop_cr main boolean false |
| 14057 | This is an obsolete option that is now a no-op. It used to affect the way Exim |
| 14058 | handled CR and LF characters in incoming messages. What happens now is |
| 14059 | described in section &<<SECTlineendings>>&. |
| 14060 | |
| 14061 | .option dsn_from main "string&!!" "see below" |
| 14062 | .cindex "&'From:'& header line" "in bounces" |
| 14063 | .cindex "bounce messages" "&'From:'& line, specifying" |
| 14064 | This option can be used to vary the contents of &'From:'& header lines in |
| 14065 | bounces and other automatically generated messages (&"Delivery Status |
| 14066 | Notifications"& &-- hence the name of the option). The default setting is: |
| 14067 | .code |
| 14068 | dsn_from = Mail Delivery System <Mailer-Daemon@$qualify_domain> |
| 14069 | .endd |
| 14070 | The value is expanded every time it is needed. If the expansion fails, a |
| 14071 | panic is logged, and the default value is used. |
| 14072 | |
| 14073 | .option envelope_to_remove main boolean true |
| 14074 | .cindex "&'Envelope-to:'& header line" |
| 14075 | Exim's transports have an option for adding an &'Envelope-to:'& header to a |
| 14076 | message when it is delivered, in exactly the same way as &'Return-path:'& is |
| 14077 | handled. &'Envelope-to:'& records the original recipient address from the |
| 14078 | messages's envelope that caused the delivery to happen. Such headers should not |
| 14079 | be present in incoming messages, and this option causes them to be removed at |
| 14080 | the time the message is received, to avoid any problems that might occur when a |
| 14081 | delivered message is subsequently sent on to some other recipient. |
| 14082 | |
| 14083 | |
| 14084 | .option errors_copy main "string list&!!" unset |
| 14085 | .cindex "bounce message" "copy to other address" |
| 14086 | .cindex "copy of bounce message" |
| 14087 | Setting this option causes Exim to send bcc copies of bounce messages that it |
| 14088 | generates to other addresses. &*Note*&: This does not apply to bounce messages |
| 14089 | coming from elsewhere. The value of the option is a colon-separated list of |
| 14090 | items. Each item consists of a pattern, terminated by white space, followed by |
| 14091 | a comma-separated list of email addresses. If a pattern contains spaces, it |
| 14092 | must be enclosed in double quotes. |
| 14093 | |
| 14094 | Each pattern is processed in the same way as a single item in an address list |
| 14095 | (see section &<<SECTaddresslist>>&). When a pattern matches the recipient of |
| 14096 | the bounce message, the message is copied to the addresses on the list. The |
| 14097 | items are scanned in order, and once a matching one is found, no further items |
| 14098 | are examined. For example: |
| 14099 | .code |
| 14100 | errors_copy = spqr@mydomain postmaster@mydomain.example :\ |
| 14101 | rqps@mydomain hostmaster@mydomain.example,\ |
| 14102 | postmaster@mydomain.example |
| 14103 | .endd |
| 14104 | .vindex "&$domain$&" |
| 14105 | .vindex "&$local_part$&" |
| 14106 | The address list is expanded before use. The expansion variables &$local_part$& |
| 14107 | and &$domain$& are set from the original recipient of the error message, and if |
| 14108 | there was any wildcard matching in the pattern, the expansion |
| 14109 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &%errors_copy%&" |
| 14110 | variables &$0$&, &$1$&, etc. are set in the normal way. |
| 14111 | |
| 14112 | |
| 14113 | .option errors_reply_to main string unset |
| 14114 | .cindex "bounce message" "&'Reply-to:'& in" |
| 14115 | By default, Exim's bounce and delivery warning messages contain the header line |
| 14116 | .display |
| 14117 | &`From: Mail Delivery System <Mailer-Daemon@`&&'qualify-domain'&&`>`& |
| 14118 | .endd |
| 14119 | .oindex &%quota_warn_message%& |
| 14120 | where &'qualify-domain'& is the value of the &%qualify_domain%& option. |
| 14121 | A warning message that is generated by the &%quota_warn_message%& option in an |
| 14122 | &(appendfile)& transport may contain its own &'From:'& header line that |
| 14123 | overrides the default. |
| 14124 | |
| 14125 | Experience shows that people reply to bounce messages. If the |
| 14126 | &%errors_reply_to%& option is set, a &'Reply-To:'& header is added to bounce |
| 14127 | and warning messages. For example: |
| 14128 | .code |
| 14129 | errors_reply_to = postmaster@my.domain.example |
| 14130 | .endd |
| 14131 | The value of the option is not expanded. It must specify a valid RFC 2822 |
| 14132 | address. However, if a warning message that is generated by the |
| 14133 | &%quota_warn_message%& option in an &(appendfile)& transport contain its |
| 14134 | own &'Reply-To:'& header line, the value of the &%errors_reply_to%& option is |
| 14135 | not used. |
| 14136 | |
| 14137 | |
| 14138 | .option exim_group main string "compile-time configured" |
| 14139 | .cindex "gid (group id)" "Exim's own" |
| 14140 | .cindex "Exim group" |
| 14141 | This option changes the gid under which Exim runs when it gives up root |
| 14142 | privilege. The default value is compiled into the binary. The value of this |
| 14143 | option is used only when &%exim_user%& is also set. Unless it consists entirely |
| 14144 | of digits, the string is looked up using &[getgrnam()]&, and failure causes a |
| 14145 | configuration error. See chapter &<<CHAPsecurity>>& for a discussion of |
| 14146 | security issues. |
| 14147 | |
| 14148 | |
| 14149 | .option exim_path main string "see below" |
| 14150 | .cindex "Exim binary, path name" |
| 14151 | This option specifies the path name of the Exim binary, which is used when Exim |
| 14152 | needs to re-exec itself. The default is set up to point to the file &'exim'& in |
| 14153 | the directory configured at compile time by the BIN_DIRECTORY setting. It |
| 14154 | is necessary to change &%exim_path%& if, exceptionally, Exim is run from some |
| 14155 | other place. |
| 14156 | &*Warning*&: Do not use a macro to define the value of this option, because |
| 14157 | you will break those Exim utilities that scan the configuration file to find |
| 14158 | where the binary is. (They then use the &%-bP%& option to extract option |
| 14159 | settings such as the value of &%spool_directory%&.) |
| 14160 | |
| 14161 | |
| 14162 | .option exim_user main string "compile-time configured" |
| 14163 | .cindex "uid (user id)" "Exim's own" |
| 14164 | .cindex "Exim user" |
| 14165 | This option changes the uid under which Exim runs when it gives up root |
| 14166 | privilege. The default value is compiled into the binary. Ownership of the run |
| 14167 | time configuration file and the use of the &%-C%& and &%-D%& command line |
| 14168 | options is checked against the values in the binary, not what is set here. |
| 14169 | |
| 14170 | Unless it consists entirely of digits, the string is looked up using |
| 14171 | &[getpwnam()]&, and failure causes a configuration error. If &%exim_group%& is |
| 14172 | not also supplied, the gid is taken from the result of &[getpwnam()]& if it is |
| 14173 | used. See chapter &<<CHAPsecurity>>& for a discussion of security issues. |
| 14174 | |
| 14175 | |
| 14176 | .option extra_local_interfaces main "string list" unset |
| 14177 | This option defines network interfaces that are to be considered local when |
| 14178 | routing, but which are not used for listening by the daemon. See section |
| 14179 | &<<SECTreclocipadd>>& for details. |
| 14180 | |
| 14181 | |
| 14182 | . Allow this long option name to split; give it unsplit as a fifth argument |
| 14183 | . for the automatic .oindex that is generated by .option. |
| 14184 | |
| 14185 | .option "extract_addresses_remove_ &~&~arguments" main boolean true &&& |
| 14186 | extract_addresses_remove_arguments |
| 14187 | .oindex "&%-t%&" |
| 14188 | .cindex "command line" "addresses with &%-t%&" |
| 14189 | .cindex "Sendmail compatibility" "&%-t%& option" |
| 14190 | According to some Sendmail documentation (Sun, IRIX, HP-UX), if any addresses |
| 14191 | are present on the command line when the &%-t%& option is used to build an |
| 14192 | envelope from a message's &'To:'&, &'Cc:'& and &'Bcc:'& headers, the command |
| 14193 | line addresses are removed from the recipients list. This is also how Smail |
| 14194 | behaves. However, other Sendmail documentation (the O'Reilly book) states that |
| 14195 | command line addresses are added to those obtained from the header lines. When |
| 14196 | &%extract_addresses_remove_arguments%& is true (the default), Exim subtracts |
| 14197 | argument headers. If it is set false, Exim adds rather than removes argument |
| 14198 | addresses. |
| 14199 | |
| 14200 | |
| 14201 | .option finduser_retries main integer 0 |
| 14202 | .cindex "NIS, retrying user lookups" |
| 14203 | On systems running NIS or other schemes in which user and group information is |
| 14204 | distributed from a remote system, there can be times when &[getpwnam()]& and |
| 14205 | related functions fail, even when given valid data, because things time out. |
| 14206 | Unfortunately these failures cannot be distinguished from genuine &"not found"& |
| 14207 | errors. If &%finduser_retries%& is set greater than zero, Exim will try that |
| 14208 | many extra times to find a user or a group, waiting for one second between |
| 14209 | retries. |
| 14210 | |
| 14211 | .cindex "&_/etc/passwd_&" "multiple reading of" |
| 14212 | You should not set this option greater than zero if your user information is in |
| 14213 | a traditional &_/etc/passwd_& file, because it will cause Exim needlessly to |
| 14214 | search the file multiple times for non-existent users, and also cause delay. |
| 14215 | |
| 14216 | |
| 14217 | |
| 14218 | .option freeze_tell main "string list, comma separated" unset |
| 14219 | .cindex "freezing messages" "sending a message when freezing" |
| 14220 | On encountering certain errors, or when configured to do so in a system filter, |
| 14221 | ACL, or special router, Exim freezes a message. This means that no further |
| 14222 | delivery attempts take place until an administrator thaws the message, or the |
| 14223 | &%auto_thaw%&, &%ignore_bounce_errors_after%&, or &%timeout_frozen_after%& |
| 14224 | feature cause it to be processed. If &%freeze_tell%& is set, Exim generates a |
| 14225 | warning message whenever it freezes something, unless the message it is |
| 14226 | freezing is a locally-generated bounce message. (Without this exception there |
| 14227 | is the possibility of looping.) The warning message is sent to the addresses |
| 14228 | supplied as the comma-separated value of this option. If several of the |
| 14229 | message's addresses cause freezing, only a single message is sent. If the |
| 14230 | freezing was automatic, the reason(s) for freezing can be found in the message |
| 14231 | log. If you configure freezing in a filter or ACL, you must arrange for any |
| 14232 | logging that you require. |
| 14233 | |
| 14234 | |
| 14235 | .option gecos_name main string&!! unset |
| 14236 | .cindex "HP-UX" |
| 14237 | .cindex "&""gecos""& field, parsing" |
| 14238 | Some operating systems, notably HP-UX, use the &"gecos"& field in the system |
| 14239 | password file to hold other information in addition to users' real names. Exim |
| 14240 | looks up this field for use when it is creating &'Sender:'& or &'From:'& |
| 14241 | headers. If either &%gecos_pattern%& or &%gecos_name%& are unset, the contents |
| 14242 | of the field are used unchanged, except that, if an ampersand is encountered, |
| 14243 | it is replaced by the user's login name with the first character forced to |
| 14244 | upper case, since this is a convention that is observed on many systems. |
| 14245 | |
| 14246 | When these options are set, &%gecos_pattern%& is treated as a regular |
| 14247 | expression that is to be applied to the field (again with && replaced by the |
| 14248 | login name), and if it matches, &%gecos_name%& is expanded and used as the |
| 14249 | user's name. |
| 14250 | |
| 14251 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &%gecos_name%&" |
| 14252 | Numeric variables such as &$1$&, &$2$&, etc. can be used in the expansion to |
| 14253 | pick up sub-fields that were matched by the pattern. In HP-UX, where the user's |
| 14254 | name terminates at the first comma, the following can be used: |
| 14255 | .code |
| 14256 | gecos_pattern = ([^,]*) |
| 14257 | gecos_name = $1 |
| 14258 | .endd |
| 14259 | |
| 14260 | .option gecos_pattern main string unset |
| 14261 | See &%gecos_name%& above. |
| 14262 | |
| 14263 | |
| 14264 | .option gnutls_compat_mode main boolean unset |
| 14265 | This option controls whether GnuTLS is used in compatibility mode in an Exim |
| 14266 | server. This reduces security slightly, but improves interworking with older |
| 14267 | implementations of TLS. |
| 14268 | |
| 14269 | |
| 14270 | option gnutls_allow_auto_pkcs11 main boolean unset |
| 14271 | This option will let GnuTLS (2.12.0 or later) autoload PKCS11 modules with |
| 14272 | the p11-kit configuration files in &_/etc/pkcs11/modules/_&. |
| 14273 | |
| 14274 | See |
| 14275 | &url(http://www.gnutls.org/manual/gnutls.html#Smart-cards-and-HSMs) |
| 14276 | for documentation. |
| 14277 | |
| 14278 | |
| 14279 | |
| 14280 | .option headers_charset main string "see below" |
| 14281 | This option sets a default character set for translating from encoded MIME |
| 14282 | &"words"& in header lines, when referenced by an &$h_xxx$& expansion item. The |
| 14283 | default is the value of HEADERS_CHARSET in &_Local/Makefile_&. The |
| 14284 | ultimate default is ISO-8859-1. For more details see the description of header |
| 14285 | insertions in section &<<SECTexpansionitems>>&. |
| 14286 | |
| 14287 | |
| 14288 | |
| 14289 | .option header_maxsize main integer "see below" |
| 14290 | .cindex "header section" "maximum size of" |
| 14291 | .cindex "limit" "size of message header section" |
| 14292 | This option controls the overall maximum size of a message's header |
| 14293 | section. The default is the value of HEADER_MAXSIZE in |
| 14294 | &_Local/Makefile_&; the default for that is 1M. Messages with larger header |
| 14295 | sections are rejected. |
| 14296 | |
| 14297 | |
| 14298 | .option header_line_maxsize main integer 0 |
| 14299 | .cindex "header lines" "maximum size of" |
| 14300 | .cindex "limit" "size of one header line" |
| 14301 | This option limits the length of any individual header line in a message, after |
| 14302 | all the continuations have been joined together. Messages with individual |
| 14303 | header lines that are longer than the limit are rejected. The default value of |
| 14304 | zero means &"no limit"&. |
| 14305 | |
| 14306 | |
| 14307 | |
| 14308 | |
| 14309 | .option helo_accept_junk_hosts main "host list&!!" unset |
| 14310 | .cindex "HELO" "accepting junk data" |
| 14311 | .cindex "EHLO" "accepting junk data" |
| 14312 | Exim checks the syntax of HELO and EHLO commands for incoming SMTP |
| 14313 | mail, and gives an error response for invalid data. Unfortunately, there are |
| 14314 | some SMTP clients that send syntactic junk. They can be accommodated by setting |
| 14315 | this option. Note that this is a syntax check only. See &%helo_verify_hosts%& |
| 14316 | if you want to do semantic checking. |
| 14317 | See also &%helo_allow_chars%& for a way of extending the permitted character |
| 14318 | set. |
| 14319 | |
| 14320 | |
| 14321 | .option helo_allow_chars main string unset |
| 14322 | .cindex "HELO" "underscores in" |
| 14323 | .cindex "EHLO" "underscores in" |
| 14324 | .cindex "underscore in EHLO/HELO" |
| 14325 | This option can be set to a string of rogue characters that are permitted in |
| 14326 | all EHLO and HELO names in addition to the standard letters, digits, |
| 14327 | hyphens, and dots. If you really must allow underscores, you can set |
| 14328 | .code |
| 14329 | helo_allow_chars = _ |
| 14330 | .endd |
| 14331 | Note that the value is one string, not a list. |
| 14332 | |
| 14333 | |
| 14334 | .option helo_lookup_domains main "domain list&!!" &`@:@[]`& |
| 14335 | .cindex "HELO" "forcing reverse lookup" |
| 14336 | .cindex "EHLO" "forcing reverse lookup" |
| 14337 | If the domain given by a client in a HELO or EHLO command matches this |
| 14338 | list, a reverse lookup is done in order to establish the host's true name. The |
| 14339 | default forces a lookup if the client host gives the server's name or any of |
| 14340 | its IP addresses (in brackets), something that broken clients have been seen to |
| 14341 | do. |
| 14342 | |
| 14343 | |
| 14344 | .option helo_try_verify_hosts main "host list&!!" unset |
| 14345 | .cindex "HELO verifying" "optional" |
| 14346 | .cindex "EHLO" "verifying, optional" |
| 14347 | By default, Exim just checks the syntax of HELO and EHLO commands (see |
| 14348 | &%helo_accept_junk_hosts%& and &%helo_allow_chars%&). However, some sites like |
| 14349 | to do more extensive checking of the data supplied by these commands. The ACL |
| 14350 | condition &`verify = helo`& is provided to make this possible. |
| 14351 | Formerly, it was necessary also to set this option (&%helo_try_verify_hosts%&) |
| 14352 | to force the check to occur. From release 4.53 onwards, this is no longer |
| 14353 | necessary. If the check has not been done before &`verify = helo`& is |
| 14354 | encountered, it is done at that time. Consequently, this option is obsolete. |
| 14355 | Its specification is retained here for backwards compatibility. |
| 14356 | |
| 14357 | When an EHLO or HELO command is received, if the calling host matches |
| 14358 | &%helo_try_verify_hosts%&, Exim checks that the host name given in the HELO or |
| 14359 | EHLO command either: |
| 14360 | |
| 14361 | .ilist |
| 14362 | is an IP literal matching the calling address of the host, or |
| 14363 | .next |
| 14364 | .cindex "DNS" "reverse lookup" |
| 14365 | .cindex "reverse DNS lookup" |
| 14366 | matches the host name that Exim obtains by doing a reverse lookup of the |
| 14367 | calling host address, or |
| 14368 | .next |
| 14369 | when looked up using &[gethostbyname()]& (or &[getipnodebyname()]& when |
| 14370 | available) yields the calling host address. |
| 14371 | .endlist |
| 14372 | |
| 14373 | However, the EHLO or HELO command is not rejected if any of the checks |
| 14374 | fail. Processing continues, but the result of the check is remembered, and can |
| 14375 | be detected later in an ACL by the &`verify = helo`& condition. |
| 14376 | |
| 14377 | .option helo_verify_hosts main "host list&!!" unset |
| 14378 | .cindex "HELO verifying" "mandatory" |
| 14379 | .cindex "EHLO" "verifying, mandatory" |
| 14380 | Like &%helo_try_verify_hosts%&, this option is obsolete, and retained only for |
| 14381 | backwards compatibility. For hosts that match this option, Exim checks the host |
| 14382 | name given in the HELO or EHLO in the same way as for |
| 14383 | &%helo_try_verify_hosts%&. If the check fails, the HELO or EHLO command is |
| 14384 | rejected with a 550 error, and entries are written to the main and reject logs. |
| 14385 | If a MAIL command is received before EHLO or HELO, it is rejected with a 503 |
| 14386 | error. |
| 14387 | |
| 14388 | .option hold_domains main "domain list&!!" unset |
| 14389 | .cindex "domain" "delaying delivery" |
| 14390 | .cindex "delivery" "delaying certain domains" |
| 14391 | This option allows mail for particular domains to be held on the queue |
| 14392 | manually. The option is overridden if a message delivery is forced with the |
| 14393 | &%-M%&, &%-qf%&, &%-Rf%& or &%-Sf%& options, and also while testing or |
| 14394 | verifying addresses using &%-bt%& or &%-bv%&. Otherwise, if a domain matches an |
| 14395 | item in &%hold_domains%&, no routing or delivery for that address is done, and |
| 14396 | it is deferred every time the message is looked at. |
| 14397 | |
| 14398 | This option is intended as a temporary operational measure for delaying the |
| 14399 | delivery of mail while some problem is being sorted out, or some new |
| 14400 | configuration tested. If you just want to delay the processing of some |
| 14401 | domains until a queue run occurs, you should use &%queue_domains%& or |
| 14402 | &%queue_smtp_domains%&, not &%hold_domains%&. |
| 14403 | |
| 14404 | A setting of &%hold_domains%& does not override Exim's code for removing |
| 14405 | messages from the queue if they have been there longer than the longest retry |
| 14406 | time in any retry rule. If you want to hold messages for longer than the normal |
| 14407 | retry times, insert a dummy retry rule with a long retry time. |
| 14408 | |
| 14409 | |
| 14410 | .option host_lookup main "host list&!!" unset |
| 14411 | .cindex "host name" "lookup, forcing" |
| 14412 | Exim does not look up the name of a calling host from its IP address unless it |
| 14413 | is required to compare against some host list, or the host matches |
| 14414 | &%helo_try_verify_hosts%& or &%helo_verify_hosts%&, or the host matches this |
| 14415 | option (which normally contains IP addresses rather than host names). The |
| 14416 | default configuration file contains |
| 14417 | .code |
| 14418 | host_lookup = * |
| 14419 | .endd |
| 14420 | which causes a lookup to happen for all hosts. If the expense of these lookups |
| 14421 | is felt to be too great, the setting can be changed or removed. |
| 14422 | |
| 14423 | After a successful reverse lookup, Exim does a forward lookup on the name it |
| 14424 | has obtained, to verify that it yields the IP address that it started with. If |
| 14425 | this check fails, Exim behaves as if the name lookup failed. |
| 14426 | |
| 14427 | .vindex "&$host_lookup_failed$&" |
| 14428 | .vindex "&$sender_host_name$&" |
| 14429 | After any kind of failure, the host name (in &$sender_host_name$&) remains |
| 14430 | unset, and &$host_lookup_failed$& is set to the string &"1"&. See also |
| 14431 | &%dns_again_means_nonexist%&, &%helo_lookup_domains%&, and |
| 14432 | &`verify = reverse_host_lookup`& in ACLs. |
| 14433 | |
| 14434 | |
| 14435 | .option host_lookup_order main "string list" &`bydns:byaddr`& |
| 14436 | This option specifies the order of different lookup methods when Exim is trying |
| 14437 | to find a host name from an IP address. The default is to do a DNS lookup |
| 14438 | first, and then to try a local lookup (using &[gethostbyaddr()]& or equivalent) |
| 14439 | if that fails. You can change the order of these lookups, or omit one entirely, |
| 14440 | if you want. |
| 14441 | |
| 14442 | &*Warning*&: The &"byaddr"& method does not always yield aliases when there are |
| 14443 | multiple PTR records in the DNS and the IP address is not listed in |
| 14444 | &_/etc/hosts_&. Different operating systems give different results in this |
| 14445 | case. That is why the default tries a DNS lookup first. |
| 14446 | |
| 14447 | |
| 14448 | |
| 14449 | .option host_reject_connection main "host list&!!" unset |
| 14450 | .cindex "host" "rejecting connections from" |
| 14451 | If this option is set, incoming SMTP calls from the hosts listed are rejected |
| 14452 | as soon as the connection is made. |
| 14453 | This option is obsolete, and retained only for backward compatibility, because |
| 14454 | nowadays the ACL specified by &%acl_smtp_connect%& can also reject incoming |
| 14455 | connections immediately. |
| 14456 | |
| 14457 | The ability to give an immediate rejection (either by this option or using an |
| 14458 | ACL) is provided for use in unusual cases. Many hosts will just try again, |
| 14459 | sometimes without much delay. Normally, it is better to use an ACL to reject |
| 14460 | incoming messages at a later stage, such as after RCPT commands. See |
| 14461 | chapter &<<CHAPACL>>&. |
| 14462 | |
| 14463 | |
| 14464 | .option hosts_connection_nolog main "host list&!!" unset |
| 14465 | .cindex "host" "not logging connections from" |
| 14466 | This option defines a list of hosts for which connection logging does not |
| 14467 | happen, even though the &%smtp_connection%& log selector is set. For example, |
| 14468 | you might want not to log SMTP connections from local processes, or from |
| 14469 | 127.0.0.1, or from your local LAN. This option is consulted in the main loop of |
| 14470 | the daemon; you should therefore strive to restrict its value to a short inline |
| 14471 | list of IP addresses and networks. To disable logging SMTP connections from |
| 14472 | local processes, you must create a host list with an empty item. For example: |
| 14473 | .code |
| 14474 | hosts_connection_nolog = : |
| 14475 | .endd |
| 14476 | If the &%smtp_connection%& log selector is not set, this option has no effect. |
| 14477 | |
| 14478 | |
| 14479 | |
| 14480 | .option hosts_treat_as_local main "domain list&!!" unset |
| 14481 | .cindex "local host" "domains treated as" |
| 14482 | .cindex "host" "treated as local" |
| 14483 | If this option is set, any host names that match the domain list are treated as |
| 14484 | if they were the local host when Exim is scanning host lists obtained from MX |
| 14485 | records |
| 14486 | or other sources. Note that the value of this option is a domain list, not a |
| 14487 | host list, because it is always used to check host names, not IP addresses. |
| 14488 | |
| 14489 | This option also applies when Exim is matching the special items |
| 14490 | &`@mx_any`&, &`@mx_primary`&, and &`@mx_secondary`& in a domain list (see |
| 14491 | section &<<SECTdomainlist>>&), and when checking the &%hosts%& option in the |
| 14492 | &(smtp)& transport for the local host (see the &%allow_localhost%& option in |
| 14493 | that transport). See also &%local_interfaces%&, &%extra_local_interfaces%&, and |
| 14494 | chapter &<<CHAPinterfaces>>&, which contains a discussion about local network |
| 14495 | interfaces and recognizing the local host. |
| 14496 | |
| 14497 | |
| 14498 | .option ibase_servers main "string list" unset |
| 14499 | .cindex "InterBase" "server list" |
| 14500 | This option provides a list of InterBase servers and associated connection data, |
| 14501 | to be used in conjunction with &(ibase)& lookups (see section &<<SECID72>>&). |
| 14502 | The option is available only if Exim has been built with InterBase support. |
| 14503 | |
| 14504 | |
| 14505 | |
| 14506 | .option ignore_bounce_errors_after main time 10w |
| 14507 | .cindex "bounce message" "discarding" |
| 14508 | .cindex "discarding bounce message" |
| 14509 | This option affects the processing of bounce messages that cannot be delivered, |
| 14510 | that is, those that suffer a permanent delivery failure. (Bounce messages that |
| 14511 | suffer temporary delivery failures are of course retried in the usual way.) |
| 14512 | |
| 14513 | After a permanent delivery failure, bounce messages are frozen, |
| 14514 | because there is no sender to whom they can be returned. When a frozen bounce |
| 14515 | message has been on the queue for more than the given time, it is unfrozen at |
| 14516 | the next queue run, and a further delivery is attempted. If delivery fails |
| 14517 | again, the bounce message is discarded. This makes it possible to keep failed |
| 14518 | bounce messages around for a shorter time than the normal maximum retry time |
| 14519 | for frozen messages. For example, |
| 14520 | .code |
| 14521 | ignore_bounce_errors_after = 12h |
| 14522 | .endd |
| 14523 | retries failed bounce message deliveries after 12 hours, discarding any further |
| 14524 | failures. If the value of this option is set to a zero time period, bounce |
| 14525 | failures are discarded immediately. Setting a very long time (as in the default |
| 14526 | value) has the effect of disabling this option. For ways of automatically |
| 14527 | dealing with other kinds of frozen message, see &%auto_thaw%& and |
| 14528 | &%timeout_frozen_after%&. |
| 14529 | |
| 14530 | |
| 14531 | .option ignore_fromline_hosts main "host list&!!" unset |
| 14532 | .cindex "&""From""& line" |
| 14533 | .cindex "UUCP" "&""From""& line" |
| 14534 | Some broken SMTP clients insist on sending a UUCP-like &"From&~"& line before |
| 14535 | the headers of a message. By default this is treated as the start of the |
| 14536 | message's body, which means that any following headers are not recognized as |
| 14537 | such. Exim can be made to ignore it by setting &%ignore_fromline_hosts%& to |
| 14538 | match those hosts that insist on sending it. If the sender is actually a local |
| 14539 | process rather than a remote host, and is using &%-bs%& to inject the messages, |
| 14540 | &%ignore_fromline_local%& must be set to achieve this effect. |
| 14541 | |
| 14542 | |
| 14543 | .option ignore_fromline_local main boolean false |
| 14544 | See &%ignore_fromline_hosts%& above. |
| 14545 | |
| 14546 | |
| 14547 | .option keep_malformed main time 4d |
| 14548 | This option specifies the length of time to keep messages whose spool files |
| 14549 | have been corrupted in some way. This should, of course, never happen. At the |
| 14550 | next attempt to deliver such a message, it gets removed. The incident is |
| 14551 | logged. |
| 14552 | |
| 14553 | |
| 14554 | .option ldap_ca_cert_dir main string unset |
| 14555 | .cindex "LDAP", "TLS CA certificate directory" |
| 14556 | This option indicates which directory contains CA certificates for verifying |
| 14557 | a TLS certificate presented by an LDAP server. |
| 14558 | While Exim does not provide a default value, your SSL library may. |
| 14559 | Analogous to &%tls_verify_certificates%& but as a client-side option for LDAP |
| 14560 | and constrained to be a directory. |
| 14561 | |
| 14562 | |
| 14563 | .option ldap_ca_cert_file main string unset |
| 14564 | .cindex "LDAP", "TLS CA certificate file" |
| 14565 | This option indicates which file contains CA certificates for verifying |
| 14566 | a TLS certificate presented by an LDAP server. |
| 14567 | While Exim does not provide a default value, your SSL library may. |
| 14568 | Analogous to &%tls_verify_certificates%& but as a client-side option for LDAP |
| 14569 | and constrained to be a file. |
| 14570 | |
| 14571 | |
| 14572 | .option ldap_cert_file main string unset |
| 14573 | .cindex "LDAP" "TLS client certificate file" |
| 14574 | This option indicates which file contains an TLS client certificate which |
| 14575 | Exim should present to the LDAP server during TLS negotiation. |
| 14576 | Should be used together with &%ldap_cert_key%&. |
| 14577 | |
| 14578 | |
| 14579 | .option ldap_cert_key main string unset |
| 14580 | .cindex "LDAP" "TLS client key file" |
| 14581 | This option indicates which file contains the secret/private key to use |
| 14582 | to prove identity to the LDAP server during TLS negotiation. |
| 14583 | Should be used together with &%ldap_cert_file%&, which contains the |
| 14584 | identity to be proven. |
| 14585 | |
| 14586 | |
| 14587 | .option ldap_cipher_suite main string unset |
| 14588 | .cindex "LDAP" "TLS cipher suite" |
| 14589 | This controls the TLS cipher-suite negotiation during TLS negotiation with |
| 14590 | the LDAP server. See &<<SECTreqciphssl>>& for more details of the format of |
| 14591 | cipher-suite options with OpenSSL (as used by LDAP client libraries). |
| 14592 | |
| 14593 | |
| 14594 | .option ldap_default_servers main "string list" unset |
| 14595 | .cindex "LDAP" "default servers" |
| 14596 | This option provides a list of LDAP servers which are tried in turn when an |
| 14597 | LDAP query does not contain a server. See section &<<SECTforldaque>>& for |
| 14598 | details of LDAP queries. This option is available only when Exim has been built |
| 14599 | with LDAP support. |
| 14600 | |
| 14601 | |
| 14602 | .option ldap_require_cert main string unset. |
| 14603 | .cindex "LDAP" "policy for LDAP server TLS cert presentation" |
| 14604 | This should be one of the values "hard", "demand", "allow", "try" or "never". |
| 14605 | A value other than one of these is interpreted as "never". |
| 14606 | See the entry "TLS_REQCERT" in your system man page for ldap.conf(5). |
| 14607 | Although Exim does not set a default, the LDAP library probably defaults |
| 14608 | to hard/demand. |
| 14609 | |
| 14610 | |
| 14611 | .option ldap_start_tls main boolean false |
| 14612 | .cindex "LDAP" "whether or not to negotiate TLS" |
| 14613 | If set, Exim will attempt to negotiate TLS with the LDAP server when |
| 14614 | connecting on a regular LDAP port. This is the LDAP equivalent of SMTP's |
| 14615 | "STARTTLS". This is distinct from using "ldaps", which is the LDAP form |
| 14616 | of SSL-on-connect. |
| 14617 | In the event of failure to negotiate TLS, the action taken is controlled |
| 14618 | by &%ldap_require_cert%&. |
| 14619 | |
| 14620 | |
| 14621 | .option ldap_version main integer unset |
| 14622 | .cindex "LDAP" "protocol version, forcing" |
| 14623 | This option can be used to force Exim to set a specific protocol version for |
| 14624 | LDAP. If it option is unset, it is shown by the &%-bP%& command line option as |
| 14625 | -1. When this is the case, the default is 3 if LDAP_VERSION3 is defined in |
| 14626 | the LDAP headers; otherwise it is 2. This option is available only when Exim |
| 14627 | has been built with LDAP support. |
| 14628 | |
| 14629 | |
| 14630 | |
| 14631 | .option local_from_check main boolean true |
| 14632 | .cindex "&'Sender:'& header line" "disabling addition of" |
| 14633 | .cindex "&'From:'& header line" "disabling checking of" |
| 14634 | When a message is submitted locally (that is, not over a TCP/IP connection) by |
| 14635 | an untrusted user, Exim removes any existing &'Sender:'& header line, and |
| 14636 | checks that the &'From:'& header line matches the login of the calling user and |
| 14637 | the domain specified by &%qualify_domain%&. |
| 14638 | |
| 14639 | &*Note*&: An unqualified address (no domain) in the &'From:'& header in a |
| 14640 | locally submitted message is automatically qualified by Exim, unless the |
| 14641 | &%-bnq%& command line option is used. |
| 14642 | |
| 14643 | You can use &%local_from_prefix%& and &%local_from_suffix%& to permit affixes |
| 14644 | on the local part. If the &'From:'& header line does not match, Exim adds a |
| 14645 | &'Sender:'& header with an address constructed from the calling user's login |
| 14646 | and the default qualify domain. |
| 14647 | |
| 14648 | If &%local_from_check%& is set false, the &'From:'& header check is disabled, |
| 14649 | and no &'Sender:'& header is ever added. If, in addition, you want to retain |
| 14650 | &'Sender:'& header lines supplied by untrusted users, you must also set |
| 14651 | &%local_sender_retain%& to be true. |
| 14652 | |
| 14653 | .cindex "envelope sender" |
| 14654 | These options affect only the header lines in the message. The envelope sender |
| 14655 | is still forced to be the login id at the qualify domain unless |
| 14656 | &%untrusted_set_sender%& permits the user to supply an envelope sender. |
| 14657 | |
| 14658 | For messages received over TCP/IP, an ACL can specify &"submission mode"& to |
| 14659 | request similar header line checking. See section &<<SECTthesenhea>>&, which |
| 14660 | has more details about &'Sender:'& processing. |
| 14661 | |
| 14662 | |
| 14663 | |
| 14664 | |
| 14665 | .option local_from_prefix main string unset |
| 14666 | When Exim checks the &'From:'& header line of locally submitted messages for |
| 14667 | matching the login id (see &%local_from_check%& above), it can be configured to |
| 14668 | ignore certain prefixes and suffixes in the local part of the address. This is |
| 14669 | done by setting &%local_from_prefix%& and/or &%local_from_suffix%& to |
| 14670 | appropriate lists, in the same form as the &%local_part_prefix%& and |
| 14671 | &%local_part_suffix%& router options (see chapter &<<CHAProutergeneric>>&). For |
| 14672 | example, if |
| 14673 | .code |
| 14674 | local_from_prefix = *- |
| 14675 | .endd |
| 14676 | is set, a &'From:'& line containing |
| 14677 | .code |
| 14678 | From: anything-user@your.domain.example |
| 14679 | .endd |
| 14680 | will not cause a &'Sender:'& header to be added if &'user@your.domain.example'& |
| 14681 | matches the actual sender address that is constructed from the login name and |
| 14682 | qualify domain. |
| 14683 | |
| 14684 | |
| 14685 | .option local_from_suffix main string unset |
| 14686 | See &%local_from_prefix%& above. |
| 14687 | |
| 14688 | |
| 14689 | .option local_interfaces main "string list" "see below" |
| 14690 | This option controls which network interfaces are used by the daemon for |
| 14691 | listening; they are also used to identify the local host when routing. Chapter |
| 14692 | &<<CHAPinterfaces>>& contains a full description of this option and the related |
| 14693 | options &%daemon_smtp_ports%&, &%extra_local_interfaces%&, |
| 14694 | &%hosts_treat_as_local%&, and &%tls_on_connect_ports%&. The default value for |
| 14695 | &%local_interfaces%& is |
| 14696 | .code |
| 14697 | local_interfaces = 0.0.0.0 |
| 14698 | .endd |
| 14699 | when Exim is built without IPv6 support; otherwise it is |
| 14700 | .code |
| 14701 | local_interfaces = <; ::0 ; 0.0.0.0 |
| 14702 | .endd |
| 14703 | |
| 14704 | .option local_scan_timeout main time 5m |
| 14705 | .cindex "timeout" "for &[local_scan()]& function" |
| 14706 | .cindex "&[local_scan()]& function" "timeout" |
| 14707 | This timeout applies to the &[local_scan()]& function (see chapter |
| 14708 | &<<CHAPlocalscan>>&). Zero means &"no timeout"&. If the timeout is exceeded, |
| 14709 | the incoming message is rejected with a temporary error if it is an SMTP |
| 14710 | message. For a non-SMTP message, the message is dropped and Exim ends with a |
| 14711 | non-zero code. The incident is logged on the main and reject logs. |
| 14712 | |
| 14713 | |
| 14714 | |
| 14715 | .option local_sender_retain main boolean false |
| 14716 | .cindex "&'Sender:'& header line" "retaining from local submission" |
| 14717 | When a message is submitted locally (that is, not over a TCP/IP connection) by |
| 14718 | an untrusted user, Exim removes any existing &'Sender:'& header line. If you |
| 14719 | do not want this to happen, you must set &%local_sender_retain%&, and you must |
| 14720 | also set &%local_from_check%& to be false (Exim will complain if you do not). |
| 14721 | See also the ACL modifier &`control = suppress_local_fixups`&. Section |
| 14722 | &<<SECTthesenhea>>& has more details about &'Sender:'& processing. |
| 14723 | |
| 14724 | |
| 14725 | |
| 14726 | |
| 14727 | .option localhost_number main string&!! unset |
| 14728 | .cindex "host" "locally unique number for" |
| 14729 | .cindex "message ids" "with multiple hosts" |
| 14730 | .vindex "&$localhost_number$&" |
| 14731 | Exim's message ids are normally unique only within the local host. If |
| 14732 | uniqueness among a set of hosts is required, each host must set a different |
| 14733 | value for the &%localhost_number%& option. The string is expanded immediately |
| 14734 | after reading the configuration file (so that a number can be computed from the |
| 14735 | host name, for example) and the result of the expansion must be a number in the |
| 14736 | range 0&--16 (or 0&--10 on operating systems with case-insensitive file |
| 14737 | systems). This is available in subsequent string expansions via the variable |
| 14738 | &$localhost_number$&. When &%localhost_number is set%&, the final two |
| 14739 | characters of the message id, instead of just being a fractional part of the |
| 14740 | time, are computed from the time and the local host number as described in |
| 14741 | section &<<SECTmessiden>>&. |
| 14742 | |
| 14743 | |
| 14744 | |
| 14745 | .option log_file_path main "string list&!!" "set at compile time" |
| 14746 | .cindex "log" "file path for" |
| 14747 | This option sets the path which is used to determine the names of Exim's log |
| 14748 | files, or indicates that logging is to be to syslog, or both. It is expanded |
| 14749 | when Exim is entered, so it can, for example, contain a reference to the host |
| 14750 | name. If no specific path is set for the log files at compile or run time, they |
| 14751 | are written in a sub-directory called &_log_& in Exim's spool directory. |
| 14752 | Chapter &<<CHAPlog>>& contains further details about Exim's logging, and |
| 14753 | section &<<SECTwhelogwri>>& describes how the contents of &%log_file_path%& are |
| 14754 | used. If this string is fixed at your installation (contains no expansion |
| 14755 | variables) it is recommended that you do not set this option in the |
| 14756 | configuration file, but instead supply the path using LOG_FILE_PATH in |
| 14757 | &_Local/Makefile_& so that it is available to Exim for logging errors detected |
| 14758 | early on &-- in particular, failure to read the configuration file. |
| 14759 | |
| 14760 | |
| 14761 | .option log_selector main string unset |
| 14762 | .cindex "log" "selectors" |
| 14763 | This option can be used to reduce or increase the number of things that Exim |
| 14764 | writes to its log files. Its argument is made up of names preceded by plus or |
| 14765 | minus characters. For example: |
| 14766 | .code |
| 14767 | log_selector = +arguments -retry_defer |
| 14768 | .endd |
| 14769 | A list of possible names and what they control is given in the chapter on |
| 14770 | logging, in section &<<SECTlogselector>>&. |
| 14771 | |
| 14772 | |
| 14773 | .option log_timezone main boolean false |
| 14774 | .cindex "log" "timezone for entries" |
| 14775 | .vindex "&$tod_log$&" |
| 14776 | .vindex "&$tod_zone$&" |
| 14777 | By default, the timestamps on log lines are in local time without the |
| 14778 | timezone. This means that if your timezone changes twice a year, the timestamps |
| 14779 | in log lines are ambiguous for an hour when the clocks go back. One way of |
| 14780 | avoiding this problem is to set the timezone to UTC. An alternative is to set |
| 14781 | &%log_timezone%& true. This turns on the addition of the timezone offset to |
| 14782 | timestamps in log lines. Turning on this option can add quite a lot to the size |
| 14783 | of log files because each line is extended by 6 characters. Note that the |
| 14784 | &$tod_log$& variable contains the log timestamp without the zone, but there is |
| 14785 | another variable called &$tod_zone$& that contains just the timezone offset. |
| 14786 | |
| 14787 | |
| 14788 | .option lookup_open_max main integer 25 |
| 14789 | .cindex "too many open files" |
| 14790 | .cindex "open files, too many" |
| 14791 | .cindex "file" "too many open" |
| 14792 | .cindex "lookup" "maximum open files" |
| 14793 | .cindex "limit" "open files for lookups" |
| 14794 | This option limits the number of simultaneously open files for single-key |
| 14795 | lookups that use regular files (that is, &(lsearch)&, &(dbm)&, and &(cdb)&). |
| 14796 | Exim normally keeps these files open during routing, because often the same |
| 14797 | file is required several times. If the limit is reached, Exim closes the least |
| 14798 | recently used file. Note that if you are using the &'ndbm'& library, it |
| 14799 | actually opens two files for each logical DBM database, though it still counts |
| 14800 | as one for the purposes of &%lookup_open_max%&. If you are getting &"too many |
| 14801 | open files"& errors with NDBM, you need to reduce the value of |
| 14802 | &%lookup_open_max%&. |
| 14803 | |
| 14804 | |
| 14805 | .option max_username_length main integer 0 |
| 14806 | .cindex "length of login name" |
| 14807 | .cindex "user name" "maximum length" |
| 14808 | .cindex "limit" "user name length" |
| 14809 | Some operating systems are broken in that they truncate long arguments to |
| 14810 | &[getpwnam()]& to eight characters, instead of returning &"no such user"&. If |
| 14811 | this option is set greater than zero, any attempt to call &[getpwnam()]& with |
| 14812 | an argument that is longer behaves as if &[getpwnam()]& failed. |
| 14813 | |
| 14814 | |
| 14815 | .option message_body_newlines main bool false |
| 14816 | .cindex "message body" "newlines in variables" |
| 14817 | .cindex "newline" "in message body variables" |
| 14818 | .vindex "&$message_body$&" |
| 14819 | .vindex "&$message_body_end$&" |
| 14820 | By default, newlines in the message body are replaced by spaces when setting |
| 14821 | the &$message_body$& and &$message_body_end$& expansion variables. If this |
| 14822 | option is set true, this no longer happens. |
| 14823 | |
| 14824 | |
| 14825 | .option message_body_visible main integer 500 |
| 14826 | .cindex "body of message" "visible size" |
| 14827 | .cindex "message body" "visible size" |
| 14828 | .vindex "&$message_body$&" |
| 14829 | .vindex "&$message_body_end$&" |
| 14830 | This option specifies how much of a message's body is to be included in the |
| 14831 | &$message_body$& and &$message_body_end$& expansion variables. |
| 14832 | |
| 14833 | |
| 14834 | .option message_id_header_domain main string&!! unset |
| 14835 | .cindex "&'Message-ID:'& header line" |
| 14836 | If this option is set, the string is expanded and used as the right hand side |
| 14837 | (domain) of the &'Message-ID:'& header that Exim creates if a |
| 14838 | locally-originated incoming message does not have one. &"Locally-originated"& |
| 14839 | means &"not received over TCP/IP."& |
| 14840 | Otherwise, the primary host name is used. |
| 14841 | Only letters, digits, dot and hyphen are accepted; any other characters are |
| 14842 | replaced by hyphens. If the expansion is forced to fail, or if the result is an |
| 14843 | empty string, the option is ignored. |
| 14844 | |
| 14845 | |
| 14846 | .option message_id_header_text main string&!! unset |
| 14847 | If this variable is set, the string is expanded and used to augment the text of |
| 14848 | the &'Message-id:'& header that Exim creates if a locally-originated incoming |
| 14849 | message does not have one. The text of this header is required by RFC 2822 to |
| 14850 | take the form of an address. By default, Exim uses its internal message id as |
| 14851 | the local part, and the primary host name as the domain. If this option is set, |
| 14852 | it is expanded, and provided the expansion is not forced to fail, and does not |
| 14853 | yield an empty string, the result is inserted into the header immediately |
| 14854 | before the @, separated from the internal message id by a dot. Any characters |
| 14855 | that are illegal in an address are automatically converted into hyphens. This |
| 14856 | means that variables such as &$tod_log$& can be used, because the spaces and |
| 14857 | colons will become hyphens. |
| 14858 | |
| 14859 | |
| 14860 | .option message_logs main boolean true |
| 14861 | .cindex "message logs" "disabling" |
| 14862 | .cindex "log" "message log; disabling" |
| 14863 | If this option is turned off, per-message log files are not created in the |
| 14864 | &_msglog_& spool sub-directory. This reduces the amount of disk I/O required by |
| 14865 | Exim, by reducing the number of files involved in handling a message from a |
| 14866 | minimum of four (header spool file, body spool file, delivery journal, and |
| 14867 | per-message log) to three. The other major I/O activity is Exim's main log, |
| 14868 | which is not affected by this option. |
| 14869 | |
| 14870 | |
| 14871 | .option message_size_limit main string&!! 50M |
| 14872 | .cindex "message" "size limit" |
| 14873 | .cindex "limit" "message size" |
| 14874 | .cindex "size" "of message, limit" |
| 14875 | This option limits the maximum size of message that Exim will process. The |
| 14876 | value is expanded for each incoming connection so, for example, it can be made |
| 14877 | to depend on the IP address of the remote host for messages arriving via |
| 14878 | TCP/IP. After expansion, the value must be a sequence of decimal digits, |
| 14879 | optionally followed by K or M. |
| 14880 | |
| 14881 | &*Note*&: This limit cannot be made to depend on a message's sender or any |
| 14882 | other properties of an individual message, because it has to be advertised in |
| 14883 | the server's response to EHLO. String expansion failure causes a temporary |
| 14884 | error. A value of zero means no limit, but its use is not recommended. See also |
| 14885 | &%bounce_return_size_limit%&. |
| 14886 | |
| 14887 | Incoming SMTP messages are failed with a 552 error if the limit is |
| 14888 | exceeded; locally-generated messages either get a stderr message or a delivery |
| 14889 | failure message to the sender, depending on the &%-oe%& setting. Rejection of |
| 14890 | an oversized message is logged in both the main and the reject logs. See also |
| 14891 | the generic transport option &%message_size_limit%&, which limits the size of |
| 14892 | message that an individual transport can process. |
| 14893 | |
| 14894 | If you use a virus-scanner and set this option to to a value larger than the |
| 14895 | maximum size that your virus-scanner is configured to support, you may get |
| 14896 | failures triggered by large mails. The right size to configure for the |
| 14897 | virus-scanner depends upon what data is passed and the options in use but it's |
| 14898 | probably safest to just set it to a little larger than this value. Eg, with a |
| 14899 | default Exim message size of 50M and a default ClamAV StreamMaxLength of 10M, |
| 14900 | some problems may result. |
| 14901 | |
| 14902 | A value of 0 will disable size limit checking; Exim will still advertise the |
| 14903 | SIZE extension in an EHLO response, but without a limit, so as to permit |
| 14904 | SMTP clients to still indicate the message size along with the MAIL verb. |
| 14905 | |
| 14906 | |
| 14907 | .option move_frozen_messages main boolean false |
| 14908 | .cindex "frozen messages" "moving" |
| 14909 | This option, which is available only if Exim has been built with the setting |
| 14910 | .code |
| 14911 | SUPPORT_MOVE_FROZEN_MESSAGES=yes |
| 14912 | .endd |
| 14913 | in &_Local/Makefile_&, causes frozen messages and their message logs to be |
| 14914 | moved from the &_input_& and &_msglog_& directories on the spool to &_Finput_& |
| 14915 | and &_Fmsglog_&, respectively. There is currently no support in Exim or the |
| 14916 | standard utilities for handling such moved messages, and they do not show up in |
| 14917 | lists generated by &%-bp%& or by the Exim monitor. |
| 14918 | |
| 14919 | |
| 14920 | .option mua_wrapper main boolean false |
| 14921 | Setting this option true causes Exim to run in a very restrictive mode in which |
| 14922 | it passes messages synchronously to a smart host. Chapter &<<CHAPnonqueueing>>& |
| 14923 | contains a full description of this facility. |
| 14924 | |
| 14925 | |
| 14926 | |
| 14927 | .option mysql_servers main "string list" unset |
| 14928 | .cindex "MySQL" "server list" |
| 14929 | This option provides a list of MySQL servers and associated connection data, to |
| 14930 | be used in conjunction with &(mysql)& lookups (see section &<<SECID72>>&). The |
| 14931 | option is available only if Exim has been built with MySQL support. |
| 14932 | |
| 14933 | |
| 14934 | .option never_users main "string list&!!" unset |
| 14935 | This option is expanded just once, at the start of Exim's processing. Local |
| 14936 | message deliveries are normally run in processes that are setuid to the |
| 14937 | recipient, and remote deliveries are normally run under Exim's own uid and gid. |
| 14938 | It is usually desirable to prevent any deliveries from running as root, as a |
| 14939 | safety precaution. |
| 14940 | |
| 14941 | When Exim is built, an option called FIXED_NEVER_USERS can be set to a |
| 14942 | list of users that must not be used for local deliveries. This list is fixed in |
| 14943 | the binary and cannot be overridden by the configuration file. By default, it |
| 14944 | contains just the single user name &"root"&. The &%never_users%& runtime option |
| 14945 | can be used to add more users to the fixed list. |
| 14946 | |
| 14947 | If a message is to be delivered as one of the users on the fixed list or the |
| 14948 | &%never_users%& list, an error occurs, and delivery is deferred. A common |
| 14949 | example is |
| 14950 | .code |
| 14951 | never_users = root:daemon:bin |
| 14952 | .endd |
| 14953 | Including root is redundant if it is also on the fixed list, but it does no |
| 14954 | harm. This option overrides the &%pipe_as_creator%& option of the &(pipe)& |
| 14955 | transport driver. |
| 14956 | |
| 14957 | |
| 14958 | .option openssl_options main "string list" "+no_sslv2" |
| 14959 | .cindex "OpenSSL "compatibility options" |
| 14960 | This option allows an administrator to adjust the SSL options applied |
| 14961 | by OpenSSL to connections. It is given as a space-separated list of items, |
| 14962 | each one to be +added or -subtracted from the current value. |
| 14963 | |
| 14964 | This option is only available if Exim is built against OpenSSL. The values |
| 14965 | available for this option vary according to the age of your OpenSSL install. |
| 14966 | The &"all"& value controls a subset of flags which are available, typically |
| 14967 | the bug workaround options. The &'SSL_CTX_set_options'& man page will |
| 14968 | list the values known on your system and Exim should support all the |
| 14969 | &"bug workaround"& options and many of the &"modifying"& options. The Exim |
| 14970 | names lose the leading &"SSL_OP_"& and are lower-cased. |
| 14971 | |
| 14972 | Note that adjusting the options can have severe impact upon the security of |
| 14973 | SSL as used by Exim. It is possible to disable safety checks and shoot |
| 14974 | yourself in the foot in various unpleasant ways. This option should not be |
| 14975 | adjusted lightly. An unrecognised item will be detected at startup, by |
| 14976 | invoking Exim with the &%-bV%& flag. |
| 14977 | |
| 14978 | Historical note: prior to release 4.80, Exim defaulted this value to |
| 14979 | "+dont_insert_empty_fragments", which may still be needed for compatibility |
| 14980 | with some clients, but which lowers security by increasing exposure to |
| 14981 | some now infamous attacks. |
| 14982 | |
| 14983 | An example: |
| 14984 | .code |
| 14985 | # Make both old MS and old Eudora happy: |
| 14986 | openssl_options = -all +microsoft_big_sslv3_buffer \ |
| 14987 | +dont_insert_empty_fragments |
| 14988 | .endd |
| 14989 | |
| 14990 | Possible options may include: |
| 14991 | .ilist |
| 14992 | &`all`& |
| 14993 | .next |
| 14994 | &`allow_unsafe_legacy_renegotiation`& |
| 14995 | .next |
| 14996 | &`cipher_server_preference`& |
| 14997 | .next |
| 14998 | &`dont_insert_empty_fragments`& |
| 14999 | .next |
| 15000 | &`ephemeral_rsa`& |
| 15001 | .next |
| 15002 | &`legacy_server_connect`& |
| 15003 | .next |
| 15004 | &`microsoft_big_sslv3_buffer`& |
| 15005 | .next |
| 15006 | &`microsoft_sess_id_bug`& |
| 15007 | .next |
| 15008 | &`msie_sslv2_rsa_padding`& |
| 15009 | .next |
| 15010 | &`netscape_challenge_bug`& |
| 15011 | .next |
| 15012 | &`netscape_reuse_cipher_change_bug`& |
| 15013 | .next |
| 15014 | &`no_compression`& |
| 15015 | .next |
| 15016 | &`no_session_resumption_on_renegotiation`& |
| 15017 | .next |
| 15018 | &`no_sslv2`& |
| 15019 | .next |
| 15020 | &`no_sslv3`& |
| 15021 | .next |
| 15022 | &`no_ticket`& |
| 15023 | .next |
| 15024 | &`no_tlsv1`& |
| 15025 | .next |
| 15026 | &`no_tlsv1_1`& |
| 15027 | .next |
| 15028 | &`no_tlsv1_2`& |
| 15029 | .next |
| 15030 | &`safari_ecdhe_ecdsa_bug`& |
| 15031 | .next |
| 15032 | &`single_dh_use`& |
| 15033 | .next |
| 15034 | &`single_ecdh_use`& |
| 15035 | .next |
| 15036 | &`ssleay_080_client_dh_bug`& |
| 15037 | .next |
| 15038 | &`sslref2_reuse_cert_type_bug`& |
| 15039 | .next |
| 15040 | &`tls_block_padding_bug`& |
| 15041 | .next |
| 15042 | &`tls_d5_bug`& |
| 15043 | .next |
| 15044 | &`tls_rollback_bug`& |
| 15045 | .endlist |
| 15046 | |
| 15047 | As an aside, the &`safari_ecdhe_ecdsa_bug`& item is a misnomer and affects |
| 15048 | all clients connecting using the MacOS SecureTransport TLS facility prior |
| 15049 | to MacOS 10.8.4, including email clients. If you see old MacOS clients failing |
| 15050 | to negotiate TLS then this option value might help, provided that your OpenSSL |
| 15051 | release is new enough to contain this work-around. This may be a situation |
| 15052 | where you have to upgrade OpenSSL to get buggy clients working. |
| 15053 | |
| 15054 | |
| 15055 | .option oracle_servers main "string list" unset |
| 15056 | .cindex "Oracle" "server list" |
| 15057 | This option provides a list of Oracle servers and associated connection data, |
| 15058 | to be used in conjunction with &(oracle)& lookups (see section &<<SECID72>>&). |
| 15059 | The option is available only if Exim has been built with Oracle support. |
| 15060 | |
| 15061 | |
| 15062 | .option percent_hack_domains main "domain list&!!" unset |
| 15063 | .cindex "&""percent hack""&" |
| 15064 | .cindex "source routing" "in email address" |
| 15065 | .cindex "address" "source-routed" |
| 15066 | The &"percent hack"& is the convention whereby a local part containing a |
| 15067 | percent sign is re-interpreted as a new email address, with the percent |
| 15068 | replaced by @. This is sometimes called &"source routing"&, though that term is |
| 15069 | also applied to RFC 2822 addresses that begin with an @ character. If this |
| 15070 | option is set, Exim implements the percent facility for those domains listed, |
| 15071 | but no others. This happens before an incoming SMTP address is tested against |
| 15072 | an ACL. |
| 15073 | |
| 15074 | &*Warning*&: The &"percent hack"& has often been abused by people who are |
| 15075 | trying to get round relaying restrictions. For this reason, it is best avoided |
| 15076 | if at all possible. Unfortunately, a number of less security-conscious MTAs |
| 15077 | implement it unconditionally. If you are running Exim on a gateway host, and |
| 15078 | routing mail through to internal MTAs without processing the local parts, it is |
| 15079 | a good idea to reject recipient addresses with percent characters in their |
| 15080 | local parts. Exim's default configuration does this. |
| 15081 | |
| 15082 | |
| 15083 | .option perl_at_start main boolean false |
| 15084 | This option is available only when Exim is built with an embedded Perl |
| 15085 | interpreter. See chapter &<<CHAPperl>>& for details of its use. |
| 15086 | |
| 15087 | |
| 15088 | .option perl_startup main string unset |
| 15089 | This option is available only when Exim is built with an embedded Perl |
| 15090 | interpreter. See chapter &<<CHAPperl>>& for details of its use. |
| 15091 | |
| 15092 | |
| 15093 | .option pgsql_servers main "string list" unset |
| 15094 | .cindex "PostgreSQL lookup type" "server list" |
| 15095 | This option provides a list of PostgreSQL servers and associated connection |
| 15096 | data, to be used in conjunction with &(pgsql)& lookups (see section |
| 15097 | &<<SECID72>>&). The option is available only if Exim has been built with |
| 15098 | PostgreSQL support. |
| 15099 | |
| 15100 | |
| 15101 | .option pid_file_path main string&!! "set at compile time" |
| 15102 | .cindex "daemon" "pid file path" |
| 15103 | .cindex "pid file, path for" |
| 15104 | This option sets the name of the file to which the Exim daemon writes its |
| 15105 | process id. The string is expanded, so it can contain, for example, references |
| 15106 | to the host name: |
| 15107 | .code |
| 15108 | pid_file_path = /var/log/$primary_hostname/exim.pid |
| 15109 | .endd |
| 15110 | If no path is set, the pid is written to the file &_exim-daemon.pid_& in Exim's |
| 15111 | spool directory. |
| 15112 | The value set by the option can be overridden by the &%-oP%& command line |
| 15113 | option. A pid file is not written if a &"non-standard"& daemon is run by means |
| 15114 | of the &%-oX%& option, unless a path is explicitly supplied by &%-oP%&. |
| 15115 | |
| 15116 | |
| 15117 | .option pipelining_advertise_hosts main "host list&!!" * |
| 15118 | .cindex "PIPELINING" "suppressing advertising" |
| 15119 | This option can be used to suppress the advertisement of the SMTP |
| 15120 | PIPELINING extension to specific hosts. See also the &*no_pipelining*& |
| 15121 | control in section &<<SECTcontrols>>&. When PIPELINING is not advertised and |
| 15122 | &%smtp_enforce_sync%& is true, an Exim server enforces strict synchronization |
| 15123 | for each SMTP command and response. When PIPELINING is advertised, Exim assumes |
| 15124 | that clients will use it; &"out of order"& commands that are &"expected"& do |
| 15125 | not count as protocol errors (see &%smtp_max_synprot_errors%&). |
| 15126 | |
| 15127 | |
| 15128 | .option prdr_enable main boolean false |
| 15129 | .cindex "PRDR" "enabling on server" |
| 15130 | This option can be used to enable the Per-Recipient Data Response extension |
| 15131 | to SMTP, defined by Eric Hall. |
| 15132 | If the option is set, PRDR is advertised by Exim when operating as a server. |
| 15133 | If the client requests PRDR, and more than one recipient, for a message |
| 15134 | an additional ACL is called for each recipient after the message content |
| 15135 | is recieved. See section &<<SECTPRDRACL>>&. |
| 15136 | |
| 15137 | .option preserve_message_logs main boolean false |
| 15138 | .cindex "message logs" "preserving" |
| 15139 | If this option is set, message log files are not deleted when messages are |
| 15140 | completed. Instead, they are moved to a sub-directory of the spool directory |
| 15141 | called &_msglog.OLD_&, where they remain available for statistical or debugging |
| 15142 | purposes. This is a dangerous option to set on systems with any appreciable |
| 15143 | volume of mail. Use with care! |
| 15144 | |
| 15145 | |
| 15146 | .option primary_hostname main string "see below" |
| 15147 | .cindex "name" "of local host" |
| 15148 | .cindex "host" "name of local" |
| 15149 | .cindex "local host" "name of" |
| 15150 | .vindex "&$primary_hostname$&" |
| 15151 | This specifies the name of the current host. It is used in the default EHLO or |
| 15152 | HELO command for outgoing SMTP messages (changeable via the &%helo_data%& |
| 15153 | option in the &(smtp)& transport), and as the default for &%qualify_domain%&. |
| 15154 | The value is also used by default in some SMTP response messages from an Exim |
| 15155 | server. This can be changed dynamically by setting &%smtp_active_hostname%&. |
| 15156 | |
| 15157 | If &%primary_hostname%& is not set, Exim calls &[uname()]& to find the host |
| 15158 | name. If this fails, Exim panics and dies. If the name returned by &[uname()]& |
| 15159 | contains only one component, Exim passes it to &[gethostbyname()]& (or |
| 15160 | &[getipnodebyname()]& when available) in order to obtain the fully qualified |
| 15161 | version. The variable &$primary_hostname$& contains the host name, whether set |
| 15162 | explicitly by this option, or defaulted. |
| 15163 | |
| 15164 | |
| 15165 | .option print_topbitchars main boolean false |
| 15166 | .cindex "printing characters" |
| 15167 | .cindex "8-bit characters" |
| 15168 | By default, Exim considers only those characters whose codes lie in the range |
| 15169 | 32&--126 to be printing characters. In a number of circumstances (for example, |
| 15170 | when writing log entries) non-printing characters are converted into escape |
| 15171 | sequences, primarily to avoid messing up the layout. If &%print_topbitchars%& |
| 15172 | is set, code values of 128 and above are also considered to be printing |
| 15173 | characters. |
| 15174 | |
| 15175 | This option also affects the header syntax checks performed by the |
| 15176 | &(autoreply)& transport, and whether Exim uses RFC 2047 encoding of |
| 15177 | the user's full name when constructing From: and Sender: addresses (as |
| 15178 | described in section &<<SECTconstr>>&). Setting this option can cause |
| 15179 | Exim to generate eight bit message headers that do not conform to the |
| 15180 | standards. |
| 15181 | |
| 15182 | |
| 15183 | .option process_log_path main string unset |
| 15184 | .cindex "process log path" |
| 15185 | .cindex "log" "process log" |
| 15186 | .cindex "&'exiwhat'&" |
| 15187 | This option sets the name of the file to which an Exim process writes its |
| 15188 | &"process log"& when sent a USR1 signal. This is used by the &'exiwhat'& |
| 15189 | utility script. If this option is unset, the file called &_exim-process.info_& |
| 15190 | in Exim's spool directory is used. The ability to specify the name explicitly |
| 15191 | can be useful in environments where two different Exims are running, using |
| 15192 | different spool directories. |
| 15193 | |
| 15194 | |
| 15195 | .option prod_requires_admin main boolean true |
| 15196 | .oindex "&%-M%&" |
| 15197 | .oindex "&%-R%&" |
| 15198 | .oindex "&%-q%&" |
| 15199 | The &%-M%&, &%-R%&, and &%-q%& command-line options require the caller to be an |
| 15200 | admin user unless &%prod_requires_admin%& is set false. See also |
| 15201 | &%queue_list_requires_admin%&. |
| 15202 | |
| 15203 | |
| 15204 | .option qualify_domain main string "see below" |
| 15205 | .cindex "domain" "for qualifying addresses" |
| 15206 | .cindex "address" "qualification" |
| 15207 | This option specifies the domain name that is added to any envelope sender |
| 15208 | addresses that do not have a domain qualification. It also applies to |
| 15209 | recipient addresses if &%qualify_recipient%& is not set. Unqualified addresses |
| 15210 | are accepted by default only for locally-generated messages. Qualification is |
| 15211 | also applied to addresses in header lines such as &'From:'& and &'To:'& for |
| 15212 | locally-generated messages, unless the &%-bnq%& command line option is used. |
| 15213 | |
| 15214 | Messages from external sources must always contain fully qualified addresses, |
| 15215 | unless the sending host matches &%sender_unqualified_hosts%& or |
| 15216 | &%recipient_unqualified_hosts%& (as appropriate), in which case incoming |
| 15217 | addresses are qualified with &%qualify_domain%& or &%qualify_recipient%& as |
| 15218 | necessary. Internally, Exim always works with fully qualified envelope |
| 15219 | addresses. If &%qualify_domain%& is not set, it defaults to the |
| 15220 | &%primary_hostname%& value. |
| 15221 | |
| 15222 | |
| 15223 | .option qualify_recipient main string "see below" |
| 15224 | This option allows you to specify a different domain for qualifying recipient |
| 15225 | addresses to the one that is used for senders. See &%qualify_domain%& above. |
| 15226 | |
| 15227 | |
| 15228 | |
| 15229 | .option queue_domains main "domain list&!!" unset |
| 15230 | .cindex "domain" "specifying non-immediate delivery" |
| 15231 | .cindex "queueing incoming messages" |
| 15232 | .cindex "message" "queueing certain domains" |
| 15233 | This option lists domains for which immediate delivery is not required. |
| 15234 | A delivery process is started whenever a message is received, but only those |
| 15235 | domains that do not match are processed. All other deliveries wait until the |
| 15236 | next queue run. See also &%hold_domains%& and &%queue_smtp_domains%&. |
| 15237 | |
| 15238 | |
| 15239 | .option queue_list_requires_admin main boolean true |
| 15240 | .oindex "&%-bp%&" |
| 15241 | The &%-bp%& command-line option, which lists the messages that are on the |
| 15242 | queue, requires the caller to be an admin user unless |
| 15243 | &%queue_list_requires_admin%& is set false. See also &%prod_requires_admin%&. |
| 15244 | |
| 15245 | |
| 15246 | .option queue_only main boolean false |
| 15247 | .cindex "queueing incoming messages" |
| 15248 | .cindex "message" "queueing unconditionally" |
| 15249 | If &%queue_only%& is set, a delivery process is not automatically started |
| 15250 | whenever a message is received. Instead, the message waits on the queue for the |
| 15251 | next queue run. Even if &%queue_only%& is false, incoming messages may not get |
| 15252 | delivered immediately when certain conditions (such as heavy load) occur. |
| 15253 | |
| 15254 | The &%-odq%& command line has the same effect as &%queue_only%&. The &%-odb%& |
| 15255 | and &%-odi%& command line options override &%queue_only%& unless |
| 15256 | &%queue_only_override%& is set false. See also &%queue_only_file%&, |
| 15257 | &%queue_only_load%&, and &%smtp_accept_queue%&. |
| 15258 | |
| 15259 | |
| 15260 | .option queue_only_file main string unset |
| 15261 | .cindex "queueing incoming messages" |
| 15262 | .cindex "message" "queueing by file existence" |
| 15263 | This option can be set to a colon-separated list of absolute path names, each |
| 15264 | one optionally preceded by &"smtp"&. When Exim is receiving a message, |
| 15265 | it tests for the existence of each listed path using a call to &[stat()]&. For |
| 15266 | each path that exists, the corresponding queueing option is set. |
| 15267 | For paths with no prefix, &%queue_only%& is set; for paths prefixed by |
| 15268 | &"smtp"&, &%queue_smtp_domains%& is set to match all domains. So, for example, |
| 15269 | .code |
| 15270 | queue_only_file = smtp/some/file |
| 15271 | .endd |
| 15272 | causes Exim to behave as if &%queue_smtp_domains%& were set to &"*"& whenever |
| 15273 | &_/some/file_& exists. |
| 15274 | |
| 15275 | |
| 15276 | .option queue_only_load main fixed-point unset |
| 15277 | .cindex "load average" |
| 15278 | .cindex "queueing incoming messages" |
| 15279 | .cindex "message" "queueing by load" |
| 15280 | If the system load average is higher than this value, incoming messages from |
| 15281 | all sources are queued, and no automatic deliveries are started. If this |
| 15282 | happens during local or remote SMTP input, all subsequent messages received on |
| 15283 | the same SMTP connection are queued by default, whatever happens to the load in |
| 15284 | the meantime, but this can be changed by setting &%queue_only_load_latch%& |
| 15285 | false. |
| 15286 | |
| 15287 | Deliveries will subsequently be performed by queue runner processes. This |
| 15288 | option has no effect on ancient operating systems on which Exim cannot |
| 15289 | determine the load average. See also &%deliver_queue_load_max%& and |
| 15290 | &%smtp_load_reserve%&. |
| 15291 | |
| 15292 | |
| 15293 | .option queue_only_load_latch main boolean true |
| 15294 | .cindex "load average" "re-evaluating per message" |
| 15295 | When this option is true (the default), once one message has been queued |
| 15296 | because the load average is higher than the value set by &%queue_only_load%&, |
| 15297 | all subsequent messages received on the same SMTP connection are also queued. |
| 15298 | This is a deliberate choice; even though the load average may fall below the |
| 15299 | threshold, it doesn't seem right to deliver later messages on the same |
| 15300 | connection when not delivering earlier ones. However, there are special |
| 15301 | circumstances such as very long-lived connections from scanning appliances |
| 15302 | where this is not the best strategy. In such cases, &%queue_only_load_latch%& |
| 15303 | should be set false. This causes the value of the load average to be |
| 15304 | re-evaluated for each message. |
| 15305 | |
| 15306 | |
| 15307 | .option queue_only_override main boolean true |
| 15308 | .cindex "queueing incoming messages" |
| 15309 | When this option is true, the &%-od%&&'x'& command line options override the |
| 15310 | setting of &%queue_only%& or &%queue_only_file%& in the configuration file. If |
| 15311 | &%queue_only_override%& is set false, the &%-od%&&'x'& options cannot be used |
| 15312 | to override; they are accepted, but ignored. |
| 15313 | |
| 15314 | |
| 15315 | .option queue_run_in_order main boolean false |
| 15316 | .cindex "queue runner" "processing messages in order" |
| 15317 | If this option is set, queue runs happen in order of message arrival instead of |
| 15318 | in an arbitrary order. For this to happen, a complete list of the entire queue |
| 15319 | must be set up before the deliveries start. When the queue is all held in a |
| 15320 | single directory (the default), a single list is created for both the ordered |
| 15321 | and the non-ordered cases. However, if &%split_spool_directory%& is set, a |
| 15322 | single list is not created when &%queue_run_in_order%& is false. In this case, |
| 15323 | the sub-directories are processed one at a time (in a random order), and this |
| 15324 | avoids setting up one huge list for the whole queue. Thus, setting |
| 15325 | &%queue_run_in_order%& with &%split_spool_directory%& may degrade performance |
| 15326 | when the queue is large, because of the extra work in setting up the single, |
| 15327 | large list. In most situations, &%queue_run_in_order%& should not be set. |
| 15328 | |
| 15329 | |
| 15330 | |
| 15331 | .option queue_run_max main integer 5 |
| 15332 | .cindex "queue runner" "maximum number of" |
| 15333 | This controls the maximum number of queue runner processes that an Exim daemon |
| 15334 | can run simultaneously. This does not mean that it starts them all at once, |
| 15335 | but rather that if the maximum number are still running when the time comes to |
| 15336 | start another one, it refrains from starting another one. This can happen with |
| 15337 | very large queues and/or very sluggish deliveries. This option does not, |
| 15338 | however, interlock with other processes, so additional queue runners can be |
| 15339 | started by other means, or by killing and restarting the daemon. |
| 15340 | |
| 15341 | Setting this option to zero does not suppress queue runs; rather, it disables |
| 15342 | the limit, allowing any number of simultaneous queue runner processes to be |
| 15343 | run. If you do not want queue runs to occur, omit the &%-q%&&'xx'& setting on |
| 15344 | the daemon's command line. |
| 15345 | |
| 15346 | .option queue_smtp_domains main "domain list&!!" unset |
| 15347 | .cindex "queueing incoming messages" |
| 15348 | .cindex "message" "queueing remote deliveries" |
| 15349 | When this option is set, a delivery process is started whenever a message is |
| 15350 | received, routing is performed, and local deliveries take place. |
| 15351 | However, if any SMTP deliveries are required for domains that match |
| 15352 | &%queue_smtp_domains%&, they are not immediately delivered, but instead the |
| 15353 | message waits on the queue for the next queue run. Since routing of the message |
| 15354 | has taken place, Exim knows to which remote hosts it must be delivered, and so |
| 15355 | when the queue run happens, multiple messages for the same host are delivered |
| 15356 | over a single SMTP connection. The &%-odqs%& command line option causes all |
| 15357 | SMTP deliveries to be queued in this way, and is equivalent to setting |
| 15358 | &%queue_smtp_domains%& to &"*"&. See also &%hold_domains%& and |
| 15359 | &%queue_domains%&. |
| 15360 | |
| 15361 | |
| 15362 | .option receive_timeout main time 0s |
| 15363 | .cindex "timeout" "for non-SMTP input" |
| 15364 | This option sets the timeout for accepting a non-SMTP message, that is, the |
| 15365 | maximum time that Exim waits when reading a message on the standard input. If |
| 15366 | the value is zero, it will wait for ever. This setting is overridden by the |
| 15367 | &%-or%& command line option. The timeout for incoming SMTP messages is |
| 15368 | controlled by &%smtp_receive_timeout%&. |
| 15369 | |
| 15370 | .option received_header_text main string&!! "see below" |
| 15371 | .cindex "customizing" "&'Received:'& header" |
| 15372 | .cindex "&'Received:'& header line" "customizing" |
| 15373 | This string defines the contents of the &'Received:'& message header that is |
| 15374 | added to each message, except for the timestamp, which is automatically added |
| 15375 | on at the end (preceded by a semicolon). The string is expanded each time it is |
| 15376 | used. If the expansion yields an empty string, no &'Received:'& header line is |
| 15377 | added to the message. Otherwise, the string should start with the text |
| 15378 | &"Received:"& and conform to the RFC 2822 specification for &'Received:'& |
| 15379 | header lines. The default setting is: |
| 15380 | |
| 15381 | .code |
| 15382 | received_header_text = Received: \ |
| 15383 | ${if def:sender_rcvhost {from $sender_rcvhost\n\t}\ |
| 15384 | {${if def:sender_ident \ |
| 15385 | {from ${quote_local_part:$sender_ident} }}\ |
| 15386 | ${if def:sender_helo_name {(helo=$sender_helo_name)\n\t}}}}\ |
| 15387 | by $primary_hostname \ |
| 15388 | ${if def:received_protocol {with $received_protocol}} \ |
| 15389 | ${if def:tls_in_cipher {($tls_in_cipher)\n\t}}\ |
| 15390 | (Exim $version_number)\n\t\ |
| 15391 | ${if def:sender_address \ |
| 15392 | {(envelope-from <$sender_address>)\n\t}}\ |
| 15393 | id $message_exim_id\ |
| 15394 | ${if def:received_for {\n\tfor $received_for}} |
| 15395 | .endd |
| 15396 | |
| 15397 | The reference to the TLS cipher is omitted when Exim is built without TLS |
| 15398 | support. The use of conditional expansions ensures that this works for both |
| 15399 | locally generated messages and messages received from remote hosts, giving |
| 15400 | header lines such as the following: |
| 15401 | .code |
| 15402 | Received: from scrooge.carol.example ([192.168.12.25] ident=root) |
| 15403 | by marley.carol.example with esmtp (Exim 4.00) |
| 15404 | (envelope-from <bob@carol.example>) |
| 15405 | id 16IOWa-00019l-00 |
| 15406 | for chas@dickens.example; Tue, 25 Dec 2001 14:43:44 +0000 |
| 15407 | Received: by scrooge.carol.example with local (Exim 4.00) |
| 15408 | id 16IOWW-000083-00; Tue, 25 Dec 2001 14:43:41 +0000 |
| 15409 | .endd |
| 15410 | Until the body of the message has been received, the timestamp is the time when |
| 15411 | the message started to be received. Once the body has arrived, and all policy |
| 15412 | checks have taken place, the timestamp is updated to the time at which the |
| 15413 | message was accepted. |
| 15414 | |
| 15415 | |
| 15416 | .option received_headers_max main integer 30 |
| 15417 | .cindex "loop" "prevention" |
| 15418 | .cindex "mail loop prevention" |
| 15419 | .cindex "&'Received:'& header line" "counting" |
| 15420 | When a message is to be delivered, the number of &'Received:'& headers is |
| 15421 | counted, and if it is greater than this parameter, a mail loop is assumed to |
| 15422 | have occurred, the delivery is abandoned, and an error message is generated. |
| 15423 | This applies to both local and remote deliveries. |
| 15424 | |
| 15425 | |
| 15426 | .option recipient_unqualified_hosts main "host list&!!" unset |
| 15427 | .cindex "unqualified addresses" |
| 15428 | .cindex "host" "unqualified addresses from" |
| 15429 | This option lists those hosts from which Exim is prepared to accept unqualified |
| 15430 | recipient addresses in message envelopes. The addresses are made fully |
| 15431 | qualified by the addition of the &%qualify_recipient%& value. This option also |
| 15432 | affects message header lines. Exim does not reject unqualified recipient |
| 15433 | addresses in headers, but it qualifies them only if the message came from a |
| 15434 | host that matches &%recipient_unqualified_hosts%&, |
| 15435 | or if the message was submitted locally (not using TCP/IP), and the &%-bnq%& |
| 15436 | option was not set. |
| 15437 | |
| 15438 | |
| 15439 | .option recipients_max main integer 0 |
| 15440 | .cindex "limit" "number of recipients" |
| 15441 | .cindex "recipient" "maximum number" |
| 15442 | If this option is set greater than zero, it specifies the maximum number of |
| 15443 | original recipients for any message. Additional recipients that are generated |
| 15444 | by aliasing or forwarding do not count. SMTP messages get a 452 response for |
| 15445 | all recipients over the limit; earlier recipients are delivered as normal. |
| 15446 | Non-SMTP messages with too many recipients are failed, and no deliveries are |
| 15447 | done. |
| 15448 | |
| 15449 | .cindex "RCPT" "maximum number of incoming" |
| 15450 | &*Note*&: The RFCs specify that an SMTP server should accept at least 100 |
| 15451 | RCPT commands in a single message. |
| 15452 | |
| 15453 | |
| 15454 | .option recipients_max_reject main boolean false |
| 15455 | If this option is set true, Exim rejects SMTP messages containing too many |
| 15456 | recipients by giving 552 errors to the surplus RCPT commands, and a 554 |
| 15457 | error to the eventual DATA command. Otherwise (the default) it gives a 452 |
| 15458 | error to the surplus RCPT commands and accepts the message on behalf of the |
| 15459 | initial set of recipients. The remote server should then re-send the message |
| 15460 | for the remaining recipients at a later time. |
| 15461 | |
| 15462 | |
| 15463 | .option remote_max_parallel main integer 2 |
| 15464 | .cindex "delivery" "parallelism for remote" |
| 15465 | This option controls parallel delivery of one message to a number of remote |
| 15466 | hosts. If the value is less than 2, parallel delivery is disabled, and Exim |
| 15467 | does all the remote deliveries for a message one by one. Otherwise, if a single |
| 15468 | message has to be delivered to more than one remote host, or if several copies |
| 15469 | have to be sent to the same remote host, up to &%remote_max_parallel%& |
| 15470 | deliveries are done simultaneously. If more than &%remote_max_parallel%& |
| 15471 | deliveries are required, the maximum number of processes are started, and as |
| 15472 | each one finishes, another is begun. The order of starting processes is the |
| 15473 | same as if sequential delivery were being done, and can be controlled by the |
| 15474 | &%remote_sort_domains%& option. If parallel delivery takes place while running |
| 15475 | with debugging turned on, the debugging output from each delivery process is |
| 15476 | tagged with its process id. |
| 15477 | |
| 15478 | This option controls only the maximum number of parallel deliveries for one |
| 15479 | message in one Exim delivery process. Because Exim has no central queue |
| 15480 | manager, there is no way of controlling the total number of simultaneous |
| 15481 | deliveries if the configuration allows a delivery attempt as soon as a message |
| 15482 | is received. |
| 15483 | |
| 15484 | .cindex "number of deliveries" |
| 15485 | .cindex "delivery" "maximum number of" |
| 15486 | If you want to control the total number of deliveries on the system, you |
| 15487 | need to set the &%queue_only%& option. This ensures that all incoming messages |
| 15488 | are added to the queue without starting a delivery process. Then set up an Exim |
| 15489 | daemon to start queue runner processes at appropriate intervals (probably |
| 15490 | fairly often, for example, every minute), and limit the total number of queue |
| 15491 | runners by setting the &%queue_run_max%& parameter. Because each queue runner |
| 15492 | delivers only one message at a time, the maximum number of deliveries that can |
| 15493 | then take place at once is &%queue_run_max%& multiplied by |
| 15494 | &%remote_max_parallel%&. |
| 15495 | |
| 15496 | If it is purely remote deliveries you want to control, use |
| 15497 | &%queue_smtp_domains%& instead of &%queue_only%&. This has the added benefit of |
| 15498 | doing the SMTP routing before queueing, so that several messages for the same |
| 15499 | host will eventually get delivered down the same connection. |
| 15500 | |
| 15501 | |
| 15502 | .option remote_sort_domains main "domain list&!!" unset |
| 15503 | .cindex "sorting remote deliveries" |
| 15504 | .cindex "delivery" "sorting remote" |
| 15505 | When there are a number of remote deliveries for a message, they are sorted by |
| 15506 | domain into the order given by this list. For example, |
| 15507 | .code |
| 15508 | remote_sort_domains = *.cam.ac.uk:*.uk |
| 15509 | .endd |
| 15510 | would attempt to deliver to all addresses in the &'cam.ac.uk'& domain first, |
| 15511 | then to those in the &%uk%& domain, then to any others. |
| 15512 | |
| 15513 | |
| 15514 | .option retry_data_expire main time 7d |
| 15515 | .cindex "hints database" "data expiry" |
| 15516 | This option sets a &"use before"& time on retry information in Exim's hints |
| 15517 | database. Any older retry data is ignored. This means that, for example, once a |
| 15518 | host has not been tried for 7 days, Exim behaves as if it has no knowledge of |
| 15519 | past failures. |
| 15520 | |
| 15521 | |
| 15522 | .option retry_interval_max main time 24h |
| 15523 | .cindex "retry" "limit on interval" |
| 15524 | .cindex "limit" "on retry interval" |
| 15525 | Chapter &<<CHAPretry>>& describes Exim's mechanisms for controlling the |
| 15526 | intervals between delivery attempts for messages that cannot be delivered |
| 15527 | straight away. This option sets an overall limit to the length of time between |
| 15528 | retries. It cannot be set greater than 24 hours; any attempt to do so forces |
| 15529 | the default value. |
| 15530 | |
| 15531 | |
| 15532 | .option return_path_remove main boolean true |
| 15533 | .cindex "&'Return-path:'& header line" "removing" |
| 15534 | RFC 2821, section 4.4, states that an SMTP server must insert a |
| 15535 | &'Return-path:'& header line into a message when it makes a &"final delivery"&. |
| 15536 | The &'Return-path:'& header preserves the sender address as received in the |
| 15537 | MAIL command. This description implies that this header should not be present |
| 15538 | in an incoming message. If &%return_path_remove%& is true, any existing |
| 15539 | &'Return-path:'& headers are removed from messages at the time they are |
| 15540 | received. Exim's transports have options for adding &'Return-path:'& headers at |
| 15541 | the time of delivery. They are normally used only for final local deliveries. |
| 15542 | |
| 15543 | |
| 15544 | .option return_size_limit main integer 100K |
| 15545 | This option is an obsolete synonym for &%bounce_return_size_limit%&. |
| 15546 | |
| 15547 | |
| 15548 | .option rfc1413_hosts main "host list&!!" * |
| 15549 | .cindex "RFC 1413" |
| 15550 | .cindex "host" "for RFC 1413 calls" |
| 15551 | RFC 1413 identification calls are made to any client host which matches an item |
| 15552 | in the list. |
| 15553 | |
| 15554 | .option rfc1413_query_timeout main time 5s |
| 15555 | .cindex "RFC 1413" "query timeout" |
| 15556 | .cindex "timeout" "for RFC 1413 call" |
| 15557 | This sets the timeout on RFC 1413 identification calls. If it is set to zero, |
| 15558 | no RFC 1413 calls are ever made. |
| 15559 | |
| 15560 | |
| 15561 | .option sender_unqualified_hosts main "host list&!!" unset |
| 15562 | .cindex "unqualified addresses" |
| 15563 | .cindex "host" "unqualified addresses from" |
| 15564 | This option lists those hosts from which Exim is prepared to accept unqualified |
| 15565 | sender addresses. The addresses are made fully qualified by the addition of |
| 15566 | &%qualify_domain%&. This option also affects message header lines. Exim does |
| 15567 | not reject unqualified addresses in headers that contain sender addresses, but |
| 15568 | it qualifies them only if the message came from a host that matches |
| 15569 | &%sender_unqualified_hosts%&, or if the message was submitted locally (not |
| 15570 | using TCP/IP), and the &%-bnq%& option was not set. |
| 15571 | |
| 15572 | |
| 15573 | .option smtp_accept_keepalive main boolean true |
| 15574 | .cindex "keepalive" "on incoming connection" |
| 15575 | This option controls the setting of the SO_KEEPALIVE option on incoming |
| 15576 | TCP/IP socket connections. When set, it causes the kernel to probe idle |
| 15577 | connections periodically, by sending packets with &"old"& sequence numbers. The |
| 15578 | other end of the connection should send an acknowledgment if the connection is |
| 15579 | still okay or a reset if the connection has been aborted. The reason for doing |
| 15580 | this is that it has the beneficial effect of freeing up certain types of |
| 15581 | connection that can get stuck when the remote host is disconnected without |
| 15582 | tidying up the TCP/IP call properly. The keepalive mechanism takes several |
| 15583 | hours to detect unreachable hosts. |
| 15584 | |
| 15585 | |
| 15586 | |
| 15587 | .option smtp_accept_max main integer 20 |
| 15588 | .cindex "limit" "incoming SMTP connections" |
| 15589 | .cindex "SMTP" "incoming connection count" |
| 15590 | .cindex "inetd" |
| 15591 | This option specifies the maximum number of simultaneous incoming SMTP calls |
| 15592 | that Exim will accept. It applies only to the listening daemon; there is no |
| 15593 | control (in Exim) when incoming SMTP is being handled by &'inetd'&. If the |
| 15594 | value is set to zero, no limit is applied. However, it is required to be |
| 15595 | non-zero if either &%smtp_accept_max_per_host%& or &%smtp_accept_queue%& is |
| 15596 | set. See also &%smtp_accept_reserve%& and &%smtp_load_reserve%&. |
| 15597 | |
| 15598 | A new SMTP connection is immediately rejected if the &%smtp_accept_max%& limit |
| 15599 | has been reached. If not, Exim first checks &%smtp_accept_max_per_host%&. If |
| 15600 | that limit has not been reached for the client host, &%smtp_accept_reserve%& |
| 15601 | and &%smtp_load_reserve%& are then checked before accepting the connection. |
| 15602 | |
| 15603 | |
| 15604 | .option smtp_accept_max_nonmail main integer 10 |
| 15605 | .cindex "limit" "non-mail SMTP commands" |
| 15606 | .cindex "SMTP" "limiting non-mail commands" |
| 15607 | Exim counts the number of &"non-mail"& commands in an SMTP session, and drops |
| 15608 | the connection if there are too many. This option defines &"too many"&. The |
| 15609 | check catches some denial-of-service attacks, repeated failing AUTHs, or a mad |
| 15610 | client looping sending EHLO, for example. The check is applied only if the |
| 15611 | client host matches &%smtp_accept_max_nonmail_hosts%&. |
| 15612 | |
| 15613 | When a new message is expected, one occurrence of RSET is not counted. This |
| 15614 | allows a client to send one RSET between messages (this is not necessary, |
| 15615 | but some clients do it). Exim also allows one uncounted occurrence of HELO |
| 15616 | or EHLO, and one occurrence of STARTTLS between messages. After |
| 15617 | starting up a TLS session, another EHLO is expected, and so it too is not |
| 15618 | counted. The first occurrence of AUTH in a connection, or immediately |
| 15619 | following STARTTLS is not counted. Otherwise, all commands other than |
| 15620 | MAIL, RCPT, DATA, and QUIT are counted. |
| 15621 | |
| 15622 | |
| 15623 | .option smtp_accept_max_nonmail_hosts main "host list&!!" * |
| 15624 | You can control which hosts are subject to the &%smtp_accept_max_nonmail%& |
| 15625 | check by setting this option. The default value makes it apply to all hosts. By |
| 15626 | changing the value, you can exclude any badly-behaved hosts that you have to |
| 15627 | live with. |
| 15628 | |
| 15629 | |
| 15630 | . Allow this long option name to split; give it unsplit as a fifth argument |
| 15631 | . for the automatic .oindex that is generated by .option. |
| 15632 | . We insert " &~&~" which is both pretty nasty visually and results in |
| 15633 | . non-searchable text. HowItWorks.txt mentions an option for inserting |
| 15634 | . zero-width-space, which would be nicer visually and results in (at least) |
| 15635 | . html that Firefox will split on when it's forced to reflow (rather than |
| 15636 | . inserting a horizontal scrollbar). However, the text is still not |
| 15637 | . searchable. NM changed this occurrence for bug 1197 to no longer allow |
| 15638 | . the option name to split. |
| 15639 | |
| 15640 | .option "smtp_accept_max_per_connection" main integer 1000 &&& |
| 15641 | smtp_accept_max_per_connection |
| 15642 | .cindex "SMTP" "limiting incoming message count" |
| 15643 | .cindex "limit" "messages per SMTP connection" |
| 15644 | The value of this option limits the number of MAIL commands that Exim is |
| 15645 | prepared to accept over a single SMTP connection, whether or not each command |
| 15646 | results in the transfer of a message. After the limit is reached, a 421 |
| 15647 | response is given to subsequent MAIL commands. This limit is a safety |
| 15648 | precaution against a client that goes mad (incidents of this type have been |
| 15649 | seen). |
| 15650 | |
| 15651 | |
| 15652 | .option smtp_accept_max_per_host main string&!! unset |
| 15653 | .cindex "limit" "SMTP connections from one host" |
| 15654 | .cindex "host" "limiting SMTP connections from" |
| 15655 | This option restricts the number of simultaneous IP connections from a single |
| 15656 | host (strictly, from a single IP address) to the Exim daemon. The option is |
| 15657 | expanded, to enable different limits to be applied to different hosts by |
| 15658 | reference to &$sender_host_address$&. Once the limit is reached, additional |
| 15659 | connection attempts from the same host are rejected with error code 421. This |
| 15660 | is entirely independent of &%smtp_accept_reserve%&. The option's default value |
| 15661 | of zero imposes no limit. If this option is set greater than zero, it is |
| 15662 | required that &%smtp_accept_max%& be non-zero. |
| 15663 | |
| 15664 | &*Warning*&: When setting this option you should not use any expansion |
| 15665 | constructions that take an appreciable amount of time. The expansion and test |
| 15666 | happen in the main daemon loop, in order to reject additional connections |
| 15667 | without forking additional processes (otherwise a denial-of-service attack |
| 15668 | could cause a vast number or processes to be created). While the daemon is |
| 15669 | doing this processing, it cannot accept any other incoming connections. |
| 15670 | |
| 15671 | |
| 15672 | |
| 15673 | .option smtp_accept_queue main integer 0 |
| 15674 | .cindex "SMTP" "incoming connection count" |
| 15675 | .cindex "queueing incoming messages" |
| 15676 | .cindex "message" "queueing by SMTP connection count" |
| 15677 | If the number of simultaneous incoming SMTP connections being handled via the |
| 15678 | listening daemon exceeds this value, messages received by SMTP are just placed |
| 15679 | on the queue; no delivery processes are started automatically. The count is |
| 15680 | fixed at the start of an SMTP connection. It cannot be updated in the |
| 15681 | subprocess that receives messages, and so the queueing or not queueing applies |
| 15682 | to all messages received in the same connection. |
| 15683 | |
| 15684 | A value of zero implies no limit, and clearly any non-zero value is useful only |
| 15685 | if it is less than the &%smtp_accept_max%& value (unless that is zero). See |
| 15686 | also &%queue_only%&, &%queue_only_load%&, &%queue_smtp_domains%&, and the |
| 15687 | various &%-od%&&'x'& command line options. |
| 15688 | |
| 15689 | |
| 15690 | . See the comment on smtp_accept_max_per_connection |
| 15691 | |
| 15692 | .option "smtp_accept_queue_per_connection" main integer 10 &&& |
| 15693 | smtp_accept_queue_per_connection |
| 15694 | .cindex "queueing incoming messages" |
| 15695 | .cindex "message" "queueing by message count" |
| 15696 | This option limits the number of delivery processes that Exim starts |
| 15697 | automatically when receiving messages via SMTP, whether via the daemon or by |
| 15698 | the use of &%-bs%& or &%-bS%&. If the value of the option is greater than zero, |
| 15699 | and the number of messages received in a single SMTP session exceeds this |
| 15700 | number, subsequent messages are placed on the queue, but no delivery processes |
| 15701 | are started. This helps to limit the number of Exim processes when a server |
| 15702 | restarts after downtime and there is a lot of mail waiting for it on other |
| 15703 | systems. On large systems, the default should probably be increased, and on |
| 15704 | dial-in client systems it should probably be set to zero (that is, disabled). |
| 15705 | |
| 15706 | |
| 15707 | .option smtp_accept_reserve main integer 0 |
| 15708 | .cindex "SMTP" "incoming call count" |
| 15709 | .cindex "host" "reserved" |
| 15710 | When &%smtp_accept_max%& is set greater than zero, this option specifies a |
| 15711 | number of SMTP connections that are reserved for connections from the hosts |
| 15712 | that are specified in &%smtp_reserve_hosts%&. The value set in |
| 15713 | &%smtp_accept_max%& includes this reserve pool. The specified hosts are not |
| 15714 | restricted to this number of connections; the option specifies a minimum number |
| 15715 | of connection slots for them, not a maximum. It is a guarantee that this group |
| 15716 | of hosts can always get at least &%smtp_accept_reserve%& connections. However, |
| 15717 | the limit specified by &%smtp_accept_max_per_host%& is still applied to each |
| 15718 | individual host. |
| 15719 | |
| 15720 | For example, if &%smtp_accept_max%& is set to 50 and &%smtp_accept_reserve%& is |
| 15721 | set to 5, once there are 45 active connections (from any hosts), new |
| 15722 | connections are accepted only from hosts listed in &%smtp_reserve_hosts%&, |
| 15723 | provided the other criteria for acceptance are met. |
| 15724 | |
| 15725 | |
| 15726 | .option smtp_active_hostname main string&!! unset |
| 15727 | .cindex "host" "name in SMTP responses" |
| 15728 | .cindex "SMTP" "host name in responses" |
| 15729 | .vindex "&$primary_hostname$&" |
| 15730 | This option is provided for multi-homed servers that want to masquerade as |
| 15731 | several different hosts. At the start of an incoming SMTP connection, its value |
| 15732 | is expanded and used instead of the value of &$primary_hostname$& in SMTP |
| 15733 | responses. For example, it is used as domain name in the response to an |
| 15734 | incoming HELO or EHLO command. |
| 15735 | |
| 15736 | .vindex "&$smtp_active_hostname$&" |
| 15737 | The active hostname is placed in the &$smtp_active_hostname$& variable, which |
| 15738 | is saved with any messages that are received. It is therefore available for use |
| 15739 | in routers and transports when the message is later delivered. |
| 15740 | |
| 15741 | If this option is unset, or if its expansion is forced to fail, or if the |
| 15742 | expansion results in an empty string, the value of &$primary_hostname$& is |
| 15743 | used. Other expansion failures cause a message to be written to the main and |
| 15744 | panic logs, and the SMTP command receives a temporary error. Typically, the |
| 15745 | value of &%smtp_active_hostname%& depends on the incoming interface address. |
| 15746 | For example: |
| 15747 | .code |
| 15748 | smtp_active_hostname = ${if eq{$received_ip_address}{10.0.0.1}\ |
| 15749 | {cox.mydomain}{box.mydomain}} |
| 15750 | .endd |
| 15751 | |
| 15752 | Although &$smtp_active_hostname$& is primarily concerned with incoming |
| 15753 | messages, it is also used as the default for HELO commands in callout |
| 15754 | verification if there is no remote transport from which to obtain a |
| 15755 | &%helo_data%& value. |
| 15756 | |
| 15757 | .option smtp_banner main string&!! "see below" |
| 15758 | .cindex "SMTP" "welcome banner" |
| 15759 | .cindex "banner for SMTP" |
| 15760 | .cindex "welcome banner for SMTP" |
| 15761 | .cindex "customizing" "SMTP banner" |
| 15762 | This string, which is expanded every time it is used, is output as the initial |
| 15763 | positive response to an SMTP connection. The default setting is: |
| 15764 | .code |
| 15765 | smtp_banner = $smtp_active_hostname ESMTP Exim \ |
| 15766 | $version_number $tod_full |
| 15767 | .endd |
| 15768 | Failure to expand the string causes a panic error. If you want to create a |
| 15769 | multiline response to the initial SMTP connection, use &"\n"& in the string at |
| 15770 | appropriate points, but not at the end. Note that the 220 code is not included |
| 15771 | in this string. Exim adds it automatically (several times in the case of a |
| 15772 | multiline response). |
| 15773 | |
| 15774 | |
| 15775 | .option smtp_check_spool_space main boolean true |
| 15776 | .cindex "checking disk space" |
| 15777 | .cindex "disk space, checking" |
| 15778 | .cindex "spool directory" "checking space" |
| 15779 | When this option is set, if an incoming SMTP session encounters the SIZE |
| 15780 | option on a MAIL command, it checks that there is enough space in the |
| 15781 | spool directory's partition to accept a message of that size, while still |
| 15782 | leaving free the amount specified by &%check_spool_space%& (even if that value |
| 15783 | is zero). If there isn't enough space, a temporary error code is returned. |
| 15784 | |
| 15785 | |
| 15786 | .option smtp_connect_backlog main integer 20 |
| 15787 | .cindex "connection backlog" |
| 15788 | .cindex "SMTP" "connection backlog" |
| 15789 | .cindex "backlog of connections" |
| 15790 | This option specifies a maximum number of waiting SMTP connections. Exim passes |
| 15791 | this value to the TCP/IP system when it sets up its listener. Once this number |
| 15792 | of connections are waiting for the daemon's attention, subsequent connection |
| 15793 | attempts are refused at the TCP/IP level. At least, that is what the manuals |
| 15794 | say; in some circumstances such connection attempts have been observed to time |
| 15795 | out instead. For large systems it is probably a good idea to increase the |
| 15796 | value (to 50, say). It also gives some protection against denial-of-service |
| 15797 | attacks by SYN flooding. |
| 15798 | |
| 15799 | |
| 15800 | .option smtp_enforce_sync main boolean true |
| 15801 | .cindex "SMTP" "synchronization checking" |
| 15802 | .cindex "synchronization checking in SMTP" |
| 15803 | The SMTP protocol specification requires the client to wait for a response from |
| 15804 | the server at certain points in the dialogue. Without PIPELINING these |
| 15805 | synchronization points are after every command; with PIPELINING they are |
| 15806 | fewer, but they still exist. |
| 15807 | |
| 15808 | Some spamming sites send out a complete set of SMTP commands without waiting |
| 15809 | for any response. Exim protects against this by rejecting a message if the |
| 15810 | client has sent further input when it should not have. The error response &"554 |
| 15811 | SMTP synchronization error"& is sent, and the connection is dropped. Testing |
| 15812 | for this error cannot be perfect because of transmission delays (unexpected |
| 15813 | input may be on its way but not yet received when Exim checks). However, it |
| 15814 | does detect many instances. |
| 15815 | |
| 15816 | The check can be globally disabled by setting &%smtp_enforce_sync%& false. |
| 15817 | If you want to disable the check selectively (for example, only for certain |
| 15818 | hosts), you can do so by an appropriate use of a &%control%& modifier in an ACL |
| 15819 | (see section &<<SECTcontrols>>&). See also &%pipelining_advertise_hosts%&. |
| 15820 | |
| 15821 | |
| 15822 | |
| 15823 | .option smtp_etrn_command main string&!! unset |
| 15824 | .cindex "ETRN" "command to be run" |
| 15825 | .vindex "&$domain$&" |
| 15826 | If this option is set, the given command is run whenever an SMTP ETRN |
| 15827 | command is received from a host that is permitted to issue such commands (see |
| 15828 | chapter &<<CHAPACL>>&). The string is split up into separate arguments which |
| 15829 | are independently expanded. The expansion variable &$domain$& is set to the |
| 15830 | argument of the ETRN command, and no syntax checking is done on it. For |
| 15831 | example: |
| 15832 | .code |
| 15833 | smtp_etrn_command = /etc/etrn_command $domain \ |
| 15834 | $sender_host_address |
| 15835 | .endd |
| 15836 | A new process is created to run the command, but Exim does not wait for it to |
| 15837 | complete. Consequently, its status cannot be checked. If the command cannot be |
| 15838 | run, a line is written to the panic log, but the ETRN caller still receives |
| 15839 | a 250 success response. Exim is normally running under its own uid when |
| 15840 | receiving SMTP, so it is not possible for it to change the uid before running |
| 15841 | the command. |
| 15842 | |
| 15843 | |
| 15844 | .option smtp_etrn_serialize main boolean true |
| 15845 | .cindex "ETRN" "serializing" |
| 15846 | When this option is set, it prevents the simultaneous execution of more than |
| 15847 | one identical command as a result of ETRN in an SMTP connection. See |
| 15848 | section &<<SECTETRN>>& for details. |
| 15849 | |
| 15850 | |
| 15851 | .option smtp_load_reserve main fixed-point unset |
| 15852 | .cindex "load average" |
| 15853 | If the system load average ever gets higher than this, incoming SMTP calls are |
| 15854 | accepted only from those hosts that match an entry in &%smtp_reserve_hosts%&. |
| 15855 | If &%smtp_reserve_hosts%& is not set, no incoming SMTP calls are accepted when |
| 15856 | the load is over the limit. The option has no effect on ancient operating |
| 15857 | systems on which Exim cannot determine the load average. See also |
| 15858 | &%deliver_queue_load_max%& and &%queue_only_load%&. |
| 15859 | |
| 15860 | |
| 15861 | |
| 15862 | .option smtp_max_synprot_errors main integer 3 |
| 15863 | .cindex "SMTP" "limiting syntax and protocol errors" |
| 15864 | .cindex "limit" "SMTP syntax and protocol errors" |
| 15865 | Exim rejects SMTP commands that contain syntax or protocol errors. In |
| 15866 | particular, a syntactically invalid email address, as in this command: |
| 15867 | .code |
| 15868 | RCPT TO:<abc xyz@a.b.c> |
| 15869 | .endd |
| 15870 | causes immediate rejection of the command, before any other tests are done. |
| 15871 | (The ACL cannot be run if there is no valid address to set up for it.) An |
| 15872 | example of a protocol error is receiving RCPT before MAIL. If there are |
| 15873 | too many syntax or protocol errors in one SMTP session, the connection is |
| 15874 | dropped. The limit is set by this option. |
| 15875 | |
| 15876 | .cindex "PIPELINING" "expected errors" |
| 15877 | When the PIPELINING extension to SMTP is in use, some protocol errors are |
| 15878 | &"expected"&, for instance, a RCPT command after a rejected MAIL command. |
| 15879 | Exim assumes that PIPELINING will be used if it advertises it (see |
| 15880 | &%pipelining_advertise_hosts%&), and in this situation, &"expected"& errors do |
| 15881 | not count towards the limit. |
| 15882 | |
| 15883 | |
| 15884 | |
| 15885 | .option smtp_max_unknown_commands main integer 3 |
| 15886 | .cindex "SMTP" "limiting unknown commands" |
| 15887 | .cindex "limit" "unknown SMTP commands" |
| 15888 | If there are too many unrecognized commands in an incoming SMTP session, an |
| 15889 | Exim server drops the connection. This is a defence against some kinds of abuse |
| 15890 | that subvert web |
| 15891 | clients |
| 15892 | into making connections to SMTP ports; in these circumstances, a number of |
| 15893 | non-SMTP command lines are sent first. |
| 15894 | |
| 15895 | |
| 15896 | |
| 15897 | .option smtp_ratelimit_hosts main "host list&!!" unset |
| 15898 | .cindex "SMTP" "rate limiting" |
| 15899 | .cindex "limit" "rate of message arrival" |
| 15900 | .cindex "RCPT" "rate limiting" |
| 15901 | Some sites find it helpful to be able to limit the rate at which certain hosts |
| 15902 | can send them messages, and the rate at which an individual message can specify |
| 15903 | recipients. |
| 15904 | |
| 15905 | Exim has two rate-limiting facilities. This section describes the older |
| 15906 | facility, which can limit rates within a single connection. The newer |
| 15907 | &%ratelimit%& ACL condition can limit rates across all connections. See section |
| 15908 | &<<SECTratelimiting>>& for details of the newer facility. |
| 15909 | |
| 15910 | When a host matches &%smtp_ratelimit_hosts%&, the values of |
| 15911 | &%smtp_ratelimit_mail%& and &%smtp_ratelimit_rcpt%& are used to control the |
| 15912 | rate of acceptance of MAIL and RCPT commands in a single SMTP session, |
| 15913 | respectively. Each option, if set, must contain a set of four comma-separated |
| 15914 | values: |
| 15915 | |
| 15916 | .ilist |
| 15917 | A threshold, before which there is no rate limiting. |
| 15918 | .next |
| 15919 | An initial time delay. Unlike other times in Exim, numbers with decimal |
| 15920 | fractional parts are allowed here. |
| 15921 | .next |
| 15922 | A factor by which to increase the delay each time. |
| 15923 | .next |
| 15924 | A maximum value for the delay. This should normally be less than 5 minutes, |
| 15925 | because after that time, the client is liable to timeout the SMTP command. |
| 15926 | .endlist |
| 15927 | |
| 15928 | For example, these settings have been used successfully at the site which |
| 15929 | first suggested this feature, for controlling mail from their customers: |
| 15930 | .code |
| 15931 | smtp_ratelimit_mail = 2,0.5s,1.05,4m |
| 15932 | smtp_ratelimit_rcpt = 4,0.25s,1.015,4m |
| 15933 | .endd |
| 15934 | The first setting specifies delays that are applied to MAIL commands after |
| 15935 | two have been received over a single connection. The initial delay is 0.5 |
| 15936 | seconds, increasing by a factor of 1.05 each time. The second setting applies |
| 15937 | delays to RCPT commands when more than four occur in a single message. |
| 15938 | |
| 15939 | |
| 15940 | .option smtp_ratelimit_mail main string unset |
| 15941 | See &%smtp_ratelimit_hosts%& above. |
| 15942 | |
| 15943 | |
| 15944 | .option smtp_ratelimit_rcpt main string unset |
| 15945 | See &%smtp_ratelimit_hosts%& above. |
| 15946 | |
| 15947 | |
| 15948 | .option smtp_receive_timeout main time 5m |
| 15949 | .cindex "timeout" "for SMTP input" |
| 15950 | .cindex "SMTP" "input timeout" |
| 15951 | This sets a timeout value for SMTP reception. It applies to all forms of SMTP |
| 15952 | input, including batch SMTP. If a line of input (either an SMTP command or a |
| 15953 | data line) is not received within this time, the SMTP connection is dropped and |
| 15954 | the message is abandoned. |
| 15955 | A line is written to the log containing one of the following messages: |
| 15956 | .code |
| 15957 | SMTP command timeout on connection from... |
| 15958 | SMTP data timeout on connection from... |
| 15959 | .endd |
| 15960 | The former means that Exim was expecting to read an SMTP command; the latter |
| 15961 | means that it was in the DATA phase, reading the contents of a message. |
| 15962 | |
| 15963 | |
| 15964 | .oindex "&%-os%&" |
| 15965 | The value set by this option can be overridden by the |
| 15966 | &%-os%& command-line option. A setting of zero time disables the timeout, but |
| 15967 | this should never be used for SMTP over TCP/IP. (It can be useful in some cases |
| 15968 | of local input using &%-bs%& or &%-bS%&.) For non-SMTP input, the reception |
| 15969 | timeout is controlled by &%receive_timeout%& and &%-or%&. |
| 15970 | |
| 15971 | |
| 15972 | .option smtp_reserve_hosts main "host list&!!" unset |
| 15973 | This option defines hosts for which SMTP connections are reserved; see |
| 15974 | &%smtp_accept_reserve%& and &%smtp_load_reserve%& above. |
| 15975 | |
| 15976 | |
| 15977 | .option smtp_return_error_details main boolean false |
| 15978 | .cindex "SMTP" "details policy failures" |
| 15979 | .cindex "policy control" "rejection, returning details" |
| 15980 | In the default state, Exim uses bland messages such as |
| 15981 | &"Administrative prohibition"& when it rejects SMTP commands for policy |
| 15982 | reasons. Many sysadmins like this because it gives away little information |
| 15983 | to spammers. However, some other sysadmins who are applying strict checking |
| 15984 | policies want to give out much fuller information about failures. Setting |
| 15985 | &%smtp_return_error_details%& true causes Exim to be more forthcoming. For |
| 15986 | example, instead of &"Administrative prohibition"&, it might give: |
| 15987 | .code |
| 15988 | 550-Rejected after DATA: '>' missing at end of address: |
| 15989 | 550 failing address in "From" header is: <user@dom.ain |
| 15990 | .endd |
| 15991 | |
| 15992 | .option spamd_address main string "see below" |
| 15993 | This option is available when Exim is compiled with the content-scanning |
| 15994 | extension. It specifies how Exim connects to SpamAssassin's &%spamd%& daemon. |
| 15995 | The default value is |
| 15996 | .code |
| 15997 | 127.0.0.1 783 |
| 15998 | .endd |
| 15999 | See section &<<SECTscanspamass>>& for more details. |
| 16000 | |
| 16001 | |
| 16002 | |
| 16003 | .option split_spool_directory main boolean false |
| 16004 | .cindex "multiple spool directories" |
| 16005 | .cindex "spool directory" "split" |
| 16006 | .cindex "directories, multiple" |
| 16007 | If this option is set, it causes Exim to split its input directory into 62 |
| 16008 | subdirectories, each with a single alphanumeric character as its name. The |
| 16009 | sixth character of the message id is used to allocate messages to |
| 16010 | subdirectories; this is the least significant base-62 digit of the time of |
| 16011 | arrival of the message. |
| 16012 | |
| 16013 | Splitting up the spool in this way may provide better performance on systems |
| 16014 | where there are long mail queues, by reducing the number of files in any one |
| 16015 | directory. The msglog directory is also split up in a similar way to the input |
| 16016 | directory; however, if &%preserve_message_logs%& is set, all old msglog files |
| 16017 | are still placed in the single directory &_msglog.OLD_&. |
| 16018 | |
| 16019 | It is not necessary to take any special action for existing messages when |
| 16020 | changing &%split_spool_directory%&. Exim notices messages that are in the |
| 16021 | &"wrong"& place, and continues to process them. If the option is turned off |
| 16022 | after a period of being on, the subdirectories will eventually empty and be |
| 16023 | automatically deleted. |
| 16024 | |
| 16025 | When &%split_spool_directory%& is set, the behaviour of queue runner processes |
| 16026 | changes. Instead of creating a list of all messages in the queue, and then |
| 16027 | trying to deliver each one in turn, it constructs a list of those in one |
| 16028 | sub-directory and tries to deliver them, before moving on to the next |
| 16029 | sub-directory. The sub-directories are processed in a random order. This |
| 16030 | spreads out the scanning of the input directories, and uses less memory. It is |
| 16031 | particularly beneficial when there are lots of messages on the queue. However, |
| 16032 | if &%queue_run_in_order%& is set, none of this new processing happens. The |
| 16033 | entire queue has to be scanned and sorted before any deliveries can start. |
| 16034 | |
| 16035 | |
| 16036 | .option spool_directory main string&!! "set at compile time" |
| 16037 | .cindex "spool directory" "path to" |
| 16038 | This defines the directory in which Exim keeps its spool, that is, the messages |
| 16039 | it is waiting to deliver. The default value is taken from the compile-time |
| 16040 | configuration setting, if there is one. If not, this option must be set. The |
| 16041 | string is expanded, so it can contain, for example, a reference to |
| 16042 | &$primary_hostname$&. |
| 16043 | |
| 16044 | If the spool directory name is fixed on your installation, it is recommended |
| 16045 | that you set it at build time rather than from this option, particularly if the |
| 16046 | log files are being written to the spool directory (see &%log_file_path%&). |
| 16047 | Otherwise log files cannot be used for errors that are detected early on, such |
| 16048 | as failures in the configuration file. |
| 16049 | |
| 16050 | By using this option to override the compiled-in path, it is possible to run |
| 16051 | tests of Exim without using the standard spool. |
| 16052 | |
| 16053 | .option sqlite_lock_timeout main time 5s |
| 16054 | .cindex "sqlite lookup type" "lock timeout" |
| 16055 | This option controls the timeout that the &(sqlite)& lookup uses when trying to |
| 16056 | access an SQLite database. See section &<<SECTsqlite>>& for more details. |
| 16057 | |
| 16058 | .option strict_acl_vars main boolean false |
| 16059 | .cindex "&ACL;" "variables, handling unset" |
| 16060 | This option controls what happens if a syntactically valid but undefined ACL |
| 16061 | variable is referenced. If it is false (the default), an empty string |
| 16062 | is substituted; if it is true, an error is generated. See section |
| 16063 | &<<SECTaclvariables>>& for details of ACL variables. |
| 16064 | |
| 16065 | .option strip_excess_angle_brackets main boolean false |
| 16066 | .cindex "angle brackets, excess" |
| 16067 | If this option is set, redundant pairs of angle brackets round &"route-addr"& |
| 16068 | items in addresses are stripped. For example, &'<<xxx@a.b.c.d>>'& is |
| 16069 | treated as &'<xxx@a.b.c.d>'&. If this is in the envelope and the message is |
| 16070 | passed on to another MTA, the excess angle brackets are not passed on. If this |
| 16071 | option is not set, multiple pairs of angle brackets cause a syntax error. |
| 16072 | |
| 16073 | |
| 16074 | .option strip_trailing_dot main boolean false |
| 16075 | .cindex "trailing dot on domain" |
| 16076 | .cindex "dot" "trailing on domain" |
| 16077 | If this option is set, a trailing dot at the end of a domain in an address is |
| 16078 | ignored. If this is in the envelope and the message is passed on to another |
| 16079 | MTA, the dot is not passed on. If this option is not set, a dot at the end of a |
| 16080 | domain causes a syntax error. |
| 16081 | However, addresses in header lines are checked only when an ACL requests header |
| 16082 | syntax checking. |
| 16083 | |
| 16084 | |
| 16085 | .option syslog_duplication main boolean true |
| 16086 | .cindex "syslog" "duplicate log lines; suppressing" |
| 16087 | When Exim is logging to syslog, it writes the log lines for its three |
| 16088 | separate logs at different syslog priorities so that they can in principle |
| 16089 | be separated on the logging hosts. Some installations do not require this |
| 16090 | separation, and in those cases, the duplication of certain log lines is a |
| 16091 | nuisance. If &%syslog_duplication%& is set false, only one copy of any |
| 16092 | particular log line is written to syslog. For lines that normally go to |
| 16093 | both the main log and the reject log, the reject log version (possibly |
| 16094 | containing message header lines) is written, at LOG_NOTICE priority. |
| 16095 | Lines that normally go to both the main and the panic log are written at |
| 16096 | the LOG_ALERT priority. |
| 16097 | |
| 16098 | |
| 16099 | .option syslog_facility main string unset |
| 16100 | .cindex "syslog" "facility; setting" |
| 16101 | This option sets the syslog &"facility"& name, used when Exim is logging to |
| 16102 | syslog. The value must be one of the strings &"mail"&, &"user"&, &"news"&, |
| 16103 | &"uucp"&, &"daemon"&, or &"local&'x'&"& where &'x'& is a digit between 0 and 7. |
| 16104 | If this option is unset, &"mail"& is used. See chapter &<<CHAPlog>>& for |
| 16105 | details of Exim's logging. |
| 16106 | |
| 16107 | |
| 16108 | |
| 16109 | .option syslog_processname main string &`exim`& |
| 16110 | .cindex "syslog" "process name; setting" |
| 16111 | This option sets the syslog &"ident"& name, used when Exim is logging to |
| 16112 | syslog. The value must be no longer than 32 characters. See chapter |
| 16113 | &<<CHAPlog>>& for details of Exim's logging. |
| 16114 | |
| 16115 | |
| 16116 | |
| 16117 | .option syslog_timestamp main boolean true |
| 16118 | .cindex "syslog" "timestamps" |
| 16119 | If &%syslog_timestamp%& is set false, the timestamps on Exim's log lines are |
| 16120 | omitted when these lines are sent to syslog. See chapter &<<CHAPlog>>& for |
| 16121 | details of Exim's logging. |
| 16122 | |
| 16123 | |
| 16124 | .option system_filter main string&!! unset |
| 16125 | .cindex "filter" "system filter" |
| 16126 | .cindex "system filter" "specifying" |
| 16127 | .cindex "Sieve filter" "not available for system filter" |
| 16128 | This option specifies an Exim filter file that is applied to all messages at |
| 16129 | the start of each delivery attempt, before any routing is done. System filters |
| 16130 | must be Exim filters; they cannot be Sieve filters. If the system filter |
| 16131 | generates any deliveries to files or pipes, or any new mail messages, the |
| 16132 | appropriate &%system_filter_..._transport%& option(s) must be set, to define |
| 16133 | which transports are to be used. Details of this facility are given in chapter |
| 16134 | &<<CHAPsystemfilter>>&. |
| 16135 | |
| 16136 | |
| 16137 | .option system_filter_directory_transport main string&!! unset |
| 16138 | .vindex "&$address_file$&" |
| 16139 | This sets the name of the transport driver that is to be used when the |
| 16140 | &%save%& command in a system message filter specifies a path ending in &"/"&, |
| 16141 | implying delivery of each message into a separate file in some directory. |
| 16142 | During the delivery, the variable &$address_file$& contains the path name. |
| 16143 | |
| 16144 | |
| 16145 | .option system_filter_file_transport main string&!! unset |
| 16146 | .cindex "file" "transport for system filter" |
| 16147 | This sets the name of the transport driver that is to be used when the &%save%& |
| 16148 | command in a system message filter specifies a path not ending in &"/"&. During |
| 16149 | the delivery, the variable &$address_file$& contains the path name. |
| 16150 | |
| 16151 | .option system_filter_group main string unset |
| 16152 | .cindex "gid (group id)" "system filter" |
| 16153 | This option is used only when &%system_filter_user%& is also set. It sets the |
| 16154 | gid under which the system filter is run, overriding any gid that is associated |
| 16155 | with the user. The value may be numerical or symbolic. |
| 16156 | |
| 16157 | .option system_filter_pipe_transport main string&!! unset |
| 16158 | .cindex "&(pipe)& transport" "for system filter" |
| 16159 | .vindex "&$address_pipe$&" |
| 16160 | This specifies the transport driver that is to be used when a &%pipe%& command |
| 16161 | is used in a system filter. During the delivery, the variable &$address_pipe$& |
| 16162 | contains the pipe command. |
| 16163 | |
| 16164 | |
| 16165 | .option system_filter_reply_transport main string&!! unset |
| 16166 | .cindex "&(autoreply)& transport" "for system filter" |
| 16167 | This specifies the transport driver that is to be used when a &%mail%& command |
| 16168 | is used in a system filter. |
| 16169 | |
| 16170 | |
| 16171 | .option system_filter_user main string unset |
| 16172 | .cindex "uid (user id)" "system filter" |
| 16173 | If this option is set to root, the system filter is run in the main Exim |
| 16174 | delivery process, as root. Otherwise, the system filter runs in a separate |
| 16175 | process, as the given user, defaulting to the Exim run-time user. |
| 16176 | Unless the string consists entirely of digits, it |
| 16177 | is looked up in the password data. Failure to find the named user causes a |
| 16178 | configuration error. The gid is either taken from the password data, or |
| 16179 | specified by &%system_filter_group%&. When the uid is specified numerically, |
| 16180 | &%system_filter_group%& is required to be set. |
| 16181 | |
| 16182 | If the system filter generates any pipe, file, or reply deliveries, the uid |
| 16183 | under which the filter is run is used when transporting them, unless a |
| 16184 | transport option overrides. |
| 16185 | |
| 16186 | |
| 16187 | .option tcp_nodelay main boolean true |
| 16188 | .cindex "daemon" "TCP_NODELAY on sockets" |
| 16189 | .cindex "Nagle algorithm" |
| 16190 | .cindex "TCP_NODELAY on listening sockets" |
| 16191 | If this option is set false, it stops the Exim daemon setting the |
| 16192 | TCP_NODELAY option on its listening sockets. Setting TCP_NODELAY |
| 16193 | turns off the &"Nagle algorithm"&, which is a way of improving network |
| 16194 | performance in interactive (character-by-character) situations. Turning it off |
| 16195 | should improve Exim's performance a bit, so that is what happens by default. |
| 16196 | However, it appears that some broken clients cannot cope, and time out. Hence |
| 16197 | this option. It affects only those sockets that are set up for listening by the |
| 16198 | daemon. Sockets created by the smtp transport for delivering mail always set |
| 16199 | TCP_NODELAY. |
| 16200 | |
| 16201 | |
| 16202 | .option timeout_frozen_after main time 0s |
| 16203 | .cindex "frozen messages" "timing out" |
| 16204 | .cindex "timeout" "frozen messages" |
| 16205 | If &%timeout_frozen_after%& is set to a time greater than zero, a frozen |
| 16206 | message of any kind that has been on the queue for longer than the given time |
| 16207 | is automatically cancelled at the next queue run. If the frozen message is a |
| 16208 | bounce message, it is just discarded; otherwise, a bounce is sent to the |
| 16209 | sender, in a similar manner to cancellation by the &%-Mg%& command line option. |
| 16210 | If you want to timeout frozen bounce messages earlier than other kinds of |
| 16211 | frozen message, see &%ignore_bounce_errors_after%&. |
| 16212 | |
| 16213 | &*Note:*& the default value of zero means no timeouts; with this setting, |
| 16214 | frozen messages remain on the queue forever (except for any frozen bounce |
| 16215 | messages that are released by &%ignore_bounce_errors_after%&). |
| 16216 | |
| 16217 | |
| 16218 | .option timezone main string unset |
| 16219 | .cindex "timezone, setting" |
| 16220 | The value of &%timezone%& is used to set the environment variable TZ while |
| 16221 | running Exim (if it is different on entry). This ensures that all timestamps |
| 16222 | created by Exim are in the required timezone. If you want all your timestamps |
| 16223 | to be in UTC (aka GMT) you should set |
| 16224 | .code |
| 16225 | timezone = UTC |
| 16226 | .endd |
| 16227 | The default value is taken from TIMEZONE_DEFAULT in &_Local/Makefile_&, |
| 16228 | or, if that is not set, from the value of the TZ environment variable when Exim |
| 16229 | is built. If &%timezone%& is set to the empty string, either at build or run |
| 16230 | time, any existing TZ variable is removed from the environment when Exim |
| 16231 | runs. This is appropriate behaviour for obtaining wall-clock time on some, but |
| 16232 | unfortunately not all, operating systems. |
| 16233 | |
| 16234 | |
| 16235 | .option tls_advertise_hosts main "host list&!!" unset |
| 16236 | .cindex "TLS" "advertising" |
| 16237 | .cindex "encryption" "on SMTP connection" |
| 16238 | .cindex "SMTP" "encrypted connection" |
| 16239 | When Exim is built with support for TLS encrypted connections, the availability |
| 16240 | of the STARTTLS command to set up an encrypted session is advertised in |
| 16241 | response to EHLO only to those client hosts that match this option. See |
| 16242 | chapter &<<CHAPTLS>>& for details of Exim's support for TLS. |
| 16243 | |
| 16244 | |
| 16245 | .option tls_certificate main string&!! unset |
| 16246 | .cindex "TLS" "server certificate; location of" |
| 16247 | .cindex "certificate" "server, location of" |
| 16248 | The value of this option is expanded, and must then be the absolute path to a |
| 16249 | file which contains the server's certificates. The server's private key is also |
| 16250 | assumed to be in this file if &%tls_privatekey%& is unset. See chapter |
| 16251 | &<<CHAPTLS>>& for further details. |
| 16252 | |
| 16253 | &*Note*&: The certificates defined by this option are used only when Exim is |
| 16254 | receiving incoming messages as a server. If you want to supply certificates for |
| 16255 | use when sending messages as a client, you must set the &%tls_certificate%& |
| 16256 | option in the relevant &(smtp)& transport. |
| 16257 | |
| 16258 | If the option contains &$tls_out_sni$& and Exim is built against OpenSSL, then |
| 16259 | if the OpenSSL build supports TLS extensions and the TLS client sends the |
| 16260 | Server Name Indication extension, then this option and others documented in |
| 16261 | &<<SECTtlssni>>& will be re-expanded. |
| 16262 | |
| 16263 | .option tls_crl main string&!! unset |
| 16264 | .cindex "TLS" "server certificate revocation list" |
| 16265 | .cindex "certificate" "revocation list for server" |
| 16266 | This option specifies a certificate revocation list. The expanded value must |
| 16267 | be the name of a file that contains a CRL in PEM format. |
| 16268 | |
| 16269 | See &<<SECTtlssni>>& for discussion of when this option might be re-expanded. |
| 16270 | |
| 16271 | |
| 16272 | .option tls_dh_max_bits main integer 2236 |
| 16273 | .cindex "TLS" "D-H bit count" |
| 16274 | The number of bits used for Diffie-Hellman key-exchange may be suggested by |
| 16275 | the chosen TLS library. That value might prove to be too high for |
| 16276 | interoperability. This option provides a maximum clamp on the value |
| 16277 | suggested, trading off security for interoperability. |
| 16278 | |
| 16279 | The value must be at least 1024. |
| 16280 | |
| 16281 | The value 2236 was chosen because, at time of adding the option, it was the |
| 16282 | hard-coded maximum value supported by the NSS cryptographic library, as used |
| 16283 | by Thunderbird, while GnuTLS was suggesting 2432 bits as normal. |
| 16284 | |
| 16285 | If you prefer more security and are willing to break some clients, raise this |
| 16286 | number. |
| 16287 | |
| 16288 | Note that the value passed to GnuTLS for *generating* a new prime may be a |
| 16289 | little less than this figure, because GnuTLS is inexact and may produce a |
| 16290 | larger prime than requested. |
| 16291 | |
| 16292 | |
| 16293 | .option tls_dhparam main string&!! unset |
| 16294 | .cindex "TLS" "D-H parameters for server" |
| 16295 | The value of this option is expanded and indicates the source of DH parameters |
| 16296 | to be used by Exim. |
| 16297 | |
| 16298 | If it is a filename starting with a &`/`&, then it names a file from which DH |
| 16299 | parameters should be loaded. If the file exists, it should hold a PEM-encoded |
| 16300 | PKCS#3 representation of the DH prime. If the file does not exist, for |
| 16301 | OpenSSL it is an error. For GnuTLS, Exim will attempt to create the file and |
| 16302 | fill it with a generated DH prime. For OpenSSL, if the DH bit-count from |
| 16303 | loading the file is greater than &%tls_dh_max_bits%& then it will be ignored, |
| 16304 | and treated as though the &%tls_dhparam%& were set to "none". |
| 16305 | |
| 16306 | If this option expands to the string "none", then no DH parameters will be |
| 16307 | loaded by Exim. |
| 16308 | |
| 16309 | If this option expands to the string "historic" and Exim is using GnuTLS, then |
| 16310 | Exim will attempt to load a file from inside the spool directory. If the file |
| 16311 | does not exist, Exim will attempt to create it. |
| 16312 | See section &<<SECTgnutlsparam>>& for further details. |
| 16313 | |
| 16314 | If Exim is using OpenSSL and this option is empty or unset, then Exim will load |
| 16315 | a default DH prime; the default is the 2048 bit prime described in section |
| 16316 | 2.2 of RFC 5114, "2048-bit MODP Group with 224-bit Prime Order Subgroup", which |
| 16317 | in IKE is assigned number 23. |
| 16318 | |
| 16319 | Otherwise, the option must expand to the name used by Exim for any of a number |
| 16320 | of DH primes specified in RFC 2409, RFC 3526 and RFC 5114. As names, Exim uses |
| 16321 | "ike" followed by the number used by IKE, of "default" which corresponds to |
| 16322 | "ike23". |
| 16323 | |
| 16324 | The available primes are: |
| 16325 | &`ike1`&, &`ike2`&, &`ike5`&, |
| 16326 | &`ike14`&, &`ike15`&, &`ike16`&, &`ike17`&, &`ike18`&, |
| 16327 | &`ike22`&, &`ike23`& (aka &`default`&) and &`ike24`&. |
| 16328 | |
| 16329 | Some of these will be too small to be accepted by clients. |
| 16330 | Some may be too large to be accepted by clients. |
| 16331 | |
| 16332 | The TLS protocol does not negotiate an acceptable size for this; clients tend |
| 16333 | to hard-drop connections if what is offered by the server is unacceptable, |
| 16334 | whether too large or too small, and there's no provision for the client to |
| 16335 | tell the server what these constraints are. Thus, as a server operator, you |
| 16336 | need to make an educated guess as to what is most likely to work for your |
| 16337 | userbase. |
| 16338 | |
| 16339 | Some known size constraints suggest that a bit-size in the range 2048 to 2236 |
| 16340 | is most likely to maximise interoperability. The upper bound comes from |
| 16341 | applications using the Mozilla Network Security Services (NSS) library, which |
| 16342 | used to set its &`DH_MAX_P_BITS`& upper-bound to 2236. This affects many |
| 16343 | mail user agents (MUAs). The lower bound comes from Debian installs of Exim4 |
| 16344 | prior to the 4.80 release, as Debian used to patch Exim to raise the minimum |
| 16345 | acceptable bound from 1024 to 2048. |
| 16346 | |
| 16347 | |
| 16348 | .option tls_ocsp_file main string&!! unset |
| 16349 | This option |
| 16350 | must if set expand to the absolute path to a file which contains a current |
| 16351 | status proof for the server's certificate, as obtained from the |
| 16352 | Certificate Authority. |
| 16353 | |
| 16354 | |
| 16355 | .option tls_on_connect_ports main "string list" unset |
| 16356 | This option specifies a list of incoming SSMTP (aka SMTPS) ports that should |
| 16357 | operate the obsolete SSMTP (SMTPS) protocol, where a TLS session is immediately |
| 16358 | set up without waiting for the client to issue a STARTTLS command. For |
| 16359 | further details, see section &<<SECTsupobssmt>>&. |
| 16360 | |
| 16361 | |
| 16362 | |
| 16363 | .option tls_privatekey main string&!! unset |
| 16364 | .cindex "TLS" "server private key; location of" |
| 16365 | The value of this option is expanded, and must then be the absolute path to a |
| 16366 | file which contains the server's private key. If this option is unset, or if |
| 16367 | the expansion is forced to fail, or the result is an empty string, the private |
| 16368 | key is assumed to be in the same file as the server's certificates. See chapter |
| 16369 | &<<CHAPTLS>>& for further details. |
| 16370 | |
| 16371 | See &<<SECTtlssni>>& for discussion of when this option might be re-expanded. |
| 16372 | |
| 16373 | |
| 16374 | .option tls_remember_esmtp main boolean false |
| 16375 | .cindex "TLS" "esmtp state; remembering" |
| 16376 | .cindex "TLS" "broken clients" |
| 16377 | If this option is set true, Exim violates the RFCs by remembering that it is in |
| 16378 | &"esmtp"& state after successfully negotiating a TLS session. This provides |
| 16379 | support for broken clients that fail to send a new EHLO after starting a |
| 16380 | TLS session. |
| 16381 | |
| 16382 | |
| 16383 | .option tls_require_ciphers main string&!! unset |
| 16384 | .cindex "TLS" "requiring specific ciphers" |
| 16385 | .cindex "cipher" "requiring specific" |
| 16386 | This option controls which ciphers can be used for incoming TLS connections. |
| 16387 | The &(smtp)& transport has an option of the same name for controlling outgoing |
| 16388 | connections. This option is expanded for each connection, so can be varied for |
| 16389 | different clients if required. The value of this option must be a list of |
| 16390 | permitted cipher suites. The OpenSSL and GnuTLS libraries handle cipher control |
| 16391 | in somewhat different ways. If GnuTLS is being used, the client controls the |
| 16392 | preference order of the available ciphers. Details are given in sections |
| 16393 | &<<SECTreqciphssl>>& and &<<SECTreqciphgnu>>&. |
| 16394 | |
| 16395 | |
| 16396 | .option tls_try_verify_hosts main "host list&!!" unset |
| 16397 | .cindex "TLS" "client certificate verification" |
| 16398 | .cindex "certificate" "verification of client" |
| 16399 | See &%tls_verify_hosts%& below. |
| 16400 | |
| 16401 | |
| 16402 | .option tls_verify_certificates main string&!! unset |
| 16403 | .cindex "TLS" "client certificate verification" |
| 16404 | .cindex "certificate" "verification of client" |
| 16405 | The value of this option is expanded, and must then be the absolute path to |
| 16406 | a file containing permitted certificates for clients that |
| 16407 | match &%tls_verify_hosts%& or &%tls_try_verify_hosts%&. Alternatively, if you |
| 16408 | are using OpenSSL, you can set &%tls_verify_certificates%& to the name of a |
| 16409 | directory containing certificate files. This does not work with GnuTLS; the |
| 16410 | option must be set to the name of a single file if you are using GnuTLS. |
| 16411 | |
| 16412 | These certificates should be for the certificate authorities trusted, rather |
| 16413 | than the public cert of individual clients. With both OpenSSL and GnuTLS, if |
| 16414 | the value is a file then the certificates are sent by Exim as a server to |
| 16415 | connecting clients, defining the list of accepted certificate authorities. |
| 16416 | Thus the values defined should be considered public data. To avoid this, |
| 16417 | use OpenSSL with a directory. |
| 16418 | |
| 16419 | See &<<SECTtlssni>>& for discussion of when this option might be re-expanded. |
| 16420 | |
| 16421 | A forced expansion failure or setting to an empty string is equivalent to |
| 16422 | being unset. |
| 16423 | |
| 16424 | |
| 16425 | .option tls_verify_hosts main "host list&!!" unset |
| 16426 | .cindex "TLS" "client certificate verification" |
| 16427 | .cindex "certificate" "verification of client" |
| 16428 | This option, along with &%tls_try_verify_hosts%&, controls the checking of |
| 16429 | certificates from clients. The expected certificates are defined by |
| 16430 | &%tls_verify_certificates%&, which must be set. A configuration error occurs if |
| 16431 | either &%tls_verify_hosts%& or &%tls_try_verify_hosts%& is set and |
| 16432 | &%tls_verify_certificates%& is not set. |
| 16433 | |
| 16434 | Any client that matches &%tls_verify_hosts%& is constrained by |
| 16435 | &%tls_verify_certificates%&. When the client initiates a TLS session, it must |
| 16436 | present one of the listed certificates. If it does not, the connection is |
| 16437 | aborted. &*Warning*&: Including a host in &%tls_verify_hosts%& does not require |
| 16438 | the host to use TLS. It can still send SMTP commands through unencrypted |
| 16439 | connections. Forcing a client to use TLS has to be done separately using an |
| 16440 | ACL to reject inappropriate commands when the connection is not encrypted. |
| 16441 | |
| 16442 | A weaker form of checking is provided by &%tls_try_verify_hosts%&. If a client |
| 16443 | matches this option (but not &%tls_verify_hosts%&), Exim requests a |
| 16444 | certificate and checks it against &%tls_verify_certificates%&, but does not |
| 16445 | abort the connection if there is no certificate or if it does not match. This |
| 16446 | state can be detected in an ACL, which makes it possible to implement policies |
| 16447 | such as &"accept for relay only if a verified certificate has been received, |
| 16448 | but accept for local delivery if encrypted, even without a verified |
| 16449 | certificate"&. |
| 16450 | |
| 16451 | Client hosts that match neither of these lists are not asked to present |
| 16452 | certificates. |
| 16453 | |
| 16454 | |
| 16455 | .option trusted_groups main "string list&!!" unset |
| 16456 | .cindex "trusted groups" |
| 16457 | .cindex "groups" "trusted" |
| 16458 | This option is expanded just once, at the start of Exim's processing. If this |
| 16459 | option is set, any process that is running in one of the listed groups, or |
| 16460 | which has one of them as a supplementary group, is trusted. The groups can be |
| 16461 | specified numerically or by name. See section &<<SECTtrustedadmin>>& for |
| 16462 | details of what trusted callers are permitted to do. If neither |
| 16463 | &%trusted_groups%& nor &%trusted_users%& is set, only root and the Exim user |
| 16464 | are trusted. |
| 16465 | |
| 16466 | .option trusted_users main "string list&!!" unset |
| 16467 | .cindex "trusted users" |
| 16468 | .cindex "user" "trusted" |
| 16469 | This option is expanded just once, at the start of Exim's processing. If this |
| 16470 | option is set, any process that is running as one of the listed users is |
| 16471 | trusted. The users can be specified numerically or by name. See section |
| 16472 | &<<SECTtrustedadmin>>& for details of what trusted callers are permitted to do. |
| 16473 | If neither &%trusted_groups%& nor &%trusted_users%& is set, only root and the |
| 16474 | Exim user are trusted. |
| 16475 | |
| 16476 | .option unknown_login main string&!! unset |
| 16477 | .cindex "uid (user id)" "unknown caller" |
| 16478 | .vindex "&$caller_uid$&" |
| 16479 | This is a specialized feature for use in unusual configurations. By default, if |
| 16480 | the uid of the caller of Exim cannot be looked up using &[getpwuid()]&, Exim |
| 16481 | gives up. The &%unknown_login%& option can be used to set a login name to be |
| 16482 | used in this circumstance. It is expanded, so values like &%user$caller_uid%& |
| 16483 | can be set. When &%unknown_login%& is used, the value of &%unknown_username%& |
| 16484 | is used for the user's real name (gecos field), unless this has been set by the |
| 16485 | &%-F%& option. |
| 16486 | |
| 16487 | .option unknown_username main string unset |
| 16488 | See &%unknown_login%&. |
| 16489 | |
| 16490 | .option untrusted_set_sender main "address list&!!" unset |
| 16491 | .cindex "trusted users" |
| 16492 | .cindex "sender" "setting by untrusted user" |
| 16493 | .cindex "untrusted user setting sender" |
| 16494 | .cindex "user" "untrusted setting sender" |
| 16495 | .cindex "envelope sender" |
| 16496 | When an untrusted user submits a message to Exim using the standard input, Exim |
| 16497 | normally creates an envelope sender address from the user's login and the |
| 16498 | default qualification domain. Data from the &%-f%& option (for setting envelope |
| 16499 | senders on non-SMTP messages) or the SMTP MAIL command (if &%-bs%& or &%-bS%& |
| 16500 | is used) is ignored. |
| 16501 | |
| 16502 | However, untrusted users are permitted to set an empty envelope sender address, |
| 16503 | to declare that a message should never generate any bounces. For example: |
| 16504 | .code |
| 16505 | exim -f '<>' user@domain.example |
| 16506 | .endd |
| 16507 | .vindex "&$sender_ident$&" |
| 16508 | The &%untrusted_set_sender%& option allows you to permit untrusted users to set |
| 16509 | other envelope sender addresses in a controlled way. When it is set, untrusted |
| 16510 | users are allowed to set envelope sender addresses that match any of the |
| 16511 | patterns in the list. Like all address lists, the string is expanded. The |
| 16512 | identity of the user is in &$sender_ident$&, so you can, for example, restrict |
| 16513 | users to setting senders that start with their login ids |
| 16514 | followed by a hyphen |
| 16515 | by a setting like this: |
| 16516 | .code |
| 16517 | untrusted_set_sender = ^$sender_ident- |
| 16518 | .endd |
| 16519 | If you want to allow untrusted users to set envelope sender addresses without |
| 16520 | restriction, you can use |
| 16521 | .code |
| 16522 | untrusted_set_sender = * |
| 16523 | .endd |
| 16524 | The &%untrusted_set_sender%& option applies to all forms of local input, but |
| 16525 | only to the setting of the envelope sender. It does not permit untrusted users |
| 16526 | to use the other options which trusted user can use to override message |
| 16527 | parameters. Furthermore, it does not stop Exim from removing an existing |
| 16528 | &'Sender:'& header in the message, or from adding a &'Sender:'& header if |
| 16529 | necessary. See &%local_sender_retain%& and &%local_from_check%& for ways of |
| 16530 | overriding these actions. The handling of the &'Sender:'& header is also |
| 16531 | described in section &<<SECTthesenhea>>&. |
| 16532 | |
| 16533 | The log line for a message's arrival shows the envelope sender following |
| 16534 | &"<="&. For local messages, the user's login always follows, after &"U="&. In |
| 16535 | &%-bp%& displays, and in the Exim monitor, if an untrusted user sets an |
| 16536 | envelope sender address, the user's login is shown in parentheses after the |
| 16537 | sender address. |
| 16538 | |
| 16539 | |
| 16540 | .option uucp_from_pattern main string "see below" |
| 16541 | .cindex "&""From""& line" |
| 16542 | .cindex "UUCP" "&""From""& line" |
| 16543 | Some applications that pass messages to an MTA via a command line interface use |
| 16544 | an initial line starting with &"From&~"& to pass the envelope sender. In |
| 16545 | particular, this is used by UUCP software. Exim recognizes such a line by means |
| 16546 | of a regular expression that is set in &%uucp_from_pattern%&. When the pattern |
| 16547 | matches, the sender address is constructed by expanding the contents of |
| 16548 | &%uucp_from_sender%&, provided that the caller of Exim is a trusted user. The |
| 16549 | default pattern recognizes lines in the following two forms: |
| 16550 | .code |
| 16551 | From ph10 Fri Jan 5 12:35 GMT 1996 |
| 16552 | From ph10 Fri, 7 Jan 97 14:00:00 GMT |
| 16553 | .endd |
| 16554 | The pattern can be seen by running |
| 16555 | .code |
| 16556 | exim -bP uucp_from_pattern |
| 16557 | .endd |
| 16558 | It checks only up to the hours and minutes, and allows for a 2-digit or 4-digit |
| 16559 | year in the second case. The first word after &"From&~"& is matched in the |
| 16560 | regular expression by a parenthesized subpattern. The default value for |
| 16561 | &%uucp_from_sender%& is &"$1"&, which therefore just uses this first word |
| 16562 | (&"ph10"& in the example above) as the message's sender. See also |
| 16563 | &%ignore_fromline_hosts%&. |
| 16564 | |
| 16565 | |
| 16566 | .option uucp_from_sender main string&!! &`$1`& |
| 16567 | See &%uucp_from_pattern%& above. |
| 16568 | |
| 16569 | |
| 16570 | .option warn_message_file main string unset |
| 16571 | .cindex "warning of delay" "customizing the message" |
| 16572 | .cindex "customizing" "warning message" |
| 16573 | This option defines a template file containing paragraphs of text to be used |
| 16574 | for constructing the warning message which is sent by Exim when a message has |
| 16575 | been on the queue for a specified amount of time, as specified by |
| 16576 | &%delay_warning%&. Details of the file's contents are given in chapter |
| 16577 | &<<CHAPemsgcust>>&. See also &%bounce_message_file%&. |
| 16578 | |
| 16579 | |
| 16580 | .option write_rejectlog main boolean true |
| 16581 | .cindex "reject log" "disabling" |
| 16582 | If this option is set false, Exim no longer writes anything to the reject log. |
| 16583 | See chapter &<<CHAPlog>>& for details of what Exim writes to its logs. |
| 16584 | .ecindex IIDconfima |
| 16585 | .ecindex IIDmaiconf |
| 16586 | |
| 16587 | |
| 16588 | |
| 16589 | |
| 16590 | . //////////////////////////////////////////////////////////////////////////// |
| 16591 | . //////////////////////////////////////////////////////////////////////////// |
| 16592 | |
| 16593 | .chapter "Generic options for routers" "CHAProutergeneric" |
| 16594 | .scindex IIDgenoprou1 "options" "generic; for routers" |
| 16595 | .scindex IIDgenoprou2 "generic options" "router" |
| 16596 | This chapter describes the generic options that apply to all routers. |
| 16597 | Those that are preconditions are marked with ‡ in the &"use"& field. |
| 16598 | |
| 16599 | For a general description of how a router operates, see sections |
| 16600 | &<<SECTrunindrou>>& and &<<SECTrouprecon>>&. The latter specifies the order in |
| 16601 | which the preconditions are tested. The order of expansion of the options that |
| 16602 | provide data for a transport is: &%errors_to%&, &%headers_add%&, |
| 16603 | &%headers_remove%&, &%transport%&. |
| 16604 | |
| 16605 | |
| 16606 | |
| 16607 | .option address_data routers string&!! unset |
| 16608 | .cindex "router" "data attached to address" |
| 16609 | The string is expanded just before the router is run, that is, after all the |
| 16610 | precondition tests have succeeded. If the expansion is forced to fail, the |
| 16611 | router declines, the value of &%address_data%& remains unchanged, and the |
| 16612 | &%more%& option controls what happens next. Other expansion failures cause |
| 16613 | delivery of the address to be deferred. |
| 16614 | |
| 16615 | .vindex "&$address_data$&" |
| 16616 | When the expansion succeeds, the value is retained with the address, and can be |
| 16617 | accessed using the variable &$address_data$& in the current router, subsequent |
| 16618 | routers, and the eventual transport. |
| 16619 | |
| 16620 | &*Warning*&: If the current or any subsequent router is a &(redirect)& router |
| 16621 | that runs a user's filter file, the contents of &$address_data$& are accessible |
| 16622 | in the filter. This is not normally a problem, because such data is usually |
| 16623 | either not confidential or it &"belongs"& to the current user, but if you do |
| 16624 | put confidential data into &$address_data$& you need to remember this point. |
| 16625 | |
| 16626 | Even if the router declines or passes, the value of &$address_data$& remains |
| 16627 | with the address, though it can be changed by another &%address_data%& setting |
| 16628 | on a subsequent router. If a router generates child addresses, the value of |
| 16629 | &$address_data$& propagates to them. This also applies to the special kind of |
| 16630 | &"child"& that is generated by a router with the &%unseen%& option. |
| 16631 | |
| 16632 | The idea of &%address_data%& is that you can use it to look up a lot of data |
| 16633 | for the address once, and then pick out parts of the data later. For example, |
| 16634 | you could use a single LDAP lookup to return a string of the form |
| 16635 | .code |
| 16636 | uid=1234 gid=5678 mailbox=/mail/xyz forward=/home/xyz/.forward |
| 16637 | .endd |
| 16638 | In the transport you could pick out the mailbox by a setting such as |
| 16639 | .code |
| 16640 | file = ${extract{mailbox}{$address_data}} |
| 16641 | .endd |
| 16642 | This makes the configuration file less messy, and also reduces the number of |
| 16643 | lookups (though Exim does cache lookups). |
| 16644 | |
| 16645 | .vindex "&$sender_address_data$&" |
| 16646 | .vindex "&$address_data$&" |
| 16647 | The &%address_data%& facility is also useful as a means of passing information |
| 16648 | from one router to another, and from a router to a transport. In addition, if |
| 16649 | &$address_data$& is set by a router when verifying a recipient address from an |
| 16650 | ACL, it remains available for use in the rest of the ACL statement. After |
| 16651 | verifying a sender, the value is transferred to &$sender_address_data$&. |
| 16652 | |
| 16653 | |
| 16654 | |
| 16655 | .option address_test routers&!? boolean true |
| 16656 | .oindex "&%-bt%&" |
| 16657 | .cindex "router" "skipping when address testing" |
| 16658 | If this option is set false, the router is skipped when routing is being tested |
| 16659 | by means of the &%-bt%& command line option. This can be a convenience when |
| 16660 | your first router sends messages to an external scanner, because it saves you |
| 16661 | having to set the &"already scanned"& indicator when testing real address |
| 16662 | routing. |
| 16663 | |
| 16664 | |
| 16665 | |
| 16666 | .option cannot_route_message routers string&!! unset |
| 16667 | .cindex "router" "customizing &""cannot route""& message" |
| 16668 | .cindex "customizing" "&""cannot route""& message" |
| 16669 | This option specifies a text message that is used when an address cannot be |
| 16670 | routed because Exim has run out of routers. The default message is |
| 16671 | &"Unrouteable address"&. This option is useful only on routers that have |
| 16672 | &%more%& set false, or on the very last router in a configuration, because the |
| 16673 | value that is used is taken from the last router that is considered. This |
| 16674 | includes a router that is skipped because its preconditions are not met, as |
| 16675 | well as a router that declines. For example, using the default configuration, |
| 16676 | you could put: |
| 16677 | .code |
| 16678 | cannot_route_message = Remote domain not found in DNS |
| 16679 | .endd |
| 16680 | on the first router, which is a &(dnslookup)& router with &%more%& set false, |
| 16681 | and |
| 16682 | .code |
| 16683 | cannot_route_message = Unknown local user |
| 16684 | .endd |
| 16685 | on the final router that checks for local users. If string expansion fails for |
| 16686 | this option, the default message is used. Unless the expansion failure was |
| 16687 | explicitly forced, a message about the failure is written to the main and panic |
| 16688 | logs, in addition to the normal message about the routing failure. |
| 16689 | |
| 16690 | |
| 16691 | .option caseful_local_part routers boolean false |
| 16692 | .cindex "case of local parts" |
| 16693 | .cindex "router" "case of local parts" |
| 16694 | By default, routers handle the local parts of addresses in a case-insensitive |
| 16695 | manner, though the actual case is preserved for transmission with the message. |
| 16696 | If you want the case of letters to be significant in a router, you must set |
| 16697 | this option true. For individual router options that contain address or local |
| 16698 | part lists (for example, &%local_parts%&), case-sensitive matching can be |
| 16699 | turned on by &"+caseful"& as a list item. See section &<<SECTcasletadd>>& for |
| 16700 | more details. |
| 16701 | |
| 16702 | .vindex "&$local_part$&" |
| 16703 | .vindex "&$original_local_part$&" |
| 16704 | .vindex "&$parent_local_part$&" |
| 16705 | The value of the &$local_part$& variable is forced to lower case while a |
| 16706 | router is running unless &%caseful_local_part%& is set. When a router assigns |
| 16707 | an address to a transport, the value of &$local_part$& when the transport runs |
| 16708 | is the same as it was in the router. Similarly, when a router generates child |
| 16709 | addresses by aliasing or forwarding, the values of &$original_local_part$& |
| 16710 | and &$parent_local_part$& are those that were used by the redirecting router. |
| 16711 | |
| 16712 | This option applies to the processing of an address by a router. When a |
| 16713 | recipient address is being processed in an ACL, there is a separate &%control%& |
| 16714 | modifier that can be used to specify case-sensitive processing within the ACL |
| 16715 | (see section &<<SECTcontrols>>&). |
| 16716 | |
| 16717 | |
| 16718 | |
| 16719 | .option check_local_user routers&!? boolean false |
| 16720 | .cindex "local user, checking in router" |
| 16721 | .cindex "router" "checking for local user" |
| 16722 | .cindex "&_/etc/passwd_&" |
| 16723 | .vindex "&$home$&" |
| 16724 | When this option is true, Exim checks that the local part of the recipient |
| 16725 | address (with affixes removed if relevant) is the name of an account on the |
| 16726 | local system. The check is done by calling the &[getpwnam()]& function rather |
| 16727 | than trying to read &_/etc/passwd_& directly. This means that other methods of |
| 16728 | holding password data (such as NIS) are supported. If the local part is a local |
| 16729 | user, &$home$& is set from the password data, and can be tested in other |
| 16730 | preconditions that are evaluated after this one (the order of evaluation is |
| 16731 | given in section &<<SECTrouprecon>>&). However, the value of &$home$& can be |
| 16732 | overridden by &%router_home_directory%&. If the local part is not a local user, |
| 16733 | the router is skipped. |
| 16734 | |
| 16735 | If you want to check that the local part is either the name of a local user |
| 16736 | or matches something else, you cannot combine &%check_local_user%& with a |
| 16737 | setting of &%local_parts%&, because that specifies the logical &'and'& of the |
| 16738 | two conditions. However, you can use a &(passwd)& lookup in a &%local_parts%& |
| 16739 | setting to achieve this. For example: |
| 16740 | .code |
| 16741 | local_parts = passwd;$local_part : lsearch;/etc/other/users |
| 16742 | .endd |
| 16743 | Note, however, that the side effects of &%check_local_user%& (such as setting |
| 16744 | up a home directory) do not occur when a &(passwd)& lookup is used in a |
| 16745 | &%local_parts%& (or any other) precondition. |
| 16746 | |
| 16747 | |
| 16748 | |
| 16749 | .option condition routers&!? string&!! unset |
| 16750 | .cindex "router" "customized precondition" |
| 16751 | This option specifies a general precondition test that has to succeed for the |
| 16752 | router to be called. The &%condition%& option is the last precondition to be |
| 16753 | evaluated (see section &<<SECTrouprecon>>&). The string is expanded, and if the |
| 16754 | result is a forced failure, or an empty string, or one of the strings &"0"& or |
| 16755 | &"no"& or &"false"& (checked without regard to the case of the letters), the |
| 16756 | router is skipped, and the address is offered to the next one. |
| 16757 | |
| 16758 | If the result is any other value, the router is run (as this is the last |
| 16759 | precondition to be evaluated, all the other preconditions must be true). |
| 16760 | |
| 16761 | This option is unusual in that multiple &%condition%& options may be present. |
| 16762 | All &%condition%& options must succeed. |
| 16763 | |
| 16764 | The &%condition%& option provides a means of applying custom conditions to the |
| 16765 | running of routers. Note that in the case of a simple conditional expansion, |
| 16766 | the default expansion values are exactly what is wanted. For example: |
| 16767 | .code |
| 16768 | condition = ${if >{$message_age}{600}} |
| 16769 | .endd |
| 16770 | Because of the default behaviour of the string expansion, this is equivalent to |
| 16771 | .code |
| 16772 | condition = ${if >{$message_age}{600}{true}{}} |
| 16773 | .endd |
| 16774 | |
| 16775 | A multiple condition example, which succeeds: |
| 16776 | .code |
| 16777 | condition = ${if >{$message_age}{600}} |
| 16778 | condition = ${if !eq{${lc:$local_part}}{postmaster}} |
| 16779 | condition = foobar |
| 16780 | .endd |
| 16781 | |
| 16782 | If the expansion fails (other than forced failure) delivery is deferred. Some |
| 16783 | of the other precondition options are common special cases that could in fact |
| 16784 | be specified using &%condition%&. |
| 16785 | |
| 16786 | |
| 16787 | .option debug_print routers string&!! unset |
| 16788 | .cindex "testing" "variables in drivers" |
| 16789 | If this option is set and debugging is enabled (see the &%-d%& command line |
| 16790 | option) or in address-testing mode (see the &%-bt%& command line option), |
| 16791 | the string is expanded and included in the debugging output. |
| 16792 | If expansion of the string fails, the error message is written to the debugging |
| 16793 | output, and Exim carries on processing. |
| 16794 | This option is provided to help with checking out the values of variables and |
| 16795 | so on when debugging router configurations. For example, if a &%condition%& |
| 16796 | option appears not to be working, &%debug_print%& can be used to output the |
| 16797 | variables it references. The output happens after checks for &%domains%&, |
| 16798 | &%local_parts%&, and &%check_local_user%& but before any other preconditions |
| 16799 | are tested. A newline is added to the text if it does not end with one. |
| 16800 | The variable &$router_name$& contains the name of the router. |
| 16801 | |
| 16802 | |
| 16803 | |
| 16804 | .option disable_logging routers boolean false |
| 16805 | If this option is set true, nothing is logged for any routing errors |
| 16806 | or for any deliveries caused by this router. You should not set this option |
| 16807 | unless you really, really know what you are doing. See also the generic |
| 16808 | transport option of the same name. |
| 16809 | |
| 16810 | |
| 16811 | .option domains routers&!? "domain list&!!" unset |
| 16812 | .cindex "router" "restricting to specific domains" |
| 16813 | .vindex "&$domain_data$&" |
| 16814 | If this option is set, the router is skipped unless the current domain matches |
| 16815 | the list. If the match is achieved by means of a file lookup, the data that the |
| 16816 | lookup returned for the domain is placed in &$domain_data$& for use in string |
| 16817 | expansions of the driver's private options. See section &<<SECTrouprecon>>& for |
| 16818 | a list of the order in which preconditions are evaluated. |
| 16819 | |
| 16820 | |
| 16821 | |
| 16822 | .option driver routers string unset |
| 16823 | This option must always be set. It specifies which of the available routers is |
| 16824 | to be used. |
| 16825 | |
| 16826 | |
| 16827 | |
| 16828 | .option errors_to routers string&!! unset |
| 16829 | .cindex "envelope sender" |
| 16830 | .cindex "router" "changing address for errors" |
| 16831 | If a router successfully handles an address, it may assign the address to a |
| 16832 | transport for delivery or it may generate child addresses. In both cases, if |
| 16833 | there is a delivery problem during later processing, the resulting bounce |
| 16834 | message is sent to the address that results from expanding this string, |
| 16835 | provided that the address verifies successfully. The &%errors_to%& option is |
| 16836 | expanded before &%headers_add%&, &%headers_remove%&, and &%transport%&. |
| 16837 | |
| 16838 | The &%errors_to%& setting associated with an address can be overridden if it |
| 16839 | subsequently passes through other routers that have their own &%errors_to%& |
| 16840 | settings, or if the message is delivered by a transport with a &%return_path%& |
| 16841 | setting. |
| 16842 | |
| 16843 | If &%errors_to%& is unset, or the expansion is forced to fail, or the result of |
| 16844 | the expansion fails to verify, the errors address associated with the incoming |
| 16845 | address is used. At top level, this is the envelope sender. A non-forced |
| 16846 | expansion failure causes delivery to be deferred. |
| 16847 | |
| 16848 | If an address for which &%errors_to%& has been set ends up being delivered over |
| 16849 | SMTP, the envelope sender for that delivery is the &%errors_to%& value, so that |
| 16850 | any bounces that are generated by other MTAs on the delivery route are also |
| 16851 | sent there. You can set &%errors_to%& to the empty string by either of these |
| 16852 | settings: |
| 16853 | .code |
| 16854 | errors_to = |
| 16855 | errors_to = "" |
| 16856 | .endd |
| 16857 | An expansion item that yields an empty string has the same effect. If you do |
| 16858 | this, a locally detected delivery error for addresses processed by this router |
| 16859 | no longer gives rise to a bounce message; the error is discarded. If the |
| 16860 | address is delivered to a remote host, the return path is set to &`<>`&, unless |
| 16861 | overridden by the &%return_path%& option on the transport. |
| 16862 | |
| 16863 | .vindex "&$address_data$&" |
| 16864 | If for some reason you want to discard local errors, but use a non-empty |
| 16865 | MAIL command for remote delivery, you can preserve the original return |
| 16866 | path in &$address_data$& in the router, and reinstate it in the transport by |
| 16867 | setting &%return_path%&. |
| 16868 | |
| 16869 | The most common use of &%errors_to%& is to direct mailing list bounces to the |
| 16870 | manager of the list, as described in section &<<SECTmailinglists>>&, or to |
| 16871 | implement VERP (Variable Envelope Return Paths) (see section &<<SECTverp>>&). |
| 16872 | |
| 16873 | |
| 16874 | |
| 16875 | .option expn routers&!? boolean true |
| 16876 | .cindex "address" "testing" |
| 16877 | .cindex "testing" "addresses" |
| 16878 | .cindex "EXPN" "router skipping" |
| 16879 | .cindex "router" "skipping for EXPN" |
| 16880 | If this option is turned off, the router is skipped when testing an address |
| 16881 | as a result of processing an SMTP EXPN command. You might, for example, |
| 16882 | want to turn it off on a router for users' &_.forward_& files, while leaving it |
| 16883 | on for the system alias file. |
| 16884 | See section &<<SECTrouprecon>>& for a list of the order in which preconditions |
| 16885 | are evaluated. |
| 16886 | |
| 16887 | The use of the SMTP EXPN command is controlled by an ACL (see chapter |
| 16888 | &<<CHAPACL>>&). When Exim is running an EXPN command, it is similar to testing |
| 16889 | an address with &%-bt%&. Compare VRFY, whose counterpart is &%-bv%&. |
| 16890 | |
| 16891 | |
| 16892 | |
| 16893 | .option fail_verify routers boolean false |
| 16894 | .cindex "router" "forcing verification failure" |
| 16895 | Setting this option has the effect of setting both &%fail_verify_sender%& and |
| 16896 | &%fail_verify_recipient%& to the same value. |
| 16897 | |
| 16898 | |
| 16899 | |
| 16900 | .option fail_verify_recipient routers boolean false |
| 16901 | If this option is true and an address is accepted by this router when |
| 16902 | verifying a recipient, verification fails. |
| 16903 | |
| 16904 | |
| 16905 | |
| 16906 | .option fail_verify_sender routers boolean false |
| 16907 | If this option is true and an address is accepted by this router when |
| 16908 | verifying a sender, verification fails. |
| 16909 | |
| 16910 | |
| 16911 | |
| 16912 | .option fallback_hosts routers "string list" unset |
| 16913 | .cindex "router" "fallback hosts" |
| 16914 | .cindex "fallback" "hosts specified on router" |
| 16915 | String expansion is not applied to this option. The argument must be a |
| 16916 | colon-separated list of host names or IP addresses. The list separator can be |
| 16917 | changed (see section &<<SECTlistconstruct>>&), and a port can be specified with |
| 16918 | each name or address. In fact, the format of each item is exactly the same as |
| 16919 | defined for the list of hosts in a &(manualroute)& router (see section |
| 16920 | &<<SECTformatonehostitem>>&). |
| 16921 | |
| 16922 | If a router queues an address for a remote transport, this host list is |
| 16923 | associated with the address, and used instead of the transport's fallback host |
| 16924 | list. If &%hosts_randomize%& is set on the transport, the order of the list is |
| 16925 | randomized for each use. See the &%fallback_hosts%& option of the &(smtp)& |
| 16926 | transport for further details. |
| 16927 | |
| 16928 | |
| 16929 | .option group routers string&!! "see below" |
| 16930 | .cindex "gid (group id)" "local delivery" |
| 16931 | .cindex "local transports" "uid and gid" |
| 16932 | .cindex "transport" "local" |
| 16933 | .cindex "router" "setting group" |
| 16934 | When a router queues an address for a transport, and the transport does not |
| 16935 | specify a group, the group given here is used when running the delivery |
| 16936 | process. |
| 16937 | The group may be specified numerically or by name. If expansion fails, the |
| 16938 | error is logged and delivery is deferred. |
| 16939 | The default is unset, unless &%check_local_user%& is set, when the default |
| 16940 | is taken from the password information. See also &%initgroups%& and &%user%& |
| 16941 | and the discussion in chapter &<<CHAPenvironment>>&. |
| 16942 | |
| 16943 | |
| 16944 | |
| 16945 | .option headers_add routers list&!! unset |
| 16946 | .cindex "header lines" "adding" |
| 16947 | .cindex "router" "adding header lines" |
| 16948 | This option specifies a list of text headers, newline-separated, |
| 16949 | that is associated with any addresses that are accepted by the router. |
| 16950 | Each item is separately expanded, at routing time. However, this |
| 16951 | option has no effect when an address is just being verified. The way in which |
| 16952 | the text is used to add header lines at transport time is described in section |
| 16953 | &<<SECTheadersaddrem>>&. New header lines are not actually added until the |
| 16954 | message is in the process of being transported. This means that references to |
| 16955 | header lines in string expansions in the transport's configuration do not |
| 16956 | &"see"& the added header lines. |
| 16957 | |
| 16958 | The &%headers_add%& option is expanded after &%errors_to%&, but before |
| 16959 | &%headers_remove%& and &%transport%&. If an item is empty, or if |
| 16960 | an item expansion is forced to fail, the item has no effect. Other expansion |
| 16961 | failures are treated as configuration errors. |
| 16962 | |
| 16963 | Unlike most options, &%headers_add%& can be specified multiple times |
| 16964 | for a router; all listed headers are added. |
| 16965 | |
| 16966 | &*Warning 1*&: The &%headers_add%& option cannot be used for a &(redirect)& |
| 16967 | router that has the &%one_time%& option set. |
| 16968 | |
| 16969 | .cindex "duplicate addresses" |
| 16970 | .oindex "&%unseen%&" |
| 16971 | &*Warning 2*&: If the &%unseen%& option is set on the router, all header |
| 16972 | additions are deleted when the address is passed on to subsequent routers. |
| 16973 | For a &%redirect%& router, if a generated address is the same as the incoming |
| 16974 | address, this can lead to duplicate addresses with different header |
| 16975 | modifications. Exim does not do duplicate deliveries (except, in certain |
| 16976 | circumstances, to pipes -- see section &<<SECTdupaddr>>&), but it is undefined |
| 16977 | which of the duplicates is discarded, so this ambiguous situation should be |
| 16978 | avoided. The &%repeat_use%& option of the &%redirect%& router may be of help. |
| 16979 | |
| 16980 | |
| 16981 | |
| 16982 | .option headers_remove routers list&!! unset |
| 16983 | .cindex "header lines" "removing" |
| 16984 | .cindex "router" "removing header lines" |
| 16985 | This option specifies a list of text headers, colon-separated, |
| 16986 | that is associated with any addresses that are accepted by the router. |
| 16987 | Each item is separately expanded, at routing time. However, this |
| 16988 | option has no effect when an address is just being verified. The way in which |
| 16989 | the text is used to remove header lines at transport time is described in |
| 16990 | section &<<SECTheadersaddrem>>&. Header lines are not actually removed until |
| 16991 | the message is in the process of being transported. This means that references |
| 16992 | to header lines in string expansions in the transport's configuration still |
| 16993 | &"see"& the original header lines. |
| 16994 | |
| 16995 | The &%headers_remove%& option is expanded after &%errors_to%& and |
| 16996 | &%headers_add%&, but before &%transport%&. If an item expansion is forced to fail, |
| 16997 | the item has no effect. Other expansion failures are treated as configuration |
| 16998 | errors. |
| 16999 | |
| 17000 | Unlike most options, &%headers_remove%& can be specified multiple times |
| 17001 | for a router; all listed headers are removed. |
| 17002 | |
| 17003 | &*Warning 1*&: The &%headers_remove%& option cannot be used for a &(redirect)& |
| 17004 | router that has the &%one_time%& option set. |
| 17005 | |
| 17006 | &*Warning 2*&: If the &%unseen%& option is set on the router, all header |
| 17007 | removal requests are deleted when the address is passed on to subsequent |
| 17008 | routers, and this can lead to problems with duplicates -- see the similar |
| 17009 | warning for &%headers_add%& above. |
| 17010 | |
| 17011 | |
| 17012 | .option ignore_target_hosts routers "host list&!!" unset |
| 17013 | .cindex "IP address" "discarding" |
| 17014 | .cindex "router" "discarding IP addresses" |
| 17015 | Although this option is a host list, it should normally contain IP address |
| 17016 | entries rather than names. If any host that is looked up by the router has an |
| 17017 | IP address that matches an item in this list, Exim behaves as if that IP |
| 17018 | address did not exist. This option allows you to cope with rogue DNS entries |
| 17019 | like |
| 17020 | .code |
| 17021 | remote.domain.example. A 127.0.0.1 |
| 17022 | .endd |
| 17023 | by setting |
| 17024 | .code |
| 17025 | ignore_target_hosts = 127.0.0.1 |
| 17026 | .endd |
| 17027 | on the relevant router. If all the hosts found by a &(dnslookup)& router are |
| 17028 | discarded in this way, the router declines. In a conventional configuration, an |
| 17029 | attempt to mail to such a domain would normally provoke the &"unrouteable |
| 17030 | domain"& error, and an attempt to verify an address in the domain would fail. |
| 17031 | Similarly, if &%ignore_target_hosts%& is set on an &(ipliteral)& router, the |
| 17032 | router declines if presented with one of the listed addresses. |
| 17033 | |
| 17034 | You can use this option to disable the use of IPv4 or IPv6 for mail delivery by |
| 17035 | means of the first or the second of the following settings, respectively: |
| 17036 | .code |
| 17037 | ignore_target_hosts = 0.0.0.0/0 |
| 17038 | ignore_target_hosts = <; 0::0/0 |
| 17039 | .endd |
| 17040 | The pattern in the first line matches all IPv4 addresses, whereas the pattern |
| 17041 | in the second line matches all IPv6 addresses. |
| 17042 | |
| 17043 | This option may also be useful for ignoring link-local and site-local IPv6 |
| 17044 | addresses. Because, like all host lists, the value of &%ignore_target_hosts%& |
| 17045 | is expanded before use as a list, it is possible to make it dependent on the |
| 17046 | domain that is being routed. |
| 17047 | |
| 17048 | .vindex "&$host_address$&" |
| 17049 | During its expansion, &$host_address$& is set to the IP address that is being |
| 17050 | checked. |
| 17051 | |
| 17052 | .option initgroups routers boolean false |
| 17053 | .cindex "additional groups" |
| 17054 | .cindex "groups" "additional" |
| 17055 | .cindex "local transports" "uid and gid" |
| 17056 | .cindex "transport" "local" |
| 17057 | If the router queues an address for a transport, and this option is true, and |
| 17058 | the uid supplied by the router is not overridden by the transport, the |
| 17059 | &[initgroups()]& function is called when running the transport to ensure that |
| 17060 | any additional groups associated with the uid are set up. See also &%group%& |
| 17061 | and &%user%& and the discussion in chapter &<<CHAPenvironment>>&. |
| 17062 | |
| 17063 | |
| 17064 | |
| 17065 | .option local_part_prefix routers&!? "string list" unset |
| 17066 | .cindex "router" "prefix for local part" |
| 17067 | .cindex "prefix" "for local part, used in router" |
| 17068 | If this option is set, the router is skipped unless the local part starts with |
| 17069 | one of the given strings, or &%local_part_prefix_optional%& is true. See |
| 17070 | section &<<SECTrouprecon>>& for a list of the order in which preconditions are |
| 17071 | evaluated. |
| 17072 | |
| 17073 | The list is scanned from left to right, and the first prefix that matches is |
| 17074 | used. A limited form of wildcard is available; if the prefix begins with an |
| 17075 | asterisk, it matches the longest possible sequence of arbitrary characters at |
| 17076 | the start of the local part. An asterisk should therefore always be followed by |
| 17077 | some character that does not occur in normal local parts. |
| 17078 | .cindex "multiple mailboxes" |
| 17079 | .cindex "mailbox" "multiple" |
| 17080 | Wildcarding can be used to set up multiple user mailboxes, as described in |
| 17081 | section &<<SECTmulbox>>&. |
| 17082 | |
| 17083 | .vindex "&$local_part$&" |
| 17084 | .vindex "&$local_part_prefix$&" |
| 17085 | During the testing of the &%local_parts%& option, and while the router is |
| 17086 | running, the prefix is removed from the local part, and is available in the |
| 17087 | expansion variable &$local_part_prefix$&. When a message is being delivered, if |
| 17088 | the router accepts the address, this remains true during subsequent delivery by |
| 17089 | a transport. In particular, the local part that is transmitted in the RCPT |
| 17090 | command for LMTP, SMTP, and BSMTP deliveries has the prefix removed by default. |
| 17091 | This behaviour can be overridden by setting &%rcpt_include_affixes%& true on |
| 17092 | the relevant transport. |
| 17093 | |
| 17094 | When an address is being verified, &%local_part_prefix%& affects only the |
| 17095 | behaviour of the router. If the callout feature of verification is in use, this |
| 17096 | means that the full address, including the prefix, will be used during the |
| 17097 | callout. |
| 17098 | |
| 17099 | The prefix facility is commonly used to handle local parts of the form |
| 17100 | &%owner-something%&. Another common use is to support local parts of the form |
| 17101 | &%real-username%& to bypass a user's &_.forward_& file &-- helpful when trying |
| 17102 | to tell a user their forwarding is broken &-- by placing a router like this one |
| 17103 | immediately before the router that handles &_.forward_& files: |
| 17104 | .code |
| 17105 | real_localuser: |
| 17106 | driver = accept |
| 17107 | local_part_prefix = real- |
| 17108 | check_local_user |
| 17109 | transport = local_delivery |
| 17110 | .endd |
| 17111 | For security, it would probably be a good idea to restrict the use of this |
| 17112 | router to locally-generated messages, using a condition such as this: |
| 17113 | .code |
| 17114 | condition = ${if match {$sender_host_address}\ |
| 17115 | {\N^(|127\.0\.0\.1)$\N}} |
| 17116 | .endd |
| 17117 | |
| 17118 | If both &%local_part_prefix%& and &%local_part_suffix%& are set for a router, |
| 17119 | both conditions must be met if not optional. Care must be taken if wildcards |
| 17120 | are used in both a prefix and a suffix on the same router. Different |
| 17121 | separator characters must be used to avoid ambiguity. |
| 17122 | |
| 17123 | |
| 17124 | .option local_part_prefix_optional routers boolean false |
| 17125 | See &%local_part_prefix%& above. |
| 17126 | |
| 17127 | |
| 17128 | |
| 17129 | .option local_part_suffix routers&!? "string list" unset |
| 17130 | .cindex "router" "suffix for local part" |
| 17131 | .cindex "suffix for local part" "used in router" |
| 17132 | This option operates in the same way as &%local_part_prefix%&, except that the |
| 17133 | local part must end (rather than start) with the given string, the |
| 17134 | &%local_part_suffix_optional%& option determines whether the suffix is |
| 17135 | mandatory, and the wildcard * character, if present, must be the last |
| 17136 | character of the suffix. This option facility is commonly used to handle local |
| 17137 | parts of the form &%something-request%& and multiple user mailboxes of the form |
| 17138 | &%username-foo%&. |
| 17139 | |
| 17140 | |
| 17141 | .option local_part_suffix_optional routers boolean false |
| 17142 | See &%local_part_suffix%& above. |
| 17143 | |
| 17144 | |
| 17145 | |
| 17146 | .option local_parts routers&!? "local part list&!!" unset |
| 17147 | .cindex "router" "restricting to specific local parts" |
| 17148 | .cindex "local part" "checking in router" |
| 17149 | The router is run only if the local part of the address matches the list. |
| 17150 | See section &<<SECTrouprecon>>& for a list of the order in which preconditions |
| 17151 | are evaluated, and |
| 17152 | section &<<SECTlocparlis>>& for a discussion of local part lists. Because the |
| 17153 | string is expanded, it is possible to make it depend on the domain, for |
| 17154 | example: |
| 17155 | .code |
| 17156 | local_parts = dbm;/usr/local/specials/$domain |
| 17157 | .endd |
| 17158 | .vindex "&$local_part_data$&" |
| 17159 | If the match is achieved by a lookup, the data that the lookup returned |
| 17160 | for the local part is placed in the variable &$local_part_data$& for use in |
| 17161 | expansions of the router's private options. You might use this option, for |
| 17162 | example, if you have a large number of local virtual domains, and you want to |
| 17163 | send all postmaster mail to the same place without having to set up an alias in |
| 17164 | each virtual domain: |
| 17165 | .code |
| 17166 | postmaster: |
| 17167 | driver = redirect |
| 17168 | local_parts = postmaster |
| 17169 | data = postmaster@real.domain.example |
| 17170 | .endd |
| 17171 | |
| 17172 | |
| 17173 | .option log_as_local routers boolean "see below" |
| 17174 | .cindex "log" "delivery line" |
| 17175 | .cindex "delivery" "log line format" |
| 17176 | Exim has two logging styles for delivery, the idea being to make local |
| 17177 | deliveries stand out more visibly from remote ones. In the &"local"& style, the |
| 17178 | recipient address is given just as the local part, without a domain. The use of |
| 17179 | this style is controlled by this option. It defaults to true for the &(accept)& |
| 17180 | router, and false for all the others. This option applies only when a |
| 17181 | router assigns an address to a transport. It has no effect on routers that |
| 17182 | redirect addresses. |
| 17183 | |
| 17184 | |
| 17185 | |
| 17186 | .option more routers boolean&!! true |
| 17187 | The result of string expansion for this option must be a valid boolean value, |
| 17188 | that is, one of the strings &"yes"&, &"no"&, &"true"&, or &"false"&. Any other |
| 17189 | result causes an error, and delivery is deferred. If the expansion is forced to |
| 17190 | fail, the default value for the option (true) is used. Other failures cause |
| 17191 | delivery to be deferred. |
| 17192 | |
| 17193 | If this option is set false, and the router declines to handle the address, no |
| 17194 | further routers are tried, routing fails, and the address is bounced. |
| 17195 | .oindex "&%self%&" |
| 17196 | However, if the router explicitly passes an address to the following router by |
| 17197 | means of the setting |
| 17198 | .code |
| 17199 | self = pass |
| 17200 | .endd |
| 17201 | or otherwise, the setting of &%more%& is ignored. Also, the setting of &%more%& |
| 17202 | does not affect the behaviour if one of the precondition tests fails. In that |
| 17203 | case, the address is always passed to the next router. |
| 17204 | |
| 17205 | Note that &%address_data%& is not considered to be a precondition. If its |
| 17206 | expansion is forced to fail, the router declines, and the value of &%more%& |
| 17207 | controls what happens next. |
| 17208 | |
| 17209 | |
| 17210 | .option pass_on_timeout routers boolean false |
| 17211 | .cindex "timeout" "of router" |
| 17212 | .cindex "router" "timeout" |
| 17213 | If a router times out during a host lookup, it normally causes deferral of the |
| 17214 | address. If &%pass_on_timeout%& is set, the address is passed on to the next |
| 17215 | router, overriding &%no_more%&. This may be helpful for systems that are |
| 17216 | intermittently connected to the Internet, or those that want to pass to a smart |
| 17217 | host any messages that cannot immediately be delivered. |
| 17218 | |
| 17219 | There are occasional other temporary errors that can occur while doing DNS |
| 17220 | lookups. They are treated in the same way as a timeout, and this option |
| 17221 | applies to all of them. |
| 17222 | |
| 17223 | |
| 17224 | |
| 17225 | .option pass_router routers string unset |
| 17226 | .cindex "router" "go to after &""pass""&" |
| 17227 | Routers that recognize the generic &%self%& option (&(dnslookup)&, |
| 17228 | &(ipliteral)&, and &(manualroute)&) are able to return &"pass"&, forcing |
| 17229 | routing to continue, and overriding a false setting of &%more%&. When one of |
| 17230 | these routers returns &"pass"&, the address is normally handed on to the next |
| 17231 | router in sequence. This can be changed by setting &%pass_router%& to the name |
| 17232 | of another router. However (unlike &%redirect_router%&) the named router must |
| 17233 | be below the current router, to avoid loops. Note that this option applies only |
| 17234 | to the special case of &"pass"&. It does not apply when a router returns |
| 17235 | &"decline"& because it cannot handle an address. |
| 17236 | |
| 17237 | |
| 17238 | |
| 17239 | .option redirect_router routers string unset |
| 17240 | .cindex "router" "start at after redirection" |
| 17241 | Sometimes an administrator knows that it is pointless to reprocess addresses |
| 17242 | generated from alias or forward files with the same router again. For |
| 17243 | example, if an alias file translates real names into login ids there is no |
| 17244 | point searching the alias file a second time, especially if it is a large file. |
| 17245 | |
| 17246 | The &%redirect_router%& option can be set to the name of any router instance. |
| 17247 | It causes the routing of any generated addresses to start at the named router |
| 17248 | instead of at the first router. This option has no effect if the router in |
| 17249 | which it is set does not generate new addresses. |
| 17250 | |
| 17251 | |
| 17252 | |
| 17253 | .option require_files routers&!? "string list&!!" unset |
| 17254 | .cindex "file" "requiring for router" |
| 17255 | .cindex "router" "requiring file existence" |
| 17256 | This option provides a general mechanism for predicating the running of a |
| 17257 | router on the existence or non-existence of certain files or directories. |
| 17258 | Before running a router, as one of its precondition tests, Exim works its way |
| 17259 | through the &%require_files%& list, expanding each item separately. |
| 17260 | |
| 17261 | Because the list is split before expansion, any colons in expansion items must |
| 17262 | be doubled, or the facility for using a different list separator must be used. |
| 17263 | If any expansion is forced to fail, the item is ignored. Other expansion |
| 17264 | failures cause routing of the address to be deferred. |
| 17265 | |
| 17266 | If any expanded string is empty, it is ignored. Otherwise, except as described |
| 17267 | below, each string must be a fully qualified file path, optionally preceded by |
| 17268 | &"!"&. The paths are passed to the &[stat()]& function to test for the |
| 17269 | existence of the files or directories. The router is skipped if any paths not |
| 17270 | preceded by &"!"& do not exist, or if any paths preceded by &"!"& do exist. |
| 17271 | |
| 17272 | .cindex "NFS" |
| 17273 | If &[stat()]& cannot determine whether a file exists or not, delivery of |
| 17274 | the message is deferred. This can happen when NFS-mounted filesystems are |
| 17275 | unavailable. |
| 17276 | |
| 17277 | This option is checked after the &%domains%&, &%local_parts%&, and &%senders%& |
| 17278 | options, so you cannot use it to check for the existence of a file in which to |
| 17279 | look up a domain, local part, or sender. (See section &<<SECTrouprecon>>& for a |
| 17280 | full list of the order in which preconditions are evaluated.) However, as |
| 17281 | these options are all expanded, you can use the &%exists%& expansion condition |
| 17282 | to make such tests. The &%require_files%& option is intended for checking files |
| 17283 | that the router may be going to use internally, or which are needed by a |
| 17284 | transport (for example &_.procmailrc_&). |
| 17285 | |
| 17286 | During delivery, the &[stat()]& function is run as root, but there is a |
| 17287 | facility for some checking of the accessibility of a file by another user. |
| 17288 | This is not a proper permissions check, but just a &"rough"& check that |
| 17289 | operates as follows: |
| 17290 | |
| 17291 | If an item in a &%require_files%& list does not contain any forward slash |
| 17292 | characters, it is taken to be the user (and optional group, separated by a |
| 17293 | comma) to be checked for subsequent files in the list. If no group is specified |
| 17294 | but the user is specified symbolically, the gid associated with the uid is |
| 17295 | used. For example: |
| 17296 | .code |
| 17297 | require_files = mail:/some/file |
| 17298 | require_files = $local_part:$home/.procmailrc |
| 17299 | .endd |
| 17300 | If a user or group name in a &%require_files%& list does not exist, the |
| 17301 | &%require_files%& condition fails. |
| 17302 | |
| 17303 | Exim performs the check by scanning along the components of the file path, and |
| 17304 | checking the access for the given uid and gid. It checks for &"x"& access on |
| 17305 | directories, and &"r"& access on the final file. Note that this means that file |
| 17306 | access control lists, if the operating system has them, are ignored. |
| 17307 | |
| 17308 | &*Warning 1*&: When the router is being run to verify addresses for an |
| 17309 | incoming SMTP message, Exim is not running as root, but under its own uid. This |
| 17310 | may affect the result of a &%require_files%& check. In particular, &[stat()]& |
| 17311 | may yield the error EACCES (&"Permission denied"&). This means that the Exim |
| 17312 | user is not permitted to read one of the directories on the file's path. |
| 17313 | |
| 17314 | &*Warning 2*&: Even when Exim is running as root while delivering a message, |
| 17315 | &[stat()]& can yield EACCES for a file in an NFS directory that is mounted |
| 17316 | without root access. In this case, if a check for access by a particular user |
| 17317 | is requested, Exim creates a subprocess that runs as that user, and tries the |
| 17318 | check again in that process. |
| 17319 | |
| 17320 | The default action for handling an unresolved EACCES is to consider it to |
| 17321 | be caused by a configuration error, and routing is deferred because the |
| 17322 | existence or non-existence of the file cannot be determined. However, in some |
| 17323 | circumstances it may be desirable to treat this condition as if the file did |
| 17324 | not exist. If the file name (or the exclamation mark that precedes the file |
| 17325 | name for non-existence) is preceded by a plus sign, the EACCES error is treated |
| 17326 | as if the file did not exist. For example: |
| 17327 | .code |
| 17328 | require_files = +/some/file |
| 17329 | .endd |
| 17330 | If the router is not an essential part of verification (for example, it |
| 17331 | handles users' &_.forward_& files), another solution is to set the &%verify%& |
| 17332 | option false so that the router is skipped when verifying. |
| 17333 | |
| 17334 | |
| 17335 | |
| 17336 | .option retry_use_local_part routers boolean "see below" |
| 17337 | .cindex "hints database" "retry keys" |
| 17338 | .cindex "local part" "in retry keys" |
| 17339 | When a delivery suffers a temporary routing failure, a retry record is created |
| 17340 | in Exim's hints database. For addresses whose routing depends only on the |
| 17341 | domain, the key for the retry record should not involve the local part, but for |
| 17342 | other addresses, both the domain and the local part should be included. |
| 17343 | Usually, remote routing is of the former kind, and local routing is of the |
| 17344 | latter kind. |
| 17345 | |
| 17346 | This option controls whether the local part is used to form the key for retry |
| 17347 | hints for addresses that suffer temporary errors while being handled by this |
| 17348 | router. The default value is true for any router that has &%check_local_user%& |
| 17349 | set, and false otherwise. Note that this option does not apply to hints keys |
| 17350 | for transport delays; they are controlled by a generic transport option of the |
| 17351 | same name. |
| 17352 | |
| 17353 | The setting of &%retry_use_local_part%& applies only to the router on which it |
| 17354 | appears. If the router generates child addresses, they are routed |
| 17355 | independently; this setting does not become attached to them. |
| 17356 | |
| 17357 | |
| 17358 | |
| 17359 | .option router_home_directory routers string&!! unset |
| 17360 | .cindex "router" "home directory for" |
| 17361 | .cindex "home directory" "for router" |
| 17362 | .vindex "&$home$&" |
| 17363 | This option sets a home directory for use while the router is running. (Compare |
| 17364 | &%transport_home_directory%&, which sets a home directory for later |
| 17365 | transporting.) In particular, if used on a &(redirect)& router, this option |
| 17366 | sets a value for &$home$& while a filter is running. The value is expanded; |
| 17367 | forced expansion failure causes the option to be ignored &-- other failures |
| 17368 | cause the router to defer. |
| 17369 | |
| 17370 | Expansion of &%router_home_directory%& happens immediately after the |
| 17371 | &%check_local_user%& test (if configured), before any further expansions take |
| 17372 | place. |
| 17373 | (See section &<<SECTrouprecon>>& for a list of the order in which preconditions |
| 17374 | are evaluated.) |
| 17375 | While the router is running, &%router_home_directory%& overrides the value of |
| 17376 | &$home$& that came from &%check_local_user%&. |
| 17377 | |
| 17378 | When a router accepts an address and assigns it to a local transport (including |
| 17379 | the cases when a &(redirect)& router generates a pipe, file, or autoreply |
| 17380 | delivery), the home directory setting for the transport is taken from the first |
| 17381 | of these values that is set: |
| 17382 | |
| 17383 | .ilist |
| 17384 | The &%home_directory%& option on the transport; |
| 17385 | .next |
| 17386 | The &%transport_home_directory%& option on the router; |
| 17387 | .next |
| 17388 | The password data if &%check_local_user%& is set on the router; |
| 17389 | .next |
| 17390 | The &%router_home_directory%& option on the router. |
| 17391 | .endlist |
| 17392 | |
| 17393 | In other words, &%router_home_directory%& overrides the password data for the |
| 17394 | router, but not for the transport. |
| 17395 | |
| 17396 | |
| 17397 | |
| 17398 | .option self routers string freeze |
| 17399 | .cindex "MX record" "pointing to local host" |
| 17400 | .cindex "local host" "MX pointing to" |
| 17401 | This option applies to those routers that use a recipient address to find a |
| 17402 | list of remote hosts. Currently, these are the &(dnslookup)&, &(ipliteral)&, |
| 17403 | and &(manualroute)& routers. |
| 17404 | Certain configurations of the &(queryprogram)& router can also specify a list |
| 17405 | of remote hosts. |
| 17406 | Usually such routers are configured to send the message to a remote host via an |
| 17407 | &(smtp)& transport. The &%self%& option specifies what happens when the first |
| 17408 | host on the list turns out to be the local host. |
| 17409 | The way in which Exim checks for the local host is described in section |
| 17410 | &<<SECTreclocipadd>>&. |
| 17411 | |
| 17412 | Normally this situation indicates either an error in Exim's configuration (for |
| 17413 | example, the router should be configured not to process this domain), or an |
| 17414 | error in the DNS (for example, the MX should not point to this host). For this |
| 17415 | reason, the default action is to log the incident, defer the address, and |
| 17416 | freeze the message. The following alternatives are provided for use in special |
| 17417 | cases: |
| 17418 | |
| 17419 | .vlist |
| 17420 | .vitem &%defer%& |
| 17421 | Delivery of the message is tried again later, but the message is not frozen. |
| 17422 | |
| 17423 | .vitem "&%reroute%&: <&'domain'&>" |
| 17424 | The domain is changed to the given domain, and the address is passed back to |
| 17425 | be reprocessed by the routers. No rewriting of headers takes place. This |
| 17426 | behaviour is essentially a redirection. |
| 17427 | |
| 17428 | .vitem "&%reroute: rewrite:%& <&'domain'&>" |
| 17429 | The domain is changed to the given domain, and the address is passed back to be |
| 17430 | reprocessed by the routers. Any headers that contain the original domain are |
| 17431 | rewritten. |
| 17432 | |
| 17433 | .vitem &%pass%& |
| 17434 | .oindex "&%more%&" |
| 17435 | .vindex "&$self_hostname$&" |
| 17436 | The router passes the address to the next router, or to the router named in the |
| 17437 | &%pass_router%& option if it is set. This overrides &%no_more%&. During |
| 17438 | subsequent routing and delivery, the variable &$self_hostname$& contains the |
| 17439 | name of the local host that the router encountered. This can be used to |
| 17440 | distinguish between different cases for hosts with multiple names. The |
| 17441 | combination |
| 17442 | .code |
| 17443 | self = pass |
| 17444 | no_more |
| 17445 | .endd |
| 17446 | ensures that only those addresses that routed to the local host are passed on. |
| 17447 | Without &%no_more%&, addresses that were declined for other reasons would also |
| 17448 | be passed to the next router. |
| 17449 | |
| 17450 | .vitem &%fail%& |
| 17451 | Delivery fails and an error report is generated. |
| 17452 | |
| 17453 | .vitem &%send%& |
| 17454 | .cindex "local host" "sending to" |
| 17455 | The anomaly is ignored and the address is queued for the transport. This |
| 17456 | setting should be used with extreme caution. For an &(smtp)& transport, it |
| 17457 | makes sense only in cases where the program that is listening on the SMTP port |
| 17458 | is not this version of Exim. That is, it must be some other MTA, or Exim with a |
| 17459 | different configuration file that handles the domain in another way. |
| 17460 | .endlist |
| 17461 | |
| 17462 | |
| 17463 | |
| 17464 | .option senders routers&!? "address list&!!" unset |
| 17465 | .cindex "router" "checking senders" |
| 17466 | If this option is set, the router is skipped unless the message's sender |
| 17467 | address matches something on the list. |
| 17468 | See section &<<SECTrouprecon>>& for a list of the order in which preconditions |
| 17469 | are evaluated. |
| 17470 | |
| 17471 | There are issues concerning verification when the running of routers is |
| 17472 | dependent on the sender. When Exim is verifying the address in an &%errors_to%& |
| 17473 | setting, it sets the sender to the null string. When using the &%-bt%& option |
| 17474 | to check a configuration file, it is necessary also to use the &%-f%& option to |
| 17475 | set an appropriate sender. For incoming mail, the sender is unset when |
| 17476 | verifying the sender, but is available when verifying any recipients. If the |
| 17477 | SMTP VRFY command is enabled, it must be used after MAIL if the sender address |
| 17478 | matters. |
| 17479 | |
| 17480 | |
| 17481 | .option translate_ip_address routers string&!! unset |
| 17482 | .cindex "IP address" "translating" |
| 17483 | .cindex "packet radio" |
| 17484 | .cindex "router" "IP address translation" |
| 17485 | There exist some rare networking situations (for example, packet radio) where |
| 17486 | it is helpful to be able to translate IP addresses generated by normal routing |
| 17487 | mechanisms into other IP addresses, thus performing a kind of manual IP |
| 17488 | routing. This should be done only if the normal IP routing of the TCP/IP stack |
| 17489 | is inadequate or broken. Because this is an extremely uncommon requirement, the |
| 17490 | code to support this option is not included in the Exim binary unless |
| 17491 | SUPPORT_TRANSLATE_IP_ADDRESS=yes is set in &_Local/Makefile_&. |
| 17492 | |
| 17493 | .vindex "&$host_address$&" |
| 17494 | The &%translate_ip_address%& string is expanded for every IP address generated |
| 17495 | by the router, with the generated address set in &$host_address$&. If the |
| 17496 | expansion is forced to fail, no action is taken. |
| 17497 | For any other expansion error, delivery of the message is deferred. |
| 17498 | If the result of the expansion is an IP address, that replaces the original |
| 17499 | address; otherwise the result is assumed to be a host name &-- this is looked |
| 17500 | up using &[gethostbyname()]& (or &[getipnodebyname()]& when available) to |
| 17501 | produce one or more replacement IP addresses. For example, to subvert all IP |
| 17502 | addresses in some specific networks, this could be added to a router: |
| 17503 | .code |
| 17504 | translate_ip_address = \ |
| 17505 | ${lookup{${mask:$host_address/26}}lsearch{/some/file}\ |
| 17506 | {$value}fail}} |
| 17507 | .endd |
| 17508 | The file would contain lines like |
| 17509 | .code |
| 17510 | 10.2.3.128/26 some.host |
| 17511 | 10.8.4.34/26 10.44.8.15 |
| 17512 | .endd |
| 17513 | You should not make use of this facility unless you really understand what you |
| 17514 | are doing. |
| 17515 | |
| 17516 | |
| 17517 | |
| 17518 | .option transport routers string&!! unset |
| 17519 | This option specifies the transport to be used when a router accepts an address |
| 17520 | and sets it up for delivery. A transport is never needed if a router is used |
| 17521 | only for verification. The value of the option is expanded at routing time, |
| 17522 | after the expansion of &%errors_to%&, &%headers_add%&, and &%headers_remove%&, |
| 17523 | and result must be the name of one of the configured transports. If it is not, |
| 17524 | delivery is deferred. |
| 17525 | |
| 17526 | The &%transport%& option is not used by the &(redirect)& router, but it does |
| 17527 | have some private options that set up transports for pipe and file deliveries |
| 17528 | (see chapter &<<CHAPredirect>>&). |
| 17529 | |
| 17530 | |
| 17531 | |
| 17532 | .option transport_current_directory routers string&!! unset |
| 17533 | .cindex "current directory for local transport" |
| 17534 | This option associates a current directory with any address that is routed |
| 17535 | to a local transport. This can happen either because a transport is |
| 17536 | explicitly configured for the router, or because it generates a delivery to a |
| 17537 | file or a pipe. During the delivery process (that is, at transport time), this |
| 17538 | option string is expanded and is set as the current directory, unless |
| 17539 | overridden by a setting on the transport. |
| 17540 | If the expansion fails for any reason, including forced failure, an error is |
| 17541 | logged, and delivery is deferred. |
| 17542 | See chapter &<<CHAPenvironment>>& for details of the local delivery |
| 17543 | environment. |
| 17544 | |
| 17545 | |
| 17546 | |
| 17547 | |
| 17548 | .option transport_home_directory routers string&!! "see below" |
| 17549 | .cindex "home directory" "for local transport" |
| 17550 | This option associates a home directory with any address that is routed to a |
| 17551 | local transport. This can happen either because a transport is explicitly |
| 17552 | configured for the router, or because it generates a delivery to a file or a |
| 17553 | pipe. During the delivery process (that is, at transport time), the option |
| 17554 | string is expanded and is set as the home directory, unless overridden by a |
| 17555 | setting of &%home_directory%& on the transport. |
| 17556 | If the expansion fails for any reason, including forced failure, an error is |
| 17557 | logged, and delivery is deferred. |
| 17558 | |
| 17559 | If the transport does not specify a home directory, and |
| 17560 | &%transport_home_directory%& is not set for the router, the home directory for |
| 17561 | the transport is taken from the password data if &%check_local_user%& is set for |
| 17562 | the router. Otherwise it is taken from &%router_home_directory%& if that option |
| 17563 | is set; if not, no home directory is set for the transport. |
| 17564 | |
| 17565 | See chapter &<<CHAPenvironment>>& for further details of the local delivery |
| 17566 | environment. |
| 17567 | |
| 17568 | |
| 17569 | |
| 17570 | |
| 17571 | .option unseen routers boolean&!! false |
| 17572 | .cindex "router" "carrying on after success" |
| 17573 | The result of string expansion for this option must be a valid boolean value, |
| 17574 | that is, one of the strings &"yes"&, &"no"&, &"true"&, or &"false"&. Any other |
| 17575 | result causes an error, and delivery is deferred. If the expansion is forced to |
| 17576 | fail, the default value for the option (false) is used. Other failures cause |
| 17577 | delivery to be deferred. |
| 17578 | |
| 17579 | When this option is set true, routing does not cease if the router accepts the |
| 17580 | address. Instead, a copy of the incoming address is passed to the next router, |
| 17581 | overriding a false setting of &%more%&. There is little point in setting |
| 17582 | &%more%& false if &%unseen%& is always true, but it may be useful in cases when |
| 17583 | the value of &%unseen%& contains expansion items (and therefore, presumably, is |
| 17584 | sometimes true and sometimes false). |
| 17585 | |
| 17586 | .cindex "copy of message (&%unseen%& option)" |
| 17587 | Setting the &%unseen%& option has a similar effect to the &%unseen%& command |
| 17588 | qualifier in filter files. It can be used to cause copies of messages to be |
| 17589 | delivered to some other destination, while also carrying out a normal delivery. |
| 17590 | In effect, the current address is made into a &"parent"& that has two children |
| 17591 | &-- one that is delivered as specified by this router, and a clone that goes on |
| 17592 | to be routed further. For this reason, &%unseen%& may not be combined with the |
| 17593 | &%one_time%& option in a &(redirect)& router. |
| 17594 | |
| 17595 | &*Warning*&: Header lines added to the address (or specified for removal) by |
| 17596 | this router or by previous routers affect the &"unseen"& copy of the message |
| 17597 | only. The clone that continues to be processed by further routers starts with |
| 17598 | no added headers and none specified for removal. For a &%redirect%& router, if |
| 17599 | a generated address is the same as the incoming address, this can lead to |
| 17600 | duplicate addresses with different header modifications. Exim does not do |
| 17601 | duplicate deliveries (except, in certain circumstances, to pipes -- see section |
| 17602 | &<<SECTdupaddr>>&), but it is undefined which of the duplicates is discarded, |
| 17603 | so this ambiguous situation should be avoided. The &%repeat_use%& option of the |
| 17604 | &%redirect%& router may be of help. |
| 17605 | |
| 17606 | Unlike the handling of header modifications, any data that was set by the |
| 17607 | &%address_data%& option in the current or previous routers &'is'& passed on to |
| 17608 | subsequent routers. |
| 17609 | |
| 17610 | |
| 17611 | .option user routers string&!! "see below" |
| 17612 | .cindex "uid (user id)" "local delivery" |
| 17613 | .cindex "local transports" "uid and gid" |
| 17614 | .cindex "transport" "local" |
| 17615 | .cindex "router" "user for filter processing" |
| 17616 | .cindex "filter" "user for processing" |
| 17617 | When a router queues an address for a transport, and the transport does not |
| 17618 | specify a user, the user given here is used when running the delivery process. |
| 17619 | The user may be specified numerically or by name. If expansion fails, the |
| 17620 | error is logged and delivery is deferred. |
| 17621 | This user is also used by the &(redirect)& router when running a filter file. |
| 17622 | The default is unset, except when &%check_local_user%& is set. In this case, |
| 17623 | the default is taken from the password information. If the user is specified as |
| 17624 | a name, and &%group%& is not set, the group associated with the user is used. |
| 17625 | See also &%initgroups%& and &%group%& and the discussion in chapter |
| 17626 | &<<CHAPenvironment>>&. |
| 17627 | |
| 17628 | |
| 17629 | |
| 17630 | .option verify routers&!? boolean true |
| 17631 | Setting this option has the effect of setting &%verify_sender%& and |
| 17632 | &%verify_recipient%& to the same value. |
| 17633 | |
| 17634 | |
| 17635 | .option verify_only routers&!? boolean false |
| 17636 | .cindex "EXPN" "with &%verify_only%&" |
| 17637 | .oindex "&%-bv%&" |
| 17638 | .cindex "router" "used only when verifying" |
| 17639 | If this option is set, the router is used only when verifying an address, |
| 17640 | delivering in cutthrough mode or |
| 17641 | testing with the &%-bv%& option, not when actually doing a delivery, testing |
| 17642 | with the &%-bt%& option, or running the SMTP EXPN command. It can be further |
| 17643 | restricted to verifying only senders or recipients by means of |
| 17644 | &%verify_sender%& and &%verify_recipient%&. |
| 17645 | |
| 17646 | &*Warning*&: When the router is being run to verify addresses for an incoming |
| 17647 | SMTP message, Exim is not running as root, but under its own uid. If the router |
| 17648 | accesses any files, you need to make sure that they are accessible to the Exim |
| 17649 | user or group. |
| 17650 | |
| 17651 | |
| 17652 | .option verify_recipient routers&!? boolean true |
| 17653 | If this option is false, the router is skipped when verifying recipient |
| 17654 | addresses, |
| 17655 | delivering in cutthrough mode |
| 17656 | or testing recipient verification using &%-bv%&. |
| 17657 | See section &<<SECTrouprecon>>& for a list of the order in which preconditions |
| 17658 | are evaluated. |
| 17659 | |
| 17660 | |
| 17661 | .option verify_sender routers&!? boolean true |
| 17662 | If this option is false, the router is skipped when verifying sender addresses |
| 17663 | or testing sender verification using &%-bvs%&. |
| 17664 | See section &<<SECTrouprecon>>& for a list of the order in which preconditions |
| 17665 | are evaluated. |
| 17666 | .ecindex IIDgenoprou1 |
| 17667 | .ecindex IIDgenoprou2 |
| 17668 | |
| 17669 | |
| 17670 | |
| 17671 | |
| 17672 | |
| 17673 | |
| 17674 | . //////////////////////////////////////////////////////////////////////////// |
| 17675 | . //////////////////////////////////////////////////////////////////////////// |
| 17676 | |
| 17677 | .chapter "The accept router" "CHID4" |
| 17678 | .cindex "&(accept)& router" |
| 17679 | .cindex "routers" "&(accept)&" |
| 17680 | The &(accept)& router has no private options of its own. Unless it is being |
| 17681 | used purely for verification (see &%verify_only%&) a transport is required to |
| 17682 | be defined by the generic &%transport%& option. If the preconditions that are |
| 17683 | specified by generic options are met, the router accepts the address and queues |
| 17684 | it for the given transport. The most common use of this router is for setting |
| 17685 | up deliveries to local mailboxes. For example: |
| 17686 | .code |
| 17687 | localusers: |
| 17688 | driver = accept |
| 17689 | domains = mydomain.example |
| 17690 | check_local_user |
| 17691 | transport = local_delivery |
| 17692 | .endd |
| 17693 | The &%domains%& condition in this example checks the domain of the address, and |
| 17694 | &%check_local_user%& checks that the local part is the login of a local user. |
| 17695 | When both preconditions are met, the &(accept)& router runs, and queues the |
| 17696 | address for the &(local_delivery)& transport. |
| 17697 | |
| 17698 | |
| 17699 | |
| 17700 | |
| 17701 | |
| 17702 | |
| 17703 | . //////////////////////////////////////////////////////////////////////////// |
| 17704 | . //////////////////////////////////////////////////////////////////////////// |
| 17705 | |
| 17706 | .chapter "The dnslookup router" "CHAPdnslookup" |
| 17707 | .scindex IIDdnsrou1 "&(dnslookup)& router" |
| 17708 | .scindex IIDdnsrou2 "routers" "&(dnslookup)&" |
| 17709 | The &(dnslookup)& router looks up the hosts that handle mail for the |
| 17710 | recipient's domain in the DNS. A transport must always be set for this router, |
| 17711 | unless &%verify_only%& is set. |
| 17712 | |
| 17713 | If SRV support is configured (see &%check_srv%& below), Exim first searches for |
| 17714 | SRV records. If none are found, or if SRV support is not configured, |
| 17715 | MX records are looked up. If no MX records exist, address records are sought. |
| 17716 | However, &%mx_domains%& can be set to disable the direct use of address |
| 17717 | records. |
| 17718 | |
| 17719 | MX records of equal priority are sorted by Exim into a random order. Exim then |
| 17720 | looks for address records for the host names obtained from MX or SRV records. |
| 17721 | When a host has more than one IP address, they are sorted into a random order, |
| 17722 | except that IPv6 addresses are always sorted before IPv4 addresses. If all the |
| 17723 | IP addresses found are discarded by a setting of the &%ignore_target_hosts%& |
| 17724 | generic option, the router declines. |
| 17725 | |
| 17726 | Unless they have the highest priority (lowest MX value), MX records that point |
| 17727 | to the local host, or to any host name that matches &%hosts_treat_as_local%&, |
| 17728 | are discarded, together with any other MX records of equal or lower priority. |
| 17729 | |
| 17730 | .cindex "MX record" "pointing to local host" |
| 17731 | .cindex "local host" "MX pointing to" |
| 17732 | .oindex "&%self%&" "in &(dnslookup)& router" |
| 17733 | If the host pointed to by the highest priority MX record, or looked up as an |
| 17734 | address record, is the local host, or matches &%hosts_treat_as_local%&, what |
| 17735 | happens is controlled by the generic &%self%& option. |
| 17736 | |
| 17737 | |
| 17738 | .section "Problems with DNS lookups" "SECTprowitdnsloo" |
| 17739 | There have been problems with DNS servers when SRV records are looked up. |
| 17740 | Some mis-behaving servers return a DNS error or timeout when a non-existent |
| 17741 | SRV record is sought. Similar problems have in the past been reported for |
| 17742 | MX records. The global &%dns_again_means_nonexist%& option can help with this |
| 17743 | problem, but it is heavy-handed because it is a global option. |
| 17744 | |
| 17745 | For this reason, there are two options, &%srv_fail_domains%& and |
| 17746 | &%mx_fail_domains%&, that control what happens when a DNS lookup in a |
| 17747 | &(dnslookup)& router results in a DNS failure or a &"try again"& response. If |
| 17748 | an attempt to look up an SRV or MX record causes one of these results, and the |
| 17749 | domain matches the relevant list, Exim behaves as if the DNS had responded &"no |
| 17750 | such record"&. In the case of an SRV lookup, this means that the router |
| 17751 | proceeds to look for MX records; in the case of an MX lookup, it proceeds to |
| 17752 | look for A or AAAA records, unless the domain matches &%mx_domains%&, in which |
| 17753 | case routing fails. |
| 17754 | |
| 17755 | |
| 17756 | .section "Declining addresses by dnslookup" "SECTdnslookupdecline" |
| 17757 | .cindex "&(dnslookup)& router" "declines" |
| 17758 | There are a few cases where a &(dnslookup)& router will decline to accept |
| 17759 | an address; if such a router is expected to handle "all remaining non-local |
| 17760 | domains", then it is important to set &%no_more%&. |
| 17761 | |
| 17762 | Reasons for a &(dnslookup)& router to decline currently include: |
| 17763 | .ilist |
| 17764 | The domain does not exist in DNS |
| 17765 | .next |
| 17766 | The domain exists but the MX record's host part is just "."; this is a common |
| 17767 | convention (borrowed from SRV) used to indicate that there is no such service |
| 17768 | for this domain and to not fall back to trying A/AAAA records. |
| 17769 | .next |
| 17770 | Ditto, but for SRV records, when &%check_srv%& is set on this router. |
| 17771 | .next |
| 17772 | MX record points to a non-existent host. |
| 17773 | .next |
| 17774 | MX record points to an IP address and the main section option |
| 17775 | &%allow_mx_to_ip%& is not set. |
| 17776 | .next |
| 17777 | MX records exist and point to valid hosts, but all hosts resolve only to |
| 17778 | addresses blocked by the &%ignore_target_hosts%& generic option on this router. |
| 17779 | .next |
| 17780 | The domain is not syntactically valid (see also &%allow_utf8_domains%& and |
| 17781 | &%dns_check_names_pattern%& for handling one variant of this) |
| 17782 | .next |
| 17783 | &%check_secondary_mx%& is set on this router but the local host can |
| 17784 | not be found in the MX records (see below) |
| 17785 | .endlist |
| 17786 | |
| 17787 | |
| 17788 | |
| 17789 | |
| 17790 | .section "Private options for dnslookup" "SECID118" |
| 17791 | .cindex "options" "&(dnslookup)& router" |
| 17792 | The private options for the &(dnslookup)& router are as follows: |
| 17793 | |
| 17794 | .option check_secondary_mx dnslookup boolean false |
| 17795 | .cindex "MX record" "checking for secondary" |
| 17796 | If this option is set, the router declines unless the local host is found in |
| 17797 | (and removed from) the list of hosts obtained by MX lookup. This can be used to |
| 17798 | process domains for which the local host is a secondary mail exchanger |
| 17799 | differently to other domains. The way in which Exim decides whether a host is |
| 17800 | the local host is described in section &<<SECTreclocipadd>>&. |
| 17801 | |
| 17802 | |
| 17803 | .option check_srv dnslookup string&!! unset |
| 17804 | .cindex "SRV record" "enabling use of" |
| 17805 | The &(dnslookup)& router supports the use of SRV records (see RFC 2782) in |
| 17806 | addition to MX and address records. The support is disabled by default. To |
| 17807 | enable SRV support, set the &%check_srv%& option to the name of the service |
| 17808 | required. For example, |
| 17809 | .code |
| 17810 | check_srv = smtp |
| 17811 | .endd |
| 17812 | looks for SRV records that refer to the normal smtp service. The option is |
| 17813 | expanded, so the service name can vary from message to message or address |
| 17814 | to address. This might be helpful if SRV records are being used for a |
| 17815 | submission service. If the expansion is forced to fail, the &%check_srv%& |
| 17816 | option is ignored, and the router proceeds to look for MX records in the |
| 17817 | normal way. |
| 17818 | |
| 17819 | When the expansion succeeds, the router searches first for SRV records for |
| 17820 | the given service (it assumes TCP protocol). A single SRV record with a |
| 17821 | host name that consists of just a single dot indicates &"no such service for |
| 17822 | this domain"&; if this is encountered, the router declines. If other kinds of |
| 17823 | SRV record are found, they are used to construct a host list for delivery |
| 17824 | according to the rules of RFC 2782. MX records are not sought in this case. |
| 17825 | |
| 17826 | When no SRV records are found, MX records (and address records) are sought in |
| 17827 | the traditional way. In other words, SRV records take precedence over MX |
| 17828 | records, just as MX records take precedence over address records. Note that |
| 17829 | this behaviour is not sanctioned by RFC 2782, though a previous draft RFC |
| 17830 | defined it. It is apparently believed that MX records are sufficient for email |
| 17831 | and that SRV records should not be used for this purpose. However, SRV records |
| 17832 | have an additional &"weight"& feature which some people might find useful when |
| 17833 | trying to split an SMTP load between hosts of different power. |
| 17834 | |
| 17835 | See section &<<SECTprowitdnsloo>>& above for a discussion of Exim's behaviour |
| 17836 | when there is a DNS lookup error. |
| 17837 | |
| 17838 | |
| 17839 | |
| 17840 | .new |
| 17841 | .option dnssec_request_domains dnslookup "domain list&!!" unset |
| 17842 | .cindex "MX record" "security" |
| 17843 | .cindex "DNSSEC" "MX lookup" |
| 17844 | .cindex "security" "MX lookup" |
| 17845 | .cindex "DNS" "DNSSEC" |
| 17846 | DNS lookups for domains matching &%dnssec_request_domains%& will be done with |
| 17847 | the dnssec request bit set. |
| 17848 | This applies to all of the SRV, MX A6, AAAA, A lookup sequence. |
| 17849 | .wen |
| 17850 | |
| 17851 | |
| 17852 | |
| 17853 | .new |
| 17854 | .option dnssec_require_domains dnslookup "domain list&!!" unset |
| 17855 | .cindex "MX record" "security" |
| 17856 | .cindex "DNSSEC" "MX lookup" |
| 17857 | .cindex "security" "MX lookup" |
| 17858 | .cindex "DNS" "DNSSEC" |
| 17859 | DNS lookups for domains matching &%dnssec_request_domains%& will be done with |
| 17860 | the dnssec request bit set. Any returns not having the Authenticated Data bit |
| 17861 | (AD bit) set wil be ignored and logged as a host-lookup failure. |
| 17862 | This applies to all of the SRV, MX A6, AAAA, A lookup sequence. |
| 17863 | .wen |
| 17864 | |
| 17865 | |
| 17866 | |
| 17867 | .option mx_domains dnslookup "domain list&!!" unset |
| 17868 | .cindex "MX record" "required to exist" |
| 17869 | .cindex "SRV record" "required to exist" |
| 17870 | A domain that matches &%mx_domains%& is required to have either an MX or an SRV |
| 17871 | record in order to be recognized. (The name of this option could be improved.) |
| 17872 | For example, if all the mail hosts in &'fict.example'& are known to have MX |
| 17873 | records, except for those in &'discworld.fict.example'&, you could use this |
| 17874 | setting: |
| 17875 | .code |
| 17876 | mx_domains = ! *.discworld.fict.example : *.fict.example |
| 17877 | .endd |
| 17878 | This specifies that messages addressed to a domain that matches the list but |
| 17879 | has no MX record should be bounced immediately instead of being routed using |
| 17880 | the address record. |
| 17881 | |
| 17882 | |
| 17883 | .option mx_fail_domains dnslookup "domain list&!!" unset |
| 17884 | If the DNS lookup for MX records for one of the domains in this list causes a |
| 17885 | DNS lookup error, Exim behaves as if no MX records were found. See section |
| 17886 | &<<SECTprowitdnsloo>>& for more discussion. |
| 17887 | |
| 17888 | |
| 17889 | |
| 17890 | |
| 17891 | .option qualify_single dnslookup boolean true |
| 17892 | .cindex "DNS" "resolver options" |
| 17893 | .cindex "DNS" "qualifying single-component names" |
| 17894 | When this option is true, the resolver option RES_DEFNAMES is set for DNS |
| 17895 | lookups. Typically, but not standardly, this causes the resolver to qualify |
| 17896 | single-component names with the default domain. For example, on a machine |
| 17897 | called &'dictionary.ref.example'&, the domain &'thesaurus'& would be changed to |
| 17898 | &'thesaurus.ref.example'& inside the resolver. For details of what your |
| 17899 | resolver actually does, consult your man pages for &'resolver'& and |
| 17900 | &'resolv.conf'&. |
| 17901 | |
| 17902 | |
| 17903 | |
| 17904 | .option rewrite_headers dnslookup boolean true |
| 17905 | .cindex "rewriting" "header lines" |
| 17906 | .cindex "header lines" "rewriting" |
| 17907 | If the domain name in the address that is being processed is not fully |
| 17908 | qualified, it may be expanded to its full form by a DNS lookup. For example, if |
| 17909 | an address is specified as &'dormouse@teaparty'&, the domain might be |
| 17910 | expanded to &'teaparty.wonderland.fict.example'&. Domain expansion can also |
| 17911 | occur as a result of setting the &%widen_domains%& option. If |
| 17912 | &%rewrite_headers%& is true, all occurrences of the abbreviated domain name in |
| 17913 | any &'Bcc:'&, &'Cc:'&, &'From:'&, &'Reply-to:'&, &'Sender:'&, and &'To:'& |
| 17914 | header lines of the message are rewritten with the full domain name. |
| 17915 | |
| 17916 | This option should be turned off only when it is known that no message is |
| 17917 | ever going to be sent outside an environment where the abbreviation makes |
| 17918 | sense. |
| 17919 | |
| 17920 | When an MX record is looked up in the DNS and matches a wildcard record, name |
| 17921 | servers normally return a record containing the name that has been looked up, |
| 17922 | making it impossible to detect whether a wildcard was present or not. However, |
| 17923 | some name servers have recently been seen to return the wildcard entry. If the |
| 17924 | name returned by a DNS lookup begins with an asterisk, it is not used for |
| 17925 | header rewriting. |
| 17926 | |
| 17927 | |
| 17928 | .option same_domain_copy_routing dnslookup boolean false |
| 17929 | .cindex "address" "copying routing" |
| 17930 | Addresses with the same domain are normally routed by the &(dnslookup)& router |
| 17931 | to the same list of hosts. However, this cannot be presumed, because the router |
| 17932 | options and preconditions may refer to the local part of the address. By |
| 17933 | default, therefore, Exim routes each address in a message independently. DNS |
| 17934 | servers run caches, so repeated DNS lookups are not normally expensive, and in |
| 17935 | any case, personal messages rarely have more than a few recipients. |
| 17936 | |
| 17937 | If you are running mailing lists with large numbers of subscribers at the same |
| 17938 | domain, and you are using a &(dnslookup)& router which is independent of the |
| 17939 | local part, you can set &%same_domain_copy_routing%& to bypass repeated DNS |
| 17940 | lookups for identical domains in one message. In this case, when &(dnslookup)& |
| 17941 | routes an address to a remote transport, any other unrouted addresses in the |
| 17942 | message that have the same domain are automatically given the same routing |
| 17943 | without processing them independently, |
| 17944 | provided the following conditions are met: |
| 17945 | |
| 17946 | .ilist |
| 17947 | No router that processed the address specified &%headers_add%& or |
| 17948 | &%headers_remove%&. |
| 17949 | .next |
| 17950 | The router did not change the address in any way, for example, by &"widening"& |
| 17951 | the domain. |
| 17952 | .endlist |
| 17953 | |
| 17954 | |
| 17955 | |
| 17956 | |
| 17957 | .option search_parents dnslookup boolean false |
| 17958 | .cindex "DNS" "resolver options" |
| 17959 | When this option is true, the resolver option RES_DNSRCH is set for DNS |
| 17960 | lookups. This is different from the &%qualify_single%& option in that it |
| 17961 | applies to domains containing dots. Typically, but not standardly, it causes |
| 17962 | the resolver to search for the name in the current domain and in parent |
| 17963 | domains. For example, on a machine in the &'fict.example'& domain, if looking |
| 17964 | up &'teaparty.wonderland'& failed, the resolver would try |
| 17965 | &'teaparty.wonderland.fict.example'&. For details of what your resolver |
| 17966 | actually does, consult your man pages for &'resolver'& and &'resolv.conf'&. |
| 17967 | |
| 17968 | Setting this option true can cause problems in domains that have a wildcard MX |
| 17969 | record, because any domain that does not have its own MX record matches the |
| 17970 | local wildcard. |
| 17971 | |
| 17972 | |
| 17973 | |
| 17974 | .option srv_fail_domains dnslookup "domain list&!!" unset |
| 17975 | If the DNS lookup for SRV records for one of the domains in this list causes a |
| 17976 | DNS lookup error, Exim behaves as if no SRV records were found. See section |
| 17977 | &<<SECTprowitdnsloo>>& for more discussion. |
| 17978 | |
| 17979 | |
| 17980 | |
| 17981 | |
| 17982 | .option widen_domains dnslookup "string list" unset |
| 17983 | .cindex "domain" "partial; widening" |
| 17984 | If a DNS lookup fails and this option is set, each of its strings in turn is |
| 17985 | added onto the end of the domain, and the lookup is tried again. For example, |
| 17986 | if |
| 17987 | .code |
| 17988 | widen_domains = fict.example:ref.example |
| 17989 | .endd |
| 17990 | is set and a lookup of &'klingon.dictionary'& fails, |
| 17991 | &'klingon.dictionary.fict.example'& is looked up, and if this fails, |
| 17992 | &'klingon.dictionary.ref.example'& is tried. Note that the &%qualify_single%& |
| 17993 | and &%search_parents%& options can cause some widening to be undertaken inside |
| 17994 | the DNS resolver. &%widen_domains%& is not applied to sender addresses |
| 17995 | when verifying, unless &%rewrite_headers%& is false (not the default). |
| 17996 | |
| 17997 | |
| 17998 | .section "Effect of qualify_single and search_parents" "SECID119" |
| 17999 | When a domain from an envelope recipient is changed by the resolver as a result |
| 18000 | of the &%qualify_single%& or &%search_parents%& options, Exim rewrites the |
| 18001 | corresponding address in the message's header lines unless &%rewrite_headers%& |
| 18002 | is set false. Exim then re-routes the address, using the full domain. |
| 18003 | |
| 18004 | These two options affect only the DNS lookup that takes place inside the router |
| 18005 | for the domain of the address that is being routed. They do not affect lookups |
| 18006 | such as that implied by |
| 18007 | .code |
| 18008 | domains = @mx_any |
| 18009 | .endd |
| 18010 | that may happen while processing a router precondition before the router is |
| 18011 | entered. No widening ever takes place for these lookups. |
| 18012 | .ecindex IIDdnsrou1 |
| 18013 | .ecindex IIDdnsrou2 |
| 18014 | |
| 18015 | |
| 18016 | |
| 18017 | |
| 18018 | |
| 18019 | |
| 18020 | |
| 18021 | |
| 18022 | |
| 18023 | . //////////////////////////////////////////////////////////////////////////// |
| 18024 | . //////////////////////////////////////////////////////////////////////////// |
| 18025 | |
| 18026 | .chapter "The ipliteral router" "CHID5" |
| 18027 | .cindex "&(ipliteral)& router" |
| 18028 | .cindex "domain literal" "routing" |
| 18029 | .cindex "routers" "&(ipliteral)&" |
| 18030 | This router has no private options. Unless it is being used purely for |
| 18031 | verification (see &%verify_only%&) a transport is required to be defined by the |
| 18032 | generic &%transport%& option. The router accepts the address if its domain part |
| 18033 | takes the form of an RFC 2822 domain literal. For example, the &(ipliteral)& |
| 18034 | router handles the address |
| 18035 | .code |
| 18036 | root@[192.168.1.1] |
| 18037 | .endd |
| 18038 | by setting up delivery to the host with that IP address. IPv4 domain literals |
| 18039 | consist of an IPv4 address enclosed in square brackets. IPv6 domain literals |
| 18040 | are similar, but the address is preceded by &`ipv6:`&. For example: |
| 18041 | .code |
| 18042 | postmaster@[ipv6:fe80::a00:20ff:fe86:a061.5678] |
| 18043 | .endd |
| 18044 | Exim allows &`ipv4:`& before IPv4 addresses, for consistency, and on the |
| 18045 | grounds that sooner or later somebody will try it. |
| 18046 | |
| 18047 | .oindex "&%self%&" "in &(ipliteral)& router" |
| 18048 | If the IP address matches something in &%ignore_target_hosts%&, the router |
| 18049 | declines. If an IP literal turns out to refer to the local host, the generic |
| 18050 | &%self%& option determines what happens. |
| 18051 | |
| 18052 | The RFCs require support for domain literals; however, their use is |
| 18053 | controversial in today's Internet. If you want to use this router, you must |
| 18054 | also set the main configuration option &%allow_domain_literals%&. Otherwise, |
| 18055 | Exim will not recognize the domain literal syntax in addresses. |
| 18056 | |
| 18057 | |
| 18058 | |
| 18059 | . //////////////////////////////////////////////////////////////////////////// |
| 18060 | . //////////////////////////////////////////////////////////////////////////// |
| 18061 | |
| 18062 | .chapter "The iplookup router" "CHID6" |
| 18063 | .cindex "&(iplookup)& router" |
| 18064 | .cindex "routers" "&(iplookup)&" |
| 18065 | The &(iplookup)& router was written to fulfil a specific requirement in |
| 18066 | Cambridge University (which in fact no longer exists). For this reason, it is |
| 18067 | not included in the binary of Exim by default. If you want to include it, you |
| 18068 | must set |
| 18069 | .code |
| 18070 | ROUTER_IPLOOKUP=yes |
| 18071 | .endd |
| 18072 | in your &_Local/Makefile_& configuration file. |
| 18073 | |
| 18074 | The &(iplookup)& router routes an address by sending it over a TCP or UDP |
| 18075 | connection to one or more specific hosts. The host can then return the same or |
| 18076 | a different address &-- in effect rewriting the recipient address in the |
| 18077 | message's envelope. The new address is then passed on to subsequent routers. If |
| 18078 | this process fails, the address can be passed on to other routers, or delivery |
| 18079 | can be deferred. Since &(iplookup)& is just a rewriting router, a transport |
| 18080 | must not be specified for it. |
| 18081 | |
| 18082 | .cindex "options" "&(iplookup)& router" |
| 18083 | .option hosts iplookup string unset |
| 18084 | This option must be supplied. Its value is a colon-separated list of host |
| 18085 | names. The hosts are looked up using &[gethostbyname()]& |
| 18086 | (or &[getipnodebyname()]& when available) |
| 18087 | and are tried in order until one responds to the query. If none respond, what |
| 18088 | happens is controlled by &%optional%&. |
| 18089 | |
| 18090 | |
| 18091 | .option optional iplookup boolean false |
| 18092 | If &%optional%& is true, if no response is obtained from any host, the address |
| 18093 | is passed to the next router, overriding &%no_more%&. If &%optional%& is false, |
| 18094 | delivery to the address is deferred. |
| 18095 | |
| 18096 | |
| 18097 | .option port iplookup integer 0 |
| 18098 | .cindex "port" "&(iplookup)& router" |
| 18099 | This option must be supplied. It specifies the port number for the TCP or UDP |
| 18100 | call. |
| 18101 | |
| 18102 | |
| 18103 | .option protocol iplookup string udp |
| 18104 | This option can be set to &"udp"& or &"tcp"& to specify which of the two |
| 18105 | protocols is to be used. |
| 18106 | |
| 18107 | |
| 18108 | .option query iplookup string&!! "see below" |
| 18109 | This defines the content of the query that is sent to the remote hosts. The |
| 18110 | default value is: |
| 18111 | .code |
| 18112 | $local_part@$domain $local_part@$domain |
| 18113 | .endd |
| 18114 | The repetition serves as a way of checking that a response is to the correct |
| 18115 | query in the default case (see &%response_pattern%& below). |
| 18116 | |
| 18117 | |
| 18118 | .option reroute iplookup string&!! unset |
| 18119 | If this option is not set, the rerouted address is precisely the byte string |
| 18120 | returned by the remote host, up to the first white space, if any. If set, the |
| 18121 | string is expanded to form the rerouted address. It can include parts matched |
| 18122 | in the response by &%response_pattern%& by means of numeric variables such as |
| 18123 | &$1$&, &$2$&, etc. The variable &$0$& refers to the entire input string, |
| 18124 | whether or not a pattern is in use. In all cases, the rerouted address must end |
| 18125 | up in the form &'local_part@domain'&. |
| 18126 | |
| 18127 | |
| 18128 | .option response_pattern iplookup string unset |
| 18129 | This option can be set to a regular expression that is applied to the string |
| 18130 | returned from the remote host. If the pattern does not match the response, the |
| 18131 | router declines. If &%response_pattern%& is not set, no checking of the |
| 18132 | response is done, unless the query was defaulted, in which case there is a |
| 18133 | check that the text returned after the first white space is the original |
| 18134 | address. This checks that the answer that has been received is in response to |
| 18135 | the correct question. For example, if the response is just a new domain, the |
| 18136 | following could be used: |
| 18137 | .code |
| 18138 | response_pattern = ^([^@]+)$ |
| 18139 | reroute = $local_part@$1 |
| 18140 | .endd |
| 18141 | |
| 18142 | .option timeout iplookup time 5s |
| 18143 | This specifies the amount of time to wait for a response from the remote |
| 18144 | machine. The same timeout is used for the &[connect()]& function for a TCP |
| 18145 | call. It does not apply to UDP. |
| 18146 | |
| 18147 | |
| 18148 | |
| 18149 | |
| 18150 | . //////////////////////////////////////////////////////////////////////////// |
| 18151 | . //////////////////////////////////////////////////////////////////////////// |
| 18152 | |
| 18153 | .chapter "The manualroute router" "CHID7" |
| 18154 | .scindex IIDmanrou1 "&(manualroute)& router" |
| 18155 | .scindex IIDmanrou2 "routers" "&(manualroute)&" |
| 18156 | .cindex "domain" "manually routing" |
| 18157 | The &(manualroute)& router is so-called because it provides a way of manually |
| 18158 | routing an address according to its domain. It is mainly used when you want to |
| 18159 | route addresses to remote hosts according to your own rules, bypassing the |
| 18160 | normal DNS routing that looks up MX records. However, &(manualroute)& can also |
| 18161 | route to local transports, a facility that may be useful if you want to save |
| 18162 | messages for dial-in hosts in local files. |
| 18163 | |
| 18164 | The &(manualroute)& router compares a list of domain patterns with the domain |
| 18165 | it is trying to route. If there is no match, the router declines. Each pattern |
| 18166 | has associated with it a list of hosts and some other optional data, which may |
| 18167 | include a transport. The combination of a pattern and its data is called a |
| 18168 | &"routing rule"&. For patterns that do not have an associated transport, the |
| 18169 | generic &%transport%& option must specify a transport, unless the router is |
| 18170 | being used purely for verification (see &%verify_only%&). |
| 18171 | |
| 18172 | .vindex "&$host$&" |
| 18173 | In the case of verification, matching the domain pattern is sufficient for the |
| 18174 | router to accept the address. When actually routing an address for delivery, |
| 18175 | an address that matches a domain pattern is queued for the associated |
| 18176 | transport. If the transport is not a local one, a host list must be associated |
| 18177 | with the pattern; IP addresses are looked up for the hosts, and these are |
| 18178 | passed to the transport along with the mail address. For local transports, a |
| 18179 | host list is optional. If it is present, it is passed in &$host$& as a single |
| 18180 | text string. |
| 18181 | |
| 18182 | The list of routing rules can be provided as an inline string in |
| 18183 | &%route_list%&, or the data can be obtained by looking up the domain in a file |
| 18184 | or database by setting &%route_data%&. Only one of these settings may appear in |
| 18185 | any one instance of &(manualroute)&. The format of routing rules is described |
| 18186 | below, following the list of private options. |
| 18187 | |
| 18188 | |
| 18189 | .section "Private options for manualroute" "SECTprioptman" |
| 18190 | |
| 18191 | .cindex "options" "&(manualroute)& router" |
| 18192 | The private options for the &(manualroute)& router are as follows: |
| 18193 | |
| 18194 | .option host_all_ignored manualroute string defer |
| 18195 | See &%host_find_failed%&. |
| 18196 | |
| 18197 | .option host_find_failed manualroute string freeze |
| 18198 | This option controls what happens when &(manualroute)& tries to find an IP |
| 18199 | address for a host, and the host does not exist. The option can be set to one |
| 18200 | of the following values: |
| 18201 | .code |
| 18202 | decline |
| 18203 | defer |
| 18204 | fail |
| 18205 | freeze |
| 18206 | ignore |
| 18207 | pass |
| 18208 | .endd |
| 18209 | The default (&"freeze"&) assumes that this state is a serious configuration |
| 18210 | error. The difference between &"pass"& and &"decline"& is that the former |
| 18211 | forces the address to be passed to the next router (or the router defined by |
| 18212 | &%pass_router%&), |
| 18213 | .oindex "&%more%&" |
| 18214 | overriding &%no_more%&, whereas the latter passes the address to the next |
| 18215 | router only if &%more%& is true. |
| 18216 | |
| 18217 | The value &"ignore"& causes Exim to completely ignore a host whose IP address |
| 18218 | cannot be found. If all the hosts in the list are ignored, the behaviour is |
| 18219 | controlled by the &%host_all_ignored%& option. This takes the same values |
| 18220 | as &%host_find_failed%&, except that it cannot be set to &"ignore"&. |
| 18221 | |
| 18222 | The &%host_find_failed%& option applies only to a definite &"does not exist"& |
| 18223 | state; if a host lookup gets a temporary error, delivery is deferred unless the |
| 18224 | generic &%pass_on_timeout%& option is set. |
| 18225 | |
| 18226 | |
| 18227 | .option hosts_randomize manualroute boolean false |
| 18228 | .cindex "randomized host list" |
| 18229 | .cindex "host" "list of; randomized" |
| 18230 | If this option is set, the order of the items in a host list in a routing rule |
| 18231 | is randomized each time the list is used, unless an option in the routing rule |
| 18232 | overrides (see below). Randomizing the order of a host list can be used to do |
| 18233 | crude load sharing. However, if more than one mail address is routed by the |
| 18234 | same router to the same host list, the host lists are considered to be the same |
| 18235 | (even though they may be randomized into different orders) for the purpose of |
| 18236 | deciding whether to batch the deliveries into a single SMTP transaction. |
| 18237 | |
| 18238 | When &%hosts_randomize%& is true, a host list may be split |
| 18239 | into groups whose order is separately randomized. This makes it possible to |
| 18240 | set up MX-like behaviour. The boundaries between groups are indicated by an |
| 18241 | item that is just &`+`& in the host list. For example: |
| 18242 | .code |
| 18243 | route_list = * host1:host2:host3:+:host4:host5 |
| 18244 | .endd |
| 18245 | The order of the first three hosts and the order of the last two hosts is |
| 18246 | randomized for each use, but the first three always end up before the last two. |
| 18247 | If &%hosts_randomize%& is not set, a &`+`& item in the list is ignored. If a |
| 18248 | randomized host list is passed to an &(smtp)& transport that also has |
| 18249 | &%hosts_randomize set%&, the list is not re-randomized. |
| 18250 | |
| 18251 | |
| 18252 | .option route_data manualroute string&!! unset |
| 18253 | If this option is set, it must expand to yield the data part of a routing rule. |
| 18254 | Typically, the expansion string includes a lookup based on the domain. For |
| 18255 | example: |
| 18256 | .code |
| 18257 | route_data = ${lookup{$domain}dbm{/etc/routes}} |
| 18258 | .endd |
| 18259 | If the expansion is forced to fail, or the result is an empty string, the |
| 18260 | router declines. Other kinds of expansion failure cause delivery to be |
| 18261 | deferred. |
| 18262 | |
| 18263 | |
| 18264 | .option route_list manualroute "string list" unset |
| 18265 | This string is a list of routing rules, in the form defined below. Note that, |
| 18266 | unlike most string lists, the items are separated by semicolons. This is so |
| 18267 | that they may contain colon-separated host lists. |
| 18268 | |
| 18269 | |
| 18270 | .option same_domain_copy_routing manualroute boolean false |
| 18271 | .cindex "address" "copying routing" |
| 18272 | Addresses with the same domain are normally routed by the &(manualroute)& |
| 18273 | router to the same list of hosts. However, this cannot be presumed, because the |
| 18274 | router options and preconditions may refer to the local part of the address. By |
| 18275 | default, therefore, Exim routes each address in a message independently. DNS |
| 18276 | servers run caches, so repeated DNS lookups are not normally expensive, and in |
| 18277 | any case, personal messages rarely have more than a few recipients. |
| 18278 | |
| 18279 | If you are running mailing lists with large numbers of subscribers at the same |
| 18280 | domain, and you are using a &(manualroute)& router which is independent of the |
| 18281 | local part, you can set &%same_domain_copy_routing%& to bypass repeated DNS |
| 18282 | lookups for identical domains in one message. In this case, when |
| 18283 | &(manualroute)& routes an address to a remote transport, any other unrouted |
| 18284 | addresses in the message that have the same domain are automatically given the |
| 18285 | same routing without processing them independently. However, this is only done |
| 18286 | if &%headers_add%& and &%headers_remove%& are unset. |
| 18287 | |
| 18288 | |
| 18289 | |
| 18290 | |
| 18291 | .section "Routing rules in route_list" "SECID120" |
| 18292 | The value of &%route_list%& is a string consisting of a sequence of routing |
| 18293 | rules, separated by semicolons. If a semicolon is needed in a rule, it can be |
| 18294 | entered as two semicolons. Alternatively, the list separator can be changed as |
| 18295 | described (for colon-separated lists) in section &<<SECTlistconstruct>>&. |
| 18296 | Empty rules are ignored. The format of each rule is |
| 18297 | .display |
| 18298 | <&'domain pattern'&> <&'list of hosts'&> <&'options'&> |
| 18299 | .endd |
| 18300 | The following example contains two rules, each with a simple domain pattern and |
| 18301 | no options: |
| 18302 | .code |
| 18303 | route_list = \ |
| 18304 | dict.ref.example mail-1.ref.example:mail-2.ref.example ; \ |
| 18305 | thes.ref.example mail-3.ref.example:mail-4.ref.example |
| 18306 | .endd |
| 18307 | The three parts of a rule are separated by white space. The pattern and the |
| 18308 | list of hosts can be enclosed in quotes if necessary, and if they are, the |
| 18309 | usual quoting rules apply. Each rule in a &%route_list%& must start with a |
| 18310 | single domain pattern, which is the only mandatory item in the rule. The |
| 18311 | pattern is in the same format as one item in a domain list (see section |
| 18312 | &<<SECTdomainlist>>&), |
| 18313 | except that it may not be the name of an interpolated file. |
| 18314 | That is, it may be wildcarded, or a regular expression, or a file or database |
| 18315 | lookup (with semicolons doubled, because of the use of semicolon as a separator |
| 18316 | in a &%route_list%&). |
| 18317 | |
| 18318 | The rules in &%route_list%& are searched in order until one of the patterns |
| 18319 | matches the domain that is being routed. The list of hosts and then options are |
| 18320 | then used as described below. If there is no match, the router declines. When |
| 18321 | &%route_list%& is set, &%route_data%& must not be set. |
| 18322 | |
| 18323 | |
| 18324 | |
| 18325 | .section "Routing rules in route_data" "SECID121" |
| 18326 | The use of &%route_list%& is convenient when there are only a small number of |
| 18327 | routing rules. For larger numbers, it is easier to use a file or database to |
| 18328 | hold the routing information, and use the &%route_data%& option instead. |
| 18329 | The value of &%route_data%& is a list of hosts, followed by (optional) options. |
| 18330 | Most commonly, &%route_data%& is set as a string that contains an |
| 18331 | expansion lookup. For example, suppose we place two routing rules in a file |
| 18332 | like this: |
| 18333 | .code |
| 18334 | dict.ref.example: mail-1.ref.example:mail-2.ref.example |
| 18335 | thes.ref.example: mail-3.ref.example:mail-4.ref.example |
| 18336 | .endd |
| 18337 | This data can be accessed by setting |
| 18338 | .code |
| 18339 | route_data = ${lookup{$domain}lsearch{/the/file/name}} |
| 18340 | .endd |
| 18341 | Failure of the lookup results in an empty string, causing the router to |
| 18342 | decline. However, you do not have to use a lookup in &%route_data%&. The only |
| 18343 | requirement is that the result of expanding the string is a list of hosts, |
| 18344 | possibly followed by options, separated by white space. The list of hosts must |
| 18345 | be enclosed in quotes if it contains white space. |
| 18346 | |
| 18347 | |
| 18348 | |
| 18349 | |
| 18350 | .section "Format of the list of hosts" "SECID122" |
| 18351 | A list of hosts, whether obtained via &%route_data%& or &%route_list%&, is |
| 18352 | always separately expanded before use. If the expansion fails, the router |
| 18353 | declines. The result of the expansion must be a colon-separated list of names |
| 18354 | and/or IP addresses, optionally also including ports. The format of each item |
| 18355 | in the list is described in the next section. The list separator can be changed |
| 18356 | as described in section &<<SECTlistconstruct>>&. |
| 18357 | |
| 18358 | If the list of hosts was obtained from a &%route_list%& item, the following |
| 18359 | variables are set during its expansion: |
| 18360 | |
| 18361 | .ilist |
| 18362 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &(manualroute)& router" |
| 18363 | If the domain was matched against a regular expression, the numeric variables |
| 18364 | &$1$&, &$2$&, etc. may be set. For example: |
| 18365 | .code |
| 18366 | route_list = ^domain(\d+) host-$1.text.example |
| 18367 | .endd |
| 18368 | .next |
| 18369 | &$0$& is always set to the entire domain. |
| 18370 | .next |
| 18371 | &$1$& is also set when partial matching is done in a file lookup. |
| 18372 | |
| 18373 | .next |
| 18374 | .vindex "&$value$&" |
| 18375 | If the pattern that matched the domain was a lookup item, the data that was |
| 18376 | looked up is available in the expansion variable &$value$&. For example: |
| 18377 | .code |
| 18378 | route_list = lsearch;;/some/file.routes $value |
| 18379 | .endd |
| 18380 | .endlist |
| 18381 | |
| 18382 | Note the doubling of the semicolon in the pattern that is necessary because |
| 18383 | semicolon is the default route list separator. |
| 18384 | |
| 18385 | |
| 18386 | |
| 18387 | .section "Format of one host item" "SECTformatonehostitem" |
| 18388 | Each item in the list of hosts is either a host name or an IP address, |
| 18389 | optionally with an attached port number. When no port is given, an IP address |
| 18390 | is not enclosed in brackets. When a port is specified, it overrides the port |
| 18391 | specification on the transport. The port is separated from the name or address |
| 18392 | by a colon. This leads to some complications: |
| 18393 | |
| 18394 | .ilist |
| 18395 | Because colon is the default separator for the list of hosts, either |
| 18396 | the colon that specifies a port must be doubled, or the list separator must |
| 18397 | be changed. The following two examples have the same effect: |
| 18398 | .code |
| 18399 | route_list = * "host1.tld::1225 : host2.tld::1226" |
| 18400 | route_list = * "<+ host1.tld:1225 + host2.tld:1226" |
| 18401 | .endd |
| 18402 | .next |
| 18403 | When IPv6 addresses are involved, it gets worse, because they contain |
| 18404 | colons of their own. To make this case easier, it is permitted to |
| 18405 | enclose an IP address (either v4 or v6) in square brackets if a port |
| 18406 | number follows. For example: |
| 18407 | .code |
| 18408 | route_list = * "</ [10.1.1.1]:1225 / [::1]:1226" |
| 18409 | .endd |
| 18410 | .endlist |
| 18411 | |
| 18412 | .section "How the list of hosts is used" "SECThostshowused" |
| 18413 | When an address is routed to an &(smtp)& transport by &(manualroute)&, each of |
| 18414 | the hosts is tried, in the order specified, when carrying out the SMTP |
| 18415 | delivery. However, the order can be changed by setting the &%hosts_randomize%& |
| 18416 | option, either on the router (see section &<<SECTprioptman>>& above), or on the |
| 18417 | transport. |
| 18418 | |
| 18419 | Hosts may be listed by name or by IP address. An unadorned name in the list of |
| 18420 | hosts is interpreted as a host name. A name that is followed by &`/MX`& is |
| 18421 | interpreted as an indirection to a sublist of hosts obtained by looking up MX |
| 18422 | records in the DNS. For example: |
| 18423 | .code |
| 18424 | route_list = * x.y.z:p.q.r/MX:e.f.g |
| 18425 | .endd |
| 18426 | If this feature is used with a port specifier, the port must come last. For |
| 18427 | example: |
| 18428 | .code |
| 18429 | route_list = * dom1.tld/mx::1225 |
| 18430 | .endd |
| 18431 | If the &%hosts_randomize%& option is set, the order of the items in the list is |
| 18432 | randomized before any lookups are done. Exim then scans the list; for any name |
| 18433 | that is not followed by &`/MX`& it looks up an IP address. If this turns out to |
| 18434 | be an interface on the local host and the item is not the first in the list, |
| 18435 | Exim discards it and any subsequent items. If it is the first item, what |
| 18436 | happens is controlled by the |
| 18437 | .oindex "&%self%&" "in &(manualroute)& router" |
| 18438 | &%self%& option of the router. |
| 18439 | |
| 18440 | A name on the list that is followed by &`/MX`& is replaced with the list of |
| 18441 | hosts obtained by looking up MX records for the name. This is always a DNS |
| 18442 | lookup; the &%bydns%& and &%byname%& options (see section &<<SECThowoptused>>& |
| 18443 | below) are not relevant here. The order of these hosts is determined by the |
| 18444 | preference values in the MX records, according to the usual rules. Because |
| 18445 | randomizing happens before the MX lookup, it does not affect the order that is |
| 18446 | defined by MX preferences. |
| 18447 | |
| 18448 | If the local host is present in the sublist obtained from MX records, but is |
| 18449 | not the most preferred host in that list, it and any equally or less |
| 18450 | preferred hosts are removed before the sublist is inserted into the main list. |
| 18451 | |
| 18452 | If the local host is the most preferred host in the MX list, what happens |
| 18453 | depends on where in the original list of hosts the &`/MX`& item appears. If it |
| 18454 | is not the first item (that is, there are previous hosts in the main list), |
| 18455 | Exim discards this name and any subsequent items in the main list. |
| 18456 | |
| 18457 | If the MX item is first in the list of hosts, and the local host is the |
| 18458 | most preferred host, what happens is controlled by the &%self%& option of the |
| 18459 | router. |
| 18460 | |
| 18461 | DNS failures when lookup up the MX records are treated in the same way as DNS |
| 18462 | failures when looking up IP addresses: &%pass_on_timeout%& and |
| 18463 | &%host_find_failed%& are used when relevant. |
| 18464 | |
| 18465 | The generic &%ignore_target_hosts%& option applies to all hosts in the list, |
| 18466 | whether obtained from an MX lookup or not. |
| 18467 | |
| 18468 | |
| 18469 | |
| 18470 | .section "How the options are used" "SECThowoptused" |
| 18471 | The options are a sequence of words; in practice no more than three are ever |
| 18472 | present. One of the words can be the name of a transport; this overrides the |
| 18473 | &%transport%& option on the router for this particular routing rule only. The |
| 18474 | other words (if present) control randomization of the list of hosts on a |
| 18475 | per-rule basis, and how the IP addresses of the hosts are to be found when |
| 18476 | routing to a remote transport. These options are as follows: |
| 18477 | |
| 18478 | .ilist |
| 18479 | &%randomize%&: randomize the order of the hosts in this list, overriding the |
| 18480 | setting of &%hosts_randomize%& for this routing rule only. |
| 18481 | .next |
| 18482 | &%no_randomize%&: do not randomize the order of the hosts in this list, |
| 18483 | overriding the setting of &%hosts_randomize%& for this routing rule only. |
| 18484 | .next |
| 18485 | &%byname%&: use &[getipnodebyname()]& (&[gethostbyname()]& on older systems) to |
| 18486 | find IP addresses. This function may ultimately cause a DNS lookup, but it may |
| 18487 | also look in &_/etc/hosts_& or other sources of information. |
| 18488 | .next |
| 18489 | &%bydns%&: look up address records for the hosts directly in the DNS; fail if |
| 18490 | no address records are found. If there is a temporary DNS error (such as a |
| 18491 | timeout), delivery is deferred. |
| 18492 | .endlist |
| 18493 | |
| 18494 | For example: |
| 18495 | .code |
| 18496 | route_list = domain1 host1:host2:host3 randomize bydns;\ |
| 18497 | domain2 host4:host5 |
| 18498 | .endd |
| 18499 | If neither &%byname%& nor &%bydns%& is given, Exim behaves as follows: First, a |
| 18500 | DNS lookup is done. If this yields anything other than HOST_NOT_FOUND, that |
| 18501 | result is used. Otherwise, Exim goes on to try a call to &[getipnodebyname()]& |
| 18502 | or &[gethostbyname()]&, and the result of the lookup is the result of that |
| 18503 | call. |
| 18504 | |
| 18505 | &*Warning*&: It has been discovered that on some systems, if a DNS lookup |
| 18506 | called via &[getipnodebyname()]& times out, HOST_NOT_FOUND is returned |
| 18507 | instead of TRY_AGAIN. That is why the default action is to try a DNS |
| 18508 | lookup first. Only if that gives a definite &"no such host"& is the local |
| 18509 | function called. |
| 18510 | |
| 18511 | |
| 18512 | |
| 18513 | If no IP address for a host can be found, what happens is controlled by the |
| 18514 | &%host_find_failed%& option. |
| 18515 | |
| 18516 | .vindex "&$host$&" |
| 18517 | When an address is routed to a local transport, IP addresses are not looked up. |
| 18518 | The host list is passed to the transport in the &$host$& variable. |
| 18519 | |
| 18520 | |
| 18521 | |
| 18522 | .section "Manualroute examples" "SECID123" |
| 18523 | In some of the examples that follow, the presence of the &%remote_smtp%& |
| 18524 | transport, as defined in the default configuration file, is assumed: |
| 18525 | |
| 18526 | .ilist |
| 18527 | .cindex "smart host" "example router" |
| 18528 | The &(manualroute)& router can be used to forward all external mail to a |
| 18529 | &'smart host'&. If you have set up, in the main part of the configuration, a |
| 18530 | named domain list that contains your local domains, for example: |
| 18531 | .code |
| 18532 | domainlist local_domains = my.domain.example |
| 18533 | .endd |
| 18534 | You can arrange for all other domains to be routed to a smart host by making |
| 18535 | your first router something like this: |
| 18536 | .code |
| 18537 | smart_route: |
| 18538 | driver = manualroute |
| 18539 | domains = !+local_domains |
| 18540 | transport = remote_smtp |
| 18541 | route_list = * smarthost.ref.example |
| 18542 | .endd |
| 18543 | This causes all non-local addresses to be sent to the single host |
| 18544 | &'smarthost.ref.example'&. If a colon-separated list of smart hosts is given, |
| 18545 | they are tried in order |
| 18546 | (but you can use &%hosts_randomize%& to vary the order each time). |
| 18547 | Another way of configuring the same thing is this: |
| 18548 | .code |
| 18549 | smart_route: |
| 18550 | driver = manualroute |
| 18551 | transport = remote_smtp |
| 18552 | route_list = !+local_domains smarthost.ref.example |
| 18553 | .endd |
| 18554 | There is no difference in behaviour between these two routers as they stand. |
| 18555 | However, they behave differently if &%no_more%& is added to them. In the first |
| 18556 | example, the router is skipped if the domain does not match the &%domains%& |
| 18557 | precondition; the following router is always tried. If the router runs, it |
| 18558 | always matches the domain and so can never decline. Therefore, &%no_more%& |
| 18559 | would have no effect. In the second case, the router is never skipped; it |
| 18560 | always runs. However, if it doesn't match the domain, it declines. In this case |
| 18561 | &%no_more%& would prevent subsequent routers from running. |
| 18562 | |
| 18563 | .next |
| 18564 | .cindex "mail hub example" |
| 18565 | A &'mail hub'& is a host which receives mail for a number of domains via MX |
| 18566 | records in the DNS and delivers it via its own private routing mechanism. Often |
| 18567 | the final destinations are behind a firewall, with the mail hub being the one |
| 18568 | machine that can connect to machines both inside and outside the firewall. The |
| 18569 | &(manualroute)& router is usually used on a mail hub to route incoming messages |
| 18570 | to the correct hosts. For a small number of domains, the routing can be inline, |
| 18571 | using the &%route_list%& option, but for a larger number a file or database |
| 18572 | lookup is easier to manage. |
| 18573 | |
| 18574 | If the domain names are in fact the names of the machines to which the mail is |
| 18575 | to be sent by the mail hub, the configuration can be quite simple. For |
| 18576 | example: |
| 18577 | .code |
| 18578 | hub_route: |
| 18579 | driver = manualroute |
| 18580 | transport = remote_smtp |
| 18581 | route_list = *.rhodes.tvs.example $domain |
| 18582 | .endd |
| 18583 | This configuration routes domains that match &`*.rhodes.tvs.example`& to hosts |
| 18584 | whose names are the same as the mail domains. A similar approach can be taken |
| 18585 | if the host name can be obtained from the domain name by a string manipulation |
| 18586 | that the expansion facilities can handle. Otherwise, a lookup based on the |
| 18587 | domain can be used to find the host: |
| 18588 | .code |
| 18589 | through_firewall: |
| 18590 | driver = manualroute |
| 18591 | transport = remote_smtp |
| 18592 | route_data = ${lookup {$domain} cdb {/internal/host/routes}} |
| 18593 | .endd |
| 18594 | The result of the lookup must be the name or IP address of the host (or |
| 18595 | hosts) to which the address is to be routed. If the lookup fails, the route |
| 18596 | data is empty, causing the router to decline. The address then passes to the |
| 18597 | next router. |
| 18598 | |
| 18599 | .next |
| 18600 | .cindex "batched SMTP output example" |
| 18601 | .cindex "SMTP" "batched outgoing; example" |
| 18602 | You can use &(manualroute)& to deliver messages to pipes or files in batched |
| 18603 | SMTP format for onward transportation by some other means. This is one way of |
| 18604 | storing mail for a dial-up host when it is not connected. The route list entry |
| 18605 | can be as simple as a single domain name in a configuration like this: |
| 18606 | .code |
| 18607 | save_in_file: |
| 18608 | driver = manualroute |
| 18609 | transport = batchsmtp_appendfile |
| 18610 | route_list = saved.domain.example |
| 18611 | .endd |
| 18612 | though often a pattern is used to pick up more than one domain. If there are |
| 18613 | several domains or groups of domains with different transport requirements, |
| 18614 | different transports can be listed in the routing information: |
| 18615 | .code |
| 18616 | save_in_file: |
| 18617 | driver = manualroute |
| 18618 | route_list = \ |
| 18619 | *.saved.domain1.example $domain batch_appendfile; \ |
| 18620 | *.saved.domain2.example \ |
| 18621 | ${lookup{$domain}dbm{/domain2/hosts}{$value}fail} \ |
| 18622 | batch_pipe |
| 18623 | .endd |
| 18624 | .vindex "&$domain$&" |
| 18625 | .vindex "&$host$&" |
| 18626 | The first of these just passes the domain in the &$host$& variable, which |
| 18627 | doesn't achieve much (since it is also in &$domain$&), but the second does a |
| 18628 | file lookup to find a value to pass, causing the router to decline to handle |
| 18629 | the address if the lookup fails. |
| 18630 | |
| 18631 | .next |
| 18632 | .cindex "UUCP" "example of router for" |
| 18633 | Routing mail directly to UUCP software is a specific case of the use of |
| 18634 | &(manualroute)& in a gateway to another mail environment. This is an example of |
| 18635 | one way it can be done: |
| 18636 | .code |
| 18637 | # Transport |
| 18638 | uucp: |
| 18639 | driver = pipe |
| 18640 | user = nobody |
| 18641 | command = /usr/local/bin/uux -r - \ |
| 18642 | ${substr_-5:$host}!rmail ${local_part} |
| 18643 | return_fail_output = true |
| 18644 | |
| 18645 | # Router |
| 18646 | uucphost: |
| 18647 | transport = uucp |
| 18648 | driver = manualroute |
| 18649 | route_data = \ |
| 18650 | ${lookup{$domain}lsearch{/usr/local/exim/uucphosts}} |
| 18651 | .endd |
| 18652 | The file &_/usr/local/exim/uucphosts_& contains entries like |
| 18653 | .code |
| 18654 | darksite.ethereal.example: darksite.UUCP |
| 18655 | .endd |
| 18656 | It can be set up more simply without adding and removing &".UUCP"& but this way |
| 18657 | makes clear the distinction between the domain name |
| 18658 | &'darksite.ethereal.example'& and the UUCP host name &'darksite'&. |
| 18659 | .endlist |
| 18660 | .ecindex IIDmanrou1 |
| 18661 | .ecindex IIDmanrou2 |
| 18662 | |
| 18663 | |
| 18664 | |
| 18665 | |
| 18666 | |
| 18667 | |
| 18668 | |
| 18669 | |
| 18670 | . //////////////////////////////////////////////////////////////////////////// |
| 18671 | . //////////////////////////////////////////////////////////////////////////// |
| 18672 | |
| 18673 | .chapter "The queryprogram router" "CHAPdriverlast" |
| 18674 | .scindex IIDquerou1 "&(queryprogram)& router" |
| 18675 | .scindex IIDquerou2 "routers" "&(queryprogram)&" |
| 18676 | .cindex "routing" "by external program" |
| 18677 | The &(queryprogram)& router routes an address by running an external command |
| 18678 | and acting on its output. This is an expensive way to route, and is intended |
| 18679 | mainly for use in lightly-loaded systems, or for performing experiments. |
| 18680 | However, if it is possible to use the precondition options (&%domains%&, |
| 18681 | &%local_parts%&, etc) to skip this router for most addresses, it could sensibly |
| 18682 | be used in special cases, even on a busy host. There are the following private |
| 18683 | options: |
| 18684 | .cindex "options" "&(queryprogram)& router" |
| 18685 | |
| 18686 | .option command queryprogram string&!! unset |
| 18687 | This option must be set. It specifies the command that is to be run. The |
| 18688 | command is split up into a command name and arguments, and then each is |
| 18689 | expanded separately (exactly as for a &(pipe)& transport, described in chapter |
| 18690 | &<<CHAPpipetransport>>&). |
| 18691 | |
| 18692 | |
| 18693 | .option command_group queryprogram string unset |
| 18694 | .cindex "gid (group id)" "in &(queryprogram)& router" |
| 18695 | This option specifies a gid to be set when running the command while routing an |
| 18696 | address for deliver. It must be set if &%command_user%& specifies a numerical |
| 18697 | uid. If it begins with a digit, it is interpreted as the numerical value of the |
| 18698 | gid. Otherwise it is looked up using &[getgrnam()]&. |
| 18699 | |
| 18700 | |
| 18701 | .option command_user queryprogram string unset |
| 18702 | .cindex "uid (user id)" "for &(queryprogram)&" |
| 18703 | This option must be set. It specifies the uid which is set when running the |
| 18704 | command while routing an address for delivery. If the value begins with a digit, |
| 18705 | it is interpreted as the numerical value of the uid. Otherwise, it is looked up |
| 18706 | using &[getpwnam()]& to obtain a value for the uid and, if &%command_group%& is |
| 18707 | not set, a value for the gid also. |
| 18708 | |
| 18709 | &*Warning:*& Changing uid and gid is possible only when Exim is running as |
| 18710 | root, which it does during a normal delivery in a conventional configuration. |
| 18711 | However, when an address is being verified during message reception, Exim is |
| 18712 | usually running as the Exim user, not as root. If the &(queryprogram)& router |
| 18713 | is called from a non-root process, Exim cannot change uid or gid before running |
| 18714 | the command. In this circumstance the command runs under the current uid and |
| 18715 | gid. |
| 18716 | |
| 18717 | |
| 18718 | .option current_directory queryprogram string / |
| 18719 | This option specifies an absolute path which is made the current directory |
| 18720 | before running the command. |
| 18721 | |
| 18722 | |
| 18723 | .option timeout queryprogram time 1h |
| 18724 | If the command does not complete within the timeout period, its process group |
| 18725 | is killed and the message is frozen. A value of zero time specifies no |
| 18726 | timeout. |
| 18727 | |
| 18728 | |
| 18729 | The standard output of the command is connected to a pipe, which is read when |
| 18730 | the command terminates. It should consist of a single line of output, |
| 18731 | containing up to five fields, separated by white space. The maximum length of |
| 18732 | the line is 1023 characters. Longer lines are silently truncated. The first |
| 18733 | field is one of the following words (case-insensitive): |
| 18734 | |
| 18735 | .ilist |
| 18736 | &'Accept'&: routing succeeded; the remaining fields specify what to do (see |
| 18737 | below). |
| 18738 | .next |
| 18739 | &'Decline'&: the router declines; pass the address to the next router, unless |
| 18740 | &%no_more%& is set. |
| 18741 | .next |
| 18742 | &'Fail'&: routing failed; do not pass the address to any more routers. Any |
| 18743 | subsequent text on the line is an error message. If the router is run as part |
| 18744 | of address verification during an incoming SMTP message, the message is |
| 18745 | included in the SMTP response. |
| 18746 | .next |
| 18747 | &'Defer'&: routing could not be completed at this time; try again later. Any |
| 18748 | subsequent text on the line is an error message which is logged. It is not |
| 18749 | included in any SMTP response. |
| 18750 | .next |
| 18751 | &'Freeze'&: the same as &'defer'&, except that the message is frozen. |
| 18752 | .next |
| 18753 | &'Pass'&: pass the address to the next router (or the router specified by |
| 18754 | &%pass_router%&), overriding &%no_more%&. |
| 18755 | .next |
| 18756 | &'Redirect'&: the message is redirected. The remainder of the line is a list of |
| 18757 | new addresses, which are routed independently, starting with the first router, |
| 18758 | or the router specified by &%redirect_router%&, if set. |
| 18759 | .endlist |
| 18760 | |
| 18761 | When the first word is &'accept'&, the remainder of the line consists of a |
| 18762 | number of keyed data values, as follows (split into two lines here, to fit on |
| 18763 | the page): |
| 18764 | .code |
| 18765 | ACCEPT TRANSPORT=<transport> HOSTS=<list of hosts> |
| 18766 | LOOKUP=byname|bydns DATA=<text> |
| 18767 | .endd |
| 18768 | The data items can be given in any order, and all are optional. If no transport |
| 18769 | is included, the transport specified by the generic &%transport%& option is |
| 18770 | used. The list of hosts and the lookup type are needed only if the transport is |
| 18771 | an &(smtp)& transport that does not itself supply a list of hosts. |
| 18772 | |
| 18773 | The format of the list of hosts is the same as for the &(manualroute)& router. |
| 18774 | As well as host names and IP addresses with optional port numbers, as described |
| 18775 | in section &<<SECTformatonehostitem>>&, it may contain names followed by |
| 18776 | &`/MX`& to specify sublists of hosts that are obtained by looking up MX records |
| 18777 | (see section &<<SECThostshowused>>&). |
| 18778 | |
| 18779 | If the lookup type is not specified, Exim behaves as follows when trying to |
| 18780 | find an IP address for each host: First, a DNS lookup is done. If this yields |
| 18781 | anything other than HOST_NOT_FOUND, that result is used. Otherwise, Exim |
| 18782 | goes on to try a call to &[getipnodebyname()]& or &[gethostbyname()]&, and the |
| 18783 | result of the lookup is the result of that call. |
| 18784 | |
| 18785 | .vindex "&$address_data$&" |
| 18786 | If the DATA field is set, its value is placed in the &$address_data$& |
| 18787 | variable. For example, this return line |
| 18788 | .code |
| 18789 | accept hosts=x1.y.example:x2.y.example data="rule1" |
| 18790 | .endd |
| 18791 | routes the address to the default transport, passing a list of two hosts. When |
| 18792 | the transport runs, the string &"rule1"& is in &$address_data$&. |
| 18793 | .ecindex IIDquerou1 |
| 18794 | .ecindex IIDquerou2 |
| 18795 | |
| 18796 | |
| 18797 | |
| 18798 | |
| 18799 | . //////////////////////////////////////////////////////////////////////////// |
| 18800 | . //////////////////////////////////////////////////////////////////////////// |
| 18801 | |
| 18802 | .chapter "The redirect router" "CHAPredirect" |
| 18803 | .scindex IIDredrou1 "&(redirect)& router" |
| 18804 | .scindex IIDredrou2 "routers" "&(redirect)&" |
| 18805 | .cindex "alias file" "in a &(redirect)& router" |
| 18806 | .cindex "address redirection" "&(redirect)& router" |
| 18807 | The &(redirect)& router handles several kinds of address redirection. Its most |
| 18808 | common uses are for resolving local part aliases from a central alias file |
| 18809 | (usually called &_/etc/aliases_&) and for handling users' personal &_.forward_& |
| 18810 | files, but it has many other potential uses. The incoming address can be |
| 18811 | redirected in several different ways: |
| 18812 | |
| 18813 | .ilist |
| 18814 | It can be replaced by one or more new addresses which are themselves routed |
| 18815 | independently. |
| 18816 | .next |
| 18817 | It can be routed to be delivered to a given file or directory. |
| 18818 | .next |
| 18819 | It can be routed to be delivered to a specified pipe command. |
| 18820 | .next |
| 18821 | It can cause an automatic reply to be generated. |
| 18822 | .next |
| 18823 | It can be forced to fail, optionally with a custom error message. |
| 18824 | .next |
| 18825 | It can be temporarily deferred, optionally with a custom message. |
| 18826 | .next |
| 18827 | It can be discarded. |
| 18828 | .endlist |
| 18829 | |
| 18830 | The generic &%transport%& option must not be set for &(redirect)& routers. |
| 18831 | However, there are some private options which define transports for delivery to |
| 18832 | files and pipes, and for generating autoreplies. See the &%file_transport%&, |
| 18833 | &%pipe_transport%& and &%reply_transport%& descriptions below. |
| 18834 | |
| 18835 | |
| 18836 | |
| 18837 | .section "Redirection data" "SECID124" |
| 18838 | The router operates by interpreting a text string which it obtains either by |
| 18839 | expanding the contents of the &%data%& option, or by reading the entire |
| 18840 | contents of a file whose name is given in the &%file%& option. These two |
| 18841 | options are mutually exclusive. The first is commonly used for handling system |
| 18842 | aliases, in a configuration like this: |
| 18843 | .code |
| 18844 | system_aliases: |
| 18845 | driver = redirect |
| 18846 | data = ${lookup{$local_part}lsearch{/etc/aliases}} |
| 18847 | .endd |
| 18848 | If the lookup fails, the expanded string in this example is empty. When the |
| 18849 | expansion of &%data%& results in an empty string, the router declines. A forced |
| 18850 | expansion failure also causes the router to decline; other expansion failures |
| 18851 | cause delivery to be deferred. |
| 18852 | |
| 18853 | A configuration using &%file%& is commonly used for handling users' |
| 18854 | &_.forward_& files, like this: |
| 18855 | .code |
| 18856 | userforward: |
| 18857 | driver = redirect |
| 18858 | check_local_user |
| 18859 | file = $home/.forward |
| 18860 | no_verify |
| 18861 | .endd |
| 18862 | If the file does not exist, or causes no action to be taken (for example, it is |
| 18863 | empty or consists only of comments), the router declines. &*Warning*&: This |
| 18864 | is not the case when the file contains syntactically valid items that happen to |
| 18865 | yield empty addresses, for example, items containing only RFC 2822 address |
| 18866 | comments. |
| 18867 | |
| 18868 | |
| 18869 | |
| 18870 | .section "Forward files and address verification" "SECID125" |
| 18871 | .cindex "address redirection" "while verifying" |
| 18872 | It is usual to set &%no_verify%& on &(redirect)& routers which handle users' |
| 18873 | &_.forward_& files, as in the example above. There are two reasons for this: |
| 18874 | |
| 18875 | .ilist |
| 18876 | When Exim is receiving an incoming SMTP message from a remote host, it is |
| 18877 | running under the Exim uid, not as root. Exim is unable to change uid to read |
| 18878 | the file as the user, and it may not be able to read it as the Exim user. So in |
| 18879 | practice the router may not be able to operate. |
| 18880 | .next |
| 18881 | However, even when the router can operate, the existence of a &_.forward_& file |
| 18882 | is unimportant when verifying an address. What should be checked is whether the |
| 18883 | local part is a valid user name or not. Cutting out the redirection processing |
| 18884 | saves some resources. |
| 18885 | .endlist |
| 18886 | |
| 18887 | |
| 18888 | |
| 18889 | |
| 18890 | |
| 18891 | |
| 18892 | .section "Interpreting redirection data" "SECID126" |
| 18893 | .cindex "Sieve filter" "specifying in redirection data" |
| 18894 | .cindex "filter" "specifying in redirection data" |
| 18895 | The contents of the data string, whether obtained from &%data%& or &%file%&, |
| 18896 | can be interpreted in two different ways: |
| 18897 | |
| 18898 | .ilist |
| 18899 | If the &%allow_filter%& option is set true, and the data begins with the text |
| 18900 | &"#Exim filter"& or &"#Sieve filter"&, it is interpreted as a list of |
| 18901 | &'filtering'& instructions in the form of an Exim or Sieve filter file, |
| 18902 | respectively. Details of the syntax and semantics of filter files are described |
| 18903 | in a separate document entitled &'Exim's interfaces to mail filtering'&; this |
| 18904 | document is intended for use by end users. |
| 18905 | .next |
| 18906 | Otherwise, the data must be a comma-separated list of redirection items, as |
| 18907 | described in the next section. |
| 18908 | .endlist |
| 18909 | |
| 18910 | When a message is redirected to a file (a &"mail folder"&), the file name given |
| 18911 | in a non-filter redirection list must always be an absolute path. A filter may |
| 18912 | generate a relative path &-- how this is handled depends on the transport's |
| 18913 | configuration. See section &<<SECTfildiropt>>& for a discussion of this issue |
| 18914 | for the &(appendfile)& transport. |
| 18915 | |
| 18916 | |
| 18917 | |
| 18918 | .section "Items in a non-filter redirection list" "SECTitenonfilred" |
| 18919 | .cindex "address redirection" "non-filter list items" |
| 18920 | When the redirection data is not an Exim or Sieve filter, for example, if it |
| 18921 | comes from a conventional alias or forward file, it consists of a list of |
| 18922 | addresses, file names, pipe commands, or certain special items (see section |
| 18923 | &<<SECTspecitredli>>& below). The special items can be individually enabled or |
| 18924 | disabled by means of options whose names begin with &%allow_%& or &%forbid_%&, |
| 18925 | depending on their default values. The items in the list are separated by |
| 18926 | commas or newlines. |
| 18927 | If a comma is required in an item, the entire item must be enclosed in double |
| 18928 | quotes. |
| 18929 | |
| 18930 | Lines starting with a # character are comments, and are ignored, and # may |
| 18931 | also appear following a comma, in which case everything between the # and the |
| 18932 | next newline character is ignored. |
| 18933 | |
| 18934 | If an item is entirely enclosed in double quotes, these are removed. Otherwise |
| 18935 | double quotes are retained because some forms of mail address require their use |
| 18936 | (but never to enclose the entire address). In the following description, |
| 18937 | &"item"& refers to what remains after any surrounding double quotes have been |
| 18938 | removed. |
| 18939 | |
| 18940 | .vindex "&$local_part$&" |
| 18941 | &*Warning*&: If you use an Exim expansion to construct a redirection address, |
| 18942 | and the expansion contains a reference to &$local_part$&, you should make use |
| 18943 | of the &%quote_local_part%& expansion operator, in case the local part contains |
| 18944 | special characters. For example, to redirect all mail for the domain |
| 18945 | &'obsolete.example'&, retaining the existing local part, you could use this |
| 18946 | setting: |
| 18947 | .code |
| 18948 | data = ${quote_local_part:$local_part}@newdomain.example |
| 18949 | .endd |
| 18950 | |
| 18951 | |
| 18952 | .section "Redirecting to a local mailbox" "SECTredlocmai" |
| 18953 | .cindex "routing" "loops in" |
| 18954 | .cindex "loop" "while routing, avoidance of" |
| 18955 | .cindex "address redirection" "to local mailbox" |
| 18956 | A redirection item may safely be the same as the address currently under |
| 18957 | consideration. This does not cause a routing loop, because a router is |
| 18958 | automatically skipped if any ancestor of the address that is being processed |
| 18959 | is the same as the current address and was processed by the current router. |
| 18960 | Such an address is therefore passed to the following routers, so it is handled |
| 18961 | as if there were no redirection. When making this loop-avoidance test, the |
| 18962 | complete local part, including any prefix or suffix, is used. |
| 18963 | |
| 18964 | .cindex "address redirection" "local part without domain" |
| 18965 | Specifying the same local part without a domain is a common usage in personal |
| 18966 | filter files when the user wants to have messages delivered to the local |
| 18967 | mailbox and also forwarded elsewhere. For example, the user whose login is |
| 18968 | &'cleo'& might have a &_.forward_& file containing this: |
| 18969 | .code |
| 18970 | cleo, cleopatra@egypt.example |
| 18971 | .endd |
| 18972 | .cindex "backslash in alias file" |
| 18973 | .cindex "alias file" "backslash in" |
| 18974 | For compatibility with other MTAs, such unqualified local parts may be |
| 18975 | preceded by &"\"&, but this is not a requirement for loop prevention. However, |
| 18976 | it does make a difference if more than one domain is being handled |
| 18977 | synonymously. |
| 18978 | |
| 18979 | If an item begins with &"\"& and the rest of the item parses as a valid RFC |
| 18980 | 2822 address that does not include a domain, the item is qualified using the |
| 18981 | domain of the incoming address. In the absence of a leading &"\"&, unqualified |
| 18982 | addresses are qualified using the value in &%qualify_recipient%&, but you can |
| 18983 | force the incoming domain to be used by setting &%qualify_preserve_domain%&. |
| 18984 | |
| 18985 | Care must be taken if there are alias names for local users. |
| 18986 | Consider an MTA handling a single local domain where the system alias file |
| 18987 | contains: |
| 18988 | .code |
| 18989 | Sam.Reman: spqr |
| 18990 | .endd |
| 18991 | Now suppose that Sam (whose login id is &'spqr'&) wants to save copies of |
| 18992 | messages in the local mailbox, and also forward copies elsewhere. He creates |
| 18993 | this forward file: |
| 18994 | .code |
| 18995 | Sam.Reman, spqr@reme.elsewhere.example |
| 18996 | .endd |
| 18997 | With these settings, an incoming message addressed to &'Sam.Reman'& fails. The |
| 18998 | &(redirect)& router for system aliases does not process &'Sam.Reman'& the |
| 18999 | second time round, because it has previously routed it, |
| 19000 | and the following routers presumably cannot handle the alias. The forward file |
| 19001 | should really contain |
| 19002 | .code |
| 19003 | spqr, spqr@reme.elsewhere.example |
| 19004 | .endd |
| 19005 | but because this is such a common error, the &%check_ancestor%& option (see |
| 19006 | below) exists to provide a way to get round it. This is normally set on a |
| 19007 | &(redirect)& router that is handling users' &_.forward_& files. |
| 19008 | |
| 19009 | |
| 19010 | |
| 19011 | .section "Special items in redirection lists" "SECTspecitredli" |
| 19012 | In addition to addresses, the following types of item may appear in redirection |
| 19013 | lists (that is, in non-filter redirection data): |
| 19014 | |
| 19015 | .ilist |
| 19016 | .cindex "pipe" "in redirection list" |
| 19017 | .cindex "address redirection" "to pipe" |
| 19018 | An item is treated as a pipe command if it begins with &"|"& and does not parse |
| 19019 | as a valid RFC 2822 address that includes a domain. A transport for running the |
| 19020 | command must be specified by the &%pipe_transport%& option. |
| 19021 | Normally, either the router or the transport specifies a user and a group under |
| 19022 | which to run the delivery. The default is to use the Exim user and group. |
| 19023 | |
| 19024 | Single or double quotes can be used for enclosing the individual arguments of |
| 19025 | the pipe command; no interpretation of escapes is done for single quotes. If |
| 19026 | the command contains a comma character, it is necessary to put the whole item |
| 19027 | in double quotes, for example: |
| 19028 | .code |
| 19029 | "|/some/command ready,steady,go" |
| 19030 | .endd |
| 19031 | since items in redirection lists are terminated by commas. Do not, however, |
| 19032 | quote just the command. An item such as |
| 19033 | .code |
| 19034 | |"/some/command ready,steady,go" |
| 19035 | .endd |
| 19036 | is interpreted as a pipe with a rather strange command name, and no arguments. |
| 19037 | |
| 19038 | Note that the above example assumes that the text comes from a lookup source |
| 19039 | of some sort, so that the quotes are part of the data. If composing a |
| 19040 | redirect router with a &%data%& option directly specifying this command, the |
| 19041 | quotes will be used by the configuration parser to define the extent of one |
| 19042 | string, but will not be passed down into the redirect router itself. There |
| 19043 | are two main approaches to get around this: escape quotes to be part of the |
| 19044 | data itself, or avoid using this mechanism and instead create a custom |
| 19045 | transport with the &%command%& option set and reference that transport from |
| 19046 | an &%accept%& router. |
| 19047 | |
| 19048 | .next |
| 19049 | .cindex "file" "in redirection list" |
| 19050 | .cindex "address redirection" "to file" |
| 19051 | An item is interpreted as a path name if it begins with &"/"& and does not |
| 19052 | parse as a valid RFC 2822 address that includes a domain. For example, |
| 19053 | .code |
| 19054 | /home/world/minbari |
| 19055 | .endd |
| 19056 | is treated as a file name, but |
| 19057 | .code |
| 19058 | /s=molari/o=babylon/@x400gate.way |
| 19059 | .endd |
| 19060 | is treated as an address. For a file name, a transport must be specified using |
| 19061 | the &%file_transport%& option. However, if the generated path name ends with a |
| 19062 | forward slash character, it is interpreted as a directory name rather than a |
| 19063 | file name, and &%directory_transport%& is used instead. |
| 19064 | |
| 19065 | Normally, either the router or the transport specifies a user and a group under |
| 19066 | which to run the delivery. The default is to use the Exim user and group. |
| 19067 | |
| 19068 | .cindex "&_/dev/null_&" |
| 19069 | However, if a redirection item is the path &_/dev/null_&, delivery to it is |
| 19070 | bypassed at a high level, and the log entry shows &"**bypassed**"& |
| 19071 | instead of a transport name. In this case the user and group are not used. |
| 19072 | |
| 19073 | .next |
| 19074 | .cindex "included address list" |
| 19075 | .cindex "address redirection" "included external list" |
| 19076 | If an item is of the form |
| 19077 | .code |
| 19078 | :include:<path name> |
| 19079 | .endd |
| 19080 | a list of further items is taken from the given file and included at that |
| 19081 | point. &*Note*&: Such a file can not be a filter file; it is just an |
| 19082 | out-of-line addition to the list. The items in the included list are separated |
| 19083 | by commas or newlines and are not subject to expansion. If this is the first |
| 19084 | item in an alias list in an &(lsearch)& file, a colon must be used to terminate |
| 19085 | the alias name. This example is incorrect: |
| 19086 | .code |
| 19087 | list1 :include:/opt/lists/list1 |
| 19088 | .endd |
| 19089 | It must be given as |
| 19090 | .code |
| 19091 | list1: :include:/opt/lists/list1 |
| 19092 | .endd |
| 19093 | .next |
| 19094 | .cindex "address redirection" "to black hole" |
| 19095 | Sometimes you want to throw away mail to a particular local part. Making the |
| 19096 | &%data%& option expand to an empty string does not work, because that causes |
| 19097 | the router to decline. Instead, the alias item |
| 19098 | .cindex "black hole" |
| 19099 | .cindex "abandoning mail" |
| 19100 | &':blackhole:'& can be used. It does what its name implies. No delivery is |
| 19101 | done, and no error message is generated. This has the same effect as specifing |
| 19102 | &_/dev/null_& as a destination, but it can be independently disabled. |
| 19103 | |
| 19104 | &*Warning*&: If &':blackhole:'& appears anywhere in a redirection list, no |
| 19105 | delivery is done for the original local part, even if other redirection items |
| 19106 | are present. If you are generating a multi-item list (for example, by reading a |
| 19107 | database) and need the ability to provide a no-op item, you must use |
| 19108 | &_/dev/null_&. |
| 19109 | |
| 19110 | .next |
| 19111 | .cindex "delivery" "forcing failure" |
| 19112 | .cindex "delivery" "forcing deferral" |
| 19113 | .cindex "failing delivery" "forcing" |
| 19114 | .cindex "deferred delivery, forcing" |
| 19115 | .cindex "customizing" "failure message" |
| 19116 | An attempt to deliver a particular address can be deferred or forced to fail by |
| 19117 | redirection items of the form |
| 19118 | .code |
| 19119 | :defer: |
| 19120 | :fail: |
| 19121 | .endd |
| 19122 | respectively. When a redirection list contains such an item, it applies |
| 19123 | to the entire redirection; any other items in the list are ignored. Any |
| 19124 | text following &':fail:'& or &':defer:'& is placed in the error text |
| 19125 | associated with the failure. For example, an alias file might contain: |
| 19126 | .code |
| 19127 | X.Employee: :fail: Gone away, no forwarding address |
| 19128 | .endd |
| 19129 | In the case of an address that is being verified from an ACL or as the subject |
| 19130 | of a |
| 19131 | .cindex "VRFY" "error text, display of" |
| 19132 | VRFY command, the text is included in the SMTP error response by |
| 19133 | default. |
| 19134 | .cindex "EXPN" "error text, display of" |
| 19135 | The text is not included in the response to an EXPN command. In non-SMTP cases |
| 19136 | the text is included in the error message that Exim generates. |
| 19137 | |
| 19138 | .cindex "SMTP" "error codes" |
| 19139 | By default, Exim sends a 451 SMTP code for a &':defer:'&, and 550 for |
| 19140 | &':fail:'&. However, if the message starts with three digits followed by a |
| 19141 | space, optionally followed by an extended code of the form &'n.n.n'&, also |
| 19142 | followed by a space, and the very first digit is the same as the default error |
| 19143 | code, the code from the message is used instead. If the very first digit is |
| 19144 | incorrect, a panic error is logged, and the default code is used. You can |
| 19145 | suppress the use of the supplied code in a redirect router by setting the |
| 19146 | &%forbid_smtp_code%& option true. In this case, any SMTP code is quietly |
| 19147 | ignored. |
| 19148 | |
| 19149 | .vindex "&$acl_verify_message$&" |
| 19150 | In an ACL, an explicitly provided message overrides the default, but the |
| 19151 | default message is available in the variable &$acl_verify_message$& and can |
| 19152 | therefore be included in a custom message if this is desired. |
| 19153 | |
| 19154 | Normally the error text is the rest of the redirection list &-- a comma does |
| 19155 | not terminate it &-- but a newline does act as a terminator. Newlines are not |
| 19156 | normally present in alias expansions. In &(lsearch)& lookups they are removed |
| 19157 | as part of the continuation process, but they may exist in other kinds of |
| 19158 | lookup and in &':include:'& files. |
| 19159 | |
| 19160 | During routing for message delivery (as opposed to verification), a redirection |
| 19161 | containing &':fail:'& causes an immediate failure of the incoming address, |
| 19162 | whereas &':defer:'& causes the message to remain on the queue so that a |
| 19163 | subsequent delivery attempt can happen at a later time. If an address is |
| 19164 | deferred for too long, it will ultimately fail, because the normal retry |
| 19165 | rules still apply. |
| 19166 | |
| 19167 | .next |
| 19168 | .cindex "alias file" "exception to default" |
| 19169 | Sometimes it is useful to use a single-key search type with a default (see |
| 19170 | chapter &<<CHAPfdlookup>>&) to look up aliases. However, there may be a need |
| 19171 | for exceptions to the default. These can be handled by aliasing them to |
| 19172 | &':unknown:'&. This differs from &':fail:'& in that it causes the &(redirect)& |
| 19173 | router to decline, whereas &':fail:'& forces routing to fail. A lookup which |
| 19174 | results in an empty redirection list has the same effect. |
| 19175 | .endlist |
| 19176 | |
| 19177 | |
| 19178 | .section "Duplicate addresses" "SECTdupaddr" |
| 19179 | .cindex "duplicate addresses" |
| 19180 | .cindex "address duplicate, discarding" |
| 19181 | .cindex "pipe" "duplicated" |
| 19182 | Exim removes duplicate addresses from the list to which it is delivering, so as |
| 19183 | to deliver just one copy to each address. This does not apply to deliveries |
| 19184 | routed to pipes by different immediate parent addresses, but an indirect |
| 19185 | aliasing scheme of the type |
| 19186 | .code |
| 19187 | pipe: |/some/command $local_part |
| 19188 | localpart1: pipe |
| 19189 | localpart2: pipe |
| 19190 | .endd |
| 19191 | does not work with a message that is addressed to both local parts, because |
| 19192 | when the second is aliased to the intermediate local part &"pipe"& it gets |
| 19193 | discarded as being the same as a previously handled address. However, a scheme |
| 19194 | such as |
| 19195 | .code |
| 19196 | localpart1: |/some/command $local_part |
| 19197 | localpart2: |/some/command $local_part |
| 19198 | .endd |
| 19199 | does result in two different pipe deliveries, because the immediate parents of |
| 19200 | the pipes are distinct. |
| 19201 | |
| 19202 | |
| 19203 | |
| 19204 | .section "Repeated redirection expansion" "SECID128" |
| 19205 | .cindex "repeated redirection expansion" |
| 19206 | .cindex "address redirection" "repeated for each delivery attempt" |
| 19207 | When a message cannot be delivered to all of its recipients immediately, |
| 19208 | leading to two or more delivery attempts, redirection expansion is carried out |
| 19209 | afresh each time for those addresses whose children were not all previously |
| 19210 | delivered. If redirection is being used as a mailing list, this can lead to new |
| 19211 | members of the list receiving copies of old messages. The &%one_time%& option |
| 19212 | can be used to avoid this. |
| 19213 | |
| 19214 | |
| 19215 | .section "Errors in redirection lists" "SECID129" |
| 19216 | .cindex "address redirection" "errors" |
| 19217 | If &%skip_syntax_errors%& is set, a malformed address that causes a parsing |
| 19218 | error is skipped, and an entry is written to the main log. This may be useful |
| 19219 | for mailing lists that are automatically managed. Otherwise, if an error is |
| 19220 | detected while generating the list of new addresses, the original address is |
| 19221 | deferred. See also &%syntax_errors_to%&. |
| 19222 | |
| 19223 | |
| 19224 | |
| 19225 | .section "Private options for the redirect router" "SECID130" |
| 19226 | |
| 19227 | .cindex "options" "&(redirect)& router" |
| 19228 | The private options for the &(redirect)& router are as follows: |
| 19229 | |
| 19230 | |
| 19231 | .option allow_defer redirect boolean false |
| 19232 | Setting this option allows the use of &':defer:'& in non-filter redirection |
| 19233 | data, or the &%defer%& command in an Exim filter file. |
| 19234 | |
| 19235 | |
| 19236 | .option allow_fail redirect boolean false |
| 19237 | .cindex "failing delivery" "from filter" |
| 19238 | If this option is true, the &':fail:'& item can be used in a redirection list, |
| 19239 | and the &%fail%& command may be used in an Exim filter file. |
| 19240 | |
| 19241 | |
| 19242 | .option allow_filter redirect boolean false |
| 19243 | .cindex "filter" "enabling use of" |
| 19244 | .cindex "Sieve filter" "enabling use of" |
| 19245 | Setting this option allows Exim to interpret redirection data that starts with |
| 19246 | &"#Exim filter"& or &"#Sieve filter"& as a set of filtering instructions. There |
| 19247 | are some features of Exim filter files that some administrators may wish to |
| 19248 | lock out; see the &%forbid_filter_%&&'xxx'& options below. |
| 19249 | |
| 19250 | It is also possible to lock out Exim filters or Sieve filters while allowing |
| 19251 | the other type; see &%forbid_exim_filter%& and &%forbid_sieve_filter%&. |
| 19252 | |
| 19253 | |
| 19254 | The filter is run using the uid and gid set by the generic &%user%& and |
| 19255 | &%group%& options. These take their defaults from the password data if |
| 19256 | &%check_local_user%& is set, so in the normal case of users' personal filter |
| 19257 | files, the filter is run as the relevant user. When &%allow_filter%& is set |
| 19258 | true, Exim insists that either &%check_local_user%& or &%user%& is set. |
| 19259 | |
| 19260 | |
| 19261 | |
| 19262 | .option allow_freeze redirect boolean false |
| 19263 | .cindex "freezing messages" "allowing in filter" |
| 19264 | Setting this option allows the use of the &%freeze%& command in an Exim filter. |
| 19265 | This command is more normally encountered in system filters, and is disabled by |
| 19266 | default for redirection filters because it isn't something you usually want to |
| 19267 | let ordinary users do. |
| 19268 | |
| 19269 | |
| 19270 | |
| 19271 | .option check_ancestor redirect boolean false |
| 19272 | This option is concerned with handling generated addresses that are the same |
| 19273 | as some address in the list of redirection ancestors of the current address. |
| 19274 | Although it is turned off by default in the code, it is set in the default |
| 19275 | configuration file for handling users' &_.forward_& files. It is recommended |
| 19276 | for this use of the &(redirect)& router. |
| 19277 | |
| 19278 | When &%check_ancestor%& is set, if a generated address (including the domain) |
| 19279 | is the same as any ancestor of the current address, it is replaced by a copy of |
| 19280 | the current address. This helps in the case where local part A is aliased to B, |
| 19281 | and B has a &_.forward_& file pointing back to A. For example, within a single |
| 19282 | domain, the local part &"Joe.Bloggs"& is aliased to &"jb"& and |
| 19283 | &_&~jb/.forward_& contains: |
| 19284 | .code |
| 19285 | \Joe.Bloggs, <other item(s)> |
| 19286 | .endd |
| 19287 | Without the &%check_ancestor%& setting, either local part (&"jb"& or |
| 19288 | &"joe.bloggs"&) gets processed once by each router and so ends up as it was |
| 19289 | originally. If &"jb"& is the real mailbox name, mail to &"jb"& gets delivered |
| 19290 | (having been turned into &"joe.bloggs"& by the &_.forward_& file and back to |
| 19291 | &"jb"& by the alias), but mail to &"joe.bloggs"& fails. Setting |
| 19292 | &%check_ancestor%& on the &(redirect)& router that handles the &_.forward_& |
| 19293 | file prevents it from turning &"jb"& back into &"joe.bloggs"& when that was the |
| 19294 | original address. See also the &%repeat_use%& option below. |
| 19295 | |
| 19296 | |
| 19297 | .option check_group redirect boolean "see below" |
| 19298 | When the &%file%& option is used, the group owner of the file is checked only |
| 19299 | when this option is set. The permitted groups are those listed in the |
| 19300 | &%owngroups%& option, together with the user's default group if |
| 19301 | &%check_local_user%& is set. If the file has the wrong group, routing is |
| 19302 | deferred. The default setting for this option is true if &%check_local_user%& |
| 19303 | is set and the &%modemask%& option permits the group write bit, or if the |
| 19304 | &%owngroups%& option is set. Otherwise it is false, and no group check occurs. |
| 19305 | |
| 19306 | |
| 19307 | |
| 19308 | .option check_owner redirect boolean "see below" |
| 19309 | When the &%file%& option is used, the owner of the file is checked only when |
| 19310 | this option is set. If &%check_local_user%& is set, the local user is |
| 19311 | permitted; otherwise the owner must be one of those listed in the &%owners%& |
| 19312 | option. The default value for this option is true if &%check_local_user%& or |
| 19313 | &%owners%& is set. Otherwise the default is false, and no owner check occurs. |
| 19314 | |
| 19315 | |
| 19316 | .option data redirect string&!! unset |
| 19317 | This option is mutually exclusive with &%file%&. One or other of them must be |
| 19318 | set, but not both. The contents of &%data%& are expanded, and then used as the |
| 19319 | list of forwarding items, or as a set of filtering instructions. If the |
| 19320 | expansion is forced to fail, or the result is an empty string or a string that |
| 19321 | has no effect (consists entirely of comments), the router declines. |
| 19322 | |
| 19323 | When filtering instructions are used, the string must begin with &"#Exim |
| 19324 | filter"&, and all comments in the string, including this initial one, must be |
| 19325 | terminated with newline characters. For example: |
| 19326 | .code |
| 19327 | data = #Exim filter\n\ |
| 19328 | if $h_to: contains Exim then save $home/mail/exim endif |
| 19329 | .endd |
| 19330 | If you are reading the data from a database where newlines cannot be included, |
| 19331 | you can use the &${sg}$& expansion item to turn the escape string of your |
| 19332 | choice into a newline. |
| 19333 | |
| 19334 | |
| 19335 | .option directory_transport redirect string&!! unset |
| 19336 | A &(redirect)& router sets up a direct delivery to a directory when a path name |
| 19337 | ending with a slash is specified as a new &"address"&. The transport used is |
| 19338 | specified by this option, which, after expansion, must be the name of a |
| 19339 | configured transport. This should normally be an &(appendfile)& transport. |
| 19340 | |
| 19341 | |
| 19342 | .option file redirect string&!! unset |
| 19343 | This option specifies the name of a file that contains the redirection data. It |
| 19344 | is mutually exclusive with the &%data%& option. The string is expanded before |
| 19345 | use; if the expansion is forced to fail, the router declines. Other expansion |
| 19346 | failures cause delivery to be deferred. The result of a successful expansion |
| 19347 | must be an absolute path. The entire file is read and used as the redirection |
| 19348 | data. If the data is an empty string or a string that has no effect (consists |
| 19349 | entirely of comments), the router declines. |
| 19350 | |
| 19351 | .cindex "NFS" "checking for file existence" |
| 19352 | If the attempt to open the file fails with a &"does not exist"& error, Exim |
| 19353 | runs a check on the containing directory, |
| 19354 | unless &%ignore_enotdir%& is true (see below). |
| 19355 | If the directory does not appear to exist, delivery is deferred. This can |
| 19356 | happen when users' &_.forward_& files are in NFS-mounted directories, and there |
| 19357 | is a mount problem. If the containing directory does exist, but the file does |
| 19358 | not, the router declines. |
| 19359 | |
| 19360 | |
| 19361 | .option file_transport redirect string&!! unset |
| 19362 | .vindex "&$address_file$&" |
| 19363 | A &(redirect)& router sets up a direct delivery to a file when a path name not |
| 19364 | ending in a slash is specified as a new &"address"&. The transport used is |
| 19365 | specified by this option, which, after expansion, must be the name of a |
| 19366 | configured transport. This should normally be an &(appendfile)& transport. When |
| 19367 | it is running, the file name is in &$address_file$&. |
| 19368 | |
| 19369 | |
| 19370 | .option filter_prepend_home redirect boolean true |
| 19371 | When this option is true, if a &(save)& command in an Exim filter specifies a |
| 19372 | relative path, and &$home$& is defined, it is automatically prepended to the |
| 19373 | relative path. If this option is set false, this action does not happen. The |
| 19374 | relative path is then passed to the transport unmodified. |
| 19375 | |
| 19376 | |
| 19377 | .option forbid_blackhole redirect boolean false |
| 19378 | If this option is true, the &':blackhole:'& item may not appear in a |
| 19379 | redirection list. |
| 19380 | |
| 19381 | |
| 19382 | .option forbid_exim_filter redirect boolean false |
| 19383 | If this option is set true, only Sieve filters are permitted when |
| 19384 | &%allow_filter%& is true. |
| 19385 | |
| 19386 | |
| 19387 | |
| 19388 | |
| 19389 | .option forbid_file redirect boolean false |
| 19390 | .cindex "delivery" "to file; forbidding" |
| 19391 | .cindex "Sieve filter" "forbidding delivery to a file" |
| 19392 | .cindex "Sieve filter" "&""keep""& facility; disabling" |
| 19393 | If this option is true, this router may not generate a new address that |
| 19394 | specifies delivery to a local file or directory, either from a filter or from a |
| 19395 | conventional forward file. This option is forced to be true if &%one_time%& is |
| 19396 | set. It applies to Sieve filters as well as to Exim filters, but if true, it |
| 19397 | locks out the Sieve's &"keep"& facility. |
| 19398 | |
| 19399 | |
| 19400 | .option forbid_filter_dlfunc redirect boolean false |
| 19401 | .cindex "filter" "locking out certain features" |
| 19402 | If this option is true, string expansions in Exim filters are not allowed to |
| 19403 | make use of the &%dlfunc%& expansion facility to run dynamically loaded |
| 19404 | functions. |
| 19405 | |
| 19406 | .option forbid_filter_existstest redirect boolean false |
| 19407 | .cindex "expansion" "statting a file" |
| 19408 | If this option is true, string expansions in Exim filters are not allowed to |
| 19409 | make use of the &%exists%& condition or the &%stat%& expansion item. |
| 19410 | |
| 19411 | .option forbid_filter_logwrite redirect boolean false |
| 19412 | If this option is true, use of the logging facility in Exim filters is not |
| 19413 | permitted. Logging is in any case available only if the filter is being run |
| 19414 | under some unprivileged uid (which is normally the case for ordinary users' |
| 19415 | &_.forward_& files). |
| 19416 | |
| 19417 | |
| 19418 | .option forbid_filter_lookup redirect boolean false |
| 19419 | If this option is true, string expansions in Exim filter files are not allowed |
| 19420 | to make use of &%lookup%& items. |
| 19421 | |
| 19422 | |
| 19423 | .option forbid_filter_perl redirect boolean false |
| 19424 | This option has an effect only if Exim is built with embedded Perl support. If |
| 19425 | it is true, string expansions in Exim filter files are not allowed to make use |
| 19426 | of the embedded Perl support. |
| 19427 | |
| 19428 | |
| 19429 | .option forbid_filter_readfile redirect boolean false |
| 19430 | If this option is true, string expansions in Exim filter files are not allowed |
| 19431 | to make use of &%readfile%& items. |
| 19432 | |
| 19433 | |
| 19434 | .option forbid_filter_readsocket redirect boolean false |
| 19435 | If this option is true, string expansions in Exim filter files are not allowed |
| 19436 | to make use of &%readsocket%& items. |
| 19437 | |
| 19438 | |
| 19439 | .option forbid_filter_reply redirect boolean false |
| 19440 | If this option is true, this router may not generate an automatic reply |
| 19441 | message. Automatic replies can be generated only from Exim or Sieve filter |
| 19442 | files, not from traditional forward files. This option is forced to be true if |
| 19443 | &%one_time%& is set. |
| 19444 | |
| 19445 | |
| 19446 | .option forbid_filter_run redirect boolean false |
| 19447 | If this option is true, string expansions in Exim filter files are not allowed |
| 19448 | to make use of &%run%& items. |
| 19449 | |
| 19450 | |
| 19451 | .option forbid_include redirect boolean false |
| 19452 | If this option is true, items of the form |
| 19453 | .code |
| 19454 | :include:<path name> |
| 19455 | .endd |
| 19456 | are not permitted in non-filter redirection lists. |
| 19457 | |
| 19458 | |
| 19459 | .option forbid_pipe redirect boolean false |
| 19460 | .cindex "delivery" "to pipe; forbidding" |
| 19461 | If this option is true, this router may not generate a new address which |
| 19462 | specifies delivery to a pipe, either from an Exim filter or from a conventional |
| 19463 | forward file. This option is forced to be true if &%one_time%& is set. |
| 19464 | |
| 19465 | |
| 19466 | .option forbid_sieve_filter redirect boolean false |
| 19467 | If this option is set true, only Exim filters are permitted when |
| 19468 | &%allow_filter%& is true. |
| 19469 | |
| 19470 | |
| 19471 | .cindex "SMTP" "error codes" |
| 19472 | .option forbid_smtp_code redirect boolean false |
| 19473 | If this option is set true, any SMTP error codes that are present at the start |
| 19474 | of messages specified for &`:defer:`& or &`:fail:`& are quietly ignored, and |
| 19475 | the default codes (451 and 550, respectively) are always used. |
| 19476 | |
| 19477 | |
| 19478 | |
| 19479 | |
| 19480 | .option hide_child_in_errmsg redirect boolean false |
| 19481 | .cindex "bounce message" "redirection details; suppressing" |
| 19482 | If this option is true, it prevents Exim from quoting a child address if it |
| 19483 | generates a bounce or delay message for it. Instead it says &"an address |
| 19484 | generated from <&'the top level address'&>"&. Of course, this applies only to |
| 19485 | bounces generated locally. If a message is forwarded to another host, &'its'& |
| 19486 | bounce may well quote the generated address. |
| 19487 | |
| 19488 | |
| 19489 | .option ignore_eacces redirect boolean false |
| 19490 | .cindex "EACCES" |
| 19491 | If this option is set and an attempt to open a redirection file yields the |
| 19492 | EACCES error (permission denied), the &(redirect)& router behaves as if the |
| 19493 | file did not exist. |
| 19494 | |
| 19495 | |
| 19496 | .option ignore_enotdir redirect boolean false |
| 19497 | .cindex "ENOTDIR" |
| 19498 | If this option is set and an attempt to open a redirection file yields the |
| 19499 | ENOTDIR error (something on the path is not a directory), the &(redirect)& |
| 19500 | router behaves as if the file did not exist. |
| 19501 | |
| 19502 | Setting &%ignore_enotdir%& has another effect as well: When a &(redirect)& |
| 19503 | router that has the &%file%& option set discovers that the file does not exist |
| 19504 | (the ENOENT error), it tries to &[stat()]& the parent directory, as a check |
| 19505 | against unmounted NFS directories. If the parent can not be statted, delivery |
| 19506 | is deferred. However, it seems wrong to do this check when &%ignore_enotdir%& |
| 19507 | is set, because that option tells Exim to ignore &"something on the path is not |
| 19508 | a directory"& (the ENOTDIR error). This is a confusing area, because it seems |
| 19509 | that some operating systems give ENOENT where others give ENOTDIR. |
| 19510 | |
| 19511 | |
| 19512 | |
| 19513 | .option include_directory redirect string unset |
| 19514 | If this option is set, the path names of any &':include:'& items in a |
| 19515 | redirection list must start with this directory. |
| 19516 | |
| 19517 | |
| 19518 | .option modemask redirect "octal integer" 022 |
| 19519 | This specifies mode bits which must not be set for a file specified by the |
| 19520 | &%file%& option. If any of the forbidden bits are set, delivery is deferred. |
| 19521 | |
| 19522 | |
| 19523 | .option one_time redirect boolean false |
| 19524 | .cindex "one-time aliasing/forwarding expansion" |
| 19525 | .cindex "alias file" "one-time expansion" |
| 19526 | .cindex "forward file" "one-time expansion" |
| 19527 | .cindex "mailing lists" "one-time expansion" |
| 19528 | .cindex "address redirection" "one-time expansion" |
| 19529 | Sometimes the fact that Exim re-evaluates aliases and reprocesses redirection |
| 19530 | files each time it tries to deliver a message causes a problem when one or more |
| 19531 | of the generated addresses fails be delivered at the first attempt. The problem |
| 19532 | is not one of duplicate delivery &-- Exim is clever enough to handle that &-- |
| 19533 | but of what happens when the redirection list changes during the time that the |
| 19534 | message is on Exim's queue. This is particularly true in the case of mailing |
| 19535 | lists, where new subscribers might receive copies of messages that were posted |
| 19536 | before they subscribed. |
| 19537 | |
| 19538 | If &%one_time%& is set and any addresses generated by the router fail to |
| 19539 | deliver at the first attempt, the failing addresses are added to the message as |
| 19540 | &"top level"& addresses, and the parent address that generated them is marked |
| 19541 | &"delivered"&. Thus, redirection does not happen again at the next delivery |
| 19542 | attempt. |
| 19543 | |
| 19544 | &*Warning 1*&: Any header line addition or removal that is specified by this |
| 19545 | router would be lost if delivery did not succeed at the first attempt. For this |
| 19546 | reason, the &%headers_add%& and &%headers_remove%& generic options are not |
| 19547 | permitted when &%one_time%& is set. |
| 19548 | |
| 19549 | &*Warning 2*&: To ensure that the router generates only addresses (as opposed |
| 19550 | to pipe or file deliveries or auto-replies) &%forbid_file%&, &%forbid_pipe%&, |
| 19551 | and &%forbid_filter_reply%& are forced to be true when &%one_time%& is set. |
| 19552 | |
| 19553 | &*Warning 3*&: The &%unseen%& generic router option may not be set with |
| 19554 | &%one_time%&. |
| 19555 | |
| 19556 | The original top-level address is remembered with each of the generated |
| 19557 | addresses, and is output in any log messages. However, any intermediate parent |
| 19558 | addresses are not recorded. This makes a difference to the log only if |
| 19559 | &%all_parents%& log selector is set. It is expected that &%one_time%& will |
| 19560 | typically be used for mailing lists, where there is normally just one level of |
| 19561 | expansion. |
| 19562 | |
| 19563 | |
| 19564 | .option owners redirect "string list" unset |
| 19565 | .cindex "ownership" "alias file" |
| 19566 | .cindex "ownership" "forward file" |
| 19567 | .cindex "alias file" "ownership" |
| 19568 | .cindex "forward file" "ownership" |
| 19569 | This specifies a list of permitted owners for the file specified by &%file%&. |
| 19570 | This list is in addition to the local user when &%check_local_user%& is set. |
| 19571 | See &%check_owner%& above. |
| 19572 | |
| 19573 | |
| 19574 | .option owngroups redirect "string list" unset |
| 19575 | This specifies a list of permitted groups for the file specified by &%file%&. |
| 19576 | The list is in addition to the local user's primary group when |
| 19577 | &%check_local_user%& is set. See &%check_group%& above. |
| 19578 | |
| 19579 | |
| 19580 | .option pipe_transport redirect string&!! unset |
| 19581 | .vindex "&$address_pipe$&" |
| 19582 | A &(redirect)& router sets up a direct delivery to a pipe when a string |
| 19583 | starting with a vertical bar character is specified as a new &"address"&. The |
| 19584 | transport used is specified by this option, which, after expansion, must be the |
| 19585 | name of a configured transport. This should normally be a &(pipe)& transport. |
| 19586 | When the transport is run, the pipe command is in &$address_pipe$&. |
| 19587 | |
| 19588 | |
| 19589 | .option qualify_domain redirect string&!! unset |
| 19590 | .vindex "&$qualify_recipient$&" |
| 19591 | If this option is set, and an unqualified address (one without a domain) is |
| 19592 | generated, and that address would normally be qualified by the global setting |
| 19593 | in &%qualify_recipient%&, it is instead qualified with the domain specified by |
| 19594 | expanding this string. If the expansion fails, the router declines. If you want |
| 19595 | to revert to the default, you can have the expansion generate |
| 19596 | &$qualify_recipient$&. |
| 19597 | |
| 19598 | This option applies to all unqualified addresses generated by Exim filters, |
| 19599 | but for traditional &_.forward_& files, it applies only to addresses that are |
| 19600 | not preceded by a backslash. Sieve filters cannot generate unqualified |
| 19601 | addresses. |
| 19602 | |
| 19603 | .option qualify_preserve_domain redirect boolean false |
| 19604 | .cindex "domain" "in redirection; preserving" |
| 19605 | .cindex "preserving domain in redirection" |
| 19606 | .cindex "address redirection" "domain; preserving" |
| 19607 | If this option is set, the router's local &%qualify_domain%& option must not be |
| 19608 | set (a configuration error occurs if it is). If an unqualified address (one |
| 19609 | without a domain) is generated, it is qualified with the domain of the parent |
| 19610 | address (the immediately preceding ancestor) instead of the global |
| 19611 | &%qualify_recipient%& value. In the case of a traditional &_.forward_& file, |
| 19612 | this applies whether or not the address is preceded by a backslash. |
| 19613 | |
| 19614 | |
| 19615 | .option repeat_use redirect boolean true |
| 19616 | If this option is set false, the router is skipped for a child address that has |
| 19617 | any ancestor that was routed by this router. This test happens before any of |
| 19618 | the other preconditions are tested. Exim's default anti-looping rules skip |
| 19619 | only when the ancestor is the same as the current address. See also |
| 19620 | &%check_ancestor%& above and the generic &%redirect_router%& option. |
| 19621 | |
| 19622 | |
| 19623 | .option reply_transport redirect string&!! unset |
| 19624 | A &(redirect)& router sets up an automatic reply when a &%mail%& or |
| 19625 | &%vacation%& command is used in a filter file. The transport used is specified |
| 19626 | by this option, which, after expansion, must be the name of a configured |
| 19627 | transport. This should normally be an &(autoreply)& transport. Other transports |
| 19628 | are unlikely to do anything sensible or useful. |
| 19629 | |
| 19630 | |
| 19631 | .option rewrite redirect boolean true |
| 19632 | .cindex "address redirection" "disabling rewriting" |
| 19633 | If this option is set false, addresses generated by the router are not |
| 19634 | subject to address rewriting. Otherwise, they are treated like new addresses |
| 19635 | and are rewritten according to the global rewriting rules. |
| 19636 | |
| 19637 | |
| 19638 | .option sieve_subaddress redirect string&!! unset |
| 19639 | The value of this option is passed to a Sieve filter to specify the |
| 19640 | :subaddress part of an address. |
| 19641 | |
| 19642 | .option sieve_useraddress redirect string&!! unset |
| 19643 | The value of this option is passed to a Sieve filter to specify the :user part |
| 19644 | of an address. However, if it is unset, the entire original local part |
| 19645 | (including any prefix or suffix) is used for :user. |
| 19646 | |
| 19647 | |
| 19648 | .option sieve_vacation_directory redirect string&!! unset |
| 19649 | .cindex "Sieve filter" "vacation directory" |
| 19650 | To enable the &"vacation"& extension for Sieve filters, you must set |
| 19651 | &%sieve_vacation_directory%& to the directory where vacation databases are held |
| 19652 | (do not put anything else in that directory), and ensure that the |
| 19653 | &%reply_transport%& option refers to an &(autoreply)& transport. Each user |
| 19654 | needs their own directory; Exim will create it if necessary. |
| 19655 | |
| 19656 | |
| 19657 | |
| 19658 | .option skip_syntax_errors redirect boolean false |
| 19659 | .cindex "forward file" "broken" |
| 19660 | .cindex "address redirection" "broken files" |
| 19661 | .cindex "alias file" "broken" |
| 19662 | .cindex "broken alias or forward files" |
| 19663 | .cindex "ignoring faulty addresses" |
| 19664 | .cindex "skipping faulty addresses" |
| 19665 | .cindex "error" "skipping bad syntax" |
| 19666 | If &%skip_syntax_errors%& is set, syntactically malformed addresses in |
| 19667 | non-filter redirection data are skipped, and each failing address is logged. If |
| 19668 | &%syntax_errors_to%& is set, a message is sent to the address it defines, |
| 19669 | giving details of the failures. If &%syntax_errors_text%& is set, its contents |
| 19670 | are expanded and placed at the head of the error message generated by |
| 19671 | &%syntax_errors_to%&. Usually it is appropriate to set &%syntax_errors_to%& to |
| 19672 | be the same address as the generic &%errors_to%& option. The |
| 19673 | &%skip_syntax_errors%& option is often used when handling mailing lists. |
| 19674 | |
| 19675 | If all the addresses in a redirection list are skipped because of syntax |
| 19676 | errors, the router declines to handle the original address, and it is passed to |
| 19677 | the following routers. |
| 19678 | |
| 19679 | If &%skip_syntax_errors%& is set when an Exim filter is interpreted, any syntax |
| 19680 | error in the filter causes filtering to be abandoned without any action being |
| 19681 | taken. The incident is logged, and the router declines to handle the address, |
| 19682 | so it is passed to the following routers. |
| 19683 | |
| 19684 | .cindex "Sieve filter" "syntax errors in" |
| 19685 | Syntax errors in a Sieve filter file cause the &"keep"& action to occur. This |
| 19686 | action is specified by RFC 3028. The values of &%skip_syntax_errors%&, |
| 19687 | &%syntax_errors_to%&, and &%syntax_errors_text%& are not used. |
| 19688 | |
| 19689 | &%skip_syntax_errors%& can be used to specify that errors in users' forward |
| 19690 | lists or filter files should not prevent delivery. The &%syntax_errors_to%& |
| 19691 | option, used with an address that does not get redirected, can be used to |
| 19692 | notify users of these errors, by means of a router like this: |
| 19693 | .code |
| 19694 | userforward: |
| 19695 | driver = redirect |
| 19696 | allow_filter |
| 19697 | check_local_user |
| 19698 | file = $home/.forward |
| 19699 | file_transport = address_file |
| 19700 | pipe_transport = address_pipe |
| 19701 | reply_transport = address_reply |
| 19702 | no_verify |
| 19703 | skip_syntax_errors |
| 19704 | syntax_errors_to = real-$local_part@$domain |
| 19705 | syntax_errors_text = \ |
| 19706 | This is an automatically generated message. An error has\n\ |
| 19707 | been found in your .forward file. Details of the error are\n\ |
| 19708 | reported below. While this error persists, you will receive\n\ |
| 19709 | a copy of this message for every message that is addressed\n\ |
| 19710 | to you. If your .forward file is a filter file, or if it is\n\ |
| 19711 | a non-filter file containing no valid forwarding addresses,\n\ |
| 19712 | a copy of each incoming message will be put in your normal\n\ |
| 19713 | mailbox. If a non-filter file contains at least one valid\n\ |
| 19714 | forwarding address, forwarding to the valid addresses will\n\ |
| 19715 | happen, and those will be the only deliveries that occur. |
| 19716 | .endd |
| 19717 | You also need a router to ensure that local addresses that are prefixed by |
| 19718 | &`real-`& are recognized, but not forwarded or filtered. For example, you could |
| 19719 | put this immediately before the &(userforward)& router: |
| 19720 | .code |
| 19721 | real_localuser: |
| 19722 | driver = accept |
| 19723 | check_local_user |
| 19724 | local_part_prefix = real- |
| 19725 | transport = local_delivery |
| 19726 | .endd |
| 19727 | For security, it would probably be a good idea to restrict the use of this |
| 19728 | router to locally-generated messages, using a condition such as this: |
| 19729 | .code |
| 19730 | condition = ${if match {$sender_host_address}\ |
| 19731 | {\N^(|127\.0\.0\.1)$\N}} |
| 19732 | .endd |
| 19733 | |
| 19734 | |
| 19735 | .option syntax_errors_text redirect string&!! unset |
| 19736 | See &%skip_syntax_errors%& above. |
| 19737 | |
| 19738 | |
| 19739 | .option syntax_errors_to redirect string unset |
| 19740 | See &%skip_syntax_errors%& above. |
| 19741 | .ecindex IIDredrou1 |
| 19742 | .ecindex IIDredrou2 |
| 19743 | |
| 19744 | |
| 19745 | |
| 19746 | |
| 19747 | |
| 19748 | |
| 19749 | . //////////////////////////////////////////////////////////////////////////// |
| 19750 | . //////////////////////////////////////////////////////////////////////////// |
| 19751 | |
| 19752 | .chapter "Environment for running local transports" "CHAPenvironment" &&& |
| 19753 | "Environment for local transports" |
| 19754 | .scindex IIDenvlotra1 "local transports" "environment for" |
| 19755 | .scindex IIDenvlotra2 "environment for local transports" |
| 19756 | .scindex IIDenvlotra3 "transport" "local; environment for" |
| 19757 | Local transports handle deliveries to files and pipes. (The &(autoreply)& |
| 19758 | transport can be thought of as similar to a pipe.) Exim always runs transports |
| 19759 | in subprocesses, under specified uids and gids. Typical deliveries to local |
| 19760 | mailboxes run under the uid and gid of the local user. |
| 19761 | |
| 19762 | Exim also sets a specific current directory while running the transport; for |
| 19763 | some transports a home directory setting is also relevant. The &(pipe)& |
| 19764 | transport is the only one that sets up environment variables; see section |
| 19765 | &<<SECTpipeenv>>& for details. |
| 19766 | |
| 19767 | The values used for the uid, gid, and the directories may come from several |
| 19768 | different places. In many cases, the router that handles the address associates |
| 19769 | settings with that address as a result of its &%check_local_user%&, &%group%&, |
| 19770 | or &%user%& options. However, values may also be given in the transport's own |
| 19771 | configuration, and these override anything that comes from the router. |
| 19772 | |
| 19773 | |
| 19774 | |
| 19775 | .section "Concurrent deliveries" "SECID131" |
| 19776 | .cindex "concurrent deliveries" |
| 19777 | .cindex "simultaneous deliveries" |
| 19778 | If two different messages for the same local recipient arrive more or less |
| 19779 | simultaneously, the two delivery processes are likely to run concurrently. When |
| 19780 | the &(appendfile)& transport is used to write to a file, Exim applies locking |
| 19781 | rules to stop concurrent processes from writing to the same file at the same |
| 19782 | time. |
| 19783 | |
| 19784 | However, when you use a &(pipe)& transport, it is up to you to arrange any |
| 19785 | locking that is needed. Here is a silly example: |
| 19786 | .code |
| 19787 | my_transport: |
| 19788 | driver = pipe |
| 19789 | command = /bin/sh -c 'cat >>/some/file' |
| 19790 | .endd |
| 19791 | This is supposed to write the message at the end of the file. However, if two |
| 19792 | messages arrive at the same time, the file will be scrambled. You can use the |
| 19793 | &%exim_lock%& utility program (see section &<<SECTmailboxmaint>>&) to lock a |
| 19794 | file using the same algorithm that Exim itself uses. |
| 19795 | |
| 19796 | |
| 19797 | |
| 19798 | |
| 19799 | .section "Uids and gids" "SECTenvuidgid" |
| 19800 | .cindex "local transports" "uid and gid" |
| 19801 | .cindex "transport" "local; uid and gid" |
| 19802 | All transports have the options &%group%& and &%user%&. If &%group%& is set, it |
| 19803 | overrides any group that the router set in the address, even if &%user%& is not |
| 19804 | set for the transport. This makes it possible, for example, to run local mail |
| 19805 | delivery under the uid of the recipient (set by the router), but in a special |
| 19806 | group (set by the transport). For example: |
| 19807 | .code |
| 19808 | # Routers ... |
| 19809 | # User/group are set by check_local_user in this router |
| 19810 | local_users: |
| 19811 | driver = accept |
| 19812 | check_local_user |
| 19813 | transport = group_delivery |
| 19814 | |
| 19815 | # Transports ... |
| 19816 | # This transport overrides the group |
| 19817 | group_delivery: |
| 19818 | driver = appendfile |
| 19819 | file = /var/spool/mail/$local_part |
| 19820 | group = mail |
| 19821 | .endd |
| 19822 | If &%user%& is set for a transport, its value overrides what is set in the |
| 19823 | address by the router. If &%user%& is non-numeric and &%group%& is not set, the |
| 19824 | gid associated with the user is used. If &%user%& is numeric, &%group%& must be |
| 19825 | set. |
| 19826 | |
| 19827 | .oindex "&%initgroups%&" |
| 19828 | When the uid is taken from the transport's configuration, the &[initgroups()]& |
| 19829 | function is called for the groups associated with that uid if the |
| 19830 | &%initgroups%& option is set for the transport. When the uid is not specified |
| 19831 | by the transport, but is associated with the address by a router, the option |
| 19832 | for calling &[initgroups()]& is taken from the router configuration. |
| 19833 | |
| 19834 | .cindex "&(pipe)& transport" "uid for" |
| 19835 | The &(pipe)& transport contains the special option &%pipe_as_creator%&. If this |
| 19836 | is set and &%user%& is not set, the uid of the process that called Exim to |
| 19837 | receive the message is used, and if &%group%& is not set, the corresponding |
| 19838 | original gid is also used. |
| 19839 | |
| 19840 | This is the detailed preference order for obtaining a gid; the first of the |
| 19841 | following that is set is used: |
| 19842 | |
| 19843 | .ilist |
| 19844 | A &%group%& setting of the transport; |
| 19845 | .next |
| 19846 | A &%group%& setting of the router; |
| 19847 | .next |
| 19848 | A gid associated with a user setting of the router, either as a result of |
| 19849 | &%check_local_user%& or an explicit non-numeric &%user%& setting; |
| 19850 | .next |
| 19851 | The group associated with a non-numeric &%user%& setting of the transport; |
| 19852 | .next |
| 19853 | In a &(pipe)& transport, the creator's gid if &%deliver_as_creator%& is set and |
| 19854 | the uid is the creator's uid; |
| 19855 | .next |
| 19856 | The Exim gid if the Exim uid is being used as a default. |
| 19857 | .endlist |
| 19858 | |
| 19859 | If, for example, the user is specified numerically on the router and there are |
| 19860 | no group settings, no gid is available. In this situation, an error occurs. |
| 19861 | This is different for the uid, for which there always is an ultimate default. |
| 19862 | The first of the following that is set is used: |
| 19863 | |
| 19864 | .ilist |
| 19865 | A &%user%& setting of the transport; |
| 19866 | .next |
| 19867 | In a &(pipe)& transport, the creator's uid if &%deliver_as_creator%& is set; |
| 19868 | .next |
| 19869 | A &%user%& setting of the router; |
| 19870 | .next |
| 19871 | A &%check_local_user%& setting of the router; |
| 19872 | .next |
| 19873 | The Exim uid. |
| 19874 | .endlist |
| 19875 | |
| 19876 | Of course, an error will still occur if the uid that is chosen is on the |
| 19877 | &%never_users%& list. |
| 19878 | |
| 19879 | |
| 19880 | |
| 19881 | |
| 19882 | |
| 19883 | .section "Current and home directories" "SECID132" |
| 19884 | .cindex "current directory for local transport" |
| 19885 | .cindex "home directory" "for local transport" |
| 19886 | .cindex "transport" "local; home directory for" |
| 19887 | .cindex "transport" "local; current directory for" |
| 19888 | Routers may set current and home directories for local transports by means of |
| 19889 | the &%transport_current_directory%& and &%transport_home_directory%& options. |
| 19890 | However, if the transport's &%current_directory%& or &%home_directory%& options |
| 19891 | are set, they override the router's values. In detail, the home directory |
| 19892 | for a local transport is taken from the first of these values that is set: |
| 19893 | |
| 19894 | .ilist |
| 19895 | The &%home_directory%& option on the transport; |
| 19896 | .next |
| 19897 | The &%transport_home_directory%& option on the router; |
| 19898 | .next |
| 19899 | The password data if &%check_local_user%& is set on the router; |
| 19900 | .next |
| 19901 | The &%router_home_directory%& option on the router. |
| 19902 | .endlist |
| 19903 | |
| 19904 | The current directory is taken from the first of these values that is set: |
| 19905 | |
| 19906 | .ilist |
| 19907 | The &%current_directory%& option on the transport; |
| 19908 | .next |
| 19909 | The &%transport_current_directory%& option on the router. |
| 19910 | .endlist |
| 19911 | |
| 19912 | |
| 19913 | If neither the router nor the transport sets a current directory, Exim uses the |
| 19914 | value of the home directory, if it is set. Otherwise it sets the current |
| 19915 | directory to &_/_& before running a local transport. |
| 19916 | |
| 19917 | |
| 19918 | |
| 19919 | .section "Expansion variables derived from the address" "SECID133" |
| 19920 | .vindex "&$domain$&" |
| 19921 | .vindex "&$local_part$&" |
| 19922 | .vindex "&$original_domain$&" |
| 19923 | Normally a local delivery is handling a single address, and in that case the |
| 19924 | variables such as &$domain$& and &$local_part$& are set during local |
| 19925 | deliveries. However, in some circumstances more than one address may be handled |
| 19926 | at once (for example, while writing batch SMTP for onward transmission by some |
| 19927 | other means). In this case, the variables associated with the local part are |
| 19928 | never set, &$domain$& is set only if all the addresses have the same domain, |
| 19929 | and &$original_domain$& is never set. |
| 19930 | .ecindex IIDenvlotra1 |
| 19931 | .ecindex IIDenvlotra2 |
| 19932 | .ecindex IIDenvlotra3 |
| 19933 | |
| 19934 | |
| 19935 | |
| 19936 | |
| 19937 | |
| 19938 | |
| 19939 | |
| 19940 | . //////////////////////////////////////////////////////////////////////////// |
| 19941 | . //////////////////////////////////////////////////////////////////////////// |
| 19942 | |
| 19943 | .chapter "Generic options for transports" "CHAPtransportgeneric" |
| 19944 | .scindex IIDgenoptra1 "generic options" "transport" |
| 19945 | .scindex IIDgenoptra2 "options" "generic; for transports" |
| 19946 | .scindex IIDgenoptra3 "transport" "generic options for" |
| 19947 | The following generic options apply to all transports: |
| 19948 | |
| 19949 | |
| 19950 | .option body_only transports boolean false |
| 19951 | .cindex "transport" "body only" |
| 19952 | .cindex "message" "transporting body only" |
| 19953 | .cindex "body of message" "transporting" |
| 19954 | If this option is set, the message's headers are not transported. It is |
| 19955 | mutually exclusive with &%headers_only%&. If it is used with the &(appendfile)& |
| 19956 | or &(pipe)& transports, the settings of &%message_prefix%& and |
| 19957 | &%message_suffix%& should be checked, because this option does not |
| 19958 | automatically suppress them. |
| 19959 | |
| 19960 | |
| 19961 | .option current_directory transports string&!! unset |
| 19962 | .cindex "transport" "current directory for" |
| 19963 | This specifies the current directory that is to be set while running the |
| 19964 | transport, overriding any value that may have been set by the router. |
| 19965 | If the expansion fails for any reason, including forced failure, an error is |
| 19966 | logged, and delivery is deferred. |
| 19967 | |
| 19968 | |
| 19969 | .option disable_logging transports boolean false |
| 19970 | If this option is set true, nothing is logged for any |
| 19971 | deliveries by the transport or for any |
| 19972 | transport errors. You should not set this option unless you really, really know |
| 19973 | what you are doing. |
| 19974 | |
| 19975 | |
| 19976 | .option debug_print transports string&!! unset |
| 19977 | .cindex "testing" "variables in drivers" |
| 19978 | If this option is set and debugging is enabled (see the &%-d%& command line |
| 19979 | option), the string is expanded and included in the debugging output when the |
| 19980 | transport is run. |
| 19981 | If expansion of the string fails, the error message is written to the debugging |
| 19982 | output, and Exim carries on processing. |
| 19983 | This facility is provided to help with checking out the values of variables and |
| 19984 | so on when debugging driver configurations. For example, if a &%headers_add%& |
| 19985 | option is not working properly, &%debug_print%& could be used to output the |
| 19986 | variables it references. A newline is added to the text if it does not end with |
| 19987 | one. |
| 19988 | The variables &$transport_name$& and &$router_name$& contain the name of the |
| 19989 | transport and the router that called it. |
| 19990 | |
| 19991 | .option delivery_date_add transports boolean false |
| 19992 | .cindex "&'Delivery-date:'& header line" |
| 19993 | If this option is true, a &'Delivery-date:'& header is added to the message. |
| 19994 | This gives the actual time the delivery was made. As this is not a standard |
| 19995 | header, Exim has a configuration option (&%delivery_date_remove%&) which |
| 19996 | requests its removal from incoming messages, so that delivered messages can |
| 19997 | safely be resent to other recipients. |
| 19998 | |
| 19999 | |
| 20000 | .option driver transports string unset |
| 20001 | This specifies which of the available transport drivers is to be used. |
| 20002 | There is no default, and this option must be set for every transport. |
| 20003 | |
| 20004 | |
| 20005 | .option envelope_to_add transports boolean false |
| 20006 | .cindex "&'Envelope-to:'& header line" |
| 20007 | If this option is true, an &'Envelope-to:'& header is added to the message. |
| 20008 | This gives the original address(es) in the incoming envelope that caused this |
| 20009 | delivery to happen. More than one address may be present if the transport is |
| 20010 | configured to handle several addresses at once, or if more than one original |
| 20011 | address was redirected to the same final address. As this is not a standard |
| 20012 | header, Exim has a configuration option (&%envelope_to_remove%&) which requests |
| 20013 | its removal from incoming messages, so that delivered messages can safely be |
| 20014 | resent to other recipients. |
| 20015 | |
| 20016 | |
| 20017 | .option group transports string&!! "Exim group" |
| 20018 | .cindex "transport" "group; specifying" |
| 20019 | This option specifies a gid for running the transport process, overriding any |
| 20020 | value that the router supplies, and also overriding any value associated with |
| 20021 | &%user%& (see below). |
| 20022 | |
| 20023 | |
| 20024 | .option headers_add transports list&!! unset |
| 20025 | .cindex "header lines" "adding in transport" |
| 20026 | .cindex "transport" "header lines; adding" |
| 20027 | This option specifies a list of text headers, newline-separated, |
| 20028 | which are (separately) expanded and added to the header |
| 20029 | portion of a message as it is transported, as described in section |
| 20030 | &<<SECTheadersaddrem>>&. Additional header lines can also be specified by |
| 20031 | routers. If the result of the expansion is an empty string, or if the expansion |
| 20032 | is forced to fail, no action is taken. Other expansion failures are treated as |
| 20033 | errors and cause the delivery to be deferred. |
| 20034 | |
| 20035 | Unlike most options, &%headers_add%& can be specified multiple times |
| 20036 | for a transport; all listed headers are added. |
| 20037 | |
| 20038 | |
| 20039 | .option headers_only transports boolean false |
| 20040 | .cindex "transport" "header lines only" |
| 20041 | .cindex "message" "transporting headers only" |
| 20042 | .cindex "header lines" "transporting" |
| 20043 | If this option is set, the message's body is not transported. It is mutually |
| 20044 | exclusive with &%body_only%&. If it is used with the &(appendfile)& or &(pipe)& |
| 20045 | transports, the settings of &%message_prefix%& and &%message_suffix%& should be |
| 20046 | checked, since this option does not automatically suppress them. |
| 20047 | |
| 20048 | |
| 20049 | .option headers_remove transports list&!! unset |
| 20050 | .cindex "header lines" "removing" |
| 20051 | .cindex "transport" "header lines; removing" |
| 20052 | This option specifies a list of header names, colon-separated; |
| 20053 | these headers are omitted from the message as it is transported, as described |
| 20054 | in section &<<SECTheadersaddrem>>&. Header removal can also be specified by |
| 20055 | routers. |
| 20056 | Each list item is separately expanded. |
| 20057 | If the result of the expansion is an empty string, or if the expansion |
| 20058 | is forced to fail, no action is taken. Other expansion failures are treated as |
| 20059 | errors and cause the delivery to be deferred. |
| 20060 | |
| 20061 | Unlike most options, &%headers_remove%& can be specified multiple times |
| 20062 | for a router; all listed headers are removed. |
| 20063 | |
| 20064 | |
| 20065 | |
| 20066 | .option headers_rewrite transports string unset |
| 20067 | .cindex "transport" "header lines; rewriting" |
| 20068 | .cindex "rewriting" "at transport time" |
| 20069 | This option allows addresses in header lines to be rewritten at transport time, |
| 20070 | that is, as the message is being copied to its destination. The contents of the |
| 20071 | option are a colon-separated list of rewriting rules. Each rule is in exactly |
| 20072 | the same form as one of the general rewriting rules that are applied when a |
| 20073 | message is received. These are described in chapter &<<CHAPrewrite>>&. For |
| 20074 | example, |
| 20075 | .code |
| 20076 | headers_rewrite = a@b c@d f : \ |
| 20077 | x@y w@z |
| 20078 | .endd |
| 20079 | changes &'a@b'& into &'c@d'& in &'From:'& header lines, and &'x@y'& into |
| 20080 | &'w@z'& in all address-bearing header lines. The rules are applied to the |
| 20081 | header lines just before they are written out at transport time, so they affect |
| 20082 | only those copies of the message that pass through the transport. However, only |
| 20083 | the message's original header lines, and any that were added by a system |
| 20084 | filter, are rewritten. If a router or transport adds header lines, they are not |
| 20085 | affected by this option. These rewriting rules are &'not'& applied to the |
| 20086 | envelope. You can change the return path using &%return_path%&, but you cannot |
| 20087 | change envelope recipients at this time. |
| 20088 | |
| 20089 | |
| 20090 | .option home_directory transports string&!! unset |
| 20091 | .cindex "transport" "home directory for" |
| 20092 | .vindex "&$home$&" |
| 20093 | This option specifies a home directory setting for a local transport, |
| 20094 | overriding any value that may be set by the router. The home directory is |
| 20095 | placed in &$home$& while expanding the transport's private options. It is also |
| 20096 | used as the current directory if no current directory is set by the |
| 20097 | &%current_directory%& option on the transport or the |
| 20098 | &%transport_current_directory%& option on the router. If the expansion fails |
| 20099 | for any reason, including forced failure, an error is logged, and delivery is |
| 20100 | deferred. |
| 20101 | |
| 20102 | |
| 20103 | .option initgroups transports boolean false |
| 20104 | .cindex "additional groups" |
| 20105 | .cindex "groups" "additional" |
| 20106 | .cindex "transport" "group; additional" |
| 20107 | If this option is true and the uid for the delivery process is provided by the |
| 20108 | transport, the &[initgroups()]& function is called when running the transport |
| 20109 | to ensure that any additional groups associated with the uid are set up. |
| 20110 | |
| 20111 | |
| 20112 | .option message_size_limit transports string&!! 0 |
| 20113 | .cindex "limit" "message size per transport" |
| 20114 | .cindex "size" "of message, limit" |
| 20115 | .cindex "transport" "message size; limiting" |
| 20116 | This option controls the size of messages passed through the transport. It is |
| 20117 | expanded before use; the result of the expansion must be a sequence of decimal |
| 20118 | digits, optionally followed by K or M. If the expansion fails for any reason, |
| 20119 | including forced failure, or if the result is not of the required form, |
| 20120 | delivery is deferred. If the value is greater than zero and the size of a |
| 20121 | message exceeds this limit, the address is failed. If there is any chance that |
| 20122 | the resulting bounce message could be routed to the same transport, you should |
| 20123 | ensure that &%return_size_limit%& is less than the transport's |
| 20124 | &%message_size_limit%&, as otherwise the bounce message will fail to get |
| 20125 | delivered. |
| 20126 | |
| 20127 | |
| 20128 | |
| 20129 | .option rcpt_include_affixes transports boolean false |
| 20130 | .cindex "prefix" "for local part, including in envelope" |
| 20131 | .cindex "suffix for local part" "including in envelope" |
| 20132 | .cindex "local part" "prefix" |
| 20133 | .cindex "local part" "suffix" |
| 20134 | When this option is false (the default), and an address that has had any |
| 20135 | affixes (prefixes or suffixes) removed from the local part is delivered by any |
| 20136 | form of SMTP or LMTP, the affixes are not included. For example, if a router |
| 20137 | that contains |
| 20138 | .code |
| 20139 | local_part_prefix = *- |
| 20140 | .endd |
| 20141 | routes the address &'abc-xyz@some.domain'& to an SMTP transport, the envelope |
| 20142 | is delivered with |
| 20143 | .code |
| 20144 | RCPT TO:<xyz@some.domain> |
| 20145 | .endd |
| 20146 | This is also the case when an ACL-time callout is being used to verify a |
| 20147 | recipient address. However, if &%rcpt_include_affixes%& is set true, the |
| 20148 | whole local part is included in the RCPT command. This option applies to BSMTP |
| 20149 | deliveries by the &(appendfile)& and &(pipe)& transports as well as to the |
| 20150 | &(lmtp)& and &(smtp)& transports. |
| 20151 | |
| 20152 | |
| 20153 | .option retry_use_local_part transports boolean "see below" |
| 20154 | .cindex "hints database" "retry keys" |
| 20155 | When a delivery suffers a temporary failure, a retry record is created |
| 20156 | in Exim's hints database. For remote deliveries, the key for the retry record |
| 20157 | is based on the name and/or IP address of the failing remote host. For local |
| 20158 | deliveries, the key is normally the entire address, including both the local |
| 20159 | part and the domain. This is suitable for most common cases of local delivery |
| 20160 | temporary failure &-- for example, exceeding a mailbox quota should delay only |
| 20161 | deliveries to that mailbox, not to the whole domain. |
| 20162 | |
| 20163 | However, in some special cases you may want to treat a temporary local delivery |
| 20164 | as a failure associated with the domain, and not with a particular local part. |
| 20165 | (For example, if you are storing all mail for some domain in files.) You can do |
| 20166 | this by setting &%retry_use_local_part%& false. |
| 20167 | |
| 20168 | For all the local transports, its default value is true. For remote transports, |
| 20169 | the default value is false for tidiness, but changing the value has no effect |
| 20170 | on a remote transport in the current implementation. |
| 20171 | |
| 20172 | |
| 20173 | .option return_path transports string&!! unset |
| 20174 | .cindex "envelope sender" |
| 20175 | .cindex "transport" "return path; changing" |
| 20176 | .cindex "return path" "changing in transport" |
| 20177 | If this option is set, the string is expanded at transport time and replaces |
| 20178 | the existing return path (envelope sender) value in the copy of the message |
| 20179 | that is being delivered. An empty return path is permitted. This feature is |
| 20180 | designed for remote deliveries, where the value of this option is used in the |
| 20181 | SMTP MAIL command. If you set &%return_path%& for a local transport, the |
| 20182 | only effect is to change the address that is placed in the &'Return-path:'& |
| 20183 | header line, if one is added to the message (see the next option). |
| 20184 | |
| 20185 | &*Note:*& A changed return path is not logged unless you add |
| 20186 | &%return_path_on_delivery%& to the log selector. |
| 20187 | |
| 20188 | .vindex "&$return_path$&" |
| 20189 | The expansion can refer to the existing value via &$return_path$&. This is |
| 20190 | either the message's envelope sender, or an address set by the |
| 20191 | &%errors_to%& option on a router. If the expansion is forced to fail, no |
| 20192 | replacement occurs; if it fails for another reason, delivery is deferred. This |
| 20193 | option can be used to support VERP (Variable Envelope Return Paths) &-- see |
| 20194 | section &<<SECTverp>>&. |
| 20195 | |
| 20196 | &*Note*&: If a delivery error is detected locally, including the case when a |
| 20197 | remote server rejects a message at SMTP time, the bounce message is not sent to |
| 20198 | the value of this option. It is sent to the previously set errors address. |
| 20199 | This defaults to the incoming sender address, but can be changed by setting |
| 20200 | &%errors_to%& in a router. |
| 20201 | |
| 20202 | |
| 20203 | |
| 20204 | .option return_path_add transports boolean false |
| 20205 | .cindex "&'Return-path:'& header line" |
| 20206 | If this option is true, a &'Return-path:'& header is added to the message. |
| 20207 | Although the return path is normally available in the prefix line of BSD |
| 20208 | mailboxes, this is commonly not displayed by MUAs, and so the user does not |
| 20209 | have easy access to it. |
| 20210 | |
| 20211 | RFC 2821 states that the &'Return-path:'& header is added to a message &"when |
| 20212 | the delivery SMTP server makes the final delivery"&. This implies that this |
| 20213 | header should not be present in incoming messages. Exim has a configuration |
| 20214 | option, &%return_path_remove%&, which requests removal of this header from |
| 20215 | incoming messages, so that delivered messages can safely be resent to other |
| 20216 | recipients. |
| 20217 | |
| 20218 | |
| 20219 | .option shadow_condition transports string&!! unset |
| 20220 | See &%shadow_transport%& below. |
| 20221 | |
| 20222 | |
| 20223 | .option shadow_transport transports string unset |
| 20224 | .cindex "shadow transport" |
| 20225 | .cindex "transport" "shadow" |
| 20226 | A local transport may set the &%shadow_transport%& option to the name of |
| 20227 | another local transport. Shadow remote transports are not supported. |
| 20228 | |
| 20229 | Whenever a delivery to the main transport succeeds, and either |
| 20230 | &%shadow_condition%& is unset, or its expansion does not result in the empty |
| 20231 | string or one of the strings &"0"& or &"no"& or &"false"&, the message is also |
| 20232 | passed to the shadow transport, with the same delivery address or addresses. If |
| 20233 | expansion fails, no action is taken except that non-forced expansion failures |
| 20234 | cause a log line to be written. |
| 20235 | |
| 20236 | The result of the shadow transport is discarded and does not affect the |
| 20237 | subsequent processing of the message. Only a single level of shadowing is |
| 20238 | provided; the &%shadow_transport%& option is ignored on any transport when it |
| 20239 | is running as a shadow. Options concerned with output from pipes are also |
| 20240 | ignored. The log line for the successful delivery has an item added on the end, |
| 20241 | of the form |
| 20242 | .code |
| 20243 | ST=<shadow transport name> |
| 20244 | .endd |
| 20245 | If the shadow transport did not succeed, the error message is put in |
| 20246 | parentheses afterwards. Shadow transports can be used for a number of different |
| 20247 | purposes, including keeping more detailed log information than Exim normally |
| 20248 | provides, and implementing automatic acknowledgment policies based on message |
| 20249 | headers that some sites insist on. |
| 20250 | |
| 20251 | |
| 20252 | .option transport_filter transports string&!! unset |
| 20253 | .cindex "transport" "filter" |
| 20254 | .cindex "filter" "transport filter" |
| 20255 | This option sets up a filtering (in the Unix shell sense) process for messages |
| 20256 | at transport time. It should not be confused with mail filtering as set up by |
| 20257 | individual users or via a system filter. |
| 20258 | |
| 20259 | When the message is about to be written out, the command specified by |
| 20260 | &%transport_filter%& is started up in a separate, parallel process, and |
| 20261 | the entire message, including the header lines, is passed to it on its standard |
| 20262 | input (this in fact is done from a third process, to avoid deadlock). The |
| 20263 | command must be specified as an absolute path. |
| 20264 | |
| 20265 | The lines of the message that are written to the transport filter are |
| 20266 | terminated by newline (&"\n"&). The message is passed to the filter before any |
| 20267 | SMTP-specific processing, such as turning &"\n"& into &"\r\n"& and escaping |
| 20268 | lines beginning with a dot, and also before any processing implied by the |
| 20269 | settings of &%check_string%& and &%escape_string%& in the &(appendfile)& or |
| 20270 | &(pipe)& transports. |
| 20271 | |
| 20272 | The standard error for the filter process is set to the same destination as its |
| 20273 | standard output; this is read and written to the message's ultimate |
| 20274 | destination. The process that writes the message to the filter, the |
| 20275 | filter itself, and the original process that reads the result and delivers it |
| 20276 | are all run in parallel, like a shell pipeline. |
| 20277 | |
| 20278 | The filter can perform any transformations it likes, but of course should take |
| 20279 | care not to break RFC 2822 syntax. Exim does not check the result, except to |
| 20280 | test for a final newline when SMTP is in use. All messages transmitted over |
| 20281 | SMTP must end with a newline, so Exim supplies one if it is missing. |
| 20282 | |
| 20283 | .cindex "content scanning" "per user" |
| 20284 | A transport filter can be used to provide content-scanning on a per-user basis |
| 20285 | at delivery time if the only required effect of the scan is to modify the |
| 20286 | message. For example, a content scan could insert a new header line containing |
| 20287 | a spam score. This could be interpreted by a filter in the user's MUA. It is |
| 20288 | not possible to discard a message at this stage. |
| 20289 | |
| 20290 | .cindex "SMTP" "SIZE" |
| 20291 | A problem might arise if the filter increases the size of a message that is |
| 20292 | being sent down an SMTP connection. If the receiving SMTP server has indicated |
| 20293 | support for the SIZE parameter, Exim will have sent the size of the message |
| 20294 | at the start of the SMTP session. If what is actually sent is substantially |
| 20295 | more, the server might reject the message. This can be worked round by setting |
| 20296 | the &%size_addition%& option on the &(smtp)& transport, either to allow for |
| 20297 | additions to the message, or to disable the use of SIZE altogether. |
| 20298 | |
| 20299 | .vindex "&$pipe_addresses$&" |
| 20300 | The value of the &%transport_filter%& option is the command string for starting |
| 20301 | the filter, which is run directly from Exim, not under a shell. The string is |
| 20302 | parsed by Exim in the same way as a command string for the &(pipe)& transport: |
| 20303 | Exim breaks it up into arguments and then expands each argument separately (see |
| 20304 | section &<<SECThowcommandrun>>&). Any kind of expansion failure causes delivery |
| 20305 | to be deferred. The special argument &$pipe_addresses$& is replaced by a number |
| 20306 | of arguments, one for each address that applies to this delivery. (This isn't |
| 20307 | an ideal name for this feature here, but as it was already implemented for the |
| 20308 | &(pipe)& transport, it seemed sensible not to change it.) |
| 20309 | |
| 20310 | .vindex "&$host$&" |
| 20311 | .vindex "&$host_address$&" |
| 20312 | The expansion variables &$host$& and &$host_address$& are available when the |
| 20313 | transport is a remote one. They contain the name and IP address of the host to |
| 20314 | which the message is being sent. For example: |
| 20315 | .code |
| 20316 | transport_filter = /some/directory/transport-filter.pl \ |
| 20317 | $host $host_address $sender_address $pipe_addresses |
| 20318 | .endd |
| 20319 | |
| 20320 | Two problems arise if you want to use more complicated expansion items to |
| 20321 | generate transport filter commands, both of which due to the fact that the |
| 20322 | command is split up &'before'& expansion. |
| 20323 | .ilist |
| 20324 | If an expansion item contains white space, you must quote it, so that it is all |
| 20325 | part of the same command item. If the entire option setting is one such |
| 20326 | expansion item, you have to take care what kind of quoting you use. For |
| 20327 | example: |
| 20328 | .code |
| 20329 | transport_filter = '/bin/cmd${if eq{$host}{a.b.c}{1}{2}}' |
| 20330 | .endd |
| 20331 | This runs the command &(/bin/cmd1)& if the host name is &'a.b.c'&, and |
| 20332 | &(/bin/cmd2)& otherwise. If double quotes had been used, they would have been |
| 20333 | stripped by Exim when it read the option's value. When the value is used, if |
| 20334 | the single quotes were missing, the line would be split into two items, |
| 20335 | &`/bin/cmd${if`& and &`eq{$host}{a.b.c}{1}{2}`&, and an error would occur when |
| 20336 | Exim tried to expand the first one. |
| 20337 | .next |
| 20338 | Except for the special case of &$pipe_addresses$& that is mentioned above, an |
| 20339 | expansion cannot generate multiple arguments, or a command name followed by |
| 20340 | arguments. Consider this example: |
| 20341 | .code |
| 20342 | transport_filter = ${lookup{$host}lsearch{/a/file}\ |
| 20343 | {$value}{/bin/cat}} |
| 20344 | .endd |
| 20345 | The result of the lookup is interpreted as the name of the command, even |
| 20346 | if it contains white space. The simplest way round this is to use a shell: |
| 20347 | .code |
| 20348 | transport_filter = /bin/sh -c ${lookup{$host}lsearch{/a/file}\ |
| 20349 | {$value}{/bin/cat}} |
| 20350 | .endd |
| 20351 | .endlist |
| 20352 | |
| 20353 | The filter process is run under the same uid and gid as the normal delivery. |
| 20354 | For remote deliveries this is the Exim uid/gid by default. The command should |
| 20355 | normally yield a zero return code. Transport filters are not supposed to fail. |
| 20356 | A non-zero code is taken to mean that the transport filter encountered some |
| 20357 | serious problem. Delivery of the message is deferred; the message remains on |
| 20358 | the queue and is tried again later. It is not possible to cause a message to be |
| 20359 | bounced from a transport filter. |
| 20360 | |
| 20361 | If a transport filter is set on an autoreply transport, the original message is |
| 20362 | passed through the filter as it is being copied into the newly generated |
| 20363 | message, which happens if the &%return_message%& option is set. |
| 20364 | |
| 20365 | |
| 20366 | .option transport_filter_timeout transports time 5m |
| 20367 | .cindex "transport" "filter, timeout" |
| 20368 | When Exim is reading the output of a transport filter, it applies a timeout |
| 20369 | that can be set by this option. Exceeding the timeout is normally treated as a |
| 20370 | temporary delivery failure. However, if a transport filter is used with a |
| 20371 | &(pipe)& transport, a timeout in the transport filter is treated in the same |
| 20372 | way as a timeout in the pipe command itself. By default, a timeout is a hard |
| 20373 | error, but if the &(pipe)& transport's &%timeout_defer%& option is set true, it |
| 20374 | becomes a temporary error. |
| 20375 | |
| 20376 | |
| 20377 | .option user transports string&!! "Exim user" |
| 20378 | .cindex "uid (user id)" "local delivery" |
| 20379 | .cindex "transport" "user, specifying" |
| 20380 | This option specifies the user under whose uid the delivery process is to be |
| 20381 | run, overriding any uid that may have been set by the router. If the user is |
| 20382 | given as a name, the uid is looked up from the password data, and the |
| 20383 | associated group is taken as the value of the gid to be used if the &%group%& |
| 20384 | option is not set. |
| 20385 | |
| 20386 | For deliveries that use local transports, a user and group are normally |
| 20387 | specified explicitly or implicitly (for example, as a result of |
| 20388 | &%check_local_user%&) by the router or transport. |
| 20389 | |
| 20390 | .cindex "hints database" "access by remote transport" |
| 20391 | For remote transports, you should leave this option unset unless you really are |
| 20392 | sure you know what you are doing. When a remote transport is running, it needs |
| 20393 | to be able to access Exim's hints databases, because each host may have its own |
| 20394 | retry data. |
| 20395 | .ecindex IIDgenoptra1 |
| 20396 | .ecindex IIDgenoptra2 |
| 20397 | .ecindex IIDgenoptra3 |
| 20398 | |
| 20399 | |
| 20400 | |
| 20401 | |
| 20402 | |
| 20403 | |
| 20404 | . //////////////////////////////////////////////////////////////////////////// |
| 20405 | . //////////////////////////////////////////////////////////////////////////// |
| 20406 | |
| 20407 | .chapter "Address batching in local transports" "CHAPbatching" &&& |
| 20408 | "Address batching" |
| 20409 | .cindex "transport" "local; address batching in" |
| 20410 | The only remote transport (&(smtp)&) is normally configured to handle more than |
| 20411 | one address at a time, so that when several addresses are routed to the same |
| 20412 | remote host, just one copy of the message is sent. Local transports, however, |
| 20413 | normally handle one address at a time. That is, a separate instance of the |
| 20414 | transport is run for each address that is routed to the transport. A separate |
| 20415 | copy of the message is delivered each time. |
| 20416 | |
| 20417 | .cindex "batched local delivery" |
| 20418 | .oindex "&%batch_max%&" |
| 20419 | .oindex "&%batch_id%&" |
| 20420 | In special cases, it may be desirable to handle several addresses at once in a |
| 20421 | local transport, for example: |
| 20422 | |
| 20423 | .ilist |
| 20424 | In an &(appendfile)& transport, when storing messages in files for later |
| 20425 | delivery by some other means, a single copy of the message with multiple |
| 20426 | recipients saves space. |
| 20427 | .next |
| 20428 | In an &(lmtp)& transport, when delivering over &"local SMTP"& to some process, |
| 20429 | a single copy saves time, and is the normal way LMTP is expected to work. |
| 20430 | .next |
| 20431 | In a &(pipe)& transport, when passing the message |
| 20432 | to a scanner program or |
| 20433 | to some other delivery mechanism such as UUCP, multiple recipients may be |
| 20434 | acceptable. |
| 20435 | .endlist |
| 20436 | |
| 20437 | These three local transports all have the same options for controlling multiple |
| 20438 | (&"batched"&) deliveries, namely &%batch_max%& and &%batch_id%&. To save |
| 20439 | repeating the information for each transport, these options are described here. |
| 20440 | |
| 20441 | The &%batch_max%& option specifies the maximum number of addresses that can be |
| 20442 | delivered together in a single run of the transport. Its default value is one |
| 20443 | (no batching). When more than one address is routed to a transport that has a |
| 20444 | &%batch_max%& value greater than one, the addresses are delivered in a batch |
| 20445 | (that is, in a single run of the transport with multiple recipients), subject |
| 20446 | to certain conditions: |
| 20447 | |
| 20448 | .ilist |
| 20449 | .vindex "&$local_part$&" |
| 20450 | If any of the transport's options contain a reference to &$local_part$&, no |
| 20451 | batching is possible. |
| 20452 | .next |
| 20453 | .vindex "&$domain$&" |
| 20454 | If any of the transport's options contain a reference to &$domain$&, only |
| 20455 | addresses with the same domain are batched. |
| 20456 | .next |
| 20457 | .cindex "customizing" "batching condition" |
| 20458 | If &%batch_id%& is set, it is expanded for each address, and only those |
| 20459 | addresses with the same expanded value are batched. This allows you to specify |
| 20460 | customized batching conditions. Failure of the expansion for any reason, |
| 20461 | including forced failure, disables batching, but it does not stop the delivery |
| 20462 | from taking place. |
| 20463 | .next |
| 20464 | Batched addresses must also have the same errors address (where to send |
| 20465 | delivery errors), the same header additions and removals, the same user and |
| 20466 | group for the transport, and if a host list is present, the first host must |
| 20467 | be the same. |
| 20468 | .endlist |
| 20469 | |
| 20470 | In the case of the &(appendfile)& and &(pipe)& transports, batching applies |
| 20471 | both when the file or pipe command is specified in the transport, and when it |
| 20472 | is specified by a &(redirect)& router, but all the batched addresses must of |
| 20473 | course be routed to the same file or pipe command. These two transports have an |
| 20474 | option called &%use_bsmtp%&, which causes them to deliver the message in |
| 20475 | &"batched SMTP"& format, with the envelope represented as SMTP commands. The |
| 20476 | &%check_string%& and &%escape_string%& options are forced to the values |
| 20477 | .code |
| 20478 | check_string = "." |
| 20479 | escape_string = ".." |
| 20480 | .endd |
| 20481 | when batched SMTP is in use. A full description of the batch SMTP mechanism is |
| 20482 | given in section &<<SECTbatchSMTP>>&. The &(lmtp)& transport does not have a |
| 20483 | &%use_bsmtp%& option, because it always delivers using the SMTP protocol. |
| 20484 | |
| 20485 | .cindex "&'Envelope-to:'& header line" |
| 20486 | If the generic &%envelope_to_add%& option is set for a batching transport, the |
| 20487 | &'Envelope-to:'& header that is added to the message contains all the addresses |
| 20488 | that are being processed together. If you are using a batching &(appendfile)& |
| 20489 | transport without &%use_bsmtp%&, the only way to preserve the recipient |
| 20490 | addresses is to set the &%envelope_to_add%& option. |
| 20491 | |
| 20492 | .cindex "&(pipe)& transport" "with multiple addresses" |
| 20493 | .vindex "&$pipe_addresses$&" |
| 20494 | If you are using a &(pipe)& transport without BSMTP, and setting the |
| 20495 | transport's &%command%& option, you can include &$pipe_addresses$& as part of |
| 20496 | the command. This is not a true variable; it is a bit of magic that causes each |
| 20497 | of the recipient addresses to be inserted into the command as a separate |
| 20498 | argument. This provides a way of accessing all the addresses that are being |
| 20499 | delivered in the batch. &*Note:*& This is not possible for pipe commands that |
| 20500 | are specified by a &(redirect)& router. |
| 20501 | |
| 20502 | |
| 20503 | |
| 20504 | |
| 20505 | . //////////////////////////////////////////////////////////////////////////// |
| 20506 | . //////////////////////////////////////////////////////////////////////////// |
| 20507 | |
| 20508 | .chapter "The appendfile transport" "CHAPappendfile" |
| 20509 | .scindex IIDapptra1 "&(appendfile)& transport" |
| 20510 | .scindex IIDapptra2 "transports" "&(appendfile)&" |
| 20511 | .cindex "directory creation" |
| 20512 | .cindex "creating directories" |
| 20513 | The &(appendfile)& transport delivers a message by appending it to an existing |
| 20514 | file, or by creating an entirely new file in a specified directory. Single |
| 20515 | files to which messages are appended can be in the traditional Unix mailbox |
| 20516 | format, or optionally in the MBX format supported by the Pine MUA and |
| 20517 | University of Washington IMAP daemon, &'inter alia'&. When each message is |
| 20518 | being delivered as a separate file, &"maildir"& format can optionally be used |
| 20519 | to give added protection against failures that happen part-way through the |
| 20520 | delivery. A third form of separate-file delivery known as &"mailstore"& is also |
| 20521 | supported. For all file formats, Exim attempts to create as many levels of |
| 20522 | directory as necessary, provided that &%create_directory%& is set. |
| 20523 | |
| 20524 | The code for the optional formats is not included in the Exim binary by |
| 20525 | default. It is necessary to set SUPPORT_MBX, SUPPORT_MAILDIR and/or |
| 20526 | SUPPORT_MAILSTORE in &_Local/Makefile_& to have the appropriate code |
| 20527 | included. |
| 20528 | |
| 20529 | .cindex "quota" "system" |
| 20530 | Exim recognizes system quota errors, and generates an appropriate message. Exim |
| 20531 | also supports its own quota control within the transport, for use when the |
| 20532 | system facility is unavailable or cannot be used for some reason. |
| 20533 | |
| 20534 | If there is an error while appending to a file (for example, quota exceeded or |
| 20535 | partition filled), Exim attempts to reset the file's length and last |
| 20536 | modification time back to what they were before. If there is an error while |
| 20537 | creating an entirely new file, the new file is removed. |
| 20538 | |
| 20539 | Before appending to a file, a number of security checks are made, and the |
| 20540 | file is locked. A detailed description is given below, after the list of |
| 20541 | private options. |
| 20542 | |
| 20543 | The &(appendfile)& transport is most commonly used for local deliveries to |
| 20544 | users' mailboxes. However, it can also be used as a pseudo-remote transport for |
| 20545 | putting messages into files for remote delivery by some means other than Exim. |
| 20546 | &"Batch SMTP"& format is often used in this case (see the &%use_bsmtp%& |
| 20547 | option). |
| 20548 | |
| 20549 | |
| 20550 | |
| 20551 | .section "The file and directory options" "SECTfildiropt" |
| 20552 | The &%file%& option specifies a single file, to which the message is appended; |
| 20553 | the &%directory%& option specifies a directory, in which a new file containing |
| 20554 | the message is created. Only one of these two options can be set, and for |
| 20555 | normal deliveries to mailboxes, one of them &'must'& be set. |
| 20556 | |
| 20557 | .vindex "&$address_file$&" |
| 20558 | .vindex "&$local_part$&" |
| 20559 | However, &(appendfile)& is also used for delivering messages to files or |
| 20560 | directories whose names (or parts of names) are obtained from alias, |
| 20561 | forwarding, or filtering operations (for example, a &%save%& command in a |
| 20562 | user's Exim filter). When such a transport is running, &$local_part$& contains |
| 20563 | the local part that was aliased or forwarded, and &$address_file$& contains the |
| 20564 | name (or partial name) of the file or directory generated by the redirection |
| 20565 | operation. There are two cases: |
| 20566 | |
| 20567 | .ilist |
| 20568 | If neither &%file%& nor &%directory%& is set, the redirection operation |
| 20569 | must specify an absolute path (one that begins with &`/`&). This is the most |
| 20570 | common case when users with local accounts use filtering to sort mail into |
| 20571 | different folders. See for example, the &(address_file)& transport in the |
| 20572 | default configuration. If the path ends with a slash, it is assumed to be the |
| 20573 | name of a directory. A delivery to a directory can also be forced by setting |
| 20574 | &%maildir_format%& or &%mailstore_format%&. |
| 20575 | .next |
| 20576 | If &%file%& or &%directory%& is set for a delivery from a redirection, it is |
| 20577 | used to determine the file or directory name for the delivery. Normally, the |
| 20578 | contents of &$address_file$& are used in some way in the string expansion. |
| 20579 | .endlist |
| 20580 | |
| 20581 | |
| 20582 | .cindex "Sieve filter" "configuring &(appendfile)&" |
| 20583 | .cindex "Sieve filter" "relative mailbox path handling" |
| 20584 | As an example of the second case, consider an environment where users do not |
| 20585 | have home directories. They may be permitted to use Exim filter commands of the |
| 20586 | form: |
| 20587 | .code |
| 20588 | save folder23 |
| 20589 | .endd |
| 20590 | or Sieve filter commands of the form: |
| 20591 | .code |
| 20592 | require "fileinto"; |
| 20593 | fileinto "folder23"; |
| 20594 | .endd |
| 20595 | In this situation, the expansion of &%file%& or &%directory%& in the transport |
| 20596 | must transform the relative path into an appropriate absolute file name. In the |
| 20597 | case of Sieve filters, the name &'inbox'& must be handled. It is the name that |
| 20598 | is used as a result of a &"keep"& action in the filter. This example shows one |
| 20599 | way of handling this requirement: |
| 20600 | .code |
| 20601 | file = ${if eq{$address_file}{inbox} \ |
| 20602 | {/var/mail/$local_part} \ |
| 20603 | {${if eq{${substr_0_1:$address_file}}{/} \ |
| 20604 | {$address_file} \ |
| 20605 | {$home/mail/$address_file} \ |
| 20606 | }} \ |
| 20607 | } |
| 20608 | .endd |
| 20609 | With this setting of &%file%&, &'inbox'& refers to the standard mailbox |
| 20610 | location, absolute paths are used without change, and other folders are in the |
| 20611 | &_mail_& directory within the home directory. |
| 20612 | |
| 20613 | &*Note 1*&: While processing an Exim filter, a relative path such as |
| 20614 | &_folder23_& is turned into an absolute path if a home directory is known to |
| 20615 | the router. In particular, this is the case if &%check_local_user%& is set. If |
| 20616 | you want to prevent this happening at routing time, you can set |
| 20617 | &%router_home_directory%& empty. This forces the router to pass the relative |
| 20618 | path to the transport. |
| 20619 | |
| 20620 | &*Note 2*&: An absolute path in &$address_file$& is not treated specially; |
| 20621 | the &%file%& or &%directory%& option is still used if it is set. |
| 20622 | |
| 20623 | |
| 20624 | |
| 20625 | |
| 20626 | .section "Private options for appendfile" "SECID134" |
| 20627 | .cindex "options" "&(appendfile)& transport" |
| 20628 | |
| 20629 | |
| 20630 | |
| 20631 | .option allow_fifo appendfile boolean false |
| 20632 | .cindex "fifo (named pipe)" |
| 20633 | .cindex "named pipe (fifo)" |
| 20634 | .cindex "pipe" "named (fifo)" |
| 20635 | Setting this option permits delivery to named pipes (FIFOs) as well as to |
| 20636 | regular files. If no process is reading the named pipe at delivery time, the |
| 20637 | delivery is deferred. |
| 20638 | |
| 20639 | |
| 20640 | .option allow_symlink appendfile boolean false |
| 20641 | .cindex "symbolic link" "to mailbox" |
| 20642 | .cindex "mailbox" "symbolic link" |
| 20643 | By default, &(appendfile)& will not deliver if the path name for the file is |
| 20644 | that of a symbolic link. Setting this option relaxes that constraint, but there |
| 20645 | are security issues involved in the use of symbolic links. Be sure you know |
| 20646 | what you are doing if you set this. Details of exactly what this option affects |
| 20647 | are included in the discussion which follows this list of options. |
| 20648 | |
| 20649 | |
| 20650 | .option batch_id appendfile string&!! unset |
| 20651 | See the description of local delivery batching in chapter &<<CHAPbatching>>&. |
| 20652 | However, batching is automatically disabled for &(appendfile)& deliveries that |
| 20653 | happen as a result of forwarding or aliasing or other redirection directly to a |
| 20654 | file. |
| 20655 | |
| 20656 | |
| 20657 | .option batch_max appendfile integer 1 |
| 20658 | See the description of local delivery batching in chapter &<<CHAPbatching>>&. |
| 20659 | |
| 20660 | |
| 20661 | .option check_group appendfile boolean false |
| 20662 | When this option is set, the group owner of the file defined by the &%file%& |
| 20663 | option is checked to see that it is the same as the group under which the |
| 20664 | delivery process is running. The default setting is false because the default |
| 20665 | file mode is 0600, which means that the group is irrelevant. |
| 20666 | |
| 20667 | |
| 20668 | .option check_owner appendfile boolean true |
| 20669 | When this option is set, the owner of the file defined by the &%file%& option |
| 20670 | is checked to ensure that it is the same as the user under which the delivery |
| 20671 | process is running. |
| 20672 | |
| 20673 | |
| 20674 | .option check_string appendfile string "see below" |
| 20675 | .cindex "&""From""& line" |
| 20676 | As &(appendfile)& writes the message, the start of each line is tested for |
| 20677 | matching &%check_string%&, and if it does, the initial matching characters are |
| 20678 | replaced by the contents of &%escape_string%&. The value of &%check_string%& is |
| 20679 | a literal string, not a regular expression, and the case of any letters it |
| 20680 | contains is significant. |
| 20681 | |
| 20682 | If &%use_bsmtp%& is set the values of &%check_string%& and &%escape_string%& |
| 20683 | are forced to &"."& and &".."& respectively, and any settings in the |
| 20684 | configuration are ignored. Otherwise, they default to &"From&~"& and |
| 20685 | &">From&~"& when the &%file%& option is set, and unset when any of the |
| 20686 | &%directory%&, &%maildir%&, or &%mailstore%& options are set. |
| 20687 | |
| 20688 | The default settings, along with &%message_prefix%& and &%message_suffix%&, are |
| 20689 | suitable for traditional &"BSD"& mailboxes, where a line beginning with |
| 20690 | &"From&~"& indicates the start of a new message. All four options need changing |
| 20691 | if another format is used. For example, to deliver to mailboxes in MMDF format: |
| 20692 | .cindex "MMDF format mailbox" |
| 20693 | .cindex "mailbox" "MMDF format" |
| 20694 | .code |
| 20695 | check_string = "\1\1\1\1\n" |
| 20696 | escape_string = "\1\1\1\1 \n" |
| 20697 | message_prefix = "\1\1\1\1\n" |
| 20698 | message_suffix = "\1\1\1\1\n" |
| 20699 | .endd |
| 20700 | .option create_directory appendfile boolean true |
| 20701 | .cindex "directory creation" |
| 20702 | When this option is true, Exim attempts to create any missing superior |
| 20703 | directories for the file that it is about to write. A created directory's mode |
| 20704 | is given by the &%directory_mode%& option. |
| 20705 | |
| 20706 | The group ownership of a newly created directory is highly dependent on the |
| 20707 | operating system (and possibly the file system) that is being used. For |
| 20708 | example, in Solaris, if the parent directory has the setgid bit set, its group |
| 20709 | is propagated to the child; if not, the currently set group is used. However, |
| 20710 | in FreeBSD, the parent's group is always used. |
| 20711 | |
| 20712 | |
| 20713 | |
| 20714 | .option create_file appendfile string anywhere |
| 20715 | This option constrains the location of files and directories that are created |
| 20716 | by this transport. It applies to files defined by the &%file%& option and |
| 20717 | directories defined by the &%directory%& option. In the case of maildir |
| 20718 | delivery, it applies to the top level directory, not the maildir directories |
| 20719 | beneath. |
| 20720 | |
| 20721 | The option must be set to one of the words &"anywhere"&, &"inhome"&, or |
| 20722 | &"belowhome"&. In the second and third cases, a home directory must have been |
| 20723 | set for the transport. This option is not useful when an explicit file name is |
| 20724 | given for normal mailbox deliveries. It is intended for the case when file |
| 20725 | names are generated from users' &_.forward_& files. These are usually handled |
| 20726 | by an &(appendfile)& transport called &%address_file%&. See also |
| 20727 | &%file_must_exist%&. |
| 20728 | |
| 20729 | |
| 20730 | .option directory appendfile string&!! unset |
| 20731 | This option is mutually exclusive with the &%file%& option, but one of &%file%& |
| 20732 | or &%directory%& must be set, unless the delivery is the direct result of a |
| 20733 | redirection (see section &<<SECTfildiropt>>&). |
| 20734 | |
| 20735 | When &%directory%& is set, the string is expanded, and the message is delivered |
| 20736 | into a new file or files in or below the given directory, instead of being |
| 20737 | appended to a single mailbox file. A number of different formats are provided |
| 20738 | (see &%maildir_format%& and &%mailstore_format%&), and see section |
| 20739 | &<<SECTopdir>>& for further details of this form of delivery. |
| 20740 | |
| 20741 | |
| 20742 | .option directory_file appendfile string&!! "see below" |
| 20743 | .cindex "base62" |
| 20744 | .vindex "&$inode$&" |
| 20745 | When &%directory%& is set, but neither &%maildir_format%& nor |
| 20746 | &%mailstore_format%& is set, &(appendfile)& delivers each message into a file |
| 20747 | whose name is obtained by expanding this string. The default value is: |
| 20748 | .code |
| 20749 | q${base62:$tod_epoch}-$inode |
| 20750 | .endd |
| 20751 | This generates a unique name from the current time, in base 62 form, and the |
| 20752 | inode of the file. The variable &$inode$& is available only when expanding this |
| 20753 | option. |
| 20754 | |
| 20755 | |
| 20756 | .option directory_mode appendfile "octal integer" 0700 |
| 20757 | If &(appendfile)& creates any directories as a result of the |
| 20758 | &%create_directory%& option, their mode is specified by this option. |
| 20759 | |
| 20760 | |
| 20761 | .option escape_string appendfile string "see description" |
| 20762 | See &%check_string%& above. |
| 20763 | |
| 20764 | |
| 20765 | .option file appendfile string&!! unset |
| 20766 | This option is mutually exclusive with the &%directory%& option, but one of |
| 20767 | &%file%& or &%directory%& must be set, unless the delivery is the direct result |
| 20768 | of a redirection (see section &<<SECTfildiropt>>&). The &%file%& option |
| 20769 | specifies a single file, to which the message is appended. One or more of |
| 20770 | &%use_fcntl_lock%&, &%use_flock_lock%&, or &%use_lockfile%& must be set with |
| 20771 | &%file%&. |
| 20772 | |
| 20773 | .cindex "NFS" "lock file" |
| 20774 | .cindex "locking files" |
| 20775 | .cindex "lock files" |
| 20776 | If you are using more than one host to deliver over NFS into the same |
| 20777 | mailboxes, you should always use lock files. |
| 20778 | |
| 20779 | The string value is expanded for each delivery, and must yield an absolute |
| 20780 | path. The most common settings of this option are variations on one of these |
| 20781 | examples: |
| 20782 | .code |
| 20783 | file = /var/spool/mail/$local_part |
| 20784 | file = /home/$local_part/inbox |
| 20785 | file = $home/inbox |
| 20786 | .endd |
| 20787 | .cindex "&""sticky""& bit" |
| 20788 | In the first example, all deliveries are done into the same directory. If Exim |
| 20789 | is configured to use lock files (see &%use_lockfile%& below) it must be able to |
| 20790 | create a file in the directory, so the &"sticky"& bit must be turned on for |
| 20791 | deliveries to be possible, or alternatively the &%group%& option can be used to |
| 20792 | run the delivery under a group id which has write access to the directory. |
| 20793 | |
| 20794 | |
| 20795 | |
| 20796 | .option file_format appendfile string unset |
| 20797 | .cindex "file" "mailbox; checking existing format" |
| 20798 | This option requests the transport to check the format of an existing file |
| 20799 | before adding to it. The check consists of matching a specific string at the |
| 20800 | start of the file. The value of the option consists of an even number of |
| 20801 | colon-separated strings. The first of each pair is the test string, and the |
| 20802 | second is the name of a transport. If the transport associated with a matched |
| 20803 | string is not the current transport, control is passed over to the other |
| 20804 | transport. For example, suppose the standard &(local_delivery)& transport has |
| 20805 | this added to it: |
| 20806 | .code |
| 20807 | file_format = "From : local_delivery :\ |
| 20808 | \1\1\1\1\n : local_mmdf_delivery" |
| 20809 | .endd |
| 20810 | Mailboxes that begin with &"From"& are still handled by this transport, but if |
| 20811 | a mailbox begins with four binary ones followed by a newline, control is passed |
| 20812 | to a transport called &%local_mmdf_delivery%&, which presumably is configured |
| 20813 | to do the delivery in MMDF format. If a mailbox does not exist or is empty, it |
| 20814 | is assumed to match the current transport. If the start of a mailbox doesn't |
| 20815 | match any string, or if the transport named for a given string is not defined, |
| 20816 | delivery is deferred. |
| 20817 | |
| 20818 | |
| 20819 | .option file_must_exist appendfile boolean false |
| 20820 | If this option is true, the file specified by the &%file%& option must exist. |
| 20821 | A temporary error occurs if it does not, causing delivery to be deferred. |
| 20822 | If this option is false, the file is created if it does not exist. |
| 20823 | |
| 20824 | |
| 20825 | .option lock_fcntl_timeout appendfile time 0s |
| 20826 | .cindex "timeout" "mailbox locking" |
| 20827 | .cindex "mailbox" "locking, blocking and non-blocking" |
| 20828 | .cindex "locking files" |
| 20829 | By default, the &(appendfile)& transport uses non-blocking calls to &[fcntl()]& |
| 20830 | when locking an open mailbox file. If the call fails, the delivery process |
| 20831 | sleeps for &%lock_interval%& and tries again, up to &%lock_retries%& times. |
| 20832 | Non-blocking calls are used so that the file is not kept open during the wait |
| 20833 | for the lock; the reason for this is to make it as safe as possible for |
| 20834 | deliveries over NFS in the case when processes might be accessing an NFS |
| 20835 | mailbox without using a lock file. This should not be done, but |
| 20836 | misunderstandings and hence misconfigurations are not unknown. |
| 20837 | |
| 20838 | On a busy system, however, the performance of a non-blocking lock approach is |
| 20839 | not as good as using a blocking lock with a timeout. In this case, the waiting |
| 20840 | is done inside the system call, and Exim's delivery process acquires the lock |
| 20841 | and can proceed as soon as the previous lock holder releases it. |
| 20842 | |
| 20843 | If &%lock_fcntl_timeout%& is set to a non-zero time, blocking locks, with that |
| 20844 | timeout, are used. There may still be some retrying: the maximum number of |
| 20845 | retries is |
| 20846 | .code |
| 20847 | (lock_retries * lock_interval) / lock_fcntl_timeout |
| 20848 | .endd |
| 20849 | rounded up to the next whole number. In other words, the total time during |
| 20850 | which &(appendfile)& is trying to get a lock is roughly the same, unless |
| 20851 | &%lock_fcntl_timeout%& is set very large. |
| 20852 | |
| 20853 | You should consider setting this option if you are getting a lot of delayed |
| 20854 | local deliveries because of errors of the form |
| 20855 | .code |
| 20856 | failed to lock mailbox /some/file (fcntl) |
| 20857 | .endd |
| 20858 | |
| 20859 | .option lock_flock_timeout appendfile time 0s |
| 20860 | This timeout applies to file locking when using &[flock()]& (see |
| 20861 | &%use_flock%&); the timeout operates in a similar manner to |
| 20862 | &%lock_fcntl_timeout%&. |
| 20863 | |
| 20864 | |
| 20865 | .option lock_interval appendfile time 3s |
| 20866 | This specifies the time to wait between attempts to lock the file. See below |
| 20867 | for details of locking. |
| 20868 | |
| 20869 | |
| 20870 | .option lock_retries appendfile integer 10 |
| 20871 | This specifies the maximum number of attempts to lock the file. A value of zero |
| 20872 | is treated as 1. See below for details of locking. |
| 20873 | |
| 20874 | |
| 20875 | .option lockfile_mode appendfile "octal integer" 0600 |
| 20876 | This specifies the mode of the created lock file, when a lock file is being |
| 20877 | used (see &%use_lockfile%& and &%use_mbx_lock%&). |
| 20878 | |
| 20879 | |
| 20880 | .option lockfile_timeout appendfile time 30m |
| 20881 | .cindex "timeout" "mailbox locking" |
| 20882 | When a lock file is being used (see &%use_lockfile%&), if a lock file already |
| 20883 | exists and is older than this value, it is assumed to have been left behind by |
| 20884 | accident, and Exim attempts to remove it. |
| 20885 | |
| 20886 | |
| 20887 | .option mailbox_filecount appendfile string&!! unset |
| 20888 | .cindex "mailbox" "specifying size of" |
| 20889 | .cindex "size" "of mailbox" |
| 20890 | If this option is set, it is expanded, and the result is taken as the current |
| 20891 | number of files in the mailbox. It must be a decimal number, optionally |
| 20892 | followed by K or M. This provides a way of obtaining this information from an |
| 20893 | external source that maintains the data. |
| 20894 | |
| 20895 | |
| 20896 | .option mailbox_size appendfile string&!! unset |
| 20897 | .cindex "mailbox" "specifying size of" |
| 20898 | .cindex "size" "of mailbox" |
| 20899 | If this option is set, it is expanded, and the result is taken as the current |
| 20900 | size the mailbox. It must be a decimal number, optionally followed by K or M. |
| 20901 | This provides a way of obtaining this information from an external source that |
| 20902 | maintains the data. This is likely to be helpful for maildir deliveries where |
| 20903 | it is computationally expensive to compute the size of a mailbox. |
| 20904 | |
| 20905 | |
| 20906 | |
| 20907 | .option maildir_format appendfile boolean false |
| 20908 | .cindex "maildir format" "specifying" |
| 20909 | If this option is set with the &%directory%& option, the delivery is into a new |
| 20910 | file, in the &"maildir"& format that is used by other mail software. When the |
| 20911 | transport is activated directly from a &(redirect)& router (for example, the |
| 20912 | &(address_file)& transport in the default configuration), setting |
| 20913 | &%maildir_format%& causes the path received from the router to be treated as a |
| 20914 | directory, whether or not it ends with &`/`&. This option is available only if |
| 20915 | SUPPORT_MAILDIR is present in &_Local/Makefile_&. See section |
| 20916 | &<<SECTmaildirdelivery>>& below for further details. |
| 20917 | |
| 20918 | |
| 20919 | .option maildir_quota_directory_regex appendfile string "See below" |
| 20920 | .cindex "maildir format" "quota; directories included in" |
| 20921 | .cindex "quota" "maildir; directories included in" |
| 20922 | This option is relevant only when &%maildir_use_size_file%& is set. It defines |
| 20923 | a regular expression for specifying directories, relative to the quota |
| 20924 | directory (see &%quota_directory%&), that should be included in the quota |
| 20925 | calculation. The default value is: |
| 20926 | .code |
| 20927 | maildir_quota_directory_regex = ^(?:cur|new|\..*)$ |
| 20928 | .endd |
| 20929 | This includes the &_cur_& and &_new_& directories, and any maildir++ folders |
| 20930 | (directories whose names begin with a dot). If you want to exclude the |
| 20931 | &_Trash_& |
| 20932 | folder from the count (as some sites do), you need to change this setting to |
| 20933 | .code |
| 20934 | maildir_quota_directory_regex = ^(?:cur|new|\.(?!Trash).*)$ |
| 20935 | .endd |
| 20936 | This uses a negative lookahead in the regular expression to exclude the |
| 20937 | directory whose name is &_.Trash_&. When a directory is excluded from quota |
| 20938 | calculations, quota processing is bypassed for any messages that are delivered |
| 20939 | directly into that directory. |
| 20940 | |
| 20941 | |
| 20942 | .option maildir_retries appendfile integer 10 |
| 20943 | This option specifies the number of times to retry when writing a file in |
| 20944 | &"maildir"& format. See section &<<SECTmaildirdelivery>>& below. |
| 20945 | |
| 20946 | |
| 20947 | .option maildir_tag appendfile string&!! unset |
| 20948 | This option applies only to deliveries in maildir format, and is described in |
| 20949 | section &<<SECTmaildirdelivery>>& below. |
| 20950 | |
| 20951 | |
| 20952 | .option maildir_use_size_file appendfile&!! boolean false |
| 20953 | .cindex "maildir format" "&_maildirsize_& file" |
| 20954 | The result of string expansion for this option must be a valid boolean value. |
| 20955 | If it is true, it enables support for &_maildirsize_& files. Exim |
| 20956 | creates a &_maildirsize_& file in a maildir if one does not exist, taking the |
| 20957 | quota from the &%quota%& option of the transport. If &%quota%& is unset, the |
| 20958 | value is zero. See &%maildir_quota_directory_regex%& above and section |
| 20959 | &<<SECTmaildirdelivery>>& below for further details. |
| 20960 | |
| 20961 | .option maildirfolder_create_regex appendfile string unset |
| 20962 | .cindex "maildir format" "&_maildirfolder_& file" |
| 20963 | .cindex "&_maildirfolder_&, creating" |
| 20964 | The value of this option is a regular expression. If it is unset, it has no |
| 20965 | effect. Otherwise, before a maildir delivery takes place, the pattern is |
| 20966 | matched against the name of the maildir directory, that is, the directory |
| 20967 | containing the &_new_& and &_tmp_& subdirectories that will be used for the |
| 20968 | delivery. If there is a match, Exim checks for the existence of a file called |
| 20969 | &_maildirfolder_& in the directory, and creates it if it does not exist. |
| 20970 | See section &<<SECTmaildirdelivery>>& for more details. |
| 20971 | |
| 20972 | |
| 20973 | .option mailstore_format appendfile boolean false |
| 20974 | .cindex "mailstore format" "specifying" |
| 20975 | If this option is set with the &%directory%& option, the delivery is into two |
| 20976 | new files in &"mailstore"& format. The option is available only if |
| 20977 | SUPPORT_MAILSTORE is present in &_Local/Makefile_&. See section &<<SECTopdir>>& |
| 20978 | below for further details. |
| 20979 | |
| 20980 | |
| 20981 | .option mailstore_prefix appendfile string&!! unset |
| 20982 | This option applies only to deliveries in mailstore format, and is described in |
| 20983 | section &<<SECTopdir>>& below. |
| 20984 | |
| 20985 | |
| 20986 | .option mailstore_suffix appendfile string&!! unset |
| 20987 | This option applies only to deliveries in mailstore format, and is described in |
| 20988 | section &<<SECTopdir>>& below. |
| 20989 | |
| 20990 | |
| 20991 | .option mbx_format appendfile boolean false |
| 20992 | .cindex "locking files" |
| 20993 | .cindex "file" "locking" |
| 20994 | .cindex "file" "MBX format" |
| 20995 | .cindex "MBX format, specifying" |
| 20996 | This option is available only if Exim has been compiled with SUPPORT_MBX |
| 20997 | set in &_Local/Makefile_&. If &%mbx_format%& is set with the &%file%& option, |
| 20998 | the message is appended to the mailbox file in MBX format instead of |
| 20999 | traditional Unix format. This format is supported by Pine4 and its associated |
| 21000 | IMAP and POP daemons, by means of the &'c-client'& library that they all use. |
| 21001 | |
| 21002 | &*Note*&: The &%message_prefix%& and &%message_suffix%& options are not |
| 21003 | automatically changed by the use of &%mbx_format%&. They should normally be set |
| 21004 | empty when using MBX format, so this option almost always appears in this |
| 21005 | combination: |
| 21006 | .code |
| 21007 | mbx_format = true |
| 21008 | message_prefix = |
| 21009 | message_suffix = |
| 21010 | .endd |
| 21011 | If none of the locking options are mentioned in the configuration, |
| 21012 | &%use_mbx_lock%& is assumed and the other locking options default to false. It |
| 21013 | is possible to specify the other kinds of locking with &%mbx_format%&, but |
| 21014 | &%use_fcntl_lock%& and &%use_mbx_lock%& are mutually exclusive. MBX locking |
| 21015 | interworks with &'c-client'&, providing for shared access to the mailbox. It |
| 21016 | should not be used if any program that does not use this form of locking is |
| 21017 | going to access the mailbox, nor should it be used if the mailbox file is NFS |
| 21018 | mounted, because it works only when the mailbox is accessed from a single host. |
| 21019 | |
| 21020 | If you set &%use_fcntl_lock%& with an MBX-format mailbox, you cannot use |
| 21021 | the standard version of &'c-client'&, because as long as it has a mailbox open |
| 21022 | (this means for the whole of a Pine or IMAP session), Exim will not be able to |
| 21023 | append messages to it. |
| 21024 | |
| 21025 | |
| 21026 | .option message_prefix appendfile string&!! "see below" |
| 21027 | .cindex "&""From""& line" |
| 21028 | The string specified here is expanded and output at the start of every message. |
| 21029 | The default is unset unless &%file%& is specified and &%use_bsmtp%& is not set, |
| 21030 | in which case it is: |
| 21031 | .code |
| 21032 | message_prefix = "From ${if def:return_path{$return_path}\ |
| 21033 | {MAILER-DAEMON}} $tod_bsdinbox\n" |
| 21034 | .endd |
| 21035 | &*Note:*& If you set &%use_crlf%& true, you must change any occurrences of |
| 21036 | &`\n`& to &`\r\n`& in &%message_prefix%&. |
| 21037 | |
| 21038 | .option message_suffix appendfile string&!! "see below" |
| 21039 | The string specified here is expanded and output at the end of every message. |
| 21040 | The default is unset unless &%file%& is specified and &%use_bsmtp%& is not set, |
| 21041 | in which case it is a single newline character. The suffix can be suppressed by |
| 21042 | setting |
| 21043 | .code |
| 21044 | message_suffix = |
| 21045 | .endd |
| 21046 | &*Note:*& If you set &%use_crlf%& true, you must change any occurrences of |
| 21047 | &`\n`& to &`\r\n`& in &%message_suffix%&. |
| 21048 | |
| 21049 | .option mode appendfile "octal integer" 0600 |
| 21050 | If the output file is created, it is given this mode. If it already exists and |
| 21051 | has wider permissions, they are reduced to this mode. If it has narrower |
| 21052 | permissions, an error occurs unless &%mode_fail_narrower%& is false. However, |
| 21053 | if the delivery is the result of a &%save%& command in a filter file specifying |
| 21054 | a particular mode, the mode of the output file is always forced to take that |
| 21055 | value, and this option is ignored. |
| 21056 | |
| 21057 | |
| 21058 | .option mode_fail_narrower appendfile boolean true |
| 21059 | This option applies in the case when an existing mailbox file has a narrower |
| 21060 | mode than that specified by the &%mode%& option. If &%mode_fail_narrower%& is |
| 21061 | true, the delivery is deferred (&"mailbox has the wrong mode"&); otherwise Exim |
| 21062 | continues with the delivery attempt, using the existing mode of the file. |
| 21063 | |
| 21064 | |
| 21065 | .option notify_comsat appendfile boolean false |
| 21066 | If this option is true, the &'comsat'& daemon is notified after every |
| 21067 | successful delivery to a user mailbox. This is the daemon that notifies logged |
| 21068 | on users about incoming mail. |
| 21069 | |
| 21070 | |
| 21071 | .option quota appendfile string&!! unset |
| 21072 | .cindex "quota" "imposed by Exim" |
| 21073 | This option imposes a limit on the size of the file to which Exim is appending, |
| 21074 | or to the total space used in the directory tree when the &%directory%& option |
| 21075 | is set. In the latter case, computation of the space used is expensive, because |
| 21076 | all the files in the directory (and any sub-directories) have to be |
| 21077 | individually inspected and their sizes summed. (See &%quota_size_regex%& and |
| 21078 | &%maildir_use_size_file%& for ways to avoid this in environments where users |
| 21079 | have no shell access to their mailboxes). |
| 21080 | |
| 21081 | As there is no interlock against two simultaneous deliveries into a |
| 21082 | multi-file mailbox, it is possible for the quota to be overrun in this case. |
| 21083 | For single-file mailboxes, of course, an interlock is a necessity. |
| 21084 | |
| 21085 | A file's size is taken as its &'used'& value. Because of blocking effects, this |
| 21086 | may be a lot less than the actual amount of disk space allocated to the file. |
| 21087 | If the sizes of a number of files are being added up, the rounding effect can |
| 21088 | become quite noticeable, especially on systems that have large block sizes. |
| 21089 | Nevertheless, it seems best to stick to the &'used'& figure, because this is |
| 21090 | the obvious value which users understand most easily. |
| 21091 | |
| 21092 | The value of the option is expanded, and must then be a numerical value |
| 21093 | (decimal point allowed), optionally followed by one of the letters K, M, or G, |
| 21094 | for kilobytes, megabytes, or gigabytes. If Exim is running on a system with |
| 21095 | large file support (Linux and FreeBSD have this), mailboxes larger than 2G can |
| 21096 | be handled. |
| 21097 | |
| 21098 | &*Note*&: A value of zero is interpreted as &"no quota"&. |
| 21099 | |
| 21100 | The expansion happens while Exim is running as root, before it changes uid for |
| 21101 | the delivery. This means that files that are inaccessible to the end user can |
| 21102 | be used to hold quota values that are looked up in the expansion. When delivery |
| 21103 | fails because this quota is exceeded, the handling of the error is as for |
| 21104 | system quota failures. |
| 21105 | |
| 21106 | By default, Exim's quota checking mimics system quotas, and restricts the |
| 21107 | mailbox to the specified maximum size, though the value is not accurate to the |
| 21108 | last byte, owing to separator lines and additional headers that may get added |
| 21109 | during message delivery. When a mailbox is nearly full, large messages may get |
| 21110 | refused even though small ones are accepted, because the size of the current |
| 21111 | message is added to the quota when the check is made. This behaviour can be |
| 21112 | changed by setting &%quota_is_inclusive%& false. When this is done, the check |
| 21113 | for exceeding the quota does not include the current message. Thus, deliveries |
| 21114 | continue until the quota has been exceeded; thereafter, no further messages are |
| 21115 | delivered. See also &%quota_warn_threshold%&. |
| 21116 | |
| 21117 | |
| 21118 | .option quota_directory appendfile string&!! unset |
| 21119 | This option defines the directory to check for quota purposes when delivering |
| 21120 | into individual files. The default is the delivery directory, or, if a file |
| 21121 | called &_maildirfolder_& exists in a maildir directory, the parent of the |
| 21122 | delivery directory. |
| 21123 | |
| 21124 | |
| 21125 | .option quota_filecount appendfile string&!! 0 |
| 21126 | This option applies when the &%directory%& option is set. It limits the total |
| 21127 | number of files in the directory (compare the inode limit in system quotas). It |
| 21128 | can only be used if &%quota%& is also set. The value is expanded; an expansion |
| 21129 | failure causes delivery to be deferred. A value of zero is interpreted as |
| 21130 | &"no quota"&. |
| 21131 | |
| 21132 | |
| 21133 | .option quota_is_inclusive appendfile boolean true |
| 21134 | See &%quota%& above. |
| 21135 | |
| 21136 | |
| 21137 | .option quota_size_regex appendfile string unset |
| 21138 | This option applies when one of the delivery modes that writes a separate file |
| 21139 | for each message is being used. When Exim wants to find the size of one of |
| 21140 | these files in order to test the quota, it first checks &%quota_size_regex%&. |
| 21141 | If this is set to a regular expression that matches the file name, and it |
| 21142 | captures one string, that string is interpreted as a representation of the |
| 21143 | file's size. The value of &%quota_size_regex%& is not expanded. |
| 21144 | |
| 21145 | This feature is useful only when users have no shell access to their mailboxes |
| 21146 | &-- otherwise they could defeat the quota simply by renaming the files. This |
| 21147 | facility can be used with maildir deliveries, by setting &%maildir_tag%& to add |
| 21148 | the file length to the file name. For example: |
| 21149 | .code |
| 21150 | maildir_tag = ,S=$message_size |
| 21151 | quota_size_regex = ,S=(\d+) |
| 21152 | .endd |
| 21153 | An alternative to &$message_size$& is &$message_linecount$&, which contains the |
| 21154 | number of lines in the message. |
| 21155 | |
| 21156 | The regular expression should not assume that the length is at the end of the |
| 21157 | file name (even though &%maildir_tag%& puts it there) because maildir MUAs |
| 21158 | sometimes add other information onto the ends of message file names. |
| 21159 | |
| 21160 | Section &<<SECID136>>& contains further information. |
| 21161 | |
| 21162 | |
| 21163 | .option quota_warn_message appendfile string&!! "see below" |
| 21164 | See below for the use of this option. If it is not set when |
| 21165 | &%quota_warn_threshold%& is set, it defaults to |
| 21166 | .code |
| 21167 | quota_warn_message = "\ |
| 21168 | To: $local_part@$domain\n\ |
| 21169 | Subject: Your mailbox\n\n\ |
| 21170 | This message is automatically created \ |
| 21171 | by mail delivery software.\n\n\ |
| 21172 | The size of your mailbox has exceeded \ |
| 21173 | a warning threshold that is\n\ |
| 21174 | set by the system administrator.\n" |
| 21175 | .endd |
| 21176 | |
| 21177 | |
| 21178 | .option quota_warn_threshold appendfile string&!! 0 |
| 21179 | .cindex "quota" "warning threshold" |
| 21180 | .cindex "mailbox" "size warning" |
| 21181 | .cindex "size" "of mailbox" |
| 21182 | This option is expanded in the same way as &%quota%& (see above). If the |
| 21183 | resulting value is greater than zero, and delivery of the message causes the |
| 21184 | size of the file or total space in the directory tree to cross the given |
| 21185 | threshold, a warning message is sent. If &%quota%& is also set, the threshold |
| 21186 | may be specified as a percentage of it by following the value with a percent |
| 21187 | sign. For example: |
| 21188 | .code |
| 21189 | quota = 10M |
| 21190 | quota_warn_threshold = 75% |
| 21191 | .endd |
| 21192 | If &%quota%& is not set, a setting of &%quota_warn_threshold%& that ends with a |
| 21193 | percent sign is ignored. |
| 21194 | |
| 21195 | The warning message itself is specified by the &%quota_warn_message%& option, |
| 21196 | and it must start with a &'To:'& header line containing the recipient(s) of the |
| 21197 | warning message. These do not necessarily have to include the recipient(s) of |
| 21198 | the original message. A &'Subject:'& line should also normally be supplied. You |
| 21199 | can include any other header lines that you want. If you do not include a |
| 21200 | &'From:'& line, the default is: |
| 21201 | .code |
| 21202 | From: Mail Delivery System <mailer-daemon@$qualify_domain_sender> |
| 21203 | .endd |
| 21204 | .oindex &%errors_reply_to%& |
| 21205 | If you supply a &'Reply-To:'& line, it overrides the global &%errors_reply_to%& |
| 21206 | option. |
| 21207 | |
| 21208 | The &%quota%& option does not have to be set in order to use this option; they |
| 21209 | are independent of one another except when the threshold is specified as a |
| 21210 | percentage. |
| 21211 | |
| 21212 | |
| 21213 | .option use_bsmtp appendfile boolean false |
| 21214 | .cindex "envelope sender" |
| 21215 | If this option is set true, &(appendfile)& writes messages in &"batch SMTP"& |
| 21216 | format, with the envelope sender and recipient(s) included as SMTP commands. If |
| 21217 | you want to include a leading HELO command with such messages, you can do |
| 21218 | so by setting the &%message_prefix%& option. See section &<<SECTbatchSMTP>>& |
| 21219 | for details of batch SMTP. |
| 21220 | |
| 21221 | |
| 21222 | .option use_crlf appendfile boolean false |
| 21223 | .cindex "carriage return" |
| 21224 | .cindex "linefeed" |
| 21225 | This option causes lines to be terminated with the two-character CRLF sequence |
| 21226 | (carriage return, linefeed) instead of just a linefeed character. In the case |
| 21227 | of batched SMTP, the byte sequence written to the file is then an exact image |
| 21228 | of what would be sent down a real SMTP connection. |
| 21229 | |
| 21230 | &*Note:*& The contents of the &%message_prefix%& and &%message_suffix%& options |
| 21231 | (which are used to supply the traditional &"From&~"& and blank line separators |
| 21232 | in Berkeley-style mailboxes) are written verbatim, so must contain their own |
| 21233 | carriage return characters if these are needed. In cases where these options |
| 21234 | have non-empty defaults, the values end with a single linefeed, so they must be |
| 21235 | changed to end with &`\r\n`& if &%use_crlf%& is set. |
| 21236 | |
| 21237 | |
| 21238 | .option use_fcntl_lock appendfile boolean "see below" |
| 21239 | This option controls the use of the &[fcntl()]& function to lock a file for |
| 21240 | exclusive use when a message is being appended. It is set by default unless |
| 21241 | &%use_flock_lock%& is set. Otherwise, it should be turned off only if you know |
| 21242 | that all your MUAs use lock file locking. When both &%use_fcntl_lock%& and |
| 21243 | &%use_flock_lock%& are unset, &%use_lockfile%& must be set. |
| 21244 | |
| 21245 | |
| 21246 | .option use_flock_lock appendfile boolean false |
| 21247 | This option is provided to support the use of &[flock()]& for file locking, for |
| 21248 | the few situations where it is needed. Most modern operating systems support |
| 21249 | &[fcntl()]& and &[lockf()]& locking, and these two functions interwork with |
| 21250 | each other. Exim uses &[fcntl()]& locking by default. |
| 21251 | |
| 21252 | This option is required only if you are using an operating system where |
| 21253 | &[flock()]& is used by programs that access mailboxes (typically MUAs), and |
| 21254 | where &[flock()]& does not correctly interwork with &[fcntl()]&. You can use |
| 21255 | both &[fcntl()]& and &[flock()]& locking simultaneously if you want. |
| 21256 | |
| 21257 | .cindex "Solaris" "&[flock()]& support" |
| 21258 | Not all operating systems provide &[flock()]&. Some versions of Solaris do not |
| 21259 | have it (and some, I think, provide a not quite right version built on top of |
| 21260 | &[lockf()]&). If the OS does not have &[flock()]&, Exim will be built without |
| 21261 | the ability to use it, and any attempt to do so will cause a configuration |
| 21262 | error. |
| 21263 | |
| 21264 | &*Warning*&: &[flock()]& locks do not work on NFS files (unless &[flock()]& |
| 21265 | is just being mapped onto &[fcntl()]& by the OS). |
| 21266 | |
| 21267 | |
| 21268 | .option use_lockfile appendfile boolean "see below" |
| 21269 | If this option is turned off, Exim does not attempt to create a lock file when |
| 21270 | appending to a mailbox file. In this situation, the only locking is by |
| 21271 | &[fcntl()]&. You should only turn &%use_lockfile%& off if you are absolutely |
| 21272 | sure that every MUA that is ever going to look at your users' mailboxes uses |
| 21273 | &[fcntl()]& rather than a lock file, and even then only when you are not |
| 21274 | delivering over NFS from more than one host. |
| 21275 | |
| 21276 | .cindex "NFS" "lock file" |
| 21277 | In order to append to an NFS file safely from more than one host, it is |
| 21278 | necessary to take out a lock &'before'& opening the file, and the lock file |
| 21279 | achieves this. Otherwise, even with &[fcntl()]& locking, there is a risk of |
| 21280 | file corruption. |
| 21281 | |
| 21282 | The &%use_lockfile%& option is set by default unless &%use_mbx_lock%& is set. |
| 21283 | It is not possible to turn both &%use_lockfile%& and &%use_fcntl_lock%& off, |
| 21284 | except when &%mbx_format%& is set. |
| 21285 | |
| 21286 | |
| 21287 | .option use_mbx_lock appendfile boolean "see below" |
| 21288 | This option is available only if Exim has been compiled with SUPPORT_MBX |
| 21289 | set in &_Local/Makefile_&. Setting the option specifies that special MBX |
| 21290 | locking rules be used. It is set by default if &%mbx_format%& is set and none |
| 21291 | of the locking options are mentioned in the configuration. The locking rules |
| 21292 | are the same as are used by the &'c-client'& library that underlies Pine and |
| 21293 | the IMAP4 and POP daemons that come with it (see the discussion below). The |
| 21294 | rules allow for shared access to the mailbox. However, this kind of locking |
| 21295 | does not work when the mailbox is NFS mounted. |
| 21296 | |
| 21297 | You can set &%use_mbx_lock%& with either (or both) of &%use_fcntl_lock%& and |
| 21298 | &%use_flock_lock%& to control what kind of locking is used in implementing the |
| 21299 | MBX locking rules. The default is to use &[fcntl()]& if &%use_mbx_lock%& is set |
| 21300 | without &%use_fcntl_lock%& or &%use_flock_lock%&. |
| 21301 | |
| 21302 | |
| 21303 | |
| 21304 | |
| 21305 | .section "Operational details for appending" "SECTopappend" |
| 21306 | .cindex "appending to a file" |
| 21307 | .cindex "file" "appending" |
| 21308 | Before appending to a file, the following preparations are made: |
| 21309 | |
| 21310 | .ilist |
| 21311 | If the name of the file is &_/dev/null_&, no action is taken, and a success |
| 21312 | return is given. |
| 21313 | |
| 21314 | .next |
| 21315 | .cindex "directory creation" |
| 21316 | If any directories on the file's path are missing, Exim creates them if the |
| 21317 | &%create_directory%& option is set. A created directory's mode is given by the |
| 21318 | &%directory_mode%& option. |
| 21319 | |
| 21320 | .next |
| 21321 | If &%file_format%& is set, the format of an existing file is checked. If this |
| 21322 | indicates that a different transport should be used, control is passed to that |
| 21323 | transport. |
| 21324 | |
| 21325 | .next |
| 21326 | .cindex "file" "locking" |
| 21327 | .cindex "locking files" |
| 21328 | .cindex "NFS" "lock file" |
| 21329 | If &%use_lockfile%& is set, a lock file is built in a way that will work |
| 21330 | reliably over NFS, as follows: |
| 21331 | |
| 21332 | .olist |
| 21333 | Create a &"hitching post"& file whose name is that of the lock file with the |
| 21334 | current time, primary host name, and process id added, by opening for writing |
| 21335 | as a new file. If this fails with an access error, delivery is deferred. |
| 21336 | .next |
| 21337 | Close the hitching post file, and hard link it to the lock file name. |
| 21338 | .next |
| 21339 | If the call to &[link()]& succeeds, creation of the lock file has succeeded. |
| 21340 | Unlink the hitching post name. |
| 21341 | .next |
| 21342 | Otherwise, use &[stat()]& to get information about the hitching post file, and |
| 21343 | then unlink hitching post name. If the number of links is exactly two, creation |
| 21344 | of the lock file succeeded but something (for example, an NFS server crash and |
| 21345 | restart) caused this fact not to be communicated to the &[link()]& call. |
| 21346 | .next |
| 21347 | If creation of the lock file failed, wait for &%lock_interval%& and try again, |
| 21348 | up to &%lock_retries%& times. However, since any program that writes to a |
| 21349 | mailbox should complete its task very quickly, it is reasonable to time out old |
| 21350 | lock files that are normally the result of user agent and system crashes. If an |
| 21351 | existing lock file is older than &%lockfile_timeout%& Exim attempts to unlink |
| 21352 | it before trying again. |
| 21353 | .endlist olist |
| 21354 | |
| 21355 | .next |
| 21356 | A call is made to &[lstat()]& to discover whether the main file exists, and if |
| 21357 | so, what its characteristics are. If &[lstat()]& fails for any reason other |
| 21358 | than non-existence, delivery is deferred. |
| 21359 | |
| 21360 | .next |
| 21361 | .cindex "symbolic link" "to mailbox" |
| 21362 | .cindex "mailbox" "symbolic link" |
| 21363 | If the file does exist and is a symbolic link, delivery is deferred, unless the |
| 21364 | &%allow_symlink%& option is set, in which case the ownership of the link is |
| 21365 | checked, and then &[stat()]& is called to find out about the real file, which |
| 21366 | is then subjected to the checks below. The check on the top-level link |
| 21367 | ownership prevents one user creating a link for another's mailbox in a sticky |
| 21368 | directory, though allowing symbolic links in this case is definitely not a good |
| 21369 | idea. If there is a chain of symbolic links, the intermediate ones are not |
| 21370 | checked. |
| 21371 | |
| 21372 | .next |
| 21373 | If the file already exists but is not a regular file, or if the file's owner |
| 21374 | and group (if the group is being checked &-- see &%check_group%& above) are |
| 21375 | different from the user and group under which the delivery is running, |
| 21376 | delivery is deferred. |
| 21377 | |
| 21378 | .next |
| 21379 | If the file's permissions are more generous than specified, they are reduced. |
| 21380 | If they are insufficient, delivery is deferred, unless &%mode_fail_narrower%& |
| 21381 | is set false, in which case the delivery is tried using the existing |
| 21382 | permissions. |
| 21383 | |
| 21384 | .next |
| 21385 | The file's inode number is saved, and the file is then opened for appending. |
| 21386 | If this fails because the file has vanished, &(appendfile)& behaves as if it |
| 21387 | hadn't existed (see below). For any other failures, delivery is deferred. |
| 21388 | |
| 21389 | .next |
| 21390 | If the file is opened successfully, check that the inode number hasn't |
| 21391 | changed, that it is still a regular file, and that the owner and permissions |
| 21392 | have not changed. If anything is wrong, defer delivery and freeze the message. |
| 21393 | |
| 21394 | .next |
| 21395 | If the file did not exist originally, defer delivery if the &%file_must_exist%& |
| 21396 | option is set. Otherwise, check that the file is being created in a permitted |
| 21397 | directory if the &%create_file%& option is set (deferring on failure), and then |
| 21398 | open for writing as a new file, with the O_EXCL and O_CREAT options, |
| 21399 | except when dealing with a symbolic link (the &%allow_symlink%& option must be |
| 21400 | set). In this case, which can happen if the link points to a non-existent file, |
| 21401 | the file is opened for writing using O_CREAT but not O_EXCL, because |
| 21402 | that prevents link following. |
| 21403 | |
| 21404 | .next |
| 21405 | .cindex "loop" "while file testing" |
| 21406 | If opening fails because the file exists, obey the tests given above for |
| 21407 | existing files. However, to avoid looping in a situation where the file is |
| 21408 | being continuously created and destroyed, the exists/not-exists loop is broken |
| 21409 | after 10 repetitions, and the message is then frozen. |
| 21410 | |
| 21411 | .next |
| 21412 | If opening fails with any other error, defer delivery. |
| 21413 | |
| 21414 | .next |
| 21415 | .cindex "file" "locking" |
| 21416 | .cindex "locking files" |
| 21417 | Once the file is open, unless both &%use_fcntl_lock%& and &%use_flock_lock%& |
| 21418 | are false, it is locked using &[fcntl()]& or &[flock()]& or both. If |
| 21419 | &%use_mbx_lock%& is false, an exclusive lock is requested in each case. |
| 21420 | However, if &%use_mbx_lock%& is true, Exim takes out a shared lock on the open |
| 21421 | file, and an exclusive lock on the file whose name is |
| 21422 | .code |
| 21423 | /tmp/.<device-number>.<inode-number> |
| 21424 | .endd |
| 21425 | using the device and inode numbers of the open mailbox file, in accordance with |
| 21426 | the MBX locking rules. This file is created with a mode that is specified by |
| 21427 | the &%lockfile_mode%& option. |
| 21428 | |
| 21429 | If Exim fails to lock the file, there are two possible courses of action, |
| 21430 | depending on the value of the locking timeout. This is obtained from |
| 21431 | &%lock_fcntl_timeout%& or &%lock_flock_timeout%&, as appropriate. |
| 21432 | |
| 21433 | If the timeout value is zero, the file is closed, Exim waits for |
| 21434 | &%lock_interval%&, and then goes back and re-opens the file as above and tries |
| 21435 | to lock it again. This happens up to &%lock_retries%& times, after which the |
| 21436 | delivery is deferred. |
| 21437 | |
| 21438 | If the timeout has a value greater than zero, blocking calls to &[fcntl()]& or |
| 21439 | &[flock()]& are used (with the given timeout), so there has already been some |
| 21440 | waiting involved by the time locking fails. Nevertheless, Exim does not give up |
| 21441 | immediately. It retries up to |
| 21442 | .code |
| 21443 | (lock_retries * lock_interval) / <timeout> |
| 21444 | .endd |
| 21445 | times (rounded up). |
| 21446 | .endlist |
| 21447 | |
| 21448 | At the end of delivery, Exim closes the file (which releases the &[fcntl()]& |
| 21449 | and/or &[flock()]& locks) and then deletes the lock file if one was created. |
| 21450 | |
| 21451 | |
| 21452 | .section "Operational details for delivery to a new file" "SECTopdir" |
| 21453 | .cindex "delivery" "to single file" |
| 21454 | .cindex "&""From""& line" |
| 21455 | When the &%directory%& option is set instead of &%file%&, each message is |
| 21456 | delivered into a newly-created file or set of files. When &(appendfile)& is |
| 21457 | activated directly from a &(redirect)& router, neither &%file%& nor |
| 21458 | &%directory%& is normally set, because the path for delivery is supplied by the |
| 21459 | router. (See for example, the &(address_file)& transport in the default |
| 21460 | configuration.) In this case, delivery is to a new file if either the path name |
| 21461 | ends in &`/`&, or the &%maildir_format%& or &%mailstore_format%& option is set. |
| 21462 | |
| 21463 | No locking is required while writing the message to a new file, so the various |
| 21464 | locking options of the transport are ignored. The &"From"& line that by default |
| 21465 | separates messages in a single file is not normally needed, nor is the escaping |
| 21466 | of message lines that start with &"From"&, and there is no need to ensure a |
| 21467 | newline at the end of each message. Consequently, the default values for |
| 21468 | &%check_string%&, &%message_prefix%&, and &%message_suffix%& are all unset when |
| 21469 | any of &%directory%&, &%maildir_format%&, or &%mailstore_format%& is set. |
| 21470 | |
| 21471 | If Exim is required to check a &%quota%& setting, it adds up the sizes of all |
| 21472 | the files in the delivery directory by default. However, you can specify a |
| 21473 | different directory by setting &%quota_directory%&. Also, for maildir |
| 21474 | deliveries (see below) the &_maildirfolder_& convention is honoured. |
| 21475 | |
| 21476 | |
| 21477 | .cindex "maildir format" |
| 21478 | .cindex "mailstore format" |
| 21479 | There are three different ways in which delivery to individual files can be |
| 21480 | done, controlled by the settings of the &%maildir_format%& and |
| 21481 | &%mailstore_format%& options. Note that code to support maildir or mailstore |
| 21482 | formats is not included in the binary unless SUPPORT_MAILDIR or |
| 21483 | SUPPORT_MAILSTORE, respectively, is set in &_Local/Makefile_&. |
| 21484 | |
| 21485 | .cindex "directory creation" |
| 21486 | In all three cases an attempt is made to create the directory and any necessary |
| 21487 | sub-directories if they do not exist, provided that the &%create_directory%& |
| 21488 | option is set (the default). The location of a created directory can be |
| 21489 | constrained by setting &%create_file%&. A created directory's mode is given by |
| 21490 | the &%directory_mode%& option. If creation fails, or if the |
| 21491 | &%create_directory%& option is not set when creation is required, delivery is |
| 21492 | deferred. |
| 21493 | |
| 21494 | |
| 21495 | |
| 21496 | .section "Maildir delivery" "SECTmaildirdelivery" |
| 21497 | .cindex "maildir format" "description of" |
| 21498 | If the &%maildir_format%& option is true, Exim delivers each message by writing |
| 21499 | it to a file whose name is &_tmp/<stime>.H<mtime>P<pid>.<host>_& in the |
| 21500 | directory that is defined by the &%directory%& option (the &"delivery |
| 21501 | directory"&). If the delivery is successful, the file is renamed into the |
| 21502 | &_new_& subdirectory. |
| 21503 | |
| 21504 | In the file name, <&'stime'&> is the current time of day in seconds, and |
| 21505 | <&'mtime'&> is the microsecond fraction of the time. After a maildir delivery, |
| 21506 | Exim checks that the time-of-day clock has moved on by at least one microsecond |
| 21507 | before terminating the delivery process. This guarantees uniqueness for the |
| 21508 | file name. However, as a precaution, Exim calls &[stat()]& for the file before |
| 21509 | opening it. If any response other than ENOENT (does not exist) is given, |
| 21510 | Exim waits 2 seconds and tries again, up to &%maildir_retries%& times. |
| 21511 | |
| 21512 | Before Exim carries out a maildir delivery, it ensures that subdirectories |
| 21513 | called &_new_&, &_cur_&, and &_tmp_& exist in the delivery directory. If they |
| 21514 | do not exist, Exim tries to create them and any superior directories in their |
| 21515 | path, subject to the &%create_directory%& and &%create_file%& options. If the |
| 21516 | &%maildirfolder_create_regex%& option is set, and the regular expression it |
| 21517 | contains matches the delivery directory, Exim also ensures that a file called |
| 21518 | &_maildirfolder_& exists in the delivery directory. If a missing directory or |
| 21519 | &_maildirfolder_& file cannot be created, delivery is deferred. |
| 21520 | |
| 21521 | These features make it possible to use Exim to create all the necessary files |
| 21522 | and directories in a maildir mailbox, including subdirectories for maildir++ |
| 21523 | folders. Consider this example: |
| 21524 | .code |
| 21525 | maildir_format = true |
| 21526 | directory = /var/mail/$local_part\ |
| 21527 | ${if eq{$local_part_suffix}{}{}\ |
| 21528 | {/.${substr_1:$local_part_suffix}}} |
| 21529 | maildirfolder_create_regex = /\.[^/]+$ |
| 21530 | .endd |
| 21531 | If &$local_part_suffix$& is empty (there was no suffix for the local part), |
| 21532 | delivery is into a toplevel maildir with a name like &_/var/mail/pimbo_& (for |
| 21533 | the user called &'pimbo'&). The pattern in &%maildirfolder_create_regex%& does |
| 21534 | not match this name, so Exim will not look for or create the file |
| 21535 | &_/var/mail/pimbo/maildirfolder_&, though it will create |
| 21536 | &_/var/mail/pimbo/{cur,new,tmp}_& if necessary. |
| 21537 | |
| 21538 | However, if &$local_part_suffix$& contains &`-eximusers`& (for example), |
| 21539 | delivery is into the maildir++ folder &_/var/mail/pimbo/.eximusers_&, which |
| 21540 | does match &%maildirfolder_create_regex%&. In this case, Exim will create |
| 21541 | &_/var/mail/pimbo/.eximusers/maildirfolder_& as well as the three maildir |
| 21542 | directories &_/var/mail/pimbo/.eximusers/{cur,new,tmp}_&. |
| 21543 | |
| 21544 | &*Warning:*& Take care when setting &%maildirfolder_create_regex%& that it does |
| 21545 | not inadvertently match the toplevel maildir directory, because a |
| 21546 | &_maildirfolder_& file at top level would completely break quota calculations. |
| 21547 | |
| 21548 | .cindex "quota" "in maildir delivery" |
| 21549 | .cindex "maildir++" |
| 21550 | If Exim is required to check a &%quota%& setting before a maildir delivery, and |
| 21551 | &%quota_directory%& is not set, it looks for a file called &_maildirfolder_& in |
| 21552 | the maildir directory (alongside &_new_&, &_cur_&, &_tmp_&). If this exists, |
| 21553 | Exim assumes the directory is a maildir++ folder directory, which is one level |
| 21554 | down from the user's top level mailbox directory. This causes it to start at |
| 21555 | the parent directory instead of the current directory when calculating the |
| 21556 | amount of space used. |
| 21557 | |
| 21558 | One problem with delivering into a multi-file mailbox is that it is |
| 21559 | computationally expensive to compute the size of the mailbox for quota |
| 21560 | checking. Various approaches have been taken to reduce the amount of work |
| 21561 | needed. The next two sections describe two of them. A third alternative is to |
| 21562 | use some external process for maintaining the size data, and use the expansion |
| 21563 | of the &%mailbox_size%& option as a way of importing it into Exim. |
| 21564 | |
| 21565 | |
| 21566 | |
| 21567 | |
| 21568 | .section "Using tags to record message sizes" "SECID135" |
| 21569 | If &%maildir_tag%& is set, the string is expanded for each delivery. |
| 21570 | When the maildir file is renamed into the &_new_& sub-directory, the |
| 21571 | tag is added to its name. However, if adding the tag takes the length of the |
| 21572 | name to the point where the test &[stat()]& call fails with ENAMETOOLONG, |
| 21573 | the tag is dropped and the maildir file is created with no tag. |
| 21574 | |
| 21575 | |
| 21576 | .vindex "&$message_size$&" |
| 21577 | Tags can be used to encode the size of files in their names; see |
| 21578 | &%quota_size_regex%& above for an example. The expansion of &%maildir_tag%& |
| 21579 | happens after the message has been written. The value of the &$message_size$& |
| 21580 | variable is set to the number of bytes actually written. If the expansion is |
| 21581 | forced to fail, the tag is ignored, but a non-forced failure causes delivery to |
| 21582 | be deferred. The expanded tag may contain any printing characters except &"/"&. |
| 21583 | Non-printing characters in the string are ignored; if the resulting string is |
| 21584 | empty, it is ignored. If it starts with an alphanumeric character, a leading |
| 21585 | colon is inserted; this default has not proven to be the path that popular |
| 21586 | maildir implementations have chosen (but changing it in Exim would break |
| 21587 | backwards compatibility). |
| 21588 | |
| 21589 | For one common implementation, you might set: |
| 21590 | .code |
| 21591 | maildir_tag = ,S=${message_size} |
| 21592 | .endd |
| 21593 | but you should check the documentation of the other software to be sure. |
| 21594 | |
| 21595 | It is advisable to also set &%quota_size_regex%& when setting &%maildir_tag%& |
| 21596 | as this allows Exim to extract the size from your tag, instead of having to |
| 21597 | &[stat()]& each message file. |
| 21598 | |
| 21599 | |
| 21600 | .section "Using a maildirsize file" "SECID136" |
| 21601 | .cindex "quota" "in maildir delivery" |
| 21602 | .cindex "maildir format" "&_maildirsize_& file" |
| 21603 | If &%maildir_use_size_file%& is true, Exim implements the maildir++ rules for |
| 21604 | storing quota and message size information in a file called &_maildirsize_& |
| 21605 | within the toplevel maildir directory. If this file does not exist, Exim |
| 21606 | creates it, setting the quota from the &%quota%& option of the transport. If |
| 21607 | the maildir directory itself does not exist, it is created before any attempt |
| 21608 | to write a &_maildirsize_& file. |
| 21609 | |
| 21610 | The &_maildirsize_& file is used to hold information about the sizes of |
| 21611 | messages in the maildir, thus speeding up quota calculations. The quota value |
| 21612 | in the file is just a cache; if the quota is changed in the transport, the new |
| 21613 | value overrides the cached value when the next message is delivered. The cache |
| 21614 | is maintained for the benefit of other programs that access the maildir and |
| 21615 | need to know the quota. |
| 21616 | |
| 21617 | If the &%quota%& option in the transport is unset or zero, the &_maildirsize_& |
| 21618 | file is maintained (with a zero quota setting), but no quota is imposed. |
| 21619 | |
| 21620 | A regular expression is available for controlling which directories in the |
| 21621 | maildir participate in quota calculations when a &_maildirsizefile_& is in use. |
| 21622 | See the description of the &%maildir_quota_directory_regex%& option above for |
| 21623 | details. |
| 21624 | |
| 21625 | |
| 21626 | .section "Mailstore delivery" "SECID137" |
| 21627 | .cindex "mailstore format" "description of" |
| 21628 | If the &%mailstore_format%& option is true, each message is written as two |
| 21629 | files in the given directory. A unique base name is constructed from the |
| 21630 | message id and the current delivery process, and the files that are written use |
| 21631 | this base name plus the suffixes &_.env_& and &_.msg_&. The &_.env_& file |
| 21632 | contains the message's envelope, and the &_.msg_& file contains the message |
| 21633 | itself. The base name is placed in the variable &$mailstore_basename$&. |
| 21634 | |
| 21635 | During delivery, the envelope is first written to a file with the suffix |
| 21636 | &_.tmp_&. The &_.msg_& file is then written, and when it is complete, the |
| 21637 | &_.tmp_& file is renamed as the &_.env_& file. Programs that access messages in |
| 21638 | mailstore format should wait for the presence of both a &_.msg_& and a &_.env_& |
| 21639 | file before accessing either of them. An alternative approach is to wait for |
| 21640 | the absence of a &_.tmp_& file. |
| 21641 | |
| 21642 | The envelope file starts with any text defined by the &%mailstore_prefix%& |
| 21643 | option, expanded and terminated by a newline if there isn't one. Then follows |
| 21644 | the sender address on one line, then all the recipient addresses, one per line. |
| 21645 | There can be more than one recipient only if the &%batch_max%& option is set |
| 21646 | greater than one. Finally, &%mailstore_suffix%& is expanded and the result |
| 21647 | appended to the file, followed by a newline if it does not end with one. |
| 21648 | |
| 21649 | If expansion of &%mailstore_prefix%& or &%mailstore_suffix%& ends with a forced |
| 21650 | failure, it is ignored. Other expansion errors are treated as serious |
| 21651 | configuration errors, and delivery is deferred. The variable |
| 21652 | &$mailstore_basename$& is available for use during these expansions. |
| 21653 | |
| 21654 | |
| 21655 | .section "Non-special new file delivery" "SECID138" |
| 21656 | If neither &%maildir_format%& nor &%mailstore_format%& is set, a single new |
| 21657 | file is created directly in the named directory. For example, when delivering |
| 21658 | messages into files in batched SMTP format for later delivery to some host (see |
| 21659 | section &<<SECTbatchSMTP>>&), a setting such as |
| 21660 | .code |
| 21661 | directory = /var/bsmtp/$host |
| 21662 | .endd |
| 21663 | might be used. A message is written to a file with a temporary name, which is |
| 21664 | then renamed when the delivery is complete. The final name is obtained by |
| 21665 | expanding the contents of the &%directory_file%& option. |
| 21666 | .ecindex IIDapptra1 |
| 21667 | .ecindex IIDapptra2 |
| 21668 | |
| 21669 | |
| 21670 | |
| 21671 | |
| 21672 | |
| 21673 | |
| 21674 | . //////////////////////////////////////////////////////////////////////////// |
| 21675 | . //////////////////////////////////////////////////////////////////////////// |
| 21676 | |
| 21677 | .chapter "The autoreply transport" "CHID8" |
| 21678 | .scindex IIDauttra1 "transports" "&(autoreply)&" |
| 21679 | .scindex IIDauttra2 "&(autoreply)& transport" |
| 21680 | The &(autoreply)& transport is not a true transport in that it does not cause |
| 21681 | the message to be transmitted. Instead, it generates a new mail message as an |
| 21682 | automatic reply to the incoming message. &'References:'& and |
| 21683 | &'Auto-Submitted:'& header lines are included. These are constructed according |
| 21684 | to the rules in RFCs 2822 and 3834, respectively. |
| 21685 | |
| 21686 | If the router that passes the message to this transport does not have the |
| 21687 | &%unseen%& option set, the original message (for the current recipient) is not |
| 21688 | delivered anywhere. However, when the &%unseen%& option is set on the router |
| 21689 | that passes the message to this transport, routing of the address continues, so |
| 21690 | another router can set up a normal message delivery. |
| 21691 | |
| 21692 | |
| 21693 | The &(autoreply)& transport is usually run as the result of mail filtering, a |
| 21694 | &"vacation"& message being the standard example. However, it can also be run |
| 21695 | directly from a router like any other transport. To reduce the possibility of |
| 21696 | message cascades, messages created by the &(autoreply)& transport always have |
| 21697 | empty envelope sender addresses, like bounce messages. |
| 21698 | |
| 21699 | The parameters of the message to be sent can be specified in the configuration |
| 21700 | by options described below. However, these are used only when the address |
| 21701 | passed to the transport does not contain its own reply information. When the |
| 21702 | transport is run as a consequence of a |
| 21703 | &%mail%& |
| 21704 | or &%vacation%& command in a filter file, the parameters of the message are |
| 21705 | supplied by the filter, and passed with the address. The transport's options |
| 21706 | that define the message are then ignored (so they are not usually set in this |
| 21707 | case). The message is specified entirely by the filter or by the transport; it |
| 21708 | is never built from a mixture of options. However, the &%file_optional%&, |
| 21709 | &%mode%&, and &%return_message%& options apply in all cases. |
| 21710 | |
| 21711 | &(Autoreply)& is implemented as a local transport. When used as a result of a |
| 21712 | command in a user's filter file, &(autoreply)& normally runs under the uid and |
| 21713 | gid of the user, and with appropriate current and home directories (see chapter |
| 21714 | &<<CHAPenvironment>>&). |
| 21715 | |
| 21716 | There is a subtle difference between routing a message to a &(pipe)& transport |
| 21717 | that generates some text to be returned to the sender, and routing it to an |
| 21718 | &(autoreply)& transport. This difference is noticeable only if more than one |
| 21719 | address from the same message is so handled. In the case of a pipe, the |
| 21720 | separate outputs from the different addresses are gathered up and returned to |
| 21721 | the sender in a single message, whereas if &(autoreply)& is used, a separate |
| 21722 | message is generated for each address that is passed to it. |
| 21723 | |
| 21724 | Non-printing characters are not permitted in the header lines generated for the |
| 21725 | message that &(autoreply)& creates, with the exception of newlines that are |
| 21726 | immediately followed by white space. If any non-printing characters are found, |
| 21727 | the transport defers. |
| 21728 | Whether characters with the top bit set count as printing characters or not is |
| 21729 | controlled by the &%print_topbitchars%& global option. |
| 21730 | |
| 21731 | If any of the generic options for manipulating headers (for example, |
| 21732 | &%headers_add%&) are set on an &(autoreply)& transport, they apply to the copy |
| 21733 | of the original message that is included in the generated message when |
| 21734 | &%return_message%& is set. They do not apply to the generated message itself. |
| 21735 | |
| 21736 | .vindex "&$sender_address$&" |
| 21737 | If the &(autoreply)& transport receives return code 2 from Exim when it submits |
| 21738 | the message, indicating that there were no recipients, it does not treat this |
| 21739 | as an error. This means that autoreplies sent to &$sender_address$& when this |
| 21740 | is empty (because the incoming message is a bounce message) do not cause |
| 21741 | problems. They are just discarded. |
| 21742 | |
| 21743 | |
| 21744 | |
| 21745 | .section "Private options for autoreply" "SECID139" |
| 21746 | .cindex "options" "&(autoreply)& transport" |
| 21747 | |
| 21748 | .option bcc autoreply string&!! unset |
| 21749 | This specifies the addresses that are to receive &"blind carbon copies"& of the |
| 21750 | message when the message is specified by the transport. |
| 21751 | |
| 21752 | |
| 21753 | .option cc autoreply string&!! unset |
| 21754 | This specifies recipients of the message and the contents of the &'Cc:'& header |
| 21755 | when the message is specified by the transport. |
| 21756 | |
| 21757 | |
| 21758 | .option file autoreply string&!! unset |
| 21759 | The contents of the file are sent as the body of the message when the message |
| 21760 | is specified by the transport. If both &%file%& and &%text%& are set, the text |
| 21761 | string comes first. |
| 21762 | |
| 21763 | |
| 21764 | .option file_expand autoreply boolean false |
| 21765 | If this is set, the contents of the file named by the &%file%& option are |
| 21766 | subjected to string expansion as they are added to the message. |
| 21767 | |
| 21768 | |
| 21769 | .option file_optional autoreply boolean false |
| 21770 | If this option is true, no error is generated if the file named by the &%file%& |
| 21771 | option or passed with the address does not exist or cannot be read. |
| 21772 | |
| 21773 | |
| 21774 | .option from autoreply string&!! unset |
| 21775 | This specifies the contents of the &'From:'& header when the message is |
| 21776 | specified by the transport. |
| 21777 | |
| 21778 | |
| 21779 | .option headers autoreply string&!! unset |
| 21780 | This specifies additional RFC 2822 headers that are to be added to the message |
| 21781 | when the message is specified by the transport. Several can be given by using |
| 21782 | &"\n"& to separate them. There is no check on the format. |
| 21783 | |
| 21784 | |
| 21785 | .option log autoreply string&!! unset |
| 21786 | This option names a file in which a record of every message sent is logged when |
| 21787 | the message is specified by the transport. |
| 21788 | |
| 21789 | |
| 21790 | .option mode autoreply "octal integer" 0600 |
| 21791 | If either the log file or the &"once"& file has to be created, this mode is |
| 21792 | used. |
| 21793 | |
| 21794 | |
| 21795 | .option never_mail autoreply "address list&!!" unset |
| 21796 | If any run of the transport creates a message with a recipient that matches any |
| 21797 | item in the list, that recipient is quietly discarded. If all recipients are |
| 21798 | discarded, no message is created. This applies both when the recipients are |
| 21799 | generated by a filter and when they are specified in the transport. |
| 21800 | |
| 21801 | |
| 21802 | |
| 21803 | .option once autoreply string&!! unset |
| 21804 | This option names a file or DBM database in which a record of each &'To:'& |
| 21805 | recipient is kept when the message is specified by the transport. &*Note*&: |
| 21806 | This does not apply to &'Cc:'& or &'Bcc:'& recipients. |
| 21807 | |
| 21808 | If &%once%& is unset, or is set to an empty string, the message is always sent. |
| 21809 | By default, if &%once%& is set to a non-empty file name, the message |
| 21810 | is not sent if a potential recipient is already listed in the database. |
| 21811 | However, if the &%once_repeat%& option specifies a time greater than zero, the |
| 21812 | message is sent if that much time has elapsed since a message was last sent to |
| 21813 | this recipient. A setting of zero time for &%once_repeat%& (the default) |
| 21814 | prevents a message from being sent a second time &-- in this case, zero means |
| 21815 | infinity. |
| 21816 | |
| 21817 | If &%once_file_size%& is zero, a DBM database is used to remember recipients, |
| 21818 | and it is allowed to grow as large as necessary. If &%once_file_size%& is set |
| 21819 | greater than zero, it changes the way Exim implements the &%once%& option. |
| 21820 | Instead of using a DBM file to record every recipient it sends to, it uses a |
| 21821 | regular file, whose size will never get larger than the given value. |
| 21822 | |
| 21823 | In the file, Exim keeps a linear list of recipient addresses and the times at |
| 21824 | which they were sent messages. If the file is full when a new address needs to |
| 21825 | be added, the oldest address is dropped. If &%once_repeat%& is not set, this |
| 21826 | means that a given recipient may receive multiple messages, but at |
| 21827 | unpredictable intervals that depend on the rate of turnover of addresses in the |
| 21828 | file. If &%once_repeat%& is set, it specifies a maximum time between repeats. |
| 21829 | |
| 21830 | |
| 21831 | .option once_file_size autoreply integer 0 |
| 21832 | See &%once%& above. |
| 21833 | |
| 21834 | |
| 21835 | .option once_repeat autoreply time&!! 0s |
| 21836 | See &%once%& above. |
| 21837 | After expansion, the value of this option must be a valid time value. |
| 21838 | |
| 21839 | |
| 21840 | .option reply_to autoreply string&!! unset |
| 21841 | This specifies the contents of the &'Reply-To:'& header when the message is |
| 21842 | specified by the transport. |
| 21843 | |
| 21844 | |
| 21845 | .option return_message autoreply boolean false |
| 21846 | If this is set, a copy of the original message is returned with the new |
| 21847 | message, subject to the maximum size set in the &%return_size_limit%& global |
| 21848 | configuration option. |
| 21849 | |
| 21850 | |
| 21851 | .option subject autoreply string&!! unset |
| 21852 | This specifies the contents of the &'Subject:'& header when the message is |
| 21853 | specified by the transport. It is tempting to quote the original subject in |
| 21854 | automatic responses. For example: |
| 21855 | .code |
| 21856 | subject = Re: $h_subject: |
| 21857 | .endd |
| 21858 | There is a danger in doing this, however. It may allow a third party to |
| 21859 | subscribe your users to an opt-in mailing list, provided that the list accepts |
| 21860 | bounce messages as subscription confirmations. Well-managed lists require a |
| 21861 | non-bounce message to confirm a subscription, so the danger is relatively |
| 21862 | small. |
| 21863 | |
| 21864 | |
| 21865 | |
| 21866 | .option text autoreply string&!! unset |
| 21867 | This specifies a single string to be used as the body of the message when the |
| 21868 | message is specified by the transport. If both &%text%& and &%file%& are set, |
| 21869 | the text comes first. |
| 21870 | |
| 21871 | |
| 21872 | .option to autoreply string&!! unset |
| 21873 | This specifies recipients of the message and the contents of the &'To:'& header |
| 21874 | when the message is specified by the transport. |
| 21875 | .ecindex IIDauttra1 |
| 21876 | .ecindex IIDauttra2 |
| 21877 | |
| 21878 | |
| 21879 | |
| 21880 | |
| 21881 | . //////////////////////////////////////////////////////////////////////////// |
| 21882 | . //////////////////////////////////////////////////////////////////////////// |
| 21883 | |
| 21884 | .chapter "The lmtp transport" "CHAPLMTP" |
| 21885 | .cindex "transports" "&(lmtp)&" |
| 21886 | .cindex "&(lmtp)& transport" |
| 21887 | .cindex "LMTP" "over a pipe" |
| 21888 | .cindex "LMTP" "over a socket" |
| 21889 | The &(lmtp)& transport runs the LMTP protocol (RFC 2033) over a pipe to a |
| 21890 | specified command |
| 21891 | or by interacting with a Unix domain socket. |
| 21892 | This transport is something of a cross between the &(pipe)& and &(smtp)& |
| 21893 | transports. Exim also has support for using LMTP over TCP/IP; this is |
| 21894 | implemented as an option for the &(smtp)& transport. Because LMTP is expected |
| 21895 | to be of minority interest, the default build-time configure in &_src/EDITME_& |
| 21896 | has it commented out. You need to ensure that |
| 21897 | .code |
| 21898 | TRANSPORT_LMTP=yes |
| 21899 | .endd |
| 21900 | .cindex "options" "&(lmtp)& transport" |
| 21901 | is present in your &_Local/Makefile_& in order to have the &(lmtp)& transport |
| 21902 | included in the Exim binary. The private options of the &(lmtp)& transport are |
| 21903 | as follows: |
| 21904 | |
| 21905 | .option batch_id lmtp string&!! unset |
| 21906 | See the description of local delivery batching in chapter &<<CHAPbatching>>&. |
| 21907 | |
| 21908 | |
| 21909 | .option batch_max lmtp integer 1 |
| 21910 | This limits the number of addresses that can be handled in a single delivery. |
| 21911 | Most LMTP servers can handle several addresses at once, so it is normally a |
| 21912 | good idea to increase this value. See the description of local delivery |
| 21913 | batching in chapter &<<CHAPbatching>>&. |
| 21914 | |
| 21915 | |
| 21916 | .option command lmtp string&!! unset |
| 21917 | This option must be set if &%socket%& is not set. The string is a command which |
| 21918 | is run in a separate process. It is split up into a command name and list of |
| 21919 | arguments, each of which is separately expanded (so expansion cannot change the |
| 21920 | number of arguments). The command is run directly, not via a shell. The message |
| 21921 | is passed to the new process using the standard input and output to operate the |
| 21922 | LMTP protocol. |
| 21923 | |
| 21924 | .option ignore_quota lmtp boolean false |
| 21925 | .cindex "LMTP" "ignoring quota errors" |
| 21926 | If this option is set true, the string &`IGNOREQUOTA`& is added to RCPT |
| 21927 | commands, provided that the LMTP server has advertised support for IGNOREQUOTA |
| 21928 | in its response to the LHLO command. |
| 21929 | |
| 21930 | .option socket lmtp string&!! unset |
| 21931 | This option must be set if &%command%& is not set. The result of expansion must |
| 21932 | be the name of a Unix domain socket. The transport connects to the socket and |
| 21933 | delivers the message to it using the LMTP protocol. |
| 21934 | |
| 21935 | |
| 21936 | .option timeout lmtp time 5m |
| 21937 | The transport is aborted if the created process or Unix domain socket does not |
| 21938 | respond to LMTP commands or message input within this timeout. Delivery |
| 21939 | is deferred, and will be tried again later. Here is an example of a typical |
| 21940 | LMTP transport: |
| 21941 | .code |
| 21942 | lmtp: |
| 21943 | driver = lmtp |
| 21944 | command = /some/local/lmtp/delivery/program |
| 21945 | batch_max = 20 |
| 21946 | user = exim |
| 21947 | .endd |
| 21948 | This delivers up to 20 addresses at a time, in a mixture of domains if |
| 21949 | necessary, running as the user &'exim'&. |
| 21950 | |
| 21951 | |
| 21952 | |
| 21953 | . //////////////////////////////////////////////////////////////////////////// |
| 21954 | . //////////////////////////////////////////////////////////////////////////// |
| 21955 | |
| 21956 | .chapter "The pipe transport" "CHAPpipetransport" |
| 21957 | .scindex IIDpiptra1 "transports" "&(pipe)&" |
| 21958 | .scindex IIDpiptra2 "&(pipe)& transport" |
| 21959 | The &(pipe)& transport is used to deliver messages via a pipe to a command |
| 21960 | running in another process. One example is the use of &(pipe)& as a |
| 21961 | pseudo-remote transport for passing messages to some other delivery mechanism |
| 21962 | (such as UUCP). Another is the use by individual users to automatically process |
| 21963 | their incoming messages. The &(pipe)& transport can be used in one of the |
| 21964 | following ways: |
| 21965 | |
| 21966 | .ilist |
| 21967 | .vindex "&$local_part$&" |
| 21968 | A router routes one address to a transport in the normal way, and the |
| 21969 | transport is configured as a &(pipe)& transport. In this case, &$local_part$& |
| 21970 | contains the local part of the address (as usual), and the command that is run |
| 21971 | is specified by the &%command%& option on the transport. |
| 21972 | .next |
| 21973 | .vindex "&$pipe_addresses$&" |
| 21974 | If the &%batch_max%& option is set greater than 1 (the default is 1), the |
| 21975 | transport can handle more than one address in a single run. In this case, when |
| 21976 | more than one address is routed to the transport, &$local_part$& is not set |
| 21977 | (because it is not unique). However, the pseudo-variable &$pipe_addresses$& |
| 21978 | (described in section &<<SECThowcommandrun>>& below) contains all the addresses |
| 21979 | that are routed to the transport. |
| 21980 | .next |
| 21981 | .vindex "&$address_pipe$&" |
| 21982 | A router redirects an address directly to a pipe command (for example, from an |
| 21983 | alias or forward file). In this case, &$address_pipe$& contains the text of the |
| 21984 | pipe command, and the &%command%& option on the transport is ignored unless |
| 21985 | &%force_command%& is set. If only one address is being transported |
| 21986 | (&%batch_max%& is not greater than one, or only one address was redirected to |
| 21987 | this pipe command), &$local_part$& contains the local part that was redirected. |
| 21988 | .endlist |
| 21989 | |
| 21990 | |
| 21991 | The &(pipe)& transport is a non-interactive delivery method. Exim can also |
| 21992 | deliver messages over pipes using the LMTP interactive protocol. This is |
| 21993 | implemented by the &(lmtp)& transport. |
| 21994 | |
| 21995 | In the case when &(pipe)& is run as a consequence of an entry in a local user's |
| 21996 | &_.forward_& file, the command runs under the uid and gid of that user. In |
| 21997 | other cases, the uid and gid have to be specified explicitly, either on the |
| 21998 | transport or on the router that handles the address. Current and &"home"& |
| 21999 | directories are also controllable. See chapter &<<CHAPenvironment>>& for |
| 22000 | details of the local delivery environment and chapter &<<CHAPbatching>>& |
| 22001 | for a discussion of local delivery batching. |
| 22002 | |
| 22003 | |
| 22004 | .section "Concurrent delivery" "SECID140" |
| 22005 | If two messages arrive at almost the same time, and both are routed to a pipe |
| 22006 | delivery, the two pipe transports may be run concurrently. You must ensure that |
| 22007 | any pipe commands you set up are robust against this happening. If the commands |
| 22008 | write to a file, the &%exim_lock%& utility might be of use. |
| 22009 | |
| 22010 | |
| 22011 | |
| 22012 | |
| 22013 | .section "Returned status and data" "SECID141" |
| 22014 | .cindex "&(pipe)& transport" "returned data" |
| 22015 | If the command exits with a non-zero return code, the delivery is deemed to |
| 22016 | have failed, unless either the &%ignore_status%& option is set (in which case |
| 22017 | the return code is treated as zero), or the return code is one of those listed |
| 22018 | in the &%temp_errors%& option, which are interpreted as meaning &"try again |
| 22019 | later"&. In this case, delivery is deferred. Details of a permanent failure are |
| 22020 | logged, but are not included in the bounce message, which merely contains |
| 22021 | &"local delivery failed"&. |
| 22022 | |
| 22023 | If the command exits on a signal and the &%freeze_signal%& option is set then |
| 22024 | the message will be frozen in the queue. If that option is not set, a bounce |
| 22025 | will be sent as normal. |
| 22026 | |
| 22027 | If the return code is greater than 128 and the command being run is a shell |
| 22028 | script, it normally means that the script was terminated by a signal whose |
| 22029 | value is the return code minus 128. The &%freeze_signal%& option does not |
| 22030 | apply in this case. |
| 22031 | |
| 22032 | If Exim is unable to run the command (that is, if &[execve()]& fails), the |
| 22033 | return code is set to 127. This is the value that a shell returns if it is |
| 22034 | asked to run a non-existent command. The wording for the log line suggests that |
| 22035 | a non-existent command may be the problem. |
| 22036 | |
| 22037 | The &%return_output%& option can affect the result of a pipe delivery. If it is |
| 22038 | set and the command produces any output on its standard output or standard |
| 22039 | error streams, the command is considered to have failed, even if it gave a zero |
| 22040 | return code or if &%ignore_status%& is set. The output from the command is |
| 22041 | included as part of the bounce message. The &%return_fail_output%& option is |
| 22042 | similar, except that output is returned only when the command exits with a |
| 22043 | failure return code, that is, a value other than zero or a code that matches |
| 22044 | &%temp_errors%&. |
| 22045 | |
| 22046 | |
| 22047 | |
| 22048 | .section "How the command is run" "SECThowcommandrun" |
| 22049 | .cindex "&(pipe)& transport" "path for command" |
| 22050 | The command line is (by default) broken down into a command name and arguments |
| 22051 | by the &(pipe)& transport itself. The &%allow_commands%& and |
| 22052 | &%restrict_to_path%& options can be used to restrict the commands that may be |
| 22053 | run. |
| 22054 | |
| 22055 | .cindex "quoting" "in pipe command" |
| 22056 | Unquoted arguments are delimited by white space. If an argument appears in |
| 22057 | double quotes, backslash is interpreted as an escape character in the usual |
| 22058 | way. If an argument appears in single quotes, no escaping is done. |
| 22059 | |
| 22060 | String expansion is applied to the command line except when it comes from a |
| 22061 | traditional &_.forward_& file (commands from a filter file are expanded). The |
| 22062 | expansion is applied to each argument in turn rather than to the whole line. |
| 22063 | For this reason, any string expansion item that contains white space must be |
| 22064 | quoted so as to be contained within a single argument. A setting such as |
| 22065 | .code |
| 22066 | command = /some/path ${if eq{$local_part}{postmaster}{xx}{yy}} |
| 22067 | .endd |
| 22068 | will not work, because the expansion item gets split between several |
| 22069 | arguments. You have to write |
| 22070 | .code |
| 22071 | command = /some/path "${if eq{$local_part}{postmaster}{xx}{yy}}" |
| 22072 | .endd |
| 22073 | to ensure that it is all in one argument. The expansion is done in this way, |
| 22074 | argument by argument, so that the number of arguments cannot be changed as a |
| 22075 | result of expansion, and quotes or backslashes in inserted variables do not |
| 22076 | interact with external quoting. However, this leads to problems if you want to |
| 22077 | generate multiple arguments (or the command name plus arguments) from a single |
| 22078 | expansion. In this situation, the simplest solution is to use a shell. For |
| 22079 | example: |
| 22080 | .code |
| 22081 | command = /bin/sh -c ${lookup{$local_part}lsearch{/some/file}} |
| 22082 | .endd |
| 22083 | |
| 22084 | .cindex "transport" "filter" |
| 22085 | .cindex "filter" "transport filter" |
| 22086 | .vindex "&$pipe_addresses$&" |
| 22087 | Special handling takes place when an argument consists of precisely the text |
| 22088 | &`$pipe_addresses`&. This is not a general expansion variable; the only |
| 22089 | place this string is recognized is when it appears as an argument for a pipe or |
| 22090 | transport filter command. It causes each address that is being handled to be |
| 22091 | inserted in the argument list at that point &'as a separate argument'&. This |
| 22092 | avoids any problems with spaces or shell metacharacters, and is of use when a |
| 22093 | &(pipe)& transport is handling groups of addresses in a batch. |
| 22094 | |
| 22095 | If &%force_command%& is enabled on the transport, Special handling takes place |
| 22096 | for an argument that consists of precisely the text &`$address_pipe`&. It |
| 22097 | is handled similarly to &$pipe_addresses$& above. It is expanded and each |
| 22098 | argument is inserted in the argument list at that point |
| 22099 | &'as a separate argument'&. The &`$address_pipe`& item does not need to be |
| 22100 | the only item in the argument; in fact, if it were then &%force_command%& |
| 22101 | should behave as a no-op. Rather, it should be used to adjust the command |
| 22102 | run while preserving the argument vector separation. |
| 22103 | |
| 22104 | After splitting up into arguments and expansion, the resulting command is run |
| 22105 | in a subprocess directly from the transport, &'not'& under a shell. The |
| 22106 | message that is being delivered is supplied on the standard input, and the |
| 22107 | standard output and standard error are both connected to a single pipe that is |
| 22108 | read by Exim. The &%max_output%& option controls how much output the command |
| 22109 | may produce, and the &%return_output%& and &%return_fail_output%& options |
| 22110 | control what is done with it. |
| 22111 | |
| 22112 | Not running the command under a shell (by default) lessens the security risks |
| 22113 | in cases when a command from a user's filter file is built out of data that was |
| 22114 | taken from an incoming message. If a shell is required, it can of course be |
| 22115 | explicitly specified as the command to be run. However, there are circumstances |
| 22116 | where existing commands (for example, in &_.forward_& files) expect to be run |
| 22117 | under a shell and cannot easily be modified. To allow for these cases, there is |
| 22118 | an option called &%use_shell%&, which changes the way the &(pipe)& transport |
| 22119 | works. Instead of breaking up the command line as just described, it expands it |
| 22120 | as a single string and passes the result to &_/bin/sh_&. The |
| 22121 | &%restrict_to_path%& option and the &$pipe_addresses$& facility cannot be used |
| 22122 | with &%use_shell%&, and the whole mechanism is inherently less secure. |
| 22123 | |
| 22124 | |
| 22125 | |
| 22126 | .section "Environment variables" "SECTpipeenv" |
| 22127 | .cindex "&(pipe)& transport" "environment for command" |
| 22128 | .cindex "environment for pipe transport" |
| 22129 | The environment variables listed below are set up when the command is invoked. |
| 22130 | This list is a compromise for maximum compatibility with other MTAs. Note that |
| 22131 | the &%environment%& option can be used to add additional variables to this |
| 22132 | environment. |
| 22133 | .display |
| 22134 | &`DOMAIN `& the domain of the address |
| 22135 | &`HOME `& the home directory, if set |
| 22136 | &`HOST `& the host name when called from a router (see below) |
| 22137 | &`LOCAL_PART `& see below |
| 22138 | &`LOCAL_PART_PREFIX `& see below |
| 22139 | &`LOCAL_PART_SUFFIX `& see below |
| 22140 | &`LOGNAME `& see below |
| 22141 | &`MESSAGE_ID `& Exim's local ID for the message |
| 22142 | &`PATH `& as specified by the &%path%& option below |
| 22143 | &`QUALIFY_DOMAIN `& the sender qualification domain |
| 22144 | &`RECIPIENT `& the complete recipient address |
| 22145 | &`SENDER `& the sender of the message (empty if a bounce) |
| 22146 | &`SHELL `& &`/bin/sh`& |
| 22147 | &`TZ `& the value of the &%timezone%& option, if set |
| 22148 | &`USER `& see below |
| 22149 | .endd |
| 22150 | When a &(pipe)& transport is called directly from (for example) an &(accept)& |
| 22151 | router, LOCAL_PART is set to the local part of the address. When it is |
| 22152 | called as a result of a forward or alias expansion, LOCAL_PART is set to |
| 22153 | the local part of the address that was expanded. In both cases, any affixes are |
| 22154 | removed from the local part, and made available in LOCAL_PART_PREFIX and |
| 22155 | LOCAL_PART_SUFFIX, respectively. LOGNAME and USER are set to the |
| 22156 | same value as LOCAL_PART for compatibility with other MTAs. |
| 22157 | |
| 22158 | .cindex "HOST" |
| 22159 | HOST is set only when a &(pipe)& transport is called from a router that |
| 22160 | associates hosts with an address, typically when using &(pipe)& as a |
| 22161 | pseudo-remote transport. HOST is set to the first host name specified by |
| 22162 | the router. |
| 22163 | |
| 22164 | .cindex "HOME" |
| 22165 | If the transport's generic &%home_directory%& option is set, its value is used |
| 22166 | for the HOME environment variable. Otherwise, a home directory may be set |
| 22167 | by the router's &%transport_home_directory%& option, which defaults to the |
| 22168 | user's home directory if &%check_local_user%& is set. |
| 22169 | |
| 22170 | |
| 22171 | .section "Private options for pipe" "SECID142" |
| 22172 | .cindex "options" "&(pipe)& transport" |
| 22173 | |
| 22174 | |
| 22175 | |
| 22176 | .option allow_commands pipe "string list&!!" unset |
| 22177 | .cindex "&(pipe)& transport" "permitted commands" |
| 22178 | The string is expanded, and is then interpreted as a colon-separated list of |
| 22179 | permitted commands. If &%restrict_to_path%& is not set, the only commands |
| 22180 | permitted are those in the &%allow_commands%& list. They need not be absolute |
| 22181 | paths; the &%path%& option is still used for relative paths. If |
| 22182 | &%restrict_to_path%& is set with &%allow_commands%&, the command must either be |
| 22183 | in the &%allow_commands%& list, or a name without any slashes that is found on |
| 22184 | the path. In other words, if neither &%allow_commands%& nor |
| 22185 | &%restrict_to_path%& is set, there is no restriction on the command, but |
| 22186 | otherwise only commands that are permitted by one or the other are allowed. For |
| 22187 | example, if |
| 22188 | .code |
| 22189 | allow_commands = /usr/bin/vacation |
| 22190 | .endd |
| 22191 | and &%restrict_to_path%& is not set, the only permitted command is |
| 22192 | &_/usr/bin/vacation_&. The &%allow_commands%& option may not be set if |
| 22193 | &%use_shell%& is set. |
| 22194 | |
| 22195 | |
| 22196 | .option batch_id pipe string&!! unset |
| 22197 | See the description of local delivery batching in chapter &<<CHAPbatching>>&. |
| 22198 | |
| 22199 | |
| 22200 | .option batch_max pipe integer 1 |
| 22201 | This limits the number of addresses that can be handled in a single delivery. |
| 22202 | See the description of local delivery batching in chapter &<<CHAPbatching>>&. |
| 22203 | |
| 22204 | |
| 22205 | .option check_string pipe string unset |
| 22206 | As &(pipe)& writes the message, the start of each line is tested for matching |
| 22207 | &%check_string%&, and if it does, the initial matching characters are replaced |
| 22208 | by the contents of &%escape_string%&, provided both are set. The value of |
| 22209 | &%check_string%& is a literal string, not a regular expression, and the case of |
| 22210 | any letters it contains is significant. When &%use_bsmtp%& is set, the contents |
| 22211 | of &%check_string%& and &%escape_string%& are forced to values that implement |
| 22212 | the SMTP escaping protocol. Any settings made in the configuration file are |
| 22213 | ignored. |
| 22214 | |
| 22215 | |
| 22216 | .option command pipe string&!! unset |
| 22217 | This option need not be set when &(pipe)& is being used to deliver to pipes |
| 22218 | obtained directly from address redirections. In other cases, the option must be |
| 22219 | set, to provide a command to be run. It need not yield an absolute path (see |
| 22220 | the &%path%& option below). The command is split up into separate arguments by |
| 22221 | Exim, and each argument is separately expanded, as described in section |
| 22222 | &<<SECThowcommandrun>>& above. |
| 22223 | |
| 22224 | |
| 22225 | .option environment pipe string&!! unset |
| 22226 | .cindex "&(pipe)& transport" "environment for command" |
| 22227 | .cindex "environment for &(pipe)& transport" |
| 22228 | This option is used to add additional variables to the environment in which the |
| 22229 | command runs (see section &<<SECTpipeenv>>& for the default list). Its value is |
| 22230 | a string which is expanded, and then interpreted as a colon-separated list of |
| 22231 | environment settings of the form <&'name'&>=<&'value'&>. |
| 22232 | |
| 22233 | |
| 22234 | .option escape_string pipe string unset |
| 22235 | See &%check_string%& above. |
| 22236 | |
| 22237 | |
| 22238 | .option freeze_exec_fail pipe boolean false |
| 22239 | .cindex "exec failure" |
| 22240 | .cindex "failure of exec" |
| 22241 | .cindex "&(pipe)& transport" "failure of exec" |
| 22242 | Failure to exec the command in a pipe transport is by default treated like |
| 22243 | any other failure while running the command. However, if &%freeze_exec_fail%& |
| 22244 | is set, failure to exec is treated specially, and causes the message to be |
| 22245 | frozen, whatever the setting of &%ignore_status%&. |
| 22246 | |
| 22247 | |
| 22248 | .option freeze_signal pipe boolean false |
| 22249 | .cindex "signal exit" |
| 22250 | .cindex "&(pipe)& transport", "signal exit" |
| 22251 | Normally if the process run by a command in a pipe transport exits on a signal, |
| 22252 | a bounce message is sent. If &%freeze_signal%& is set, the message will be |
| 22253 | frozen in Exim's queue instead. |
| 22254 | |
| 22255 | |
| 22256 | .option force_command pipe boolean false |
| 22257 | .cindex "force command" |
| 22258 | .cindex "&(pipe)& transport", "force command" |
| 22259 | Normally when a router redirects an address directly to a pipe command |
| 22260 | the &%command%& option on the transport is ignored. If &%force_command%& |
| 22261 | is set, the &%command%& option will used. This is especially |
| 22262 | useful for forcing a wrapper or additional argument to be added to the |
| 22263 | command. For example: |
| 22264 | .code |
| 22265 | command = /usr/bin/remote_exec myhost -- $address_pipe |
| 22266 | force_command |
| 22267 | .endd |
| 22268 | |
| 22269 | Note that &$address_pipe$& is handled specially in &%command%& when |
| 22270 | &%force_command%& is set, expanding out to the original argument vector as |
| 22271 | separate items, similarly to a Unix shell &`"$@"`& construct. |
| 22272 | |
| 22273 | .option ignore_status pipe boolean false |
| 22274 | If this option is true, the status returned by the subprocess that is set up to |
| 22275 | run the command is ignored, and Exim behaves as if zero had been returned. |
| 22276 | Otherwise, a non-zero status or termination by signal causes an error return |
| 22277 | from the transport unless the status value is one of those listed in |
| 22278 | &%temp_errors%&; these cause the delivery to be deferred and tried again later. |
| 22279 | |
| 22280 | &*Note*&: This option does not apply to timeouts, which do not return a status. |
| 22281 | See the &%timeout_defer%& option for how timeouts are handled. |
| 22282 | |
| 22283 | .option log_defer_output pipe boolean false |
| 22284 | .cindex "&(pipe)& transport" "logging output" |
| 22285 | If this option is set, and the status returned by the command is |
| 22286 | one of the codes listed in &%temp_errors%& (that is, delivery was deferred), |
| 22287 | and any output was produced, the first line of it is written to the main log. |
| 22288 | |
| 22289 | |
| 22290 | .option log_fail_output pipe boolean false |
| 22291 | If this option is set, and the command returns any output, and also ends with a |
| 22292 | return code that is neither zero nor one of the return codes listed in |
| 22293 | &%temp_errors%& (that is, the delivery failed), the first line of output is |
| 22294 | written to the main log. This option and &%log_output%& are mutually exclusive. |
| 22295 | Only one of them may be set. |
| 22296 | |
| 22297 | |
| 22298 | |
| 22299 | .option log_output pipe boolean false |
| 22300 | If this option is set and the command returns any output, the first line of |
| 22301 | output is written to the main log, whatever the return code. This option and |
| 22302 | &%log_fail_output%& are mutually exclusive. Only one of them may be set. |
| 22303 | |
| 22304 | |
| 22305 | |
| 22306 | .option max_output pipe integer 20K |
| 22307 | This specifies the maximum amount of output that the command may produce on its |
| 22308 | standard output and standard error file combined. If the limit is exceeded, the |
| 22309 | process running the command is killed. This is intended as a safety measure to |
| 22310 | catch runaway processes. The limit is applied independently of the settings of |
| 22311 | the options that control what is done with such output (for example, |
| 22312 | &%return_output%&). Because of buffering effects, the amount of output may |
| 22313 | exceed the limit by a small amount before Exim notices. |
| 22314 | |
| 22315 | |
| 22316 | .option message_prefix pipe string&!! "see below" |
| 22317 | The string specified here is expanded and output at the start of every message. |
| 22318 | The default is unset if &%use_bsmtp%& is set. Otherwise it is |
| 22319 | .code |
| 22320 | message_prefix = \ |
| 22321 | From ${if def:return_path{$return_path}{MAILER-DAEMON}}\ |
| 22322 | ${tod_bsdinbox}\n |
| 22323 | .endd |
| 22324 | .cindex "Cyrus" |
| 22325 | .cindex "&%tmail%&" |
| 22326 | .cindex "&""From""& line" |
| 22327 | This is required by the commonly used &_/usr/bin/vacation_& program. |
| 22328 | However, it must &'not'& be present if delivery is to the Cyrus IMAP server, |
| 22329 | or to the &%tmail%& local delivery agent. The prefix can be suppressed by |
| 22330 | setting |
| 22331 | .code |
| 22332 | message_prefix = |
| 22333 | .endd |
| 22334 | &*Note:*& If you set &%use_crlf%& true, you must change any occurrences of |
| 22335 | &`\n`& to &`\r\n`& in &%message_prefix%&. |
| 22336 | |
| 22337 | |
| 22338 | .option message_suffix pipe string&!! "see below" |
| 22339 | The string specified here is expanded and output at the end of every message. |
| 22340 | The default is unset if &%use_bsmtp%& is set. Otherwise it is a single newline. |
| 22341 | The suffix can be suppressed by setting |
| 22342 | .code |
| 22343 | message_suffix = |
| 22344 | .endd |
| 22345 | &*Note:*& If you set &%use_crlf%& true, you must change any occurrences of |
| 22346 | &`\n`& to &`\r\n`& in &%message_suffix%&. |
| 22347 | |
| 22348 | |
| 22349 | .option path pipe string "see below" |
| 22350 | This option specifies the string that is set up in the PATH environment |
| 22351 | variable of the subprocess. The default is: |
| 22352 | .code |
| 22353 | /bin:/usr/bin |
| 22354 | .endd |
| 22355 | If the &%command%& option does not yield an absolute path name, the command is |
| 22356 | sought in the PATH directories, in the usual way. &*Warning*&: This does not |
| 22357 | apply to a command specified as a transport filter. |
| 22358 | |
| 22359 | |
| 22360 | .option permit_coredump pipe boolean false |
| 22361 | Normally Exim inhibits core-dumps during delivery. If you have a need to get |
| 22362 | a core-dump of a pipe command, enable this command. This enables core-dumps |
| 22363 | during delivery and affects both the Exim binary and the pipe command run. |
| 22364 | It is recommended that this option remain off unless and until you have a need |
| 22365 | for it and that this only be enabled when needed, as the risk of excessive |
| 22366 | resource consumption can be quite high. Note also that Exim is typically |
| 22367 | installed as a setuid binary and most operating systems will inhibit coredumps |
| 22368 | of these by default, so further OS-specific action may be required. |
| 22369 | |
| 22370 | |
| 22371 | .option pipe_as_creator pipe boolean false |
| 22372 | .cindex "uid (user id)" "local delivery" |
| 22373 | If the generic &%user%& option is not set and this option is true, the delivery |
| 22374 | process is run under the uid that was in force when Exim was originally called |
| 22375 | to accept the message. If the group id is not otherwise set (via the generic |
| 22376 | &%group%& option), the gid that was in force when Exim was originally called to |
| 22377 | accept the message is used. |
| 22378 | |
| 22379 | |
| 22380 | .option restrict_to_path pipe boolean false |
| 22381 | When this option is set, any command name not listed in &%allow_commands%& must |
| 22382 | contain no slashes. The command is searched for only in the directories listed |
| 22383 | in the &%path%& option. This option is intended for use in the case when a pipe |
| 22384 | command has been generated from a user's &_.forward_& file. This is usually |
| 22385 | handled by a &(pipe)& transport called &%address_pipe%&. |
| 22386 | |
| 22387 | |
| 22388 | .option return_fail_output pipe boolean false |
| 22389 | If this option is true, and the command produced any output and ended with a |
| 22390 | return code other than zero or one of the codes listed in &%temp_errors%& (that |
| 22391 | is, the delivery failed), the output is returned in the bounce message. |
| 22392 | However, if the message has a null sender (that is, it is itself a bounce |
| 22393 | message), output from the command is discarded. This option and |
| 22394 | &%return_output%& are mutually exclusive. Only one of them may be set. |
| 22395 | |
| 22396 | |
| 22397 | |
| 22398 | .option return_output pipe boolean false |
| 22399 | If this option is true, and the command produced any output, the delivery is |
| 22400 | deemed to have failed whatever the return code from the command, and the output |
| 22401 | is returned in the bounce message. Otherwise, the output is just discarded. |
| 22402 | However, if the message has a null sender (that is, it is a bounce message), |
| 22403 | output from the command is always discarded, whatever the setting of this |
| 22404 | option. This option and &%return_fail_output%& are mutually exclusive. Only one |
| 22405 | of them may be set. |
| 22406 | |
| 22407 | |
| 22408 | |
| 22409 | .option temp_errors pipe "string list" "see below" |
| 22410 | .cindex "&(pipe)& transport" "temporary failure" |
| 22411 | This option contains either a colon-separated list of numbers, or a single |
| 22412 | asterisk. If &%ignore_status%& is false |
| 22413 | and &%return_output%& is not set, |
| 22414 | and the command exits with a non-zero return code, the failure is treated as |
| 22415 | temporary and the delivery is deferred if the return code matches one of the |
| 22416 | numbers, or if the setting is a single asterisk. Otherwise, non-zero return |
| 22417 | codes are treated as permanent errors. The default setting contains the codes |
| 22418 | defined by EX_TEMPFAIL and EX_CANTCREAT in &_sysexits.h_&. If Exim is |
| 22419 | compiled on a system that does not define these macros, it assumes values of 75 |
| 22420 | and 73, respectively. |
| 22421 | |
| 22422 | |
| 22423 | .option timeout pipe time 1h |
| 22424 | If the command fails to complete within this time, it is killed. This normally |
| 22425 | causes the delivery to fail (but see &%timeout_defer%&). A zero time interval |
| 22426 | specifies no timeout. In order to ensure that any subprocesses created by the |
| 22427 | command are also killed, Exim makes the initial process a process group leader, |
| 22428 | and kills the whole process group on a timeout. However, this can be defeated |
| 22429 | if one of the processes starts a new process group. |
| 22430 | |
| 22431 | .option timeout_defer pipe boolean false |
| 22432 | A timeout in a &(pipe)& transport, either in the command that the transport |
| 22433 | runs, or in a transport filter that is associated with it, is by default |
| 22434 | treated as a hard error, and the delivery fails. However, if &%timeout_defer%& |
| 22435 | is set true, both kinds of timeout become temporary errors, causing the |
| 22436 | delivery to be deferred. |
| 22437 | |
| 22438 | .option umask pipe "octal integer" 022 |
| 22439 | This specifies the umask setting for the subprocess that runs the command. |
| 22440 | |
| 22441 | |
| 22442 | .option use_bsmtp pipe boolean false |
| 22443 | .cindex "envelope sender" |
| 22444 | If this option is set true, the &(pipe)& transport writes messages in &"batch |
| 22445 | SMTP"& format, with the envelope sender and recipient(s) included as SMTP |
| 22446 | commands. If you want to include a leading HELO command with such messages, |
| 22447 | you can do so by setting the &%message_prefix%& option. See section |
| 22448 | &<<SECTbatchSMTP>>& for details of batch SMTP. |
| 22449 | |
| 22450 | .option use_classresources pipe boolean false |
| 22451 | .cindex "class resources (BSD)" |
| 22452 | This option is available only when Exim is running on FreeBSD, NetBSD, or |
| 22453 | BSD/OS. If it is set true, the &[setclassresources()]& function is used to set |
| 22454 | resource limits when a &(pipe)& transport is run to perform a delivery. The |
| 22455 | limits for the uid under which the pipe is to run are obtained from the login |
| 22456 | class database. |
| 22457 | |
| 22458 | |
| 22459 | .option use_crlf pipe boolean false |
| 22460 | .cindex "carriage return" |
| 22461 | .cindex "linefeed" |
| 22462 | This option causes lines to be terminated with the two-character CRLF sequence |
| 22463 | (carriage return, linefeed) instead of just a linefeed character. In the case |
| 22464 | of batched SMTP, the byte sequence written to the pipe is then an exact image |
| 22465 | of what would be sent down a real SMTP connection. |
| 22466 | |
| 22467 | The contents of the &%message_prefix%& and &%message_suffix%& options are |
| 22468 | written verbatim, so must contain their own carriage return characters if these |
| 22469 | are needed. When &%use_bsmtp%& is not set, the default values for both |
| 22470 | &%message_prefix%& and &%message_suffix%& end with a single linefeed, so their |
| 22471 | values must be changed to end with &`\r\n`& if &%use_crlf%& is set. |
| 22472 | |
| 22473 | |
| 22474 | .option use_shell pipe boolean false |
| 22475 | .vindex "&$pipe_addresses$&" |
| 22476 | If this option is set, it causes the command to be passed to &_/bin/sh_& |
| 22477 | instead of being run directly from the transport, as described in section |
| 22478 | &<<SECThowcommandrun>>&. This is less secure, but is needed in some situations |
| 22479 | where the command is expected to be run under a shell and cannot easily be |
| 22480 | modified. The &%allow_commands%& and &%restrict_to_path%& options, and the |
| 22481 | &`$pipe_addresses`& facility are incompatible with &%use_shell%&. The |
| 22482 | command is expanded as a single string, and handed to &_/bin/sh_& as data for |
| 22483 | its &%-c%& option. |
| 22484 | |
| 22485 | |
| 22486 | |
| 22487 | .section "Using an external local delivery agent" "SECID143" |
| 22488 | .cindex "local delivery" "using an external agent" |
| 22489 | .cindex "&'procmail'&" |
| 22490 | .cindex "external local delivery" |
| 22491 | .cindex "delivery" "&'procmail'&" |
| 22492 | .cindex "delivery" "by external agent" |
| 22493 | The &(pipe)& transport can be used to pass all messages that require local |
| 22494 | delivery to a separate local delivery agent such as &%procmail%&. When doing |
| 22495 | this, care must be taken to ensure that the pipe is run under an appropriate |
| 22496 | uid and gid. In some configurations one wants this to be a uid that is trusted |
| 22497 | by the delivery agent to supply the correct sender of the message. It may be |
| 22498 | necessary to recompile or reconfigure the delivery agent so that it trusts an |
| 22499 | appropriate user. The following is an example transport and router |
| 22500 | configuration for &%procmail%&: |
| 22501 | .code |
| 22502 | # transport |
| 22503 | procmail_pipe: |
| 22504 | driver = pipe |
| 22505 | command = /usr/local/bin/procmail -d $local_part |
| 22506 | return_path_add |
| 22507 | delivery_date_add |
| 22508 | envelope_to_add |
| 22509 | check_string = "From " |
| 22510 | escape_string = ">From " |
| 22511 | umask = 077 |
| 22512 | user = $local_part |
| 22513 | group = mail |
| 22514 | |
| 22515 | # router |
| 22516 | procmail: |
| 22517 | driver = accept |
| 22518 | check_local_user |
| 22519 | transport = procmail_pipe |
| 22520 | .endd |
| 22521 | In this example, the pipe is run as the local user, but with the group set to |
| 22522 | &'mail'&. An alternative is to run the pipe as a specific user such as &'mail'& |
| 22523 | or &'exim'&, but in this case you must arrange for &%procmail%& to trust that |
| 22524 | user to supply a correct sender address. If you do not specify either a |
| 22525 | &%group%& or a &%user%& option, the pipe command is run as the local user. The |
| 22526 | home directory is the user's home directory by default. |
| 22527 | |
| 22528 | &*Note*&: The command that the pipe transport runs does &'not'& begin with |
| 22529 | .code |
| 22530 | IFS=" " |
| 22531 | .endd |
| 22532 | as shown in some &%procmail%& documentation, because Exim does not by default |
| 22533 | use a shell to run pipe commands. |
| 22534 | |
| 22535 | .cindex "Cyrus" |
| 22536 | The next example shows a transport and a router for a system where local |
| 22537 | deliveries are handled by the Cyrus IMAP server. |
| 22538 | .code |
| 22539 | # transport |
| 22540 | local_delivery_cyrus: |
| 22541 | driver = pipe |
| 22542 | command = /usr/cyrus/bin/deliver \ |
| 22543 | -m ${substr_1:$local_part_suffix} -- $local_part |
| 22544 | user = cyrus |
| 22545 | group = mail |
| 22546 | return_output |
| 22547 | log_output |
| 22548 | message_prefix = |
| 22549 | message_suffix = |
| 22550 | |
| 22551 | # router |
| 22552 | local_user_cyrus: |
| 22553 | driver = accept |
| 22554 | check_local_user |
| 22555 | local_part_suffix = .* |
| 22556 | transport = local_delivery_cyrus |
| 22557 | .endd |
| 22558 | Note the unsetting of &%message_prefix%& and &%message_suffix%&, and the use of |
| 22559 | &%return_output%& to cause any text written by Cyrus to be returned to the |
| 22560 | sender. |
| 22561 | .ecindex IIDpiptra1 |
| 22562 | .ecindex IIDpiptra2 |
| 22563 | |
| 22564 | |
| 22565 | . //////////////////////////////////////////////////////////////////////////// |
| 22566 | . //////////////////////////////////////////////////////////////////////////// |
| 22567 | |
| 22568 | .chapter "The smtp transport" "CHAPsmtptrans" |
| 22569 | .scindex IIDsmttra1 "transports" "&(smtp)&" |
| 22570 | .scindex IIDsmttra2 "&(smtp)& transport" |
| 22571 | The &(smtp)& transport delivers messages over TCP/IP connections using the SMTP |
| 22572 | or LMTP protocol. The list of hosts to try can either be taken from the address |
| 22573 | that is being processed (having been set up by the router), or specified |
| 22574 | explicitly for the transport. Timeout and retry processing (see chapter |
| 22575 | &<<CHAPretry>>&) is applied to each IP address independently. |
| 22576 | |
| 22577 | |
| 22578 | .section "Multiple messages on a single connection" "SECID144" |
| 22579 | The sending of multiple messages over a single TCP/IP connection can arise in |
| 22580 | two ways: |
| 22581 | |
| 22582 | .ilist |
| 22583 | If a message contains more than &%max_rcpt%& (see below) addresses that are |
| 22584 | routed to the same host, more than one copy of the message has to be sent to |
| 22585 | that host. In this situation, multiple copies may be sent in a single run of |
| 22586 | the &(smtp)& transport over a single TCP/IP connection. (What Exim actually |
| 22587 | does when it has too many addresses to send in one message also depends on the |
| 22588 | value of the global &%remote_max_parallel%& option. Details are given in |
| 22589 | section &<<SECToutSMTPTCP>>&.) |
| 22590 | .next |
| 22591 | .cindex "hints database" "remembering routing" |
| 22592 | When a message has been successfully delivered over a TCP/IP connection, Exim |
| 22593 | looks in its hints database to see if there are any other messages awaiting a |
| 22594 | connection to the same host. If there are, a new delivery process is started |
| 22595 | for one of them, and the current TCP/IP connection is passed on to it. The new |
| 22596 | process may in turn send multiple copies and possibly create yet another |
| 22597 | process. |
| 22598 | .endlist |
| 22599 | |
| 22600 | |
| 22601 | For each copy sent over the same TCP/IP connection, a sequence counter is |
| 22602 | incremented, and if it ever gets to the value of &%connection_max_messages%&, |
| 22603 | no further messages are sent over that connection. |
| 22604 | |
| 22605 | |
| 22606 | |
| 22607 | .section "Use of the $host and $host_address variables" "SECID145" |
| 22608 | .vindex "&$host$&" |
| 22609 | .vindex "&$host_address$&" |
| 22610 | At the start of a run of the &(smtp)& transport, the values of &$host$& and |
| 22611 | &$host_address$& are the name and IP address of the first host on the host list |
| 22612 | passed by the router. However, when the transport is about to connect to a |
| 22613 | specific host, and while it is connected to that host, &$host$& and |
| 22614 | &$host_address$& are set to the values for that host. These are the values |
| 22615 | that are in force when the &%helo_data%&, &%hosts_try_auth%&, &%interface%&, |
| 22616 | &%serialize_hosts%&, and the various TLS options are expanded. |
| 22617 | |
| 22618 | |
| 22619 | .section "Use of $tls_cipher and $tls_peerdn" "usecippeer" |
| 22620 | .vindex &$tls_bits$& |
| 22621 | .vindex &$tls_cipher$& |
| 22622 | .vindex &$tls_peerdn$& |
| 22623 | .vindex &$tls_sni$& |
| 22624 | At the start of a run of the &(smtp)& transport, the values of &$tls_bits$&, |
| 22625 | &$tls_cipher$&, &$tls_peerdn$& and &$tls_sni$& |
| 22626 | are the values that were set when the message was received. |
| 22627 | These are the values that are used for options that are expanded before any |
| 22628 | SMTP connections are made. Just before each connection is made, these four |
| 22629 | variables are emptied. If TLS is subsequently started, they are set to the |
| 22630 | appropriate values for the outgoing connection, and these are the values that |
| 22631 | are in force when any authenticators are run and when the |
| 22632 | &%authenticated_sender%& option is expanded. |
| 22633 | |
| 22634 | These variables are deprecated in favour of &$tls_in_cipher$& et. al. |
| 22635 | and will be removed in a future release. |
| 22636 | |
| 22637 | |
| 22638 | .section "Private options for smtp" "SECID146" |
| 22639 | .cindex "options" "&(smtp)& transport" |
| 22640 | The private options of the &(smtp)& transport are as follows: |
| 22641 | |
| 22642 | |
| 22643 | .option address_retry_include_sender smtp boolean true |
| 22644 | .cindex "4&'xx'& responses" "retrying after" |
| 22645 | When an address is delayed because of a 4&'xx'& response to a RCPT command, it |
| 22646 | is the combination of sender and recipient that is delayed in subsequent queue |
| 22647 | runs until the retry time is reached. You can delay the recipient without |
| 22648 | reference to the sender (which is what earlier versions of Exim did), by |
| 22649 | setting &%address_retry_include_sender%& false. However, this can lead to |
| 22650 | problems with servers that regularly issue 4&'xx'& responses to RCPT commands. |
| 22651 | |
| 22652 | .option allow_localhost smtp boolean false |
| 22653 | .cindex "local host" "sending to" |
| 22654 | .cindex "fallback" "hosts specified on transport" |
| 22655 | When a host specified in &%hosts%& or &%fallback_hosts%& (see below) turns out |
| 22656 | to be the local host, or is listed in &%hosts_treat_as_local%&, delivery is |
| 22657 | deferred by default. However, if &%allow_localhost%& is set, Exim goes on to do |
| 22658 | the delivery anyway. This should be used only in special cases when the |
| 22659 | configuration ensures that no looping will result (for example, a differently |
| 22660 | configured Exim is listening on the port to which the message is sent). |
| 22661 | |
| 22662 | |
| 22663 | .option authenticated_sender smtp string&!! unset |
| 22664 | .cindex "Cyrus" |
| 22665 | When Exim has authenticated as a client, or if &%authenticated_sender_force%& |
| 22666 | is true, this option sets a value for the AUTH= item on outgoing MAIL commands, |
| 22667 | overriding any existing authenticated sender value. If the string expansion is |
| 22668 | forced to fail, the option is ignored. Other expansion failures cause delivery |
| 22669 | to be deferred. If the result of expansion is an empty string, that is also |
| 22670 | ignored. |
| 22671 | |
| 22672 | The expansion happens after the outgoing connection has been made and TLS |
| 22673 | started, if required. This means that the &$host$&, &$host_address$&, |
| 22674 | &$tls_out_cipher$&, and &$tls_out_peerdn$& variables are set according to the |
| 22675 | particular connection. |
| 22676 | |
| 22677 | If the SMTP session is not authenticated, the expansion of |
| 22678 | &%authenticated_sender%& still happens (and can cause the delivery to be |
| 22679 | deferred if it fails), but no AUTH= item is added to MAIL commands |
| 22680 | unless &%authenticated_sender_force%& is true. |
| 22681 | |
| 22682 | This option allows you to use the &(smtp)& transport in LMTP mode to |
| 22683 | deliver mail to Cyrus IMAP and provide the proper local part as the |
| 22684 | &"authenticated sender"&, via a setting such as: |
| 22685 | .code |
| 22686 | authenticated_sender = $local_part |
| 22687 | .endd |
| 22688 | This removes the need for IMAP subfolders to be assigned special ACLs to |
| 22689 | allow direct delivery to those subfolders. |
| 22690 | |
| 22691 | Because of expected uses such as that just described for Cyrus (when no |
| 22692 | domain is involved), there is no checking on the syntax of the provided |
| 22693 | value. |
| 22694 | |
| 22695 | |
| 22696 | .option authenticated_sender_force smtp boolean false |
| 22697 | If this option is set true, the &%authenticated_sender%& option's value |
| 22698 | is used for the AUTH= item on outgoing MAIL commands, even if Exim has not |
| 22699 | authenticated as a client. |
| 22700 | |
| 22701 | |
| 22702 | .option command_timeout smtp time 5m |
| 22703 | This sets a timeout for receiving a response to an SMTP command that has been |
| 22704 | sent out. It is also used when waiting for the initial banner line from the |
| 22705 | remote host. Its value must not be zero. |
| 22706 | |
| 22707 | |
| 22708 | .option connect_timeout smtp time 5m |
| 22709 | This sets a timeout for the &[connect()]& function, which sets up a TCP/IP call |
| 22710 | to a remote host. A setting of zero allows the system timeout (typically |
| 22711 | several minutes) to act. To have any effect, the value of this option must be |
| 22712 | less than the system timeout. However, it has been observed that on some |
| 22713 | systems there is no system timeout, which is why the default value for this |
| 22714 | option is 5 minutes, a value recommended by RFC 1123. |
| 22715 | |
| 22716 | |
| 22717 | .option connection_max_messages smtp integer 500 |
| 22718 | .cindex "SMTP" "passed connection" |
| 22719 | .cindex "SMTP" "multiple deliveries" |
| 22720 | .cindex "multiple SMTP deliveries" |
| 22721 | This controls the maximum number of separate message deliveries that are sent |
| 22722 | over a single TCP/IP connection. If the value is zero, there is no limit. |
| 22723 | For testing purposes, this value can be overridden by the &%-oB%& command line |
| 22724 | option. |
| 22725 | |
| 22726 | |
| 22727 | .option data_timeout smtp time 5m |
| 22728 | This sets a timeout for the transmission of each block in the data portion of |
| 22729 | the message. As a result, the overall timeout for a message depends on the size |
| 22730 | of the message. Its value must not be zero. See also &%final_timeout%&. |
| 22731 | |
| 22732 | |
| 22733 | .option delay_after_cutoff smtp boolean true |
| 22734 | This option controls what happens when all remote IP addresses for a given |
| 22735 | domain have been inaccessible for so long that they have passed their retry |
| 22736 | cutoff times. |
| 22737 | |
| 22738 | In the default state, if the next retry time has not been reached for any of |
| 22739 | them, the address is bounced without trying any deliveries. In other words, |
| 22740 | Exim delays retrying an IP address after the final cutoff time until a new |
| 22741 | retry time is reached, and can therefore bounce an address without ever trying |
| 22742 | a delivery, when machines have been down for a long time. Some people are |
| 22743 | unhappy at this prospect, so... |
| 22744 | |
| 22745 | If &%delay_after_cutoff%& is set false, Exim behaves differently. If all IP |
| 22746 | addresses are past their final cutoff time, Exim tries to deliver to those |
| 22747 | IP addresses that have not been tried since the message arrived. If there are |
| 22748 | none, of if they all fail, the address is bounced. In other words, it does not |
| 22749 | delay when a new message arrives, but immediately tries those expired IP |
| 22750 | addresses that haven't been tried since the message arrived. If there is a |
| 22751 | continuous stream of messages for the dead hosts, unsetting |
| 22752 | &%delay_after_cutoff%& means that there will be many more attempts to deliver |
| 22753 | to them. |
| 22754 | |
| 22755 | |
| 22756 | .option dns_qualify_single smtp boolean true |
| 22757 | If the &%hosts%& or &%fallback_hosts%& option is being used, |
| 22758 | and the &%gethostbyname%& option is false, |
| 22759 | the RES_DEFNAMES resolver option is set. See the &%qualify_single%& option |
| 22760 | in chapter &<<CHAPdnslookup>>& for more details. |
| 22761 | |
| 22762 | |
| 22763 | .option dns_search_parents smtp boolean false |
| 22764 | If the &%hosts%& or &%fallback_hosts%& option is being used, and the |
| 22765 | &%gethostbyname%& option is false, the RES_DNSRCH resolver option is set. |
| 22766 | See the &%search_parents%& option in chapter &<<CHAPdnslookup>>& for more |
| 22767 | details. |
| 22768 | |
| 22769 | |
| 22770 | .new |
| 22771 | .option dnssec_request_domains smtp "domain list&!!" unset |
| 22772 | .cindex "MX record" "security" |
| 22773 | .cindex "DNSSEC" "MX lookup" |
| 22774 | .cindex "security" "MX lookup" |
| 22775 | .cindex "DNS" "DNSSEC" |
| 22776 | DNS lookups for domains matching &%dnssec_request_domains%& will be done with |
| 22777 | the dnssec request bit set. |
| 22778 | This applies to all of the SRV, MX A6, AAAA, A lookup sequence. |
| 22779 | .wen |
| 22780 | |
| 22781 | |
| 22782 | |
| 22783 | .new |
| 22784 | .option dnssec_require_domains smtp "domain list&!!" unset |
| 22785 | .cindex "MX record" "security" |
| 22786 | .cindex "DNSSEC" "MX lookup" |
| 22787 | .cindex "security" "MX lookup" |
| 22788 | .cindex "DNS" "DNSSEC" |
| 22789 | DNS lookups for domains matching &%dnssec_request_domains%& will be done with |
| 22790 | the dnssec request bit set. Any returns not having the Authenticated Data bit |
| 22791 | (AD bit) set wil be ignored and logged as a host-lookup failure. |
| 22792 | This applies to all of the SRV, MX A6, AAAA, A lookup sequence. |
| 22793 | .wen |
| 22794 | |
| 22795 | |
| 22796 | |
| 22797 | .option dscp smtp string&!! unset |
| 22798 | .cindex "DCSP" "outbound" |
| 22799 | This option causes the DSCP value associated with a socket to be set to one |
| 22800 | of a number of fixed strings or to numeric value. |
| 22801 | The &%-bI:dscp%& option may be used to ask Exim which names it knows of. |
| 22802 | Common values include &`throughput`&, &`mincost`&, and on newer systems |
| 22803 | &`ef`&, &`af41`&, etc. Numeric values may be in the range 0 to 0x3F. |
| 22804 | |
| 22805 | The outbound packets from Exim will be marked with this value in the header |
| 22806 | (for IPv4, the TOS field; for IPv6, the TCLASS field); there is no guarantee |
| 22807 | that these values will have any effect, not be stripped by networking |
| 22808 | equipment, or do much of anything without cooperation with your Network |
| 22809 | Engineer and those of all network operators between the source and destination. |
| 22810 | |
| 22811 | |
| 22812 | .option fallback_hosts smtp "string list" unset |
| 22813 | .cindex "fallback" "hosts specified on transport" |
| 22814 | String expansion is not applied to this option. The argument must be a |
| 22815 | colon-separated list of host names or IP addresses, optionally also including |
| 22816 | port numbers, though the separator can be changed, as described in section |
| 22817 | &<<SECTlistconstruct>>&. Each individual item in the list is the same as an |
| 22818 | item in a &%route_list%& setting for the &(manualroute)& router, as described |
| 22819 | in section &<<SECTformatonehostitem>>&. |
| 22820 | |
| 22821 | Fallback hosts can also be specified on routers, which associate them with the |
| 22822 | addresses they process. As for the &%hosts%& option without &%hosts_override%&, |
| 22823 | &%fallback_hosts%& specified on the transport is used only if the address does |
| 22824 | not have its own associated fallback host list. Unlike &%hosts%&, a setting of |
| 22825 | &%fallback_hosts%& on an address is not overridden by &%hosts_override%&. |
| 22826 | However, &%hosts_randomize%& does apply to fallback host lists. |
| 22827 | |
| 22828 | If Exim is unable to deliver to any of the hosts for a particular address, and |
| 22829 | the errors are not permanent rejections, the address is put on a separate |
| 22830 | transport queue with its host list replaced by the fallback hosts, unless the |
| 22831 | address was routed via MX records and the current host was in the original MX |
| 22832 | list. In that situation, the fallback host list is not used. |
| 22833 | |
| 22834 | Once normal deliveries are complete, the fallback queue is delivered by |
| 22835 | re-running the same transports with the new host lists. If several failing |
| 22836 | addresses have the same fallback hosts (and &%max_rcpt%& permits it), a single |
| 22837 | copy of the message is sent. |
| 22838 | |
| 22839 | The resolution of the host names on the fallback list is controlled by the |
| 22840 | &%gethostbyname%& option, as for the &%hosts%& option. Fallback hosts apply |
| 22841 | both to cases when the host list comes with the address and when it is taken |
| 22842 | from &%hosts%&. This option provides a &"use a smart host only if delivery |
| 22843 | fails"& facility. |
| 22844 | |
| 22845 | |
| 22846 | .option final_timeout smtp time 10m |
| 22847 | This is the timeout that applies while waiting for the response to the final |
| 22848 | line containing just &"."& that terminates a message. Its value must not be |
| 22849 | zero. |
| 22850 | |
| 22851 | .option gethostbyname smtp boolean false |
| 22852 | If this option is true when the &%hosts%& and/or &%fallback_hosts%& options are |
| 22853 | being used, names are looked up using &[gethostbyname()]& |
| 22854 | (or &[getipnodebyname()]& when available) |
| 22855 | instead of using the DNS. Of course, that function may in fact use the DNS, but |
| 22856 | it may also consult other sources of information such as &_/etc/hosts_&. |
| 22857 | |
| 22858 | .option gnutls_compat_mode smtp boolean unset |
| 22859 | This option controls whether GnuTLS is used in compatibility mode in an Exim |
| 22860 | server. This reduces security slightly, but improves interworking with older |
| 22861 | implementations of TLS. |
| 22862 | |
| 22863 | .option helo_data smtp string&!! "see below" |
| 22864 | .cindex "HELO" "argument, setting" |
| 22865 | .cindex "EHLO" "argument, setting" |
| 22866 | .cindex "LHLO argument setting" |
| 22867 | The value of this option is expanded after a connection to a another host has |
| 22868 | been set up. The result is used as the argument for the EHLO, HELO, or LHLO |
| 22869 | command that starts the outgoing SMTP or LMTP session. The default value of the |
| 22870 | option is: |
| 22871 | .code |
| 22872 | $primary_hostname |
| 22873 | .endd |
| 22874 | During the expansion, the variables &$host$& and &$host_address$& are set to |
| 22875 | the identity of the remote host, and the variables &$sending_ip_address$& and |
| 22876 | &$sending_port$& are set to the local IP address and port number that are being |
| 22877 | used. These variables can be used to generate different values for different |
| 22878 | servers or different local IP addresses. For example, if you want the string |
| 22879 | that is used for &%helo_data%& to be obtained by a DNS lookup of the outgoing |
| 22880 | interface address, you could use this: |
| 22881 | .code |
| 22882 | helo_data = ${lookup dnsdb{ptr=$sending_ip_address}{$value}\ |
| 22883 | {$primary_hostname}} |
| 22884 | .endd |
| 22885 | The use of &%helo_data%& applies both to sending messages and when doing |
| 22886 | callouts. |
| 22887 | |
| 22888 | .option hosts smtp "string list&!!" unset |
| 22889 | Hosts are associated with an address by a router such as &(dnslookup)&, which |
| 22890 | finds the hosts by looking up the address domain in the DNS, or by |
| 22891 | &(manualroute)&, which has lists of hosts in its configuration. However, |
| 22892 | email addresses can be passed to the &(smtp)& transport by any router, and not |
| 22893 | all of them can provide an associated list of hosts. |
| 22894 | |
| 22895 | The &%hosts%& option specifies a list of hosts to be used if the address being |
| 22896 | processed does not have any hosts associated with it. The hosts specified by |
| 22897 | &%hosts%& are also used, whether or not the address has its own hosts, if |
| 22898 | &%hosts_override%& is set. |
| 22899 | |
| 22900 | The string is first expanded, before being interpreted as a colon-separated |
| 22901 | list of host names or IP addresses, possibly including port numbers. The |
| 22902 | separator may be changed to something other than colon, as described in section |
| 22903 | &<<SECTlistconstruct>>&. Each individual item in the list is the same as an |
| 22904 | item in a &%route_list%& setting for the &(manualroute)& router, as described |
| 22905 | in section &<<SECTformatonehostitem>>&. However, note that the &`/MX`& facility |
| 22906 | of the &(manualroute)& router is not available here. |
| 22907 | |
| 22908 | If the expansion fails, delivery is deferred. Unless the failure was caused by |
| 22909 | the inability to complete a lookup, the error is logged to the panic log as |
| 22910 | well as the main log. Host names are looked up either by searching directly for |
| 22911 | address records in the DNS or by calling &[gethostbyname()]& (or |
| 22912 | &[getipnodebyname()]& when available), depending on the setting of the |
| 22913 | &%gethostbyname%& option. When Exim is compiled with IPv6 support, if a host |
| 22914 | that is looked up in the DNS has both IPv4 and IPv6 addresses, both types of |
| 22915 | address are used. |
| 22916 | |
| 22917 | During delivery, the hosts are tried in order, subject to their retry status, |
| 22918 | unless &%hosts_randomize%& is set. |
| 22919 | |
| 22920 | |
| 22921 | .option hosts_avoid_esmtp smtp "host list&!!" unset |
| 22922 | .cindex "ESMTP, avoiding use of" |
| 22923 | .cindex "HELO" "forcing use of" |
| 22924 | .cindex "EHLO" "avoiding use of" |
| 22925 | .cindex "PIPELINING" "avoiding the use of" |
| 22926 | This option is for use with broken hosts that announce ESMTP facilities (for |
| 22927 | example, PIPELINING) and then fail to implement them properly. When a host |
| 22928 | matches &%hosts_avoid_esmtp%&, Exim sends HELO rather than EHLO at the |
| 22929 | start of the SMTP session. This means that it cannot use any of the ESMTP |
| 22930 | facilities such as AUTH, PIPELINING, SIZE, and STARTTLS. |
| 22931 | |
| 22932 | |
| 22933 | .option hosts_avoid_pipelining smtp "host list&!!" unset |
| 22934 | .cindex "PIPELINING" "avoiding the use of" |
| 22935 | Exim will not use the SMTP PIPELINING extension when delivering to any host |
| 22936 | that matches this list, even if the server host advertises PIPELINING support. |
| 22937 | |
| 22938 | |
| 22939 | .option hosts_avoid_tls smtp "host list&!!" unset |
| 22940 | .cindex "TLS" "avoiding for certain hosts" |
| 22941 | Exim will not try to start a TLS session when delivering to any host that |
| 22942 | matches this list. See chapter &<<CHAPTLS>>& for details of TLS. |
| 22943 | |
| 22944 | .option hosts_verify_avoid_tls smtp "host list&!!" * |
| 22945 | .cindex "TLS" "avoiding for certain hosts" |
| 22946 | Exim will not try to start a TLS session for a verify callout, |
| 22947 | or when delivering in cutthrough mode, |
| 22948 | to any host that matches this list. |
| 22949 | Note that the default is to not use TLS. |
| 22950 | |
| 22951 | |
| 22952 | .option hosts_max_try smtp integer 5 |
| 22953 | .cindex "host" "maximum number to try" |
| 22954 | .cindex "limit" "number of hosts tried" |
| 22955 | .cindex "limit" "number of MX tried" |
| 22956 | .cindex "MX record" "maximum tried" |
| 22957 | This option limits the number of IP addresses that are tried for any one |
| 22958 | delivery in cases where there are temporary delivery errors. Section |
| 22959 | &<<SECTvalhosmax>>& describes in detail how the value of this option is used. |
| 22960 | |
| 22961 | |
| 22962 | .option hosts_max_try_hardlimit smtp integer 50 |
| 22963 | This is an additional check on the maximum number of IP addresses that Exim |
| 22964 | tries for any one delivery. Section &<<SECTvalhosmax>>& describes its use and |
| 22965 | why it exists. |
| 22966 | |
| 22967 | |
| 22968 | |
| 22969 | .option hosts_nopass_tls smtp "host list&!!" unset |
| 22970 | .cindex "TLS" "passing connection" |
| 22971 | .cindex "multiple SMTP deliveries" |
| 22972 | .cindex "TLS" "multiple message deliveries" |
| 22973 | For any host that matches this list, a connection on which a TLS session has |
| 22974 | been started will not be passed to a new delivery process for sending another |
| 22975 | message on the same connection. See section &<<SECTmulmessam>>& for an |
| 22976 | explanation of when this might be needed. |
| 22977 | |
| 22978 | |
| 22979 | .option hosts_override smtp boolean false |
| 22980 | If this option is set and the &%hosts%& option is also set, any hosts that are |
| 22981 | attached to the address are ignored, and instead the hosts specified by the |
| 22982 | &%hosts%& option are always used. This option does not apply to |
| 22983 | &%fallback_hosts%&. |
| 22984 | |
| 22985 | |
| 22986 | .option hosts_randomize smtp boolean false |
| 22987 | .cindex "randomized host list" |
| 22988 | .cindex "host" "list of; randomized" |
| 22989 | .cindex "fallback" "randomized hosts" |
| 22990 | If this option is set, and either the list of hosts is taken from the |
| 22991 | &%hosts%& or the &%fallback_hosts%& option, or the hosts supplied by the router |
| 22992 | were not obtained from MX records (this includes fallback hosts from the |
| 22993 | router), and were not randomized by the router, the order of trying the hosts |
| 22994 | is randomized each time the transport runs. Randomizing the order of a host |
| 22995 | list can be used to do crude load sharing. |
| 22996 | |
| 22997 | When &%hosts_randomize%& is true, a host list may be split into groups whose |
| 22998 | order is separately randomized. This makes it possible to set up MX-like |
| 22999 | behaviour. The boundaries between groups are indicated by an item that is just |
| 23000 | &`+`& in the host list. For example: |
| 23001 | .code |
| 23002 | hosts = host1:host2:host3:+:host4:host5 |
| 23003 | .endd |
| 23004 | The order of the first three hosts and the order of the last two hosts is |
| 23005 | randomized for each use, but the first three always end up before the last two. |
| 23006 | If &%hosts_randomize%& is not set, a &`+`& item in the list is ignored. |
| 23007 | |
| 23008 | .option hosts_require_auth smtp "host list&!!" unset |
| 23009 | .cindex "authentication" "required by client" |
| 23010 | This option provides a list of servers for which authentication must succeed |
| 23011 | before Exim will try to transfer a message. If authentication fails for |
| 23012 | servers which are not in this list, Exim tries to send unauthenticated. If |
| 23013 | authentication fails for one of these servers, delivery is deferred. This |
| 23014 | temporary error is detectable in the retry rules, so it can be turned into a |
| 23015 | hard failure if required. See also &%hosts_try_auth%&, and chapter |
| 23016 | &<<CHAPSMTPAUTH>>& for details of authentication. |
| 23017 | |
| 23018 | |
| 23019 | .option hosts_request_ocsp smtp "host list&!!" * |
| 23020 | .cindex "TLS" "requiring for certain servers" |
| 23021 | Exim will request a Certificate Status on a |
| 23022 | TLS session for any host that matches this list. |
| 23023 | &%tls_verify_certificates%& should also be set for the transport. |
| 23024 | |
| 23025 | .option hosts_require_ocsp smtp "host list&!!" unset |
| 23026 | .cindex "TLS" "requiring for certain servers" |
| 23027 | Exim will request, and check for a valid Certificate Status being given, on a |
| 23028 | TLS session for any host that matches this list. |
| 23029 | &%tls_verify_certificates%& should also be set for the transport. |
| 23030 | |
| 23031 | .option hosts_require_tls smtp "host list&!!" unset |
| 23032 | .cindex "TLS" "requiring for certain servers" |
| 23033 | Exim will insist on using a TLS session when delivering to any host that |
| 23034 | matches this list. See chapter &<<CHAPTLS>>& for details of TLS. |
| 23035 | &*Note*&: This option affects outgoing mail only. To insist on TLS for |
| 23036 | incoming messages, use an appropriate ACL. |
| 23037 | |
| 23038 | .option hosts_try_auth smtp "host list&!!" unset |
| 23039 | .cindex "authentication" "optional in client" |
| 23040 | This option provides a list of servers to which, provided they announce |
| 23041 | authentication support, Exim will attempt to authenticate as a client when it |
| 23042 | connects. If authentication fails, Exim will try to transfer the message |
| 23043 | unauthenticated. See also &%hosts_require_auth%&, and chapter |
| 23044 | &<<CHAPSMTPAUTH>>& for details of authentication. |
| 23045 | |
| 23046 | .option hosts_try_prdr smtp "host list&!!" unset |
| 23047 | .cindex "PRDR" "enabling, optional in client" |
| 23048 | This option provides a list of servers to which, provided they announce |
| 23049 | PRDR support, Exim will attempt to negotiate PRDR |
| 23050 | for multi-recipient messages. |
| 23051 | |
| 23052 | .option interface smtp "string list&!!" unset |
| 23053 | .cindex "bind IP address" |
| 23054 | .cindex "IP address" "binding" |
| 23055 | .vindex "&$host$&" |
| 23056 | .vindex "&$host_address$&" |
| 23057 | This option specifies which interface to bind to when making an outgoing SMTP |
| 23058 | call. The value is an IP address, not an interface name such as |
| 23059 | &`eth0`&. Do not confuse this with the interface address that was used when a |
| 23060 | message was received, which is in &$received_ip_address$&, formerly known as |
| 23061 | &$interface_address$&. The name was changed to minimize confusion with the |
| 23062 | outgoing interface address. There is no variable that contains an outgoing |
| 23063 | interface address because, unless it is set by this option, its value is |
| 23064 | unknown. |
| 23065 | |
| 23066 | During the expansion of the &%interface%& option the variables &$host$& and |
| 23067 | &$host_address$& refer to the host to which a connection is about to be made |
| 23068 | during the expansion of the string. Forced expansion failure, or an empty |
| 23069 | string result causes the option to be ignored. Otherwise, after expansion, the |
| 23070 | string must be a list of IP addresses, colon-separated by default, but the |
| 23071 | separator can be changed in the usual way. For example: |
| 23072 | .code |
| 23073 | interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061 |
| 23074 | .endd |
| 23075 | The first interface of the correct type (IPv4 or IPv6) is used for the outgoing |
| 23076 | connection. If none of them are the correct type, the option is ignored. If |
| 23077 | &%interface%& is not set, or is ignored, the system's IP functions choose which |
| 23078 | interface to use if the host has more than one. |
| 23079 | |
| 23080 | |
| 23081 | .option keepalive smtp boolean true |
| 23082 | .cindex "keepalive" "on outgoing connection" |
| 23083 | This option controls the setting of SO_KEEPALIVE on outgoing TCP/IP socket |
| 23084 | connections. When set, it causes the kernel to probe idle connections |
| 23085 | periodically, by sending packets with &"old"& sequence numbers. The other end |
| 23086 | of the connection should send a acknowledgment if the connection is still okay |
| 23087 | or a reset if the connection has been aborted. The reason for doing this is |
| 23088 | that it has the beneficial effect of freeing up certain types of connection |
| 23089 | that can get stuck when the remote host is disconnected without tidying up the |
| 23090 | TCP/IP call properly. The keepalive mechanism takes several hours to detect |
| 23091 | unreachable hosts. |
| 23092 | |
| 23093 | |
| 23094 | .option lmtp_ignore_quota smtp boolean false |
| 23095 | .cindex "LMTP" "ignoring quota errors" |
| 23096 | If this option is set true when the &%protocol%& option is set to &"lmtp"&, the |
| 23097 | string &`IGNOREQUOTA`& is added to RCPT commands, provided that the LMTP server |
| 23098 | has advertised support for IGNOREQUOTA in its response to the LHLO command. |
| 23099 | |
| 23100 | .option max_rcpt smtp integer 100 |
| 23101 | .cindex "RCPT" "maximum number of outgoing" |
| 23102 | This option limits the number of RCPT commands that are sent in a single |
| 23103 | SMTP message transaction. Each set of addresses is treated independently, and |
| 23104 | so can cause parallel connections to the same host if &%remote_max_parallel%& |
| 23105 | permits this. |
| 23106 | |
| 23107 | |
| 23108 | .option multi_domain smtp boolean true |
| 23109 | .vindex "&$domain$&" |
| 23110 | When this option is set, the &(smtp)& transport can handle a number of |
| 23111 | addresses containing a mixture of different domains provided they all resolve |
| 23112 | to the same list of hosts. Turning the option off restricts the transport to |
| 23113 | handling only one domain at a time. This is useful if you want to use |
| 23114 | &$domain$& in an expansion for the transport, because it is set only when there |
| 23115 | is a single domain involved in a remote delivery. |
| 23116 | |
| 23117 | |
| 23118 | .option port smtp string&!! "see below" |
| 23119 | .cindex "port" "sending TCP/IP" |
| 23120 | .cindex "TCP/IP" "setting outgoing port" |
| 23121 | This option specifies the TCP/IP port on the server to which Exim connects. |
| 23122 | &*Note:*& Do not confuse this with the port that was used when a message was |
| 23123 | received, which is in &$received_port$&, formerly known as &$interface_port$&. |
| 23124 | The name was changed to minimize confusion with the outgoing port. There is no |
| 23125 | variable that contains an outgoing port. |
| 23126 | |
| 23127 | If the value of this option begins with a digit it is taken as a port number; |
| 23128 | otherwise it is looked up using &[getservbyname()]&. The default value is |
| 23129 | normally &"smtp"&, but if &%protocol%& is set to &"lmtp"&, the default is |
| 23130 | &"lmtp"&. If the expansion fails, or if a port number cannot be found, delivery |
| 23131 | is deferred. |
| 23132 | |
| 23133 | |
| 23134 | |
| 23135 | .option protocol smtp string smtp |
| 23136 | .cindex "LMTP" "over TCP/IP" |
| 23137 | .cindex "ssmtp protocol" "outbound" |
| 23138 | .cindex "TLS" "SSL-on-connect outbound" |
| 23139 | .vindex "&$port$&" |
| 23140 | If this option is set to &"lmtp"& instead of &"smtp"&, the default value for |
| 23141 | the &%port%& option changes to &"lmtp"&, and the transport operates the LMTP |
| 23142 | protocol (RFC 2033) instead of SMTP. This protocol is sometimes used for local |
| 23143 | deliveries into closed message stores. Exim also has support for running LMTP |
| 23144 | over a pipe to a local process &-- see chapter &<<CHAPLMTP>>&. |
| 23145 | |
| 23146 | If this option is set to &"smtps"&, the default vaule for the &%port%& option |
| 23147 | changes to &"smtps"&, and the transport initiates TLS immediately after |
| 23148 | connecting, as an outbound SSL-on-connect, instead of using STARTTLS to upgrade. |
| 23149 | The Internet standards bodies strongly discourage use of this mode. |
| 23150 | |
| 23151 | |
| 23152 | .option retry_include_ip_address smtp boolean true |
| 23153 | Exim normally includes both the host name and the IP address in the key it |
| 23154 | constructs for indexing retry data after a temporary delivery failure. This |
| 23155 | means that when one of several IP addresses for a host is failing, it gets |
| 23156 | tried periodically (controlled by the retry rules), but use of the other IP |
| 23157 | addresses is not affected. |
| 23158 | |
| 23159 | However, in some dialup environments hosts are assigned a different IP address |
| 23160 | each time they connect. In this situation the use of the IP address as part of |
| 23161 | the retry key leads to undesirable behaviour. Setting this option false causes |
| 23162 | Exim to use only the host name. This should normally be done on a separate |
| 23163 | instance of the &(smtp)& transport, set up specially to handle the dialup |
| 23164 | hosts. |
| 23165 | |
| 23166 | |
| 23167 | .option serialize_hosts smtp "host list&!!" unset |
| 23168 | .cindex "serializing connections" |
| 23169 | .cindex "host" "serializing connections" |
| 23170 | Because Exim operates in a distributed manner, if several messages for the same |
| 23171 | host arrive at around the same time, more than one simultaneous connection to |
| 23172 | the remote host can occur. This is not usually a problem except when there is a |
| 23173 | slow link between the hosts. In that situation it may be helpful to restrict |
| 23174 | Exim to one connection at a time. This can be done by setting |
| 23175 | &%serialize_hosts%& to match the relevant hosts. |
| 23176 | |
| 23177 | .cindex "hints database" "serializing deliveries to a host" |
| 23178 | Exim implements serialization by means of a hints database in which a record is |
| 23179 | written whenever a process connects to one of the restricted hosts. The record |
| 23180 | is deleted when the connection is completed. Obviously there is scope for |
| 23181 | records to get left lying around if there is a system or program crash. To |
| 23182 | guard against this, Exim ignores any records that are more than six hours old. |
| 23183 | |
| 23184 | If you set up this kind of serialization, you should also arrange to delete the |
| 23185 | relevant hints database whenever your system reboots. The names of the files |
| 23186 | start with &_misc_& and they are kept in the &_spool/db_& directory. There |
| 23187 | may be one or two files, depending on the type of DBM in use. The same files |
| 23188 | are used for ETRN serialization. |
| 23189 | |
| 23190 | |
| 23191 | .option size_addition smtp integer 1024 |
| 23192 | .cindex "SMTP" "SIZE" |
| 23193 | .cindex "message" "size issue for transport filter" |
| 23194 | .cindex "size" "of message" |
| 23195 | .cindex "transport" "filter" |
| 23196 | .cindex "filter" "transport filter" |
| 23197 | If a remote SMTP server indicates that it supports the SIZE option of the |
| 23198 | MAIL command, Exim uses this to pass over the message size at the start of |
| 23199 | an SMTP transaction. It adds the value of &%size_addition%& to the value it |
| 23200 | sends, to allow for headers and other text that may be added during delivery by |
| 23201 | configuration options or in a transport filter. It may be necessary to increase |
| 23202 | this if a lot of text is added to messages. |
| 23203 | |
| 23204 | Alternatively, if the value of &%size_addition%& is set negative, it disables |
| 23205 | the use of the SIZE option altogether. |
| 23206 | |
| 23207 | |
| 23208 | .option tls_certificate smtp string&!! unset |
| 23209 | .cindex "TLS" "client certificate, location of" |
| 23210 | .cindex "certificate" "client, location of" |
| 23211 | .vindex "&$host$&" |
| 23212 | .vindex "&$host_address$&" |
| 23213 | The value of this option must be the absolute path to a file which contains the |
| 23214 | client's certificate, for possible use when sending a message over an encrypted |
| 23215 | connection. The values of &$host$& and &$host_address$& are set to the name and |
| 23216 | address of the server during the expansion. See chapter &<<CHAPTLS>>& for |
| 23217 | details of TLS. |
| 23218 | |
| 23219 | &*Note*&: This option must be set if you want Exim to be able to use a TLS |
| 23220 | certificate when sending messages as a client. The global option of the same |
| 23221 | name specifies the certificate for Exim as a server; it is not automatically |
| 23222 | assumed that the same certificate should be used when Exim is operating as a |
| 23223 | client. |
| 23224 | |
| 23225 | |
| 23226 | .option tls_crl smtp string&!! unset |
| 23227 | .cindex "TLS" "client certificate revocation list" |
| 23228 | .cindex "certificate" "revocation list for client" |
| 23229 | This option specifies a certificate revocation list. The expanded value must |
| 23230 | be the name of a file that contains a CRL in PEM format. |
| 23231 | |
| 23232 | |
| 23233 | .option tls_dh_min_bits smtp integer 1024 |
| 23234 | .cindex "TLS" "Diffie-Hellman minimum acceptable size" |
| 23235 | When establishing a TLS session, if a ciphersuite which uses Diffie-Hellman |
| 23236 | key agreement is negotiated, the server will provide a large prime number |
| 23237 | for use. This option establishes the minimum acceptable size of that number. |
| 23238 | If the parameter offered by the server is too small, then the TLS handshake |
| 23239 | will fail. |
| 23240 | |
| 23241 | Only supported when using GnuTLS. |
| 23242 | |
| 23243 | |
| 23244 | .option tls_privatekey smtp string&!! unset |
| 23245 | .cindex "TLS" "client private key, location of" |
| 23246 | .vindex "&$host$&" |
| 23247 | .vindex "&$host_address$&" |
| 23248 | The value of this option must be the absolute path to a file which contains the |
| 23249 | client's private key. This is used when sending a message over an encrypted |
| 23250 | connection using a client certificate. The values of &$host$& and |
| 23251 | &$host_address$& are set to the name and address of the server during the |
| 23252 | expansion. If this option is unset, or the expansion is forced to fail, or the |
| 23253 | result is an empty string, the private key is assumed to be in the same file as |
| 23254 | the certificate. See chapter &<<CHAPTLS>>& for details of TLS. |
| 23255 | |
| 23256 | |
| 23257 | .option tls_require_ciphers smtp string&!! unset |
| 23258 | .cindex "TLS" "requiring specific ciphers" |
| 23259 | .cindex "cipher" "requiring specific" |
| 23260 | .vindex "&$host$&" |
| 23261 | .vindex "&$host_address$&" |
| 23262 | The value of this option must be a list of permitted cipher suites, for use |
| 23263 | when setting up an outgoing encrypted connection. (There is a global option of |
| 23264 | the same name for controlling incoming connections.) The values of &$host$& and |
| 23265 | &$host_address$& are set to the name and address of the server during the |
| 23266 | expansion. See chapter &<<CHAPTLS>>& for details of TLS; note that this option |
| 23267 | is used in different ways by OpenSSL and GnuTLS (see sections |
| 23268 | &<<SECTreqciphssl>>& and &<<SECTreqciphgnu>>&). For GnuTLS, the order of the |
| 23269 | ciphers is a preference order. |
| 23270 | |
| 23271 | |
| 23272 | |
| 23273 | .option tls_sni smtp string&!! unset |
| 23274 | .cindex "TLS" "Server Name Indication" |
| 23275 | .vindex "&$tls_sni$&" |
| 23276 | If this option is set then it sets the $tls_out_sni variable and causes any |
| 23277 | TLS session to pass this value as the Server Name Indication extension to |
| 23278 | the remote side, which can be used by the remote side to select an appropriate |
| 23279 | certificate and private key for the session. |
| 23280 | |
| 23281 | See &<<SECTtlssni>>& for more information. |
| 23282 | |
| 23283 | Note that for OpenSSL, this feature requires a build of OpenSSL that supports |
| 23284 | TLS extensions. |
| 23285 | |
| 23286 | |
| 23287 | |
| 23288 | |
| 23289 | .option tls_tempfail_tryclear smtp boolean true |
| 23290 | .cindex "4&'xx'& responses" "to STARTTLS" |
| 23291 | When the server host is not in &%hosts_require_tls%&, and there is a problem in |
| 23292 | setting up a TLS session, this option determines whether or not Exim should try |
| 23293 | to deliver the message unencrypted. If it is set false, delivery to the |
| 23294 | current host is deferred; if there are other hosts, they are tried. If this |
| 23295 | option is set true, Exim attempts to deliver unencrypted after a 4&'xx'& |
| 23296 | response to STARTTLS. Also, if STARTTLS is accepted, but the subsequent |
| 23297 | TLS negotiation fails, Exim closes the current connection (because it is in an |
| 23298 | unknown state), opens a new one to the same host, and then tries the delivery |
| 23299 | in clear. |
| 23300 | |
| 23301 | |
| 23302 | .option tls_try_verify_hosts smtp "host list&!! unset |
| 23303 | .cindex "TLS" "server certificate verification" |
| 23304 | .cindex "certificate" "verification of server" |
| 23305 | This option gives a list of hosts for which, on encrypted connections, |
| 23306 | certificate verification will be tried but need not succeed. |
| 23307 | The &%tls_verify_certificates%& option must also be set. |
| 23308 | Note that unless the host is in this list |
| 23309 | TLS connections will be denied to hosts using self-signed certificates |
| 23310 | when &%tls_verify_certificates%& is set. |
| 23311 | The &$tls_out_certificate_verified$& variable is set when |
| 23312 | certificate verification succeeds. |
| 23313 | |
| 23314 | |
| 23315 | .option tls_verify_certificates smtp string&!! unset |
| 23316 | .cindex "TLS" "server certificate verification" |
| 23317 | .cindex "certificate" "verification of server" |
| 23318 | .vindex "&$host$&" |
| 23319 | .vindex "&$host_address$&" |
| 23320 | The value of this option must be the absolute path to a file containing |
| 23321 | permitted server certificates, for use when setting up an encrypted connection. |
| 23322 | Alternatively, if you are using OpenSSL, you can set |
| 23323 | &%tls_verify_certificates%& to the name of a directory containing certificate |
| 23324 | files. This does not work with GnuTLS; the option must be set to the name of a |
| 23325 | single file if you are using GnuTLS. The values of &$host$& and |
| 23326 | &$host_address$& are set to the name and address of the server during the |
| 23327 | expansion of this option. See chapter &<<CHAPTLS>>& for details of TLS. |
| 23328 | |
| 23329 | For back-compatability, |
| 23330 | if neither tls_verify_hosts nor tls_try_verify_hosts are set |
| 23331 | and certificate verification fails the TLS connection is closed. |
| 23332 | |
| 23333 | |
| 23334 | .option tls_verify_hosts smtp "host list&!! unset |
| 23335 | .cindex "TLS" "server certificate verification" |
| 23336 | .cindex "certificate" "verification of server" |
| 23337 | This option gives a list of hosts for which. on encrypted connections, |
| 23338 | certificate verification must succeed. |
| 23339 | The &%tls_verify_certificates%& option must also be set. |
| 23340 | If both this option and &%tls_try_verify_hosts%& are unset |
| 23341 | operation is as if this option selected all hosts. |
| 23342 | |
| 23343 | |
| 23344 | |
| 23345 | |
| 23346 | .section "How the limits for the number of hosts to try are used" &&& |
| 23347 | "SECTvalhosmax" |
| 23348 | .cindex "host" "maximum number to try" |
| 23349 | .cindex "limit" "hosts; maximum number tried" |
| 23350 | There are two options that are concerned with the number of hosts that are |
| 23351 | tried when an SMTP delivery takes place. They are &%hosts_max_try%& and |
| 23352 | &%hosts_max_try_hardlimit%&. |
| 23353 | |
| 23354 | |
| 23355 | The &%hosts_max_try%& option limits the number of hosts that are tried |
| 23356 | for a single delivery. However, despite the term &"host"& in its name, the |
| 23357 | option actually applies to each IP address independently. In other words, a |
| 23358 | multihomed host is treated as several independent hosts, just as it is for |
| 23359 | retrying. |
| 23360 | |
| 23361 | Many of the larger ISPs have multiple MX records which often point to |
| 23362 | multihomed hosts. As a result, a list of a dozen or more IP addresses may be |
| 23363 | created as a result of routing one of these domains. |
| 23364 | |
| 23365 | Trying every single IP address on such a long list does not seem sensible; if |
| 23366 | several at the top of the list fail, it is reasonable to assume there is some |
| 23367 | problem that is likely to affect all of them. Roughly speaking, the value of |
| 23368 | &%hosts_max_try%& is the maximum number that are tried before deferring the |
| 23369 | delivery. However, the logic cannot be quite that simple. |
| 23370 | |
| 23371 | Firstly, IP addresses that are skipped because their retry times have not |
| 23372 | arrived do not count, and in addition, addresses that are past their retry |
| 23373 | limits are also not counted, even when they are tried. This means that when |
| 23374 | some IP addresses are past their retry limits, more than the value of |
| 23375 | &%hosts_max_retry%& may be tried. The reason for this behaviour is to ensure |
| 23376 | that all IP addresses are considered before timing out an email address (but |
| 23377 | see below for an exception). |
| 23378 | |
| 23379 | Secondly, when the &%hosts_max_try%& limit is reached, Exim looks down the host |
| 23380 | list to see if there is a subsequent host with a different (higher valued) MX. |
| 23381 | If there is, that host is considered next, and the current IP address is used |
| 23382 | but not counted. This behaviour helps in the case of a domain with a retry rule |
| 23383 | that hardly ever delays any hosts, as is now explained: |
| 23384 | |
| 23385 | Consider the case of a long list of hosts with one MX value, and a few with a |
| 23386 | higher MX value. If &%hosts_max_try%& is small (the default is 5) only a few |
| 23387 | hosts at the top of the list are tried at first. With the default retry rule, |
| 23388 | which specifies increasing retry times, the higher MX hosts are eventually |
| 23389 | tried when those at the top of the list are skipped because they have not |
| 23390 | reached their retry times. |
| 23391 | |
| 23392 | However, it is common practice to put a fixed short retry time on domains for |
| 23393 | large ISPs, on the grounds that their servers are rarely down for very long. |
| 23394 | Unfortunately, these are exactly the domains that tend to resolve to long lists |
| 23395 | of hosts. The short retry time means that the lowest MX hosts are tried every |
| 23396 | time. The attempts may be in a different order because of random sorting, but |
| 23397 | without the special MX check, the higher MX hosts would never be tried until |
| 23398 | all the lower MX hosts had timed out (which might be several days), because |
| 23399 | there are always some lower MX hosts that have reached their retry times. With |
| 23400 | the special check, Exim considers at least one IP address from each MX value at |
| 23401 | every delivery attempt, even if the &%hosts_max_try%& limit has already been |
| 23402 | reached. |
| 23403 | |
| 23404 | The above logic means that &%hosts_max_try%& is not a hard limit, and in |
| 23405 | particular, Exim normally eventually tries all the IP addresses before timing |
| 23406 | out an email address. When &%hosts_max_try%& was implemented, this seemed a |
| 23407 | reasonable thing to do. Recently, however, some lunatic DNS configurations have |
| 23408 | been set up with hundreds of IP addresses for some domains. It can |
| 23409 | take a very long time indeed for an address to time out in these cases. |
| 23410 | |
| 23411 | The &%hosts_max_try_hardlimit%& option was added to help with this problem. |
| 23412 | Exim never tries more than this number of IP addresses; if it hits this limit |
| 23413 | and they are all timed out, the email address is bounced, even though not all |
| 23414 | possible IP addresses have been tried. |
| 23415 | .ecindex IIDsmttra1 |
| 23416 | .ecindex IIDsmttra2 |
| 23417 | |
| 23418 | |
| 23419 | |
| 23420 | |
| 23421 | |
| 23422 | . //////////////////////////////////////////////////////////////////////////// |
| 23423 | . //////////////////////////////////////////////////////////////////////////// |
| 23424 | |
| 23425 | .chapter "Address rewriting" "CHAPrewrite" |
| 23426 | .scindex IIDaddrew "rewriting" "addresses" |
| 23427 | There are some circumstances in which Exim automatically rewrites domains in |
| 23428 | addresses. The two most common are when an address is given without a domain |
| 23429 | (referred to as an &"unqualified address"&) or when an address contains an |
| 23430 | abbreviated domain that is expanded by DNS lookup. |
| 23431 | |
| 23432 | Unqualified envelope addresses are accepted only for locally submitted |
| 23433 | messages, or for messages that are received from hosts matching |
| 23434 | &%sender_unqualified_hosts%& or &%recipient_unqualified_hosts%&, as |
| 23435 | appropriate. Unqualified addresses in header lines are qualified if they are in |
| 23436 | locally submitted messages, or messages from hosts that are permitted to send |
| 23437 | unqualified envelope addresses. Otherwise, unqualified addresses in header |
| 23438 | lines are neither qualified nor rewritten. |
| 23439 | |
| 23440 | One situation in which Exim does &'not'& automatically rewrite a domain is |
| 23441 | when it is the name of a CNAME record in the DNS. The older RFCs suggest that |
| 23442 | such a domain should be rewritten using the &"canonical"& name, and some MTAs |
| 23443 | do this. The new RFCs do not contain this suggestion. |
| 23444 | |
| 23445 | |
| 23446 | .section "Explicitly configured address rewriting" "SECID147" |
| 23447 | This chapter describes the rewriting rules that can be used in the |
| 23448 | main rewrite section of the configuration file, and also in the generic |
| 23449 | &%headers_rewrite%& option that can be set on any transport. |
| 23450 | |
| 23451 | Some people believe that configured address rewriting is a Mortal Sin. |
| 23452 | Others believe that life is not possible without it. Exim provides the |
| 23453 | facility; you do not have to use it. |
| 23454 | |
| 23455 | The main rewriting rules that appear in the &"rewrite"& section of the |
| 23456 | configuration file are applied to addresses in incoming messages, both envelope |
| 23457 | addresses and addresses in header lines. Each rule specifies the types of |
| 23458 | address to which it applies. |
| 23459 | |
| 23460 | Whether or not addresses in header lines are rewritten depends on the origin of |
| 23461 | the headers and the type of rewriting. Global rewriting, that is, rewriting |
| 23462 | rules from the rewrite section of the configuration file, is applied only to |
| 23463 | those headers that were received with the message. Header lines that are added |
| 23464 | by ACLs or by a system filter or by individual routers or transports (which |
| 23465 | are specific to individual recipient addresses) are not rewritten by the global |
| 23466 | rules. |
| 23467 | |
| 23468 | Rewriting at transport time, by means of the &%headers_rewrite%& option, |
| 23469 | applies all headers except those added by routers and transports. That is, as |
| 23470 | well as the headers that were received with the message, it also applies to |
| 23471 | headers that were added by an ACL or a system filter. |
| 23472 | |
| 23473 | |
| 23474 | In general, rewriting addresses from your own system or domain has some |
| 23475 | legitimacy. Rewriting other addresses should be done only with great care and |
| 23476 | in special circumstances. The author of Exim believes that rewriting should be |
| 23477 | used sparingly, and mainly for &"regularizing"& addresses in your own domains. |
| 23478 | Although it can sometimes be used as a routing tool, this is very strongly |
| 23479 | discouraged. |
| 23480 | |
| 23481 | There are two commonly encountered circumstances where rewriting is used, as |
| 23482 | illustrated by these examples: |
| 23483 | |
| 23484 | .ilist |
| 23485 | The company whose domain is &'hitch.fict.example'& has a number of hosts that |
| 23486 | exchange mail with each other behind a firewall, but there is only a single |
| 23487 | gateway to the outer world. The gateway rewrites &'*.hitch.fict.example'& as |
| 23488 | &'hitch.fict.example'& when sending mail off-site. |
| 23489 | .next |
| 23490 | A host rewrites the local parts of its own users so that, for example, |
| 23491 | &'fp42@hitch.fict.example'& becomes &'Ford.Prefect@hitch.fict.example'&. |
| 23492 | .endlist |
| 23493 | |
| 23494 | |
| 23495 | |
| 23496 | .section "When does rewriting happen?" "SECID148" |
| 23497 | .cindex "rewriting" "timing of" |
| 23498 | .cindex "&ACL;" "rewriting addresses in" |
| 23499 | Configured address rewriting can take place at several different stages of a |
| 23500 | message's processing. |
| 23501 | |
| 23502 | .vindex "&$sender_address$&" |
| 23503 | At the start of an ACL for MAIL, the sender address may have been rewritten |
| 23504 | by a special SMTP-time rewrite rule (see section &<<SECTrewriteS>>&), but no |
| 23505 | ordinary rewrite rules have yet been applied. If, however, the sender address |
| 23506 | is verified in the ACL, it is rewritten before verification, and remains |
| 23507 | rewritten thereafter. The subsequent value of &$sender_address$& is the |
| 23508 | rewritten address. This also applies if sender verification happens in a |
| 23509 | RCPT ACL. Otherwise, when the sender address is not verified, it is |
| 23510 | rewritten as soon as a message's header lines have been received. |
| 23511 | |
| 23512 | .vindex "&$domain$&" |
| 23513 | .vindex "&$local_part$&" |
| 23514 | Similarly, at the start of an ACL for RCPT, the current recipient's address |
| 23515 | may have been rewritten by a special SMTP-time rewrite rule, but no ordinary |
| 23516 | rewrite rules have yet been applied to it. However, the behaviour is different |
| 23517 | from the sender address when a recipient is verified. The address is rewritten |
| 23518 | for the verification, but the rewriting is not remembered at this stage. The |
| 23519 | value of &$local_part$& and &$domain$& after verification are always the same |
| 23520 | as they were before (that is, they contain the unrewritten &-- except for |
| 23521 | SMTP-time rewriting &-- address). |
| 23522 | |
| 23523 | As soon as a message's header lines have been received, all the envelope |
| 23524 | recipient addresses are permanently rewritten, and rewriting is also applied to |
| 23525 | the addresses in the header lines (if configured). This happens before adding |
| 23526 | any header lines that were specified in MAIL or RCPT ACLs, and |
| 23527 | .cindex "&[local_scan()]& function" "address rewriting; timing of" |
| 23528 | before the DATA ACL and &[local_scan()]& functions are run. |
| 23529 | |
| 23530 | When an address is being routed, either for delivery or for verification, |
| 23531 | rewriting is applied immediately to child addresses that are generated by |
| 23532 | redirection, unless &%no_rewrite%& is set on the router. |
| 23533 | |
| 23534 | .cindex "envelope sender" "rewriting at transport time" |
| 23535 | .cindex "rewriting" "at transport time" |
| 23536 | .cindex "header lines" "rewriting at transport time" |
| 23537 | At transport time, additional rewriting of addresses in header lines can be |
| 23538 | specified by setting the generic &%headers_rewrite%& option on a transport. |
| 23539 | This option contains rules that are identical in form to those in the rewrite |
| 23540 | section of the configuration file. They are applied to the original message |
| 23541 | header lines and any that were added by ACLs or a system filter. They are not |
| 23542 | applied to header lines that are added by routers or the transport. |
| 23543 | |
| 23544 | The outgoing envelope sender can be rewritten by means of the &%return_path%& |
| 23545 | transport option. However, it is not possible to rewrite envelope recipients at |
| 23546 | transport time. |
| 23547 | |
| 23548 | |
| 23549 | |
| 23550 | |
| 23551 | .section "Testing the rewriting rules that apply on input" "SECID149" |
| 23552 | .cindex "rewriting" "testing" |
| 23553 | .cindex "testing" "rewriting" |
| 23554 | Exim's input rewriting configuration appears in a part of the run time |
| 23555 | configuration file headed by &"begin rewrite"&. It can be tested by the |
| 23556 | &%-brw%& command line option. This takes an address (which can be a full RFC |
| 23557 | 2822 address) as its argument. The output is a list of how the address would be |
| 23558 | transformed by the rewriting rules for each of the different places it might |
| 23559 | appear in an incoming message, that is, for each different header and for the |
| 23560 | envelope sender and recipient fields. For example, |
| 23561 | .code |
| 23562 | exim -brw ph10@exim.workshop.example |
| 23563 | .endd |
| 23564 | might produce the output |
| 23565 | .code |
| 23566 | sender: Philip.Hazel@exim.workshop.example |
| 23567 | from: Philip.Hazel@exim.workshop.example |
| 23568 | to: ph10@exim.workshop.example |
| 23569 | cc: ph10@exim.workshop.example |
| 23570 | bcc: ph10@exim.workshop.example |
| 23571 | reply-to: Philip.Hazel@exim.workshop.example |
| 23572 | env-from: Philip.Hazel@exim.workshop.example |
| 23573 | env-to: ph10@exim.workshop.example |
| 23574 | .endd |
| 23575 | which shows that rewriting has been set up for that address when used in any of |
| 23576 | the source fields, but not when it appears as a recipient address. At the |
| 23577 | present time, there is no equivalent way of testing rewriting rules that are |
| 23578 | set for a particular transport. |
| 23579 | |
| 23580 | |
| 23581 | .section "Rewriting rules" "SECID150" |
| 23582 | .cindex "rewriting" "rules" |
| 23583 | The rewrite section of the configuration file consists of lines of rewriting |
| 23584 | rules in the form |
| 23585 | .display |
| 23586 | <&'source pattern'&> <&'replacement'&> <&'flags'&> |
| 23587 | .endd |
| 23588 | Rewriting rules that are specified for the &%headers_rewrite%& generic |
| 23589 | transport option are given as a colon-separated list. Each item in the list |
| 23590 | takes the same form as a line in the main rewriting configuration (except that |
| 23591 | any colons must be doubled, of course). |
| 23592 | |
| 23593 | The formats of source patterns and replacement strings are described below. |
| 23594 | Each is terminated by white space, unless enclosed in double quotes, in which |
| 23595 | case normal quoting conventions apply inside the quotes. The flags are single |
| 23596 | characters which may appear in any order. Spaces and tabs between them are |
| 23597 | ignored. |
| 23598 | |
| 23599 | For each address that could potentially be rewritten, the rules are scanned in |
| 23600 | order, and replacements for the address from earlier rules can themselves be |
| 23601 | replaced by later rules (but see the &"q"& and &"R"& flags). |
| 23602 | |
| 23603 | The order in which addresses are rewritten is undefined, may change between |
| 23604 | releases, and must not be relied on, with one exception: when a message is |
| 23605 | received, the envelope sender is always rewritten first, before any header |
| 23606 | lines are rewritten. For example, the replacement string for a rewrite of an |
| 23607 | address in &'To:'& must not assume that the message's address in &'From:'& has |
| 23608 | (or has not) already been rewritten. However, a rewrite of &'From:'& may assume |
| 23609 | that the envelope sender has already been rewritten. |
| 23610 | |
| 23611 | .vindex "&$domain$&" |
| 23612 | .vindex "&$local_part$&" |
| 23613 | The variables &$local_part$& and &$domain$& can be used in the replacement |
| 23614 | string to refer to the address that is being rewritten. Note that lookup-driven |
| 23615 | rewriting can be done by a rule of the form |
| 23616 | .code |
| 23617 | *@* ${lookup ... |
| 23618 | .endd |
| 23619 | where the lookup key uses &$1$& and &$2$& or &$local_part$& and &$domain$& to |
| 23620 | refer to the address that is being rewritten. |
| 23621 | |
| 23622 | |
| 23623 | .section "Rewriting patterns" "SECID151" |
| 23624 | .cindex "rewriting" "patterns" |
| 23625 | .cindex "address list" "in a rewriting pattern" |
| 23626 | The source pattern in a rewriting rule is any item which may appear in an |
| 23627 | address list (see section &<<SECTaddresslist>>&). It is in fact processed as a |
| 23628 | single-item address list, which means that it is expanded before being tested |
| 23629 | against the address. As always, if you use a regular expression as a pattern, |
| 23630 | you must take care to escape dollar and backslash characters, or use the &`\N`& |
| 23631 | facility to suppress string expansion within the regular expression. |
| 23632 | |
| 23633 | Domains in patterns should be given in lower case. Local parts in patterns are |
| 23634 | case-sensitive. If you want to do case-insensitive matching of local parts, you |
| 23635 | can use a regular expression that starts with &`^(?i)`&. |
| 23636 | |
| 23637 | .cindex "numerical variables (&$1$& &$2$& etc)" "in rewriting rules" |
| 23638 | After matching, the numerical variables &$1$&, &$2$&, etc. may be set, |
| 23639 | depending on the type of match which occurred. These can be used in the |
| 23640 | replacement string to insert portions of the incoming address. &$0$& always |
| 23641 | refers to the complete incoming address. When a regular expression is used, the |
| 23642 | numerical variables are set from its capturing subexpressions. For other types |
| 23643 | of pattern they are set as follows: |
| 23644 | |
| 23645 | .ilist |
| 23646 | If a local part or domain starts with an asterisk, the numerical variables |
| 23647 | refer to the character strings matched by asterisks, with &$1$& associated with |
| 23648 | the first asterisk, and &$2$& with the second, if present. For example, if the |
| 23649 | pattern |
| 23650 | .code |
| 23651 | *queen@*.fict.example |
| 23652 | .endd |
| 23653 | is matched against the address &'hearts-queen@wonderland.fict.example'& then |
| 23654 | .code |
| 23655 | $0 = hearts-queen@wonderland.fict.example |
| 23656 | $1 = hearts- |
| 23657 | $2 = wonderland |
| 23658 | .endd |
| 23659 | Note that if the local part does not start with an asterisk, but the domain |
| 23660 | does, it is &$1$& that contains the wild part of the domain. |
| 23661 | |
| 23662 | .next |
| 23663 | If the domain part of the pattern is a partial lookup, the wild and fixed parts |
| 23664 | of the domain are placed in the next available numerical variables. Suppose, |
| 23665 | for example, that the address &'foo@bar.baz.example'& is processed by a |
| 23666 | rewriting rule of the form |
| 23667 | .display |
| 23668 | &`*@partial-dbm;/some/dbm/file`& <&'replacement string'&> |
| 23669 | .endd |
| 23670 | and the key in the file that matches the domain is &`*.baz.example`&. Then |
| 23671 | .code |
| 23672 | $1 = foo |
| 23673 | $2 = bar |
| 23674 | $3 = baz.example |
| 23675 | .endd |
| 23676 | If the address &'foo@baz.example'& is looked up, this matches the same |
| 23677 | wildcard file entry, and in this case &$2$& is set to the empty string, but |
| 23678 | &$3$& is still set to &'baz.example'&. If a non-wild key is matched in a |
| 23679 | partial lookup, &$2$& is again set to the empty string and &$3$& is set to the |
| 23680 | whole domain. For non-partial domain lookups, no numerical variables are set. |
| 23681 | .endlist |
| 23682 | |
| 23683 | |
| 23684 | .section "Rewriting replacements" "SECID152" |
| 23685 | .cindex "rewriting" "replacements" |
| 23686 | If the replacement string for a rule is a single asterisk, addresses that |
| 23687 | match the pattern and the flags are &'not'& rewritten, and no subsequent |
| 23688 | rewriting rules are scanned. For example, |
| 23689 | .code |
| 23690 | hatta@lookingglass.fict.example * f |
| 23691 | .endd |
| 23692 | specifies that &'hatta@lookingglass.fict.example'& is never to be rewritten in |
| 23693 | &'From:'& headers. |
| 23694 | |
| 23695 | .vindex "&$domain$&" |
| 23696 | .vindex "&$local_part$&" |
| 23697 | If the replacement string is not a single asterisk, it is expanded, and must |
| 23698 | yield a fully qualified address. Within the expansion, the variables |
| 23699 | &$local_part$& and &$domain$& refer to the address that is being rewritten. |
| 23700 | Any letters they contain retain their original case &-- they are not lower |
| 23701 | cased. The numerical variables are set up according to the type of pattern that |
| 23702 | matched the address, as described above. If the expansion is forced to fail by |
| 23703 | the presence of &"fail"& in a conditional or lookup item, rewriting by the |
| 23704 | current rule is abandoned, but subsequent rules may take effect. Any other |
| 23705 | expansion failure causes the entire rewriting operation to be abandoned, and an |
| 23706 | entry written to the panic log. |
| 23707 | |
| 23708 | |
| 23709 | |
| 23710 | .section "Rewriting flags" "SECID153" |
| 23711 | There are three different kinds of flag that may appear on rewriting rules: |
| 23712 | |
| 23713 | .ilist |
| 23714 | Flags that specify which headers and envelope addresses to rewrite: E, F, T, b, |
| 23715 | c, f, h, r, s, t. |
| 23716 | .next |
| 23717 | A flag that specifies rewriting at SMTP time: S. |
| 23718 | .next |
| 23719 | Flags that control the rewriting process: Q, q, R, w. |
| 23720 | .endlist |
| 23721 | |
| 23722 | For rules that are part of the &%headers_rewrite%& generic transport option, |
| 23723 | E, F, T, and S are not permitted. |
| 23724 | |
| 23725 | |
| 23726 | |
| 23727 | .section "Flags specifying which headers and envelope addresses to rewrite" &&& |
| 23728 | "SECID154" |
| 23729 | .cindex "rewriting" "flags" |
| 23730 | If none of the following flag letters, nor the &"S"& flag (see section |
| 23731 | &<<SECTrewriteS>>&) are present, a main rewriting rule applies to all headers |
| 23732 | and to both the sender and recipient fields of the envelope, whereas a |
| 23733 | transport-time rewriting rule just applies to all headers. Otherwise, the |
| 23734 | rewriting rule is skipped unless the relevant addresses are being processed. |
| 23735 | .display |
| 23736 | &`E`& rewrite all envelope fields |
| 23737 | &`F`& rewrite the envelope From field |
| 23738 | &`T`& rewrite the envelope To field |
| 23739 | &`b`& rewrite the &'Bcc:'& header |
| 23740 | &`c`& rewrite the &'Cc:'& header |
| 23741 | &`f`& rewrite the &'From:'& header |
| 23742 | &`h`& rewrite all headers |
| 23743 | &`r`& rewrite the &'Reply-To:'& header |
| 23744 | &`s`& rewrite the &'Sender:'& header |
| 23745 | &`t`& rewrite the &'To:'& header |
| 23746 | .endd |
| 23747 | "All headers" means all of the headers listed above that can be selected |
| 23748 | individually, plus their &'Resent-'& versions. It does not include |
| 23749 | other headers such as &'Subject:'& etc. |
| 23750 | |
| 23751 | You should be particularly careful about rewriting &'Sender:'& headers, and |
| 23752 | restrict this to special known cases in your own domains. |
| 23753 | |
| 23754 | |
| 23755 | .section "The SMTP-time rewriting flag" "SECTrewriteS" |
| 23756 | .cindex "SMTP" "rewriting malformed addresses" |
| 23757 | .cindex "RCPT" "rewriting argument of" |
| 23758 | .cindex "MAIL" "rewriting argument of" |
| 23759 | The rewrite flag &"S"& specifies a rewrite of incoming envelope addresses at |
| 23760 | SMTP time, as soon as an address is received in a MAIL or RCPT command, and |
| 23761 | before any other processing; even before syntax checking. The pattern is |
| 23762 | required to be a regular expression, and it is matched against the whole of the |
| 23763 | data for the command, including any surrounding angle brackets. |
| 23764 | |
| 23765 | .vindex "&$domain$&" |
| 23766 | .vindex "&$local_part$&" |
| 23767 | This form of rewrite rule allows for the handling of addresses that are not |
| 23768 | compliant with RFCs 2821 and 2822 (for example, &"bang paths"& in batched SMTP |
| 23769 | input). Because the input is not required to be a syntactically valid address, |
| 23770 | the variables &$local_part$& and &$domain$& are not available during the |
| 23771 | expansion of the replacement string. The result of rewriting replaces the |
| 23772 | original address in the MAIL or RCPT command. |
| 23773 | |
| 23774 | |
| 23775 | .section "Flags controlling the rewriting process" "SECID155" |
| 23776 | There are four flags which control the way the rewriting process works. These |
| 23777 | take effect only when a rule is invoked, that is, when the address is of the |
| 23778 | correct type (matches the flags) and matches the pattern: |
| 23779 | |
| 23780 | .ilist |
| 23781 | If the &"Q"& flag is set on a rule, the rewritten address is permitted to be an |
| 23782 | unqualified local part. It is qualified with &%qualify_recipient%&. In the |
| 23783 | absence of &"Q"& the rewritten address must always include a domain. |
| 23784 | .next |
| 23785 | If the &"q"& flag is set on a rule, no further rewriting rules are considered, |
| 23786 | even if no rewriting actually takes place because of a &"fail"& in the |
| 23787 | expansion. The &"q"& flag is not effective if the address is of the wrong type |
| 23788 | (does not match the flags) or does not match the pattern. |
| 23789 | .next |
| 23790 | The &"R"& flag causes a successful rewriting rule to be re-applied to the new |
| 23791 | address, up to ten times. It can be combined with the &"q"& flag, to stop |
| 23792 | rewriting once it fails to match (after at least one successful rewrite). |
| 23793 | .next |
| 23794 | .cindex "rewriting" "whole addresses" |
| 23795 | When an address in a header is rewritten, the rewriting normally applies only |
| 23796 | to the working part of the address, with any comments and RFC 2822 &"phrase"& |
| 23797 | left unchanged. For example, rewriting might change |
| 23798 | .code |
| 23799 | From: Ford Prefect <fp42@restaurant.hitch.fict.example> |
| 23800 | .endd |
| 23801 | into |
| 23802 | .code |
| 23803 | From: Ford Prefect <prefectf@hitch.fict.example> |
| 23804 | .endd |
| 23805 | .cindex "RFC 2047" |
| 23806 | Sometimes there is a need to replace the whole address item, and this can be |
| 23807 | done by adding the flag letter &"w"& to a rule. If this is set on a rule that |
| 23808 | causes an address in a header line to be rewritten, the entire address is |
| 23809 | replaced, not just the working part. The replacement must be a complete RFC |
| 23810 | 2822 address, including the angle brackets if necessary. If text outside angle |
| 23811 | brackets contains a character whose value is greater than 126 or less than 32 |
| 23812 | (except for tab), the text is encoded according to RFC 2047. The character set |
| 23813 | is taken from &%headers_charset%&, which defaults to ISO-8859-1. |
| 23814 | |
| 23815 | When the &"w"& flag is set on a rule that causes an envelope address to be |
| 23816 | rewritten, all but the working part of the replacement address is discarded. |
| 23817 | .endlist |
| 23818 | |
| 23819 | |
| 23820 | .section "Rewriting examples" "SECID156" |
| 23821 | Here is an example of the two common rewriting paradigms: |
| 23822 | .code |
| 23823 | *@*.hitch.fict.example $1@hitch.fict.example |
| 23824 | *@hitch.fict.example ${lookup{$1}dbm{/etc/realnames}\ |
| 23825 | {$value}fail}@hitch.fict.example bctfrF |
| 23826 | .endd |
| 23827 | Note the use of &"fail"& in the lookup expansion in the second rule, forcing |
| 23828 | the string expansion to fail if the lookup does not succeed. In this context it |
| 23829 | has the effect of leaving the original address unchanged, but Exim goes on to |
| 23830 | consider subsequent rewriting rules, if any, because the &"q"& flag is not |
| 23831 | present in that rule. An alternative to &"fail"& would be to supply &$1$& |
| 23832 | explicitly, which would cause the rewritten address to be the same as before, |
| 23833 | at the cost of a small bit of processing. Not supplying either of these is an |
| 23834 | error, since the rewritten address would then contain no local part. |
| 23835 | |
| 23836 | The first example above replaces the domain with a superior, more general |
| 23837 | domain. This may not be desirable for certain local parts. If the rule |
| 23838 | .code |
| 23839 | root@*.hitch.fict.example * |
| 23840 | .endd |
| 23841 | were inserted before the first rule, rewriting would be suppressed for the |
| 23842 | local part &'root'& at any domain ending in &'hitch.fict.example'&. |
| 23843 | |
| 23844 | Rewriting can be made conditional on a number of tests, by making use of |
| 23845 | &${if$& in the expansion item. For example, to apply a rewriting rule only to |
| 23846 | messages that originate outside the local host: |
| 23847 | .code |
| 23848 | *@*.hitch.fict.example "${if !eq {$sender_host_address}{}\ |
| 23849 | {$1@hitch.fict.example}fail}" |
| 23850 | .endd |
| 23851 | The replacement string is quoted in this example because it contains white |
| 23852 | space. |
| 23853 | |
| 23854 | .cindex "rewriting" "bang paths" |
| 23855 | .cindex "bang paths" "rewriting" |
| 23856 | Exim does not handle addresses in the form of &"bang paths"&. If it sees such |
| 23857 | an address it treats it as an unqualified local part which it qualifies with |
| 23858 | the local qualification domain (if the source of the message is local or if the |
| 23859 | remote host is permitted to send unqualified addresses). Rewriting can |
| 23860 | sometimes be used to handle simple bang paths with a fixed number of |
| 23861 | components. For example, the rule |
| 23862 | .code |
| 23863 | \N^([^!]+)!(.*)@your.domain.example$\N $2@$1 |
| 23864 | .endd |
| 23865 | rewrites a two-component bang path &'host.name!user'& as the domain address |
| 23866 | &'user@host.name'&. However, there is a security implication in using this as |
| 23867 | a global rewriting rule for envelope addresses. It can provide a backdoor |
| 23868 | method for using your system as a relay, because the incoming addresses appear |
| 23869 | to be local. If the bang path addresses are received via SMTP, it is safer to |
| 23870 | use the &"S"& flag to rewrite them as they are received, so that relay checking |
| 23871 | can be done on the rewritten addresses. |
| 23872 | .ecindex IIDaddrew |
| 23873 | |
| 23874 | |
| 23875 | |
| 23876 | |
| 23877 | |
| 23878 | . //////////////////////////////////////////////////////////////////////////// |
| 23879 | . //////////////////////////////////////////////////////////////////////////// |
| 23880 | |
| 23881 | .chapter "Retry configuration" "CHAPretry" |
| 23882 | .scindex IIDretconf1 "retry" "configuration, description of" |
| 23883 | .scindex IIDregconf2 "configuration file" "retry section" |
| 23884 | The &"retry"& section of the runtime configuration file contains a list of |
| 23885 | retry rules that control how often Exim tries to deliver messages that cannot |
| 23886 | be delivered at the first attempt. If there are no retry rules (the section is |
| 23887 | empty or not present), there are no retries. In this situation, temporary |
| 23888 | errors are treated as permanent. The default configuration contains a single, |
| 23889 | general-purpose retry rule (see section &<<SECID57>>&). The &%-brt%& command |
| 23890 | line option can be used to test which retry rule will be used for a given |
| 23891 | address, domain and error. |
| 23892 | |
| 23893 | The most common cause of retries is temporary failure to deliver to a remote |
| 23894 | host because the host is down, or inaccessible because of a network problem. |
| 23895 | Exim's retry processing in this case is applied on a per-host (strictly, per IP |
| 23896 | address) basis, not on a per-message basis. Thus, if one message has recently |
| 23897 | been delayed, delivery of a new message to the same host is not immediately |
| 23898 | tried, but waits for the host's retry time to arrive. If the &%retry_defer%& |
| 23899 | log selector is set, the message |
| 23900 | .cindex "retry" "time not reached" |
| 23901 | &"retry time not reached"& is written to the main log whenever a delivery is |
| 23902 | skipped for this reason. Section &<<SECToutSMTPerr>>& contains more details of |
| 23903 | the handling of errors during remote deliveries. |
| 23904 | |
| 23905 | Retry processing applies to routing as well as to delivering, except as covered |
| 23906 | in the next paragraph. The retry rules do not distinguish between these |
| 23907 | actions. It is not possible, for example, to specify different behaviour for |
| 23908 | failures to route the domain &'snark.fict.example'& and failures to deliver to |
| 23909 | the host &'snark.fict.example'&. I didn't think anyone would ever need this |
| 23910 | added complication, so did not implement it. However, although they share the |
| 23911 | same retry rule, the actual retry times for routing and transporting a given |
| 23912 | domain are maintained independently. |
| 23913 | |
| 23914 | When a delivery is not part of a queue run (typically an immediate delivery on |
| 23915 | receipt of a message), the routers are always run, and local deliveries are |
| 23916 | always attempted, even if retry times are set for them. This makes for better |
| 23917 | behaviour if one particular message is causing problems (for example, causing |
| 23918 | quota overflow, or provoking an error in a filter file). If such a delivery |
| 23919 | suffers a temporary failure, the retry data is updated as normal, and |
| 23920 | subsequent delivery attempts from queue runs occur only when the retry time for |
| 23921 | the local address is reached. |
| 23922 | |
| 23923 | .section "Changing retry rules" "SECID157" |
| 23924 | If you change the retry rules in your configuration, you should consider |
| 23925 | whether or not to delete the retry data that is stored in Exim's spool area in |
| 23926 | files with names like &_db/retry_&. Deleting any of Exim's hints files is |
| 23927 | always safe; that is why they are called &"hints"&. |
| 23928 | |
| 23929 | The hints retry data contains suggested retry times based on the previous |
| 23930 | rules. In the case of a long-running problem with a remote host, it might |
| 23931 | record the fact that the host has timed out. If your new rules increase the |
| 23932 | timeout time for such a host, you should definitely remove the old retry data |
| 23933 | and let Exim recreate it, based on the new rules. Otherwise Exim might bounce |
| 23934 | messages that it should now be retaining. |
| 23935 | |
| 23936 | |
| 23937 | |
| 23938 | .section "Format of retry rules" "SECID158" |
| 23939 | .cindex "retry" "rules" |
| 23940 | Each retry rule occupies one line and consists of three or four parts, |
| 23941 | separated by white space: a pattern, an error name, an optional list of sender |
| 23942 | addresses, and a list of retry parameters. The pattern and sender lists must be |
| 23943 | enclosed in double quotes if they contain white space. The rules are searched |
| 23944 | in order until one is found where the pattern, error name, and sender list (if |
| 23945 | present) match the failing host or address, the error that occurred, and the |
| 23946 | message's sender, respectively. |
| 23947 | |
| 23948 | |
| 23949 | The pattern is any single item that may appear in an address list (see section |
| 23950 | &<<SECTaddresslist>>&). It is in fact processed as a one-item address list, |
| 23951 | which means that it is expanded before being tested against the address that |
| 23952 | has been delayed. A negated address list item is permitted. Address |
| 23953 | list processing treats a plain domain name as if it were preceded by &"*@"&, |
| 23954 | which makes it possible for many retry rules to start with just a domain. For |
| 23955 | example, |
| 23956 | .code |
| 23957 | lookingglass.fict.example * F,24h,30m; |
| 23958 | .endd |
| 23959 | provides a rule for any address in the &'lookingglass.fict.example'& domain, |
| 23960 | whereas |
| 23961 | .code |
| 23962 | alice@lookingglass.fict.example * F,24h,30m; |
| 23963 | .endd |
| 23964 | applies only to temporary failures involving the local part &%alice%&. |
| 23965 | In practice, almost all rules start with a domain name pattern without a local |
| 23966 | part. |
| 23967 | |
| 23968 | .cindex "regular expressions" "in retry rules" |
| 23969 | &*Warning*&: If you use a regular expression in a retry rule pattern, it |
| 23970 | must match a complete address, not just a domain, because that is how regular |
| 23971 | expressions work in address lists. |
| 23972 | .display |
| 23973 | &`^\Nxyz\d+\.abc\.example$\N * G,1h,10m,2`& &%Wrong%& |
| 23974 | &`^\N[^@]+@xyz\d+\.abc\.example$\N * G,1h,10m,2`& &%Right%& |
| 23975 | .endd |
| 23976 | |
| 23977 | |
| 23978 | .section "Choosing which retry rule to use for address errors" "SECID159" |
| 23979 | When Exim is looking for a retry rule after a routing attempt has failed (for |
| 23980 | example, after a DNS timeout), each line in the retry configuration is tested |
| 23981 | against the complete address only if &%retry_use_local_part%& is set for the |
| 23982 | router. Otherwise, only the domain is used, except when matching against a |
| 23983 | regular expression, when the local part of the address is replaced with &"*"&. |
| 23984 | A domain on its own can match a domain pattern, or a pattern that starts with |
| 23985 | &"*@"&. By default, &%retry_use_local_part%& is true for routers where |
| 23986 | &%check_local_user%& is true, and false for other routers. |
| 23987 | |
| 23988 | Similarly, when Exim is looking for a retry rule after a local delivery has |
| 23989 | failed (for example, after a mailbox full error), each line in the retry |
| 23990 | configuration is tested against the complete address only if |
| 23991 | &%retry_use_local_part%& is set for the transport (it defaults true for all |
| 23992 | local transports). |
| 23993 | |
| 23994 | .cindex "4&'xx'& responses" "retry rules for" |
| 23995 | However, when Exim is looking for a retry rule after a remote delivery attempt |
| 23996 | suffers an address error (a 4&'xx'& SMTP response for a recipient address), the |
| 23997 | whole address is always used as the key when searching the retry rules. The |
| 23998 | rule that is found is used to create a retry time for the combination of the |
| 23999 | failing address and the message's sender. It is the combination of sender and |
| 24000 | recipient that is delayed in subsequent queue runs until its retry time is |
| 24001 | reached. You can delay the recipient without regard to the sender by setting |
| 24002 | &%address_retry_include_sender%& false in the &(smtp)& transport but this can |
| 24003 | lead to problems with servers that regularly issue 4&'xx'& responses to RCPT |
| 24004 | commands. |
| 24005 | |
| 24006 | |
| 24007 | |
| 24008 | .section "Choosing which retry rule to use for host and message errors" &&& |
| 24009 | "SECID160" |
| 24010 | For a temporary error that is not related to an individual address (for |
| 24011 | example, a connection timeout), each line in the retry configuration is checked |
| 24012 | twice. First, the name of the remote host is used as a domain name (preceded by |
| 24013 | &"*@"& when matching a regular expression). If this does not match the line, |
| 24014 | the domain from the email address is tried in a similar fashion. For example, |
| 24015 | suppose the MX records for &'a.b.c.example'& are |
| 24016 | .code |
| 24017 | a.b.c.example MX 5 x.y.z.example |
| 24018 | MX 6 p.q.r.example |
| 24019 | MX 7 m.n.o.example |
| 24020 | .endd |
| 24021 | and the retry rules are |
| 24022 | .code |
| 24023 | p.q.r.example * F,24h,30m; |
| 24024 | a.b.c.example * F,4d,45m; |
| 24025 | .endd |
| 24026 | and a delivery to the host &'x.y.z.example'& suffers a connection failure. The |
| 24027 | first rule matches neither the host nor the domain, so Exim looks at the second |
| 24028 | rule. This does not match the host, but it does match the domain, so it is used |
| 24029 | to calculate the retry time for the host &'x.y.z.example'&. Meanwhile, Exim |
| 24030 | tries to deliver to &'p.q.r.example'&. If this also suffers a host error, the |
| 24031 | first retry rule is used, because it matches the host. |
| 24032 | |
| 24033 | In other words, temporary failures to deliver to host &'p.q.r.example'& use the |
| 24034 | first rule to determine retry times, but for all the other hosts for the domain |
| 24035 | &'a.b.c.example'&, the second rule is used. The second rule is also used if |
| 24036 | routing to &'a.b.c.example'& suffers a temporary failure. |
| 24037 | |
| 24038 | &*Note*&: The host name is used when matching the patterns, not its IP address. |
| 24039 | However, if a message is routed directly to an IP address without the use of a |
| 24040 | host name, for example, if a &(manualroute)& router contains a setting such as: |
| 24041 | .code |
| 24042 | route_list = *.a.example 192.168.34.23 |
| 24043 | .endd |
| 24044 | then the &"host name"& that is used when searching for a retry rule is the |
| 24045 | textual form of the IP address. |
| 24046 | |
| 24047 | .section "Retry rules for specific errors" "SECID161" |
| 24048 | .cindex "retry" "specific errors; specifying" |
| 24049 | The second field in a retry rule is the name of a particular error, or an |
| 24050 | asterisk, which matches any error. The errors that can be tested for are: |
| 24051 | |
| 24052 | .vlist |
| 24053 | .vitem &%auth_failed%& |
| 24054 | Authentication failed when trying to send to a host in the |
| 24055 | &%hosts_require_auth%& list in an &(smtp)& transport. |
| 24056 | |
| 24057 | .vitem &%data_4xx%& |
| 24058 | A 4&'xx'& error was received for an outgoing DATA command, either immediately |
| 24059 | after the command, or after sending the message's data. |
| 24060 | |
| 24061 | .vitem &%mail_4xx%& |
| 24062 | A 4&'xx'& error was received for an outgoing MAIL command. |
| 24063 | |
| 24064 | .vitem &%rcpt_4xx%& |
| 24065 | A 4&'xx'& error was received for an outgoing RCPT command. |
| 24066 | .endlist |
| 24067 | |
| 24068 | For the three 4&'xx'& errors, either the first or both of the x's can be given |
| 24069 | as specific digits, for example: &`mail_45x`& or &`rcpt_436`&. For example, to |
| 24070 | recognize 452 errors given to RCPT commands for addresses in a certain domain, |
| 24071 | and have retries every ten minutes with a one-hour timeout, you could set up a |
| 24072 | retry rule of this form: |
| 24073 | .code |
| 24074 | the.domain.name rcpt_452 F,1h,10m |
| 24075 | .endd |
| 24076 | These errors apply to both outgoing SMTP (the &(smtp)& transport) and outgoing |
| 24077 | LMTP (either the &(lmtp)& transport, or the &(smtp)& transport in LMTP mode). |
| 24078 | |
| 24079 | .vlist |
| 24080 | .vitem &%lost_connection%& |
| 24081 | A server unexpectedly closed the SMTP connection. There may, of course, |
| 24082 | legitimate reasons for this (host died, network died), but if it repeats a lot |
| 24083 | for the same host, it indicates something odd. |
| 24084 | |
| 24085 | .vitem &%refused_MX%& |
| 24086 | A connection to a host obtained from an MX record was refused. |
| 24087 | |
| 24088 | .vitem &%refused_A%& |
| 24089 | A connection to a host not obtained from an MX record was refused. |
| 24090 | |
| 24091 | .vitem &%refused%& |
| 24092 | A connection was refused. |
| 24093 | |
| 24094 | .vitem &%timeout_connect_MX%& |
| 24095 | A connection attempt to a host obtained from an MX record timed out. |
| 24096 | |
| 24097 | .vitem &%timeout_connect_A%& |
| 24098 | A connection attempt to a host not obtained from an MX record timed out. |
| 24099 | |
| 24100 | .vitem &%timeout_connect%& |
| 24101 | A connection attempt timed out. |
| 24102 | |
| 24103 | .vitem &%timeout_MX%& |
| 24104 | There was a timeout while connecting or during an SMTP session with a host |
| 24105 | obtained from an MX record. |
| 24106 | |
| 24107 | .vitem &%timeout_A%& |
| 24108 | There was a timeout while connecting or during an SMTP session with a host not |
| 24109 | obtained from an MX record. |
| 24110 | |
| 24111 | .vitem &%timeout%& |
| 24112 | There was a timeout while connecting or during an SMTP session. |
| 24113 | |
| 24114 | .vitem &%tls_required%& |
| 24115 | The server was required to use TLS (it matched &%hosts_require_tls%& in the |
| 24116 | &(smtp)& transport), but either did not offer TLS, or it responded with 4&'xx'& |
| 24117 | to STARTTLS, or there was a problem setting up the TLS connection. |
| 24118 | |
| 24119 | .vitem &%quota%& |
| 24120 | A mailbox quota was exceeded in a local delivery by the &(appendfile)& |
| 24121 | transport. |
| 24122 | |
| 24123 | .vitem &%quota_%&<&'time'&> |
| 24124 | .cindex "quota" "error testing in retry rule" |
| 24125 | .cindex "retry" "quota error testing" |
| 24126 | A mailbox quota was exceeded in a local delivery by the &(appendfile)& |
| 24127 | transport, and the mailbox has not been accessed for <&'time'&>. For example, |
| 24128 | &'quota_4d'& applies to a quota error when the mailbox has not been accessed |
| 24129 | for four days. |
| 24130 | .endlist |
| 24131 | |
| 24132 | .cindex "mailbox" "time of last read" |
| 24133 | The idea of &%quota_%&<&'time'&> is to make it possible to have shorter |
| 24134 | timeouts when the mailbox is full and is not being read by its owner. Ideally, |
| 24135 | it should be based on the last time that the user accessed the mailbox. |
| 24136 | However, it is not always possible to determine this. Exim uses the following |
| 24137 | heuristic rules: |
| 24138 | |
| 24139 | .ilist |
| 24140 | If the mailbox is a single file, the time of last access (the &"atime"&) is |
| 24141 | used. As no new messages are being delivered (because the mailbox is over |
| 24142 | quota), Exim does not access the file, so this is the time of last user access. |
| 24143 | .next |
| 24144 | .cindex "maildir format" "time of last read" |
| 24145 | For a maildir delivery, the time of last modification of the &_new_& |
| 24146 | subdirectory is used. As the mailbox is over quota, no new files are created in |
| 24147 | the &_new_& subdirectory, because no new messages are being delivered. Any |
| 24148 | change to the &_new_& subdirectory is therefore assumed to be the result of an |
| 24149 | MUA moving a new message to the &_cur_& directory when it is first read. The |
| 24150 | time that is used is therefore the last time that the user read a new message. |
| 24151 | .next |
| 24152 | For other kinds of multi-file mailbox, the time of last access cannot be |
| 24153 | obtained, so a retry rule that uses this type of error field is never matched. |
| 24154 | .endlist |
| 24155 | |
| 24156 | The quota errors apply both to system-enforced quotas and to Exim's own quota |
| 24157 | mechanism in the &(appendfile)& transport. The &'quota'& error also applies |
| 24158 | when a local delivery is deferred because a partition is full (the ENOSPC |
| 24159 | error). |
| 24160 | |
| 24161 | |
| 24162 | |
| 24163 | .section "Retry rules for specified senders" "SECID162" |
| 24164 | .cindex "retry" "rules; sender-specific" |
| 24165 | You can specify retry rules that apply only when the failing message has a |
| 24166 | specific sender. In particular, this can be used to define retry rules that |
| 24167 | apply only to bounce messages. The third item in a retry rule can be of this |
| 24168 | form: |
| 24169 | .display |
| 24170 | &`senders=`&<&'address list'&> |
| 24171 | .endd |
| 24172 | The retry timings themselves are then the fourth item. For example: |
| 24173 | .code |
| 24174 | * rcpt_4xx senders=: F,1h,30m |
| 24175 | .endd |
| 24176 | matches recipient 4&'xx'& errors for bounce messages sent to any address at any |
| 24177 | host. If the address list contains white space, it must be enclosed in quotes. |
| 24178 | For example: |
| 24179 | .code |
| 24180 | a.domain rcpt_452 senders="xb.dom : yc.dom" G,8h,10m,1.5 |
| 24181 | .endd |
| 24182 | &*Warning*&: This facility can be unhelpful if it is used for host errors |
| 24183 | (which do not depend on the recipient). The reason is that the sender is used |
| 24184 | only to match the retry rule. Once the rule has been found for a host error, |
| 24185 | its contents are used to set a retry time for the host, and this will apply to |
| 24186 | all messages, not just those with specific senders. |
| 24187 | |
| 24188 | When testing retry rules using &%-brt%&, you can supply a sender using the |
| 24189 | &%-f%& command line option, like this: |
| 24190 | .code |
| 24191 | exim -f "" -brt user@dom.ain |
| 24192 | .endd |
| 24193 | If you do not set &%-f%& with &%-brt%&, a retry rule that contains a senders |
| 24194 | list is never matched. |
| 24195 | |
| 24196 | |
| 24197 | |
| 24198 | |
| 24199 | |
| 24200 | .section "Retry parameters" "SECID163" |
| 24201 | .cindex "retry" "parameters in rules" |
| 24202 | The third (or fourth, if a senders list is present) field in a retry rule is a |
| 24203 | sequence of retry parameter sets, separated by semicolons. Each set consists of |
| 24204 | .display |
| 24205 | <&'letter'&>,<&'cutoff time'&>,<&'arguments'&> |
| 24206 | .endd |
| 24207 | The letter identifies the algorithm for computing a new retry time; the cutoff |
| 24208 | time is the time beyond which this algorithm no longer applies, and the |
| 24209 | arguments vary the algorithm's action. The cutoff time is measured from the |
| 24210 | time that the first failure for the domain (combined with the local part if |
| 24211 | relevant) was detected, not from the time the message was received. |
| 24212 | |
| 24213 | .cindex "retry" "algorithms" |
| 24214 | .cindex "retry" "fixed intervals" |
| 24215 | .cindex "retry" "increasing intervals" |
| 24216 | .cindex "retry" "random intervals" |
| 24217 | The available algorithms are: |
| 24218 | |
| 24219 | .ilist |
| 24220 | &'F'&: retry at fixed intervals. There is a single time parameter specifying |
| 24221 | the interval. |
| 24222 | .next |
| 24223 | &'G'&: retry at geometrically increasing intervals. The first argument |
| 24224 | specifies a starting value for the interval, and the second a multiplier, which |
| 24225 | is used to increase the size of the interval at each retry. |
| 24226 | .next |
| 24227 | &'H'&: retry at randomized intervals. The arguments are as for &'G'&. For each |
| 24228 | retry, the previous interval is multiplied by the factor in order to get a |
| 24229 | maximum for the next interval. The minimum interval is the first argument of |
| 24230 | the parameter, and an actual interval is chosen randomly between them. Such a |
| 24231 | rule has been found to be helpful in cluster configurations when all the |
| 24232 | members of the cluster restart at once, and may therefore synchronize their |
| 24233 | queue processing times. |
| 24234 | .endlist |
| 24235 | |
| 24236 | When computing the next retry time, the algorithm definitions are scanned in |
| 24237 | order until one whose cutoff time has not yet passed is reached. This is then |
| 24238 | used to compute a new retry time that is later than the current time. In the |
| 24239 | case of fixed interval retries, this simply means adding the interval to the |
| 24240 | current time. For geometrically increasing intervals, retry intervals are |
| 24241 | computed from the rule's parameters until one that is greater than the previous |
| 24242 | interval is found. The main configuration variable |
| 24243 | .cindex "limit" "retry interval" |
| 24244 | .cindex "retry" "interval, maximum" |
| 24245 | .oindex "&%retry_interval_max%&" |
| 24246 | &%retry_interval_max%& limits the maximum interval between retries. It |
| 24247 | cannot be set greater than &`24h`&, which is its default value. |
| 24248 | |
| 24249 | A single remote domain may have a number of hosts associated with it, and each |
| 24250 | host may have more than one IP address. Retry algorithms are selected on the |
| 24251 | basis of the domain name, but are applied to each IP address independently. If, |
| 24252 | for example, a host has two IP addresses and one is unusable, Exim will |
| 24253 | generate retry times for it and will not try to use it until its next retry |
| 24254 | time comes. Thus the good IP address is likely to be tried first most of the |
| 24255 | time. |
| 24256 | |
| 24257 | .cindex "hints database" "use for retrying" |
| 24258 | Retry times are hints rather than promises. Exim does not make any attempt to |
| 24259 | run deliveries exactly at the computed times. Instead, a queue runner process |
| 24260 | starts delivery processes for delayed messages periodically, and these attempt |
| 24261 | new deliveries only for those addresses that have passed their next retry time. |
| 24262 | If a new message arrives for a deferred address, an immediate delivery attempt |
| 24263 | occurs only if the address has passed its retry time. In the absence of new |
| 24264 | messages, the minimum time between retries is the interval between queue runner |
| 24265 | processes. There is not much point in setting retry times of five minutes if |
| 24266 | your queue runners happen only once an hour, unless there are a significant |
| 24267 | number of incoming messages (which might be the case on a system that is |
| 24268 | sending everything to a smart host, for example). |
| 24269 | |
| 24270 | The data in the retry hints database can be inspected by using the |
| 24271 | &'exim_dumpdb'& or &'exim_fixdb'& utility programs (see chapter |
| 24272 | &<<CHAPutils>>&). The latter utility can also be used to change the data. The |
| 24273 | &'exinext'& utility script can be used to find out what the next retry times |
| 24274 | are for the hosts associated with a particular mail domain, and also for local |
| 24275 | deliveries that have been deferred. |
| 24276 | |
| 24277 | |
| 24278 | .section "Retry rule examples" "SECID164" |
| 24279 | Here are some example retry rules: |
| 24280 | .code |
| 24281 | alice@wonderland.fict.example quota_5d F,7d,3h |
| 24282 | wonderland.fict.example quota_5d |
| 24283 | wonderland.fict.example * F,1h,15m; G,2d,1h,2; |
| 24284 | lookingglass.fict.example * F,24h,30m; |
| 24285 | * refused_A F,2h,20m; |
| 24286 | * * F,2h,15m; G,16h,1h,1.5; F,5d,8h |
| 24287 | .endd |
| 24288 | The first rule sets up special handling for mail to |
| 24289 | &'alice@wonderland.fict.example'& when there is an over-quota error and the |
| 24290 | mailbox has not been read for at least 5 days. Retries continue every three |
| 24291 | hours for 7 days. The second rule handles over-quota errors for all other local |
| 24292 | parts at &'wonderland.fict.example'&; the absence of a local part has the same |
| 24293 | effect as supplying &"*@"&. As no retry algorithms are supplied, messages that |
| 24294 | fail are bounced immediately if the mailbox has not been read for at least 5 |
| 24295 | days. |
| 24296 | |
| 24297 | The third rule handles all other errors at &'wonderland.fict.example'&; retries |
| 24298 | happen every 15 minutes for an hour, then with geometrically increasing |
| 24299 | intervals until two days have passed since a delivery first failed. After the |
| 24300 | first hour there is a delay of one hour, then two hours, then four hours, and |
| 24301 | so on (this is a rather extreme example). |
| 24302 | |
| 24303 | The fourth rule controls retries for the domain &'lookingglass.fict.example'&. |
| 24304 | They happen every 30 minutes for 24 hours only. The remaining two rules handle |
| 24305 | all other domains, with special action for connection refusal from hosts that |
| 24306 | were not obtained from an MX record. |
| 24307 | |
| 24308 | The final rule in a retry configuration should always have asterisks in the |
| 24309 | first two fields so as to provide a general catch-all for any addresses that do |
| 24310 | not have their own special handling. This example tries every 15 minutes for 2 |
| 24311 | hours, then with intervals starting at one hour and increasing by a factor of |
| 24312 | 1.5 up to 16 hours, then every 8 hours up to 5 days. |
| 24313 | |
| 24314 | |
| 24315 | |
| 24316 | .section "Timeout of retry data" "SECID165" |
| 24317 | .cindex "timeout" "of retry data" |
| 24318 | .oindex "&%retry_data_expire%&" |
| 24319 | .cindex "hints database" "data expiry" |
| 24320 | .cindex "retry" "timeout of data" |
| 24321 | Exim timestamps the data that it writes to its retry hints database. When it |
| 24322 | consults the data during a delivery it ignores any that is older than the value |
| 24323 | set in &%retry_data_expire%& (default 7 days). If, for example, a host hasn't |
| 24324 | been tried for 7 days, Exim will try to deliver to it immediately a message |
| 24325 | arrives, and if that fails, it will calculate a retry time as if it were |
| 24326 | failing for the first time. |
| 24327 | |
| 24328 | This improves the behaviour for messages routed to rarely-used hosts such as MX |
| 24329 | backups. If such a host was down at one time, and happens to be down again when |
| 24330 | Exim tries a month later, using the old retry data would imply that it had been |
| 24331 | down all the time, which is not a justified assumption. |
| 24332 | |
| 24333 | If a host really is permanently dead, this behaviour causes a burst of retries |
| 24334 | every now and again, but only if messages routed to it are rare. If there is a |
| 24335 | message at least once every 7 days the retry data never expires. |
| 24336 | |
| 24337 | |
| 24338 | |
| 24339 | |
| 24340 | .section "Long-term failures" "SECID166" |
| 24341 | .cindex "delivery failure, long-term" |
| 24342 | .cindex "retry" "after long-term failure" |
| 24343 | Special processing happens when an email address has been failing for so long |
| 24344 | that the cutoff time for the last algorithm is reached. For example, using the |
| 24345 | default retry rule: |
| 24346 | .code |
| 24347 | * * F,2h,15m; G,16h,1h,1.5; F,4d,6h |
| 24348 | .endd |
| 24349 | the cutoff time is four days. Reaching the retry cutoff is independent of how |
| 24350 | long any specific message has been failing; it is the length of continuous |
| 24351 | failure for the recipient address that counts. |
| 24352 | |
| 24353 | When the cutoff time is reached for a local delivery, or for all the IP |
| 24354 | addresses associated with a remote delivery, a subsequent delivery failure |
| 24355 | causes Exim to give up on the address, and a bounce message is generated. |
| 24356 | In order to cater for new messages that use the failing address, a next retry |
| 24357 | time is still computed from the final algorithm, and is used as follows: |
| 24358 | |
| 24359 | For local deliveries, one delivery attempt is always made for any subsequent |
| 24360 | messages. If this delivery fails, the address fails immediately. The |
| 24361 | post-cutoff retry time is not used. |
| 24362 | |
| 24363 | If the delivery is remote, there are two possibilities, controlled by the |
| 24364 | .oindex "&%delay_after_cutoff%&" |
| 24365 | &%delay_after_cutoff%& option of the &(smtp)& transport. The option is true by |
| 24366 | default. Until the post-cutoff retry time for one of the IP addresses is |
| 24367 | reached, the failing email address is bounced immediately, without a delivery |
| 24368 | attempt taking place. After that time, one new delivery attempt is made to |
| 24369 | those IP addresses that are past their retry times, and if that still fails, |
| 24370 | the address is bounced and new retry times are computed. |
| 24371 | |
| 24372 | In other words, when all the hosts for a given email address have been failing |
| 24373 | for a long time, Exim bounces rather then defers until one of the hosts' retry |
| 24374 | times is reached. Then it tries once, and bounces if that attempt fails. This |
| 24375 | behaviour ensures that few resources are wasted in repeatedly trying to deliver |
| 24376 | to a broken destination, but if the host does recover, Exim will eventually |
| 24377 | notice. |
| 24378 | |
| 24379 | If &%delay_after_cutoff%& is set false, Exim behaves differently. If all IP |
| 24380 | addresses are past their final cutoff time, Exim tries to deliver to those IP |
| 24381 | addresses that have not been tried since the message arrived. If there are |
| 24382 | no suitable IP addresses, or if they all fail, the address is bounced. In other |
| 24383 | words, it does not delay when a new message arrives, but tries the expired |
| 24384 | addresses immediately, unless they have been tried since the message arrived. |
| 24385 | If there is a continuous stream of messages for the failing domains, setting |
| 24386 | &%delay_after_cutoff%& false means that there will be many more attempts to |
| 24387 | deliver to permanently failing IP addresses than when &%delay_after_cutoff%& is |
| 24388 | true. |
| 24389 | |
| 24390 | .section "Deliveries that work intermittently" "SECID167" |
| 24391 | .cindex "retry" "intermittently working deliveries" |
| 24392 | Some additional logic is needed to cope with cases where a host is |
| 24393 | intermittently available, or when a message has some attribute that prevents |
| 24394 | its delivery when others to the same address get through. In this situation, |
| 24395 | because some messages are successfully delivered, the &"retry clock"& for the |
| 24396 | host or address keeps getting reset by the successful deliveries, and so |
| 24397 | failing messages remain on the queue for ever because the cutoff time is never |
| 24398 | reached. |
| 24399 | |
| 24400 | Two exceptional actions are applied to prevent this happening. The first |
| 24401 | applies to errors that are related to a message rather than a remote host. |
| 24402 | Section &<<SECToutSMTPerr>>& has a discussion of the different kinds of error; |
| 24403 | examples of message-related errors are 4&'xx'& responses to MAIL or DATA |
| 24404 | commands, and quota failures. For this type of error, if a message's arrival |
| 24405 | time is earlier than the &"first failed"& time for the error, the earlier time |
| 24406 | is used when scanning the retry rules to decide when to try next and when to |
| 24407 | time out the address. |
| 24408 | |
| 24409 | The exceptional second action applies in all cases. If a message has been on |
| 24410 | the queue for longer than the cutoff time of any applicable retry rule for a |
| 24411 | given address, a delivery is attempted for that address, even if it is not yet |
| 24412 | time, and if this delivery fails, the address is timed out. A new retry time is |
| 24413 | not computed in this case, so that other messages for the same address are |
| 24414 | considered immediately. |
| 24415 | .ecindex IIDretconf1 |
| 24416 | .ecindex IIDregconf2 |
| 24417 | |
| 24418 | |
| 24419 | |
| 24420 | |
| 24421 | |
| 24422 | |
| 24423 | . //////////////////////////////////////////////////////////////////////////// |
| 24424 | . //////////////////////////////////////////////////////////////////////////// |
| 24425 | |
| 24426 | .chapter "SMTP authentication" "CHAPSMTPAUTH" |
| 24427 | .scindex IIDauthconf1 "SMTP" "authentication configuration" |
| 24428 | .scindex IIDauthconf2 "authentication" |
| 24429 | The &"authenticators"& section of Exim's run time configuration is concerned |
| 24430 | with SMTP authentication. This facility is an extension to the SMTP protocol, |
| 24431 | described in RFC 2554, which allows a client SMTP host to authenticate itself |
| 24432 | to a server. This is a common way for a server to recognize clients that are |
| 24433 | permitted to use it as a relay. SMTP authentication is not of relevance to the |
| 24434 | transfer of mail between servers that have no managerial connection with each |
| 24435 | other. |
| 24436 | |
| 24437 | .cindex "AUTH" "description of" |
| 24438 | Very briefly, the way SMTP authentication works is as follows: |
| 24439 | |
| 24440 | .ilist |
| 24441 | The server advertises a number of authentication &'mechanisms'& in response to |
| 24442 | the client's EHLO command. |
| 24443 | .next |
| 24444 | The client issues an AUTH command, naming a specific mechanism. The command |
| 24445 | may, optionally, contain some authentication data. |
| 24446 | .next |
| 24447 | The server may issue one or more &'challenges'&, to which the client must send |
| 24448 | appropriate responses. In simple authentication mechanisms, the challenges are |
| 24449 | just prompts for user names and passwords. The server does not have to issue |
| 24450 | any challenges &-- in some mechanisms the relevant data may all be transmitted |
| 24451 | with the AUTH command. |
| 24452 | .next |
| 24453 | The server either accepts or denies authentication. |
| 24454 | .next |
| 24455 | If authentication succeeds, the client may optionally make use of the AUTH |
| 24456 | option on the MAIL command to pass an authenticated sender in subsequent |
| 24457 | mail transactions. Authentication lasts for the remainder of the SMTP |
| 24458 | connection. |
| 24459 | .next |
| 24460 | If authentication fails, the client may give up, or it may try a different |
| 24461 | authentication mechanism, or it may try transferring mail over the |
| 24462 | unauthenticated connection. |
| 24463 | .endlist |
| 24464 | |
| 24465 | If you are setting up a client, and want to know which authentication |
| 24466 | mechanisms the server supports, you can use Telnet to connect to port 25 (the |
| 24467 | SMTP port) on the server, and issue an EHLO command. The response to this |
| 24468 | includes the list of supported mechanisms. For example: |
| 24469 | .display |
| 24470 | &`$ `&&*&`telnet server.example 25`&*& |
| 24471 | &`Trying 192.168.34.25...`& |
| 24472 | &`Connected to server.example.`& |
| 24473 | &`Escape character is '^]'.`& |
| 24474 | &`220 server.example ESMTP Exim 4.20 ...`& |
| 24475 | &*&`ehlo client.example`&*& |
| 24476 | &`250-server.example Hello client.example [10.8.4.5]`& |
| 24477 | &`250-SIZE 52428800`& |
| 24478 | &`250-PIPELINING`& |
| 24479 | &`250-AUTH PLAIN`& |
| 24480 | &`250 HELP`& |
| 24481 | .endd |
| 24482 | The second-last line of this example output shows that the server supports |
| 24483 | authentication using the PLAIN mechanism. In Exim, the different authentication |
| 24484 | mechanisms are configured by specifying &'authenticator'& drivers. Like the |
| 24485 | routers and transports, which authenticators are included in the binary is |
| 24486 | controlled by build-time definitions. The following are currently available, |
| 24487 | included by setting |
| 24488 | .code |
| 24489 | AUTH_CRAM_MD5=yes |
| 24490 | AUTH_CYRUS_SASL=yes |
| 24491 | AUTH_DOVECOT=yes |
| 24492 | AUTH_GSASL=yes |
| 24493 | AUTH_HEIMDAL_GSSAPI=yes |
| 24494 | AUTH_PLAINTEXT=yes |
| 24495 | AUTH_SPA=yes |
| 24496 | .endd |
| 24497 | in &_Local/Makefile_&, respectively. The first of these supports the CRAM-MD5 |
| 24498 | authentication mechanism (RFC 2195), and the second provides an interface to |
| 24499 | the Cyrus SASL authentication library. |
| 24500 | The third is an interface to Dovecot's authentication system, delegating the |
| 24501 | work via a socket interface. |
| 24502 | The fourth provides an interface to the GNU SASL authentication library, which |
| 24503 | provides mechanisms but typically not data sources. |
| 24504 | The fifth provides direct access to Heimdal GSSAPI, geared for Kerberos, but |
| 24505 | supporting setting a server keytab. |
| 24506 | The sixth can be configured to support |
| 24507 | the PLAIN authentication mechanism (RFC 2595) or the LOGIN mechanism, which is |
| 24508 | not formally documented, but used by several MUAs. The seventh authenticator |
| 24509 | supports Microsoft's &'Secure Password Authentication'& mechanism. |
| 24510 | |
| 24511 | The authenticators are configured using the same syntax as other drivers (see |
| 24512 | section &<<SECTfordricon>>&). If no authenticators are required, no |
| 24513 | authentication section need be present in the configuration file. Each |
| 24514 | authenticator can in principle have both server and client functions. When Exim |
| 24515 | is receiving SMTP mail, it is acting as a server; when it is sending out |
| 24516 | messages over SMTP, it is acting as a client. Authenticator configuration |
| 24517 | options are provided for use in both these circumstances. |
| 24518 | |
| 24519 | To make it clear which options apply to which situation, the prefixes |
| 24520 | &%server_%& and &%client_%& are used on option names that are specific to |
| 24521 | either the server or the client function, respectively. Server and client |
| 24522 | functions are disabled if none of their options are set. If an authenticator is |
| 24523 | to be used for both server and client functions, a single definition, using |
| 24524 | both sets of options, is required. For example: |
| 24525 | .code |
| 24526 | cram: |
| 24527 | driver = cram_md5 |
| 24528 | public_name = CRAM-MD5 |
| 24529 | server_secret = ${if eq{$auth1}{ph10}{secret1}fail} |
| 24530 | client_name = ph10 |
| 24531 | client_secret = secret2 |
| 24532 | .endd |
| 24533 | The &%server_%& option is used when Exim is acting as a server, and the |
| 24534 | &%client_%& options when it is acting as a client. |
| 24535 | |
| 24536 | Descriptions of the individual authenticators are given in subsequent chapters. |
| 24537 | The remainder of this chapter covers the generic options for the |
| 24538 | authenticators, followed by general discussion of the way authentication works |
| 24539 | in Exim. |
| 24540 | |
| 24541 | &*Beware:*& the meaning of &$auth1$&, &$auth2$&, ... varies on a per-driver and |
| 24542 | per-mechanism basis. Please read carefully to determine which variables hold |
| 24543 | account labels such as usercodes and which hold passwords or other |
| 24544 | authenticating data. |
| 24545 | |
| 24546 | Note that some mechanisms support two different identifiers for accounts: the |
| 24547 | &'authentication id'& and the &'authorization id'&. The contractions &'authn'& |
| 24548 | and &'authz'& are commonly encountered. The American spelling is standard here. |
| 24549 | Conceptually, authentication data such as passwords are tied to the identifier |
| 24550 | used to authenticate; servers may have rules to permit one user to act as a |
| 24551 | second user, so that after login the session is treated as though that second |
| 24552 | user had logged in. That second user is the &'authorization id'&. A robust |
| 24553 | configuration might confirm that the &'authz'& field is empty or matches the |
| 24554 | &'authn'& field. Often this is just ignored. The &'authn'& can be considered |
| 24555 | as verified data, the &'authz'& as an unverified request which the server might |
| 24556 | choose to honour. |
| 24557 | |
| 24558 | A &'realm'& is a text string, typically a domain name, presented by a server |
| 24559 | to a client to help it select an account and credentials to use. In some |
| 24560 | mechanisms, the client and server provably agree on the realm, but clients |
| 24561 | typically can not treat the realm as secure data to be blindly trusted. |
| 24562 | |
| 24563 | |
| 24564 | |
| 24565 | .section "Generic options for authenticators" "SECID168" |
| 24566 | .cindex "authentication" "generic options" |
| 24567 | .cindex "options" "generic; for authenticators" |
| 24568 | |
| 24569 | .option client_condition authenticators string&!! unset |
| 24570 | When Exim is authenticating as a client, it skips any authenticator whose |
| 24571 | &%client_condition%& expansion yields &"0"&, &"no"&, or &"false"&. This can be |
| 24572 | used, for example, to skip plain text authenticators when the connection is not |
| 24573 | encrypted by a setting such as: |
| 24574 | .code |
| 24575 | client_condition = ${if !eq{$tls_out_cipher}{}} |
| 24576 | .endd |
| 24577 | |
| 24578 | |
| 24579 | .option client_set_id authenticators string&!! unset |
| 24580 | When client authentication succeeds, this condition is expanded; the |
| 24581 | result is used in the log lines for outbound messasges. |
| 24582 | Typically it will be the user name used for authentication. |
| 24583 | |
| 24584 | |
| 24585 | .option driver authenticators string unset |
| 24586 | This option must always be set. It specifies which of the available |
| 24587 | authenticators is to be used. |
| 24588 | |
| 24589 | |
| 24590 | .option public_name authenticators string unset |
| 24591 | This option specifies the name of the authentication mechanism that the driver |
| 24592 | implements, and by which it is known to the outside world. These names should |
| 24593 | contain only upper case letters, digits, underscores, and hyphens (RFC 2222), |
| 24594 | but Exim in fact matches them caselessly. If &%public_name%& is not set, it |
| 24595 | defaults to the driver's instance name. |
| 24596 | |
| 24597 | |
| 24598 | .option server_advertise_condition authenticators string&!! unset |
| 24599 | When a server is about to advertise an authentication mechanism, the condition |
| 24600 | is expanded. If it yields the empty string, &"0"&, &"no"&, or &"false"&, the |
| 24601 | mechanism is not advertised. |
| 24602 | If the expansion fails, the mechanism is not advertised. If the failure was not |
| 24603 | forced, and was not caused by a lookup defer, the incident is logged. |
| 24604 | See section &<<SECTauthexiser>>& below for further discussion. |
| 24605 | |
| 24606 | |
| 24607 | .option server_condition authenticators string&!! unset |
| 24608 | This option must be set for a &%plaintext%& server authenticator, where it |
| 24609 | is used directly to control authentication. See section &<<SECTplainserver>>& |
| 24610 | for details. |
| 24611 | |
| 24612 | For the &(gsasl)& authenticator, this option is required for various |
| 24613 | mechanisms; see chapter &<<CHAPgsasl>>& for details. |
| 24614 | |
| 24615 | For the other authenticators, &%server_condition%& can be used as an additional |
| 24616 | authentication or authorization mechanism that is applied after the other |
| 24617 | authenticator conditions succeed. If it is set, it is expanded when the |
| 24618 | authenticator would otherwise return a success code. If the expansion is forced |
| 24619 | to fail, authentication fails. Any other expansion failure causes a temporary |
| 24620 | error code to be returned. If the result of a successful expansion is an empty |
| 24621 | string, &"0"&, &"no"&, or &"false"&, authentication fails. If the result of the |
| 24622 | expansion is &"1"&, &"yes"&, or &"true"&, authentication succeeds. For any |
| 24623 | other result, a temporary error code is returned, with the expanded string as |
| 24624 | the error text. |
| 24625 | |
| 24626 | |
| 24627 | .option server_debug_print authenticators string&!! unset |
| 24628 | If this option is set and authentication debugging is enabled (see the &%-d%& |
| 24629 | command line option), the string is expanded and included in the debugging |
| 24630 | output when the authenticator is run as a server. This can help with checking |
| 24631 | out the values of variables. |
| 24632 | If expansion of the string fails, the error message is written to the debugging |
| 24633 | output, and Exim carries on processing. |
| 24634 | |
| 24635 | |
| 24636 | .option server_set_id authenticators string&!! unset |
| 24637 | .vindex "&$authenticated_id$&" |
| 24638 | When an Exim server successfully authenticates a client, this string is |
| 24639 | expanded using data from the authentication, and preserved for any incoming |
| 24640 | messages in the variable &$authenticated_id$&. It is also included in the log |
| 24641 | lines for incoming messages. For example, a user/password authenticator |
| 24642 | configuration might preserve the user name that was used to authenticate, and |
| 24643 | refer to it subsequently during delivery of the message. |
| 24644 | If expansion fails, the option is ignored. |
| 24645 | |
| 24646 | |
| 24647 | .option server_mail_auth_condition authenticators string&!! unset |
| 24648 | This option allows a server to discard authenticated sender addresses supplied |
| 24649 | as part of MAIL commands in SMTP connections that are authenticated by the |
| 24650 | driver on which &%server_mail_auth_condition%& is set. The option is not used |
| 24651 | as part of the authentication process; instead its (unexpanded) value is |
| 24652 | remembered for later use. |
| 24653 | How it is used is described in the following section. |
| 24654 | |
| 24655 | |
| 24656 | |
| 24657 | |
| 24658 | |
| 24659 | .section "The AUTH parameter on MAIL commands" "SECTauthparamail" |
| 24660 | .cindex "authentication" "sender; authenticated" |
| 24661 | .cindex "AUTH" "on MAIL command" |
| 24662 | When a client supplied an AUTH= item on a MAIL command, Exim applies |
| 24663 | the following checks before accepting it as the authenticated sender of the |
| 24664 | message: |
| 24665 | |
| 24666 | .ilist |
| 24667 | If the connection is not using extended SMTP (that is, HELO was used rather |
| 24668 | than EHLO), the use of AUTH= is a syntax error. |
| 24669 | .next |
| 24670 | If the value of the AUTH= parameter is &"<>"&, it is ignored. |
| 24671 | .next |
| 24672 | .vindex "&$authenticated_sender$&" |
| 24673 | If &%acl_smtp_mailauth%& is defined, the ACL it specifies is run. While it is |
| 24674 | running, the value of &$authenticated_sender$& is set to the value obtained |
| 24675 | from the AUTH= parameter. If the ACL does not yield &"accept"&, the value of |
| 24676 | &$authenticated_sender$& is deleted. The &%acl_smtp_mailauth%& ACL may not |
| 24677 | return &"drop"& or &"discard"&. If it defers, a temporary error code (451) is |
| 24678 | given for the MAIL command. |
| 24679 | .next |
| 24680 | If &%acl_smtp_mailauth%& is not defined, the value of the AUTH= parameter |
| 24681 | is accepted and placed in &$authenticated_sender$& only if the client has |
| 24682 | authenticated. |
| 24683 | .next |
| 24684 | If the AUTH= value was accepted by either of the two previous rules, and |
| 24685 | the client has authenticated, and the authenticator has a setting for the |
| 24686 | &%server_mail_auth_condition%&, the condition is checked at this point. The |
| 24687 | valued that was saved from the authenticator is expanded. If the expansion |
| 24688 | fails, or yields an empty string, &"0"&, &"no"&, or &"false"&, the value of |
| 24689 | &$authenticated_sender$& is deleted. If the expansion yields any other value, |
| 24690 | the value of &$authenticated_sender$& is retained and passed on with the |
| 24691 | message. |
| 24692 | .endlist |
| 24693 | |
| 24694 | |
| 24695 | When &$authenticated_sender$& is set for a message, it is passed on to other |
| 24696 | hosts to which Exim authenticates as a client. Do not confuse this value with |
| 24697 | &$authenticated_id$&, which is a string obtained from the authentication |
| 24698 | process, and which is not usually a complete email address. |
| 24699 | |
| 24700 | .vindex "&$sender_address$&" |
| 24701 | Whenever an AUTH= value is ignored, the incident is logged. The ACL for |
| 24702 | MAIL, if defined, is run after AUTH= is accepted or ignored. It can |
| 24703 | therefore make use of &$authenticated_sender$&. The converse is not true: the |
| 24704 | value of &$sender_address$& is not yet set up when the &%acl_smtp_mailauth%& |
| 24705 | ACL is run. |
| 24706 | |
| 24707 | |
| 24708 | |
| 24709 | .section "Authentication on an Exim server" "SECTauthexiser" |
| 24710 | .cindex "authentication" "on an Exim server" |
| 24711 | When Exim receives an EHLO command, it advertises the public names of those |
| 24712 | authenticators that are configured as servers, subject to the following |
| 24713 | conditions: |
| 24714 | |
| 24715 | .ilist |
| 24716 | The client host must match &%auth_advertise_hosts%& (default *). |
| 24717 | .next |
| 24718 | It the &%server_advertise_condition%& option is set, its expansion must not |
| 24719 | yield the empty string, &"0"&, &"no"&, or &"false"&. |
| 24720 | .endlist |
| 24721 | |
| 24722 | The order in which the authenticators are defined controls the order in which |
| 24723 | the mechanisms are advertised. |
| 24724 | |
| 24725 | Some mail clients (for example, some versions of Netscape) require the user to |
| 24726 | provide a name and password for authentication whenever AUTH is advertised, |
| 24727 | even though authentication may not in fact be needed (for example, Exim may be |
| 24728 | set up to allow unconditional relaying from the client by an IP address check). |
| 24729 | You can make such clients more friendly by not advertising AUTH to them. |
| 24730 | For example, if clients on the 10.9.8.0/24 network are permitted (by the ACL |
| 24731 | that runs for RCPT) to relay without authentication, you should set |
| 24732 | .code |
| 24733 | auth_advertise_hosts = ! 10.9.8.0/24 |
| 24734 | .endd |
| 24735 | so that no authentication mechanisms are advertised to them. |
| 24736 | |
| 24737 | The &%server_advertise_condition%& controls the advertisement of individual |
| 24738 | authentication mechanisms. For example, it can be used to restrict the |
| 24739 | advertisement of a particular mechanism to encrypted connections, by a setting |
| 24740 | such as: |
| 24741 | .code |
| 24742 | server_advertise_condition = ${if eq{$tls_in_cipher}{}{no}{yes}} |
| 24743 | .endd |
| 24744 | .vindex "&$tls_in_cipher$&" |
| 24745 | If the session is encrypted, &$tls_in_cipher$& is not empty, and so the expansion |
| 24746 | yields &"yes"&, which allows the advertisement to happen. |
| 24747 | |
| 24748 | When an Exim server receives an AUTH command from a client, it rejects it |
| 24749 | immediately if AUTH was not advertised in response to an earlier EHLO |
| 24750 | command. This is the case if |
| 24751 | |
| 24752 | .ilist |
| 24753 | The client host does not match &%auth_advertise_hosts%&; or |
| 24754 | .next |
| 24755 | No authenticators are configured with server options; or |
| 24756 | .next |
| 24757 | Expansion of &%server_advertise_condition%& blocked the advertising of all the |
| 24758 | server authenticators. |
| 24759 | .endlist |
| 24760 | |
| 24761 | |
| 24762 | Otherwise, Exim runs the ACL specified by &%acl_smtp_auth%& in order |
| 24763 | to decide whether to accept the command. If &%acl_smtp_auth%& is not set, |
| 24764 | AUTH is accepted from any client host. |
| 24765 | |
| 24766 | If AUTH is not rejected by the ACL, Exim searches its configuration for a |
| 24767 | server authentication mechanism that was advertised in response to EHLO and |
| 24768 | that matches the one named in the AUTH command. If it finds one, it runs |
| 24769 | the appropriate authentication protocol, and authentication either succeeds or |
| 24770 | fails. If there is no matching advertised mechanism, the AUTH command is |
| 24771 | rejected with a 504 error. |
| 24772 | |
| 24773 | .vindex "&$received_protocol$&" |
| 24774 | .vindex "&$sender_host_authenticated$&" |
| 24775 | When a message is received from an authenticated host, the value of |
| 24776 | &$received_protocol$& is set to &"esmtpa"& or &"esmtpsa"& instead of &"esmtp"& |
| 24777 | or &"esmtps"&, and &$sender_host_authenticated$& contains the name (not the |
| 24778 | public name) of the authenticator driver that successfully authenticated the |
| 24779 | client from which the message was received. This variable is empty if there was |
| 24780 | no successful authentication. |
| 24781 | |
| 24782 | |
| 24783 | |
| 24784 | |
| 24785 | .section "Testing server authentication" "SECID169" |
| 24786 | .cindex "authentication" "testing a server" |
| 24787 | .cindex "AUTH" "testing a server" |
| 24788 | .cindex "base64 encoding" "creating authentication test data" |
| 24789 | Exim's &%-bh%& option can be useful for testing server authentication |
| 24790 | configurations. The data for the AUTH command has to be sent using base64 |
| 24791 | encoding. A quick way to produce such data for testing is the following Perl |
| 24792 | script: |
| 24793 | .code |
| 24794 | use MIME::Base64; |
| 24795 | printf ("%s", encode_base64(eval "\"$ARGV[0]\"")); |
| 24796 | .endd |
| 24797 | .cindex "binary zero" "in authentication data" |
| 24798 | This interprets its argument as a Perl string, and then encodes it. The |
| 24799 | interpretation as a Perl string allows binary zeros, which are required for |
| 24800 | some kinds of authentication, to be included in the data. For example, a |
| 24801 | command line to run this script on such data might be |
| 24802 | .code |
| 24803 | encode '\0user\0password' |
| 24804 | .endd |
| 24805 | Note the use of single quotes to prevent the shell interpreting the |
| 24806 | backslashes, so that they can be interpreted by Perl to specify characters |
| 24807 | whose code value is zero. |
| 24808 | |
| 24809 | &*Warning 1*&: If either of the user or password strings starts with an octal |
| 24810 | digit, you must use three zeros instead of one after the leading backslash. If |
| 24811 | you do not, the octal digit that starts your string will be incorrectly |
| 24812 | interpreted as part of the code for the first character. |
| 24813 | |
| 24814 | &*Warning 2*&: If there are characters in the strings that Perl interprets |
| 24815 | specially, you must use a Perl escape to prevent them being misinterpreted. For |
| 24816 | example, a command such as |
| 24817 | .code |
| 24818 | encode '\0user@domain.com\0pas$$word' |
| 24819 | .endd |
| 24820 | gives an incorrect answer because of the unescaped &"@"& and &"$"& characters. |
| 24821 | |
| 24822 | If you have the &%mimencode%& command installed, another way to do produce |
| 24823 | base64-encoded strings is to run the command |
| 24824 | .code |
| 24825 | echo -e -n `\0user\0password' | mimencode |
| 24826 | .endd |
| 24827 | The &%-e%& option of &%echo%& enables the interpretation of backslash escapes |
| 24828 | in the argument, and the &%-n%& option specifies no newline at the end of its |
| 24829 | output. However, not all versions of &%echo%& recognize these options, so you |
| 24830 | should check your version before relying on this suggestion. |
| 24831 | |
| 24832 | |
| 24833 | |
| 24834 | .section "Authentication by an Exim client" "SECID170" |
| 24835 | .cindex "authentication" "on an Exim client" |
| 24836 | The &(smtp)& transport has two options called &%hosts_require_auth%& and |
| 24837 | &%hosts_try_auth%&. When the &(smtp)& transport connects to a server that |
| 24838 | announces support for authentication, and the host matches an entry in either |
| 24839 | of these options, Exim (as a client) tries to authenticate as follows: |
| 24840 | |
| 24841 | .ilist |
| 24842 | For each authenticator that is configured as a client, in the order in which |
| 24843 | they are defined in the configuration, it searches the authentication |
| 24844 | mechanisms announced by the server for one whose name matches the public name |
| 24845 | of the authenticator. |
| 24846 | .next |
| 24847 | .vindex "&$host$&" |
| 24848 | .vindex "&$host_address$&" |
| 24849 | When it finds one that matches, it runs the authenticator's client code. The |
| 24850 | variables &$host$& and &$host_address$& are available for any string expansions |
| 24851 | that the client might do. They are set to the server's name and IP address. If |
| 24852 | any expansion is forced to fail, the authentication attempt is abandoned, and |
| 24853 | Exim moves on to the next authenticator. Otherwise an expansion failure causes |
| 24854 | delivery to be deferred. |
| 24855 | .next |
| 24856 | If the result of the authentication attempt is a temporary error or a timeout, |
| 24857 | Exim abandons trying to send the message to the host for the moment. It will |
| 24858 | try again later. If there are any backup hosts available, they are tried in the |
| 24859 | usual way. |
| 24860 | .next |
| 24861 | If the response to authentication is a permanent error (5&'xx'& code), Exim |
| 24862 | carries on searching the list of authenticators and tries another one if |
| 24863 | possible. If all authentication attempts give permanent errors, or if there are |
| 24864 | no attempts because no mechanisms match (or option expansions force failure), |
| 24865 | what happens depends on whether the host matches &%hosts_require_auth%& or |
| 24866 | &%hosts_try_auth%&. In the first case, a temporary error is generated, and |
| 24867 | delivery is deferred. The error can be detected in the retry rules, and thereby |
| 24868 | turned into a permanent error if you wish. In the second case, Exim tries to |
| 24869 | deliver the message unauthenticated. |
| 24870 | .endlist |
| 24871 | |
| 24872 | .cindex "AUTH" "on MAIL command" |
| 24873 | When Exim has authenticated itself to a remote server, it adds the AUTH |
| 24874 | parameter to the MAIL commands it sends, if it has an authenticated sender for |
| 24875 | the message. If the message came from a remote host, the authenticated sender |
| 24876 | is the one that was receiving on an incoming MAIL command, provided that the |
| 24877 | incoming connection was authenticated and the &%server_mail_auth%& condition |
| 24878 | allowed the authenticated sender to be retained. If a local process calls Exim |
| 24879 | to send a message, the sender address that is built from the login name and |
| 24880 | &%qualify_domain%& is treated as authenticated. However, if the |
| 24881 | &%authenticated_sender%& option is set on the &(smtp)& transport, it overrides |
| 24882 | the authenticated sender that was received with the message. |
| 24883 | .ecindex IIDauthconf1 |
| 24884 | .ecindex IIDauthconf2 |
| 24885 | |
| 24886 | |
| 24887 | |
| 24888 | |
| 24889 | |
| 24890 | |
| 24891 | . //////////////////////////////////////////////////////////////////////////// |
| 24892 | . //////////////////////////////////////////////////////////////////////////// |
| 24893 | |
| 24894 | .chapter "The plaintext authenticator" "CHAPplaintext" |
| 24895 | .scindex IIDplaiauth1 "&(plaintext)& authenticator" |
| 24896 | .scindex IIDplaiauth2 "authenticators" "&(plaintext)&" |
| 24897 | The &(plaintext)& authenticator can be configured to support the PLAIN and |
| 24898 | LOGIN authentication mechanisms, both of which transfer authentication data as |
| 24899 | plain (unencrypted) text (though base64 encoded). The use of plain text is a |
| 24900 | security risk; you are strongly advised to insist on the use of SMTP encryption |
| 24901 | (see chapter &<<CHAPTLS>>&) if you use the PLAIN or LOGIN mechanisms. If you do |
| 24902 | use unencrypted plain text, you should not use the same passwords for SMTP |
| 24903 | connections as you do for login accounts. |
| 24904 | |
| 24905 | .section "Plaintext options" "SECID171" |
| 24906 | .cindex "options" "&(plaintext)& authenticator (server)" |
| 24907 | When configured as a server, &(plaintext)& uses the following options: |
| 24908 | |
| 24909 | .option server_condition authenticators string&!! unset |
| 24910 | This is actually a global authentication option, but it must be set in order to |
| 24911 | configure the &(plaintext)& driver as a server. Its use is described below. |
| 24912 | |
| 24913 | .option server_prompts plaintext string&!! unset |
| 24914 | The contents of this option, after expansion, must be a colon-separated list of |
| 24915 | prompt strings. If expansion fails, a temporary authentication rejection is |
| 24916 | given. |
| 24917 | |
| 24918 | .section "Using plaintext in a server" "SECTplainserver" |
| 24919 | .cindex "AUTH" "in &(plaintext)& authenticator" |
| 24920 | .cindex "binary zero" "in &(plaintext)& authenticator" |
| 24921 | .cindex "numerical variables (&$1$& &$2$& etc)" &&& |
| 24922 | "in &(plaintext)& authenticator" |
| 24923 | .vindex "&$auth1$&, &$auth2$&, etc" |
| 24924 | .cindex "base64 encoding" "in &(plaintext)& authenticator" |
| 24925 | |
| 24926 | When running as a server, &(plaintext)& performs the authentication test by |
| 24927 | expanding a string. The data sent by the client with the AUTH command, or in |
| 24928 | response to subsequent prompts, is base64 encoded, and so may contain any byte |
| 24929 | values when decoded. If any data is supplied with the command, it is treated as |
| 24930 | a list of strings, separated by NULs (binary zeros), the first three of which |
| 24931 | are placed in the expansion variables &$auth1$&, &$auth2$&, and &$auth3$& |
| 24932 | (neither LOGIN nor PLAIN uses more than three strings). |
| 24933 | |
| 24934 | For compatibility with previous releases of Exim, the values are also placed in |
| 24935 | the expansion variables &$1$&, &$2$&, and &$3$&. However, the use of these |
| 24936 | variables for this purpose is now deprecated, as it can lead to confusion in |
| 24937 | string expansions that also use them for other things. |
| 24938 | |
| 24939 | If there are more strings in &%server_prompts%& than the number of strings |
| 24940 | supplied with the AUTH command, the remaining prompts are used to obtain more |
| 24941 | data. Each response from the client may be a list of NUL-separated strings. |
| 24942 | |
| 24943 | .vindex "&$authenticated_id$&" |
| 24944 | Once a sufficient number of data strings have been received, |
| 24945 | &%server_condition%& is expanded. If the expansion is forced to fail, |
| 24946 | authentication fails. Any other expansion failure causes a temporary error code |
| 24947 | to be returned. If the result of a successful expansion is an empty string, |
| 24948 | &"0"&, &"no"&, or &"false"&, authentication fails. If the result of the |
| 24949 | expansion is &"1"&, &"yes"&, or &"true"&, authentication succeeds and the |
| 24950 | generic &%server_set_id%& option is expanded and saved in &$authenticated_id$&. |
| 24951 | For any other result, a temporary error code is returned, with the expanded |
| 24952 | string as the error text |
| 24953 | |
| 24954 | &*Warning*&: If you use a lookup in the expansion to find the user's |
| 24955 | password, be sure to make the authentication fail if the user is unknown. |
| 24956 | There are good and bad examples at the end of the next section. |
| 24957 | |
| 24958 | |
| 24959 | |
| 24960 | .section "The PLAIN authentication mechanism" "SECID172" |
| 24961 | .cindex "PLAIN authentication mechanism" |
| 24962 | .cindex "authentication" "PLAIN mechanism" |
| 24963 | .cindex "binary zero" "in &(plaintext)& authenticator" |
| 24964 | The PLAIN authentication mechanism (RFC 2595) specifies that three strings be |
| 24965 | sent as one item of data (that is, one combined string containing two NUL |
| 24966 | separators). The data is sent either as part of the AUTH command, or |
| 24967 | subsequently in response to an empty prompt from the server. |
| 24968 | |
| 24969 | The second and third strings are a user name and a corresponding password. |
| 24970 | Using a single fixed user name and password as an example, this could be |
| 24971 | configured as follows: |
| 24972 | .code |
| 24973 | fixed_plain: |
| 24974 | driver = plaintext |
| 24975 | public_name = PLAIN |
| 24976 | server_prompts = : |
| 24977 | server_condition = \ |
| 24978 | ${if and {{eq{$auth2}{username}}{eq{$auth3}{mysecret}}}} |
| 24979 | server_set_id = $auth2 |
| 24980 | .endd |
| 24981 | Note that the default result strings from &%if%& (&"true"& or an empty string) |
| 24982 | are exactly what we want here, so they need not be specified. Obviously, if the |
| 24983 | password contains expansion-significant characters such as dollar, backslash, |
| 24984 | or closing brace, they have to be escaped. |
| 24985 | |
| 24986 | The &%server_prompts%& setting specifies a single, empty prompt (empty items at |
| 24987 | the end of a string list are ignored). If all the data comes as part of the |
| 24988 | AUTH command, as is commonly the case, the prompt is not used. This |
| 24989 | authenticator is advertised in the response to EHLO as |
| 24990 | .code |
| 24991 | 250-AUTH PLAIN |
| 24992 | .endd |
| 24993 | and a client host can authenticate itself by sending the command |
| 24994 | .code |
| 24995 | AUTH PLAIN AHVzZXJuYW1lAG15c2VjcmV0 |
| 24996 | .endd |
| 24997 | As this contains three strings (more than the number of prompts), no further |
| 24998 | data is required from the client. Alternatively, the client may just send |
| 24999 | .code |
| 25000 | AUTH PLAIN |
| 25001 | .endd |
| 25002 | to initiate authentication, in which case the server replies with an empty |
| 25003 | prompt. The client must respond with the combined data string. |
| 25004 | |
| 25005 | The data string is base64 encoded, as required by the RFC. This example, |
| 25006 | when decoded, is <&'NUL'&>&`username`&<&'NUL'&>&`mysecret`&, where <&'NUL'&> |
| 25007 | represents a zero byte. This is split up into three strings, the first of which |
| 25008 | is empty. The &%server_condition%& option in the authenticator checks that the |
| 25009 | second two are &`username`& and &`mysecret`& respectively. |
| 25010 | |
| 25011 | Having just one fixed user name and password, as in this example, is not very |
| 25012 | realistic, though for a small organization with only a handful of |
| 25013 | authenticating clients it could make sense. |
| 25014 | |
| 25015 | A more sophisticated instance of this authenticator could use the user name in |
| 25016 | &$auth2$& to look up a password in a file or database, and maybe do an encrypted |
| 25017 | comparison (see &%crypteq%& in chapter &<<CHAPexpand>>&). Here is a example of |
| 25018 | this approach, where the passwords are looked up in a DBM file. &*Warning*&: |
| 25019 | This is an incorrect example: |
| 25020 | .code |
| 25021 | server_condition = \ |
| 25022 | ${if eq{$auth3}{${lookup{$auth2}dbm{/etc/authpwd}}}} |
| 25023 | .endd |
| 25024 | The expansion uses the user name (&$auth2$&) as the key to look up a password, |
| 25025 | which it then compares to the supplied password (&$auth3$&). Why is this example |
| 25026 | incorrect? It works fine for existing users, but consider what happens if a |
| 25027 | non-existent user name is given. The lookup fails, but as no success/failure |
| 25028 | strings are given for the lookup, it yields an empty string. Thus, to defeat |
| 25029 | the authentication, all a client has to do is to supply a non-existent user |
| 25030 | name and an empty password. The correct way of writing this test is: |
| 25031 | .code |
| 25032 | server_condition = ${lookup{$auth2}dbm{/etc/authpwd}\ |
| 25033 | {${if eq{$value}{$auth3}}} {false}} |
| 25034 | .endd |
| 25035 | In this case, if the lookup succeeds, the result is checked; if the lookup |
| 25036 | fails, &"false"& is returned and authentication fails. If &%crypteq%& is being |
| 25037 | used instead of &%eq%&, the first example is in fact safe, because &%crypteq%& |
| 25038 | always fails if its second argument is empty. However, the second way of |
| 25039 | writing the test makes the logic clearer. |
| 25040 | |
| 25041 | |
| 25042 | .section "The LOGIN authentication mechanism" "SECID173" |
| 25043 | .cindex "LOGIN authentication mechanism" |
| 25044 | .cindex "authentication" "LOGIN mechanism" |
| 25045 | The LOGIN authentication mechanism is not documented in any RFC, but is in use |
| 25046 | in a number of programs. No data is sent with the AUTH command. Instead, a |
| 25047 | user name and password are supplied separately, in response to prompts. The |
| 25048 | plaintext authenticator can be configured to support this as in this example: |
| 25049 | .code |
| 25050 | fixed_login: |
| 25051 | driver = plaintext |
| 25052 | public_name = LOGIN |
| 25053 | server_prompts = User Name : Password |
| 25054 | server_condition = \ |
| 25055 | ${if and {{eq{$auth1}{username}}{eq{$auth2}{mysecret}}}} |
| 25056 | server_set_id = $auth1 |
| 25057 | .endd |
| 25058 | Because of the way plaintext operates, this authenticator accepts data supplied |
| 25059 | with the AUTH command (in contravention of the specification of LOGIN), but |
| 25060 | if the client does not supply it (as is the case for LOGIN clients), the prompt |
| 25061 | strings are used to obtain two data items. |
| 25062 | |
| 25063 | Some clients are very particular about the precise text of the prompts. For |
| 25064 | example, Outlook Express is reported to recognize only &"Username:"& and |
| 25065 | &"Password:"&. Here is an example of a LOGIN authenticator that uses those |
| 25066 | strings. It uses the &%ldapauth%& expansion condition to check the user |
| 25067 | name and password by binding to an LDAP server: |
| 25068 | .code |
| 25069 | login: |
| 25070 | driver = plaintext |
| 25071 | public_name = LOGIN |
| 25072 | server_prompts = Username:: : Password:: |
| 25073 | server_condition = ${if and{{ \ |
| 25074 | !eq{}{$auth1} }{ \ |
| 25075 | ldapauth{\ |
| 25076 | user="uid=${quote_ldap_dn:$auth1},ou=people,o=example.org" \ |
| 25077 | pass=${quote:$auth2} \ |
| 25078 | ldap://ldap.example.org/} }} } |
| 25079 | server_set_id = uid=$auth1,ou=people,o=example.org |
| 25080 | .endd |
| 25081 | We have to check that the username is not empty before using it, because LDAP |
| 25082 | does not permit empty DN components. We must also use the &%quote_ldap_dn%& |
| 25083 | operator to correctly quote the DN for authentication. However, the basic |
| 25084 | &%quote%& operator, rather than any of the LDAP quoting operators, is the |
| 25085 | correct one to use for the password, because quoting is needed only to make |
| 25086 | the password conform to the Exim syntax. At the LDAP level, the password is an |
| 25087 | uninterpreted string. |
| 25088 | |
| 25089 | |
| 25090 | .section "Support for different kinds of authentication" "SECID174" |
| 25091 | A number of string expansion features are provided for the purpose of |
| 25092 | interfacing to different ways of user authentication. These include checking |
| 25093 | traditionally encrypted passwords from &_/etc/passwd_& (or equivalent), PAM, |
| 25094 | Radius, &%ldapauth%&, &'pwcheck'&, and &'saslauthd'&. For details see section |
| 25095 | &<<SECTexpcond>>&. |
| 25096 | |
| 25097 | |
| 25098 | |
| 25099 | |
| 25100 | .section "Using plaintext in a client" "SECID175" |
| 25101 | .cindex "options" "&(plaintext)& authenticator (client)" |
| 25102 | The &(plaintext)& authenticator has two client options: |
| 25103 | |
| 25104 | .option client_ignore_invalid_base64 plaintext boolean false |
| 25105 | If the client receives a server prompt that is not a valid base64 string, |
| 25106 | authentication is abandoned by default. However, if this option is set true, |
| 25107 | the error in the challenge is ignored and the client sends the response as |
| 25108 | usual. |
| 25109 | |
| 25110 | .option client_send plaintext string&!! unset |
| 25111 | The string is a colon-separated list of authentication data strings. Each |
| 25112 | string is independently expanded before being sent to the server. The first |
| 25113 | string is sent with the AUTH command; any more strings are sent in response |
| 25114 | to prompts from the server. Before each string is expanded, the value of the |
| 25115 | most recent prompt is placed in the next &$auth$&<&'n'&> variable, starting |
| 25116 | with &$auth1$& for the first prompt. Up to three prompts are stored in this |
| 25117 | way. Thus, the prompt that is received in response to sending the first string |
| 25118 | (with the AUTH command) can be used in the expansion of the second string, and |
| 25119 | so on. If an invalid base64 string is received when |
| 25120 | &%client_ignore_invalid_base64%& is set, an empty string is put in the |
| 25121 | &$auth$&<&'n'&> variable. |
| 25122 | |
| 25123 | &*Note*&: You cannot use expansion to create multiple strings, because |
| 25124 | splitting takes priority and happens first. |
| 25125 | |
| 25126 | Because the PLAIN authentication mechanism requires NUL (binary zero) bytes in |
| 25127 | the data, further processing is applied to each string before it is sent. If |
| 25128 | there are any single circumflex characters in the string, they are converted to |
| 25129 | NULs. Should an actual circumflex be required as data, it must be doubled in |
| 25130 | the string. |
| 25131 | |
| 25132 | This is an example of a client configuration that implements the PLAIN |
| 25133 | authentication mechanism with a fixed user name and password: |
| 25134 | .code |
| 25135 | fixed_plain: |
| 25136 | driver = plaintext |
| 25137 | public_name = PLAIN |
| 25138 | client_send = ^username^mysecret |
| 25139 | .endd |
| 25140 | The lack of colons means that the entire text is sent with the AUTH |
| 25141 | command, with the circumflex characters converted to NULs. A similar example |
| 25142 | that uses the LOGIN mechanism is: |
| 25143 | .code |
| 25144 | fixed_login: |
| 25145 | driver = plaintext |
| 25146 | public_name = LOGIN |
| 25147 | client_send = : username : mysecret |
| 25148 | .endd |
| 25149 | The initial colon means that the first string is empty, so no data is sent with |
| 25150 | the AUTH command itself. The remaining strings are sent in response to |
| 25151 | prompts. |
| 25152 | .ecindex IIDplaiauth1 |
| 25153 | .ecindex IIDplaiauth2 |
| 25154 | |
| 25155 | |
| 25156 | |
| 25157 | |
| 25158 | . //////////////////////////////////////////////////////////////////////////// |
| 25159 | . //////////////////////////////////////////////////////////////////////////// |
| 25160 | |
| 25161 | .chapter "The cram_md5 authenticator" "CHID9" |
| 25162 | .scindex IIDcramauth1 "&(cram_md5)& authenticator" |
| 25163 | .scindex IIDcramauth2 "authenticators" "&(cram_md5)&" |
| 25164 | .cindex "CRAM-MD5 authentication mechanism" |
| 25165 | .cindex "authentication" "CRAM-MD5 mechanism" |
| 25166 | The CRAM-MD5 authentication mechanism is described in RFC 2195. The server |
| 25167 | sends a challenge string to the client, and the response consists of a user |
| 25168 | name and the CRAM-MD5 digest of the challenge string combined with a secret |
| 25169 | string (password) which is known to both server and client. Thus, the secret |
| 25170 | is not sent over the network as plain text, which makes this authenticator more |
| 25171 | secure than &(plaintext)&. However, the downside is that the secret has to be |
| 25172 | available in plain text at either end. |
| 25173 | |
| 25174 | |
| 25175 | .section "Using cram_md5 as a server" "SECID176" |
| 25176 | .cindex "options" "&(cram_md5)& authenticator (server)" |
| 25177 | This authenticator has one server option, which must be set to configure the |
| 25178 | authenticator as a server: |
| 25179 | |
| 25180 | .option server_secret cram_md5 string&!! unset |
| 25181 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &(cram_md5)& authenticator" |
| 25182 | When the server receives the client's response, the user name is placed in |
| 25183 | the expansion variable &$auth1$&, and &%server_secret%& is expanded to |
| 25184 | obtain the password for that user. The server then computes the CRAM-MD5 digest |
| 25185 | that the client should have sent, and checks that it received the correct |
| 25186 | string. If the expansion of &%server_secret%& is forced to fail, authentication |
| 25187 | fails. If the expansion fails for some other reason, a temporary error code is |
| 25188 | returned to the client. |
| 25189 | |
| 25190 | For compatibility with previous releases of Exim, the user name is also placed |
| 25191 | in &$1$&. However, the use of this variables for this purpose is now |
| 25192 | deprecated, as it can lead to confusion in string expansions that also use |
| 25193 | numeric variables for other things. |
| 25194 | |
| 25195 | For example, the following authenticator checks that the user name given by the |
| 25196 | client is &"ph10"&, and if so, uses &"secret"& as the password. For any other |
| 25197 | user name, authentication fails. |
| 25198 | .code |
| 25199 | fixed_cram: |
| 25200 | driver = cram_md5 |
| 25201 | public_name = CRAM-MD5 |
| 25202 | server_secret = ${if eq{$auth1}{ph10}{secret}fail} |
| 25203 | server_set_id = $auth1 |
| 25204 | .endd |
| 25205 | .vindex "&$authenticated_id$&" |
| 25206 | If authentication succeeds, the setting of &%server_set_id%& preserves the user |
| 25207 | name in &$authenticated_id$&. A more typical configuration might look up the |
| 25208 | secret string in a file, using the user name as the key. For example: |
| 25209 | .code |
| 25210 | lookup_cram: |
| 25211 | driver = cram_md5 |
| 25212 | public_name = CRAM-MD5 |
| 25213 | server_secret = ${lookup{$auth1}lsearch{/etc/authpwd}\ |
| 25214 | {$value}fail} |
| 25215 | server_set_id = $auth1 |
| 25216 | .endd |
| 25217 | Note that this expansion explicitly forces failure if the lookup fails |
| 25218 | because &$auth1$& contains an unknown user name. |
| 25219 | |
| 25220 | As another example, if you wish to re-use a Cyrus SASL sasldb2 file without |
| 25221 | using the relevant libraries, you need to know the realm to specify in the |
| 25222 | lookup and then ask for the &"userPassword"& attribute for that user in that |
| 25223 | realm, with: |
| 25224 | .code |
| 25225 | cyrusless_crammd5: |
| 25226 | driver = cram_md5 |
| 25227 | public_name = CRAM-MD5 |
| 25228 | server_secret = ${lookup{$auth1:mail.example.org:userPassword}\ |
| 25229 | dbmjz{/etc/sasldb2}} |
| 25230 | server_set_id = $auth1 |
| 25231 | .endd |
| 25232 | |
| 25233 | .section "Using cram_md5 as a client" "SECID177" |
| 25234 | .cindex "options" "&(cram_md5)& authenticator (client)" |
| 25235 | When used as a client, the &(cram_md5)& authenticator has two options: |
| 25236 | |
| 25237 | |
| 25238 | |
| 25239 | .option client_name cram_md5 string&!! "the primary host name" |
| 25240 | This string is expanded, and the result used as the user name data when |
| 25241 | computing the response to the server's challenge. |
| 25242 | |
| 25243 | |
| 25244 | .option client_secret cram_md5 string&!! unset |
| 25245 | This option must be set for the authenticator to work as a client. Its value is |
| 25246 | expanded and the result used as the secret string when computing the response. |
| 25247 | |
| 25248 | |
| 25249 | .vindex "&$host$&" |
| 25250 | .vindex "&$host_address$&" |
| 25251 | Different user names and secrets can be used for different servers by referring |
| 25252 | to &$host$& or &$host_address$& in the options. Forced failure of either |
| 25253 | expansion string is treated as an indication that this authenticator is not |
| 25254 | prepared to handle this case. Exim moves on to the next configured client |
| 25255 | authenticator. Any other expansion failure causes Exim to give up trying to |
| 25256 | send the message to the current server. |
| 25257 | |
| 25258 | A simple example configuration of a &(cram_md5)& authenticator, using fixed |
| 25259 | strings, is: |
| 25260 | .code |
| 25261 | fixed_cram: |
| 25262 | driver = cram_md5 |
| 25263 | public_name = CRAM-MD5 |
| 25264 | client_name = ph10 |
| 25265 | client_secret = secret |
| 25266 | .endd |
| 25267 | .ecindex IIDcramauth1 |
| 25268 | .ecindex IIDcramauth2 |
| 25269 | |
| 25270 | |
| 25271 | |
| 25272 | . //////////////////////////////////////////////////////////////////////////// |
| 25273 | . //////////////////////////////////////////////////////////////////////////// |
| 25274 | |
| 25275 | .chapter "The cyrus_sasl authenticator" "CHID10" |
| 25276 | .scindex IIDcyrauth1 "&(cyrus_sasl)& authenticator" |
| 25277 | .scindex IIDcyrauth2 "authenticators" "&(cyrus_sasl)&" |
| 25278 | .cindex "Cyrus" "SASL library" |
| 25279 | .cindex "Kerberos" |
| 25280 | The code for this authenticator was provided by Matthew Byng-Maddick of A L |
| 25281 | Digital Ltd (&url(http://www.aldigital.co.uk)). |
| 25282 | |
| 25283 | The &(cyrus_sasl)& authenticator provides server support for the Cyrus SASL |
| 25284 | library implementation of the RFC 2222 (&"Simple Authentication and Security |
| 25285 | Layer"&). This library supports a number of authentication mechanisms, |
| 25286 | including PLAIN and LOGIN, but also several others that Exim does not support |
| 25287 | directly. In particular, there is support for Kerberos authentication. |
| 25288 | |
| 25289 | The &(cyrus_sasl)& authenticator provides a gatewaying mechanism directly to |
| 25290 | the Cyrus interface, so if your Cyrus library can do, for example, CRAM-MD5, |
| 25291 | then so can the &(cyrus_sasl)& authenticator. By default it uses the public |
| 25292 | name of the driver to determine which mechanism to support. |
| 25293 | |
| 25294 | Where access to some kind of secret file is required, for example in GSSAPI |
| 25295 | or CRAM-MD5, it is worth noting that the authenticator runs as the Exim |
| 25296 | user, and that the Cyrus SASL library has no way of escalating privileges |
| 25297 | by default. You may also find you need to set environment variables, |
| 25298 | depending on the driver you are using. |
| 25299 | |
| 25300 | The application name provided by Exim is &"exim"&, so various SASL options may |
| 25301 | be set in &_exim.conf_& in your SASL directory. If you are using GSSAPI for |
| 25302 | Kerberos, note that because of limitations in the GSSAPI interface, |
| 25303 | changing the server keytab might need to be communicated down to the Kerberos |
| 25304 | layer independently. The mechanism for doing so is dependent upon the Kerberos |
| 25305 | implementation. |
| 25306 | |
| 25307 | For example, for older releases of Heimdal, the environment variable KRB5_KTNAME |
| 25308 | may be set to point to an alternative keytab file. Exim will pass this |
| 25309 | variable through from its own inherited environment when started as root or the |
| 25310 | Exim user. The keytab file needs to be readable by the Exim user. |
| 25311 | With newer releases of Heimdal, a setuid Exim may cause Heimdal to discard the |
| 25312 | environment variable. In practice, for those releases, the Cyrus authenticator |
| 25313 | is not a suitable interface for GSSAPI (Kerberos) support. Instead, consider |
| 25314 | the &(heimdal_gssapi)& authenticator, described in chapter &<<CHAPheimdalgss>>& |
| 25315 | |
| 25316 | |
| 25317 | .section "Using cyrus_sasl as a server" "SECID178" |
| 25318 | The &(cyrus_sasl)& authenticator has four private options. It puts the username |
| 25319 | (on a successful authentication) into &$auth1$&. For compatibility with |
| 25320 | previous releases of Exim, the username is also placed in &$1$&. However, the |
| 25321 | use of this variable for this purpose is now deprecated, as it can lead to |
| 25322 | confusion in string expansions that also use numeric variables for other |
| 25323 | things. |
| 25324 | |
| 25325 | |
| 25326 | .option server_hostname cyrus_sasl string&!! "see below" |
| 25327 | This option selects the hostname that is used when communicating with the |
| 25328 | library. The default value is &`$primary_hostname`&. It is up to the underlying |
| 25329 | SASL plug-in what it does with this data. |
| 25330 | |
| 25331 | |
| 25332 | .option server_mech cyrus_sasl string "see below" |
| 25333 | This option selects the authentication mechanism this driver should use. The |
| 25334 | default is the value of the generic &%public_name%& option. This option allows |
| 25335 | you to use a different underlying mechanism from the advertised name. For |
| 25336 | example: |
| 25337 | .code |
| 25338 | sasl: |
| 25339 | driver = cyrus_sasl |
| 25340 | public_name = X-ANYTHING |
| 25341 | server_mech = CRAM-MD5 |
| 25342 | server_set_id = $auth1 |
| 25343 | .endd |
| 25344 | |
| 25345 | .option server_realm cyrus_sasl string&!! unset |
| 25346 | This specifies the SASL realm that the server claims to be in. |
| 25347 | |
| 25348 | |
| 25349 | .option server_service cyrus_sasl string &`smtp`& |
| 25350 | This is the SASL service that the server claims to implement. |
| 25351 | |
| 25352 | |
| 25353 | For straightforward cases, you do not need to set any of the authenticator's |
| 25354 | private options. All you need to do is to specify an appropriate mechanism as |
| 25355 | the public name. Thus, if you have a SASL library that supports CRAM-MD5 and |
| 25356 | PLAIN, you could have two authenticators as follows: |
| 25357 | .code |
| 25358 | sasl_cram_md5: |
| 25359 | driver = cyrus_sasl |
| 25360 | public_name = CRAM-MD5 |
| 25361 | server_set_id = $auth1 |
| 25362 | |
| 25363 | sasl_plain: |
| 25364 | driver = cyrus_sasl |
| 25365 | public_name = PLAIN |
| 25366 | server_set_id = $auth2 |
| 25367 | .endd |
| 25368 | Cyrus SASL does implement the LOGIN authentication method, even though it is |
| 25369 | not a standard method. It is disabled by default in the source distribution, |
| 25370 | but it is present in many binary distributions. |
| 25371 | .ecindex IIDcyrauth1 |
| 25372 | .ecindex IIDcyrauth2 |
| 25373 | |
| 25374 | |
| 25375 | |
| 25376 | |
| 25377 | . //////////////////////////////////////////////////////////////////////////// |
| 25378 | . //////////////////////////////////////////////////////////////////////////// |
| 25379 | .chapter "The dovecot authenticator" "CHAPdovecot" |
| 25380 | .scindex IIDdcotauth1 "&(dovecot)& authenticator" |
| 25381 | .scindex IIDdcotauth2 "authenticators" "&(dovecot)&" |
| 25382 | This authenticator is an interface to the authentication facility of the |
| 25383 | Dovecot POP/IMAP server, which can support a number of authentication methods. |
| 25384 | If you are using Dovecot to authenticate POP/IMAP clients, it might be helpful |
| 25385 | to use the same mechanisms for SMTP authentication. This is a server |
| 25386 | authenticator only. There is only one option: |
| 25387 | |
| 25388 | .option server_socket dovecot string unset |
| 25389 | |
| 25390 | This option must specify the socket that is the interface to Dovecot |
| 25391 | authentication. The &%public_name%& option must specify an authentication |
| 25392 | mechanism that Dovecot is configured to support. You can have several |
| 25393 | authenticators for different mechanisms. For example: |
| 25394 | .code |
| 25395 | dovecot_plain: |
| 25396 | driver = dovecot |
| 25397 | public_name = PLAIN |
| 25398 | server_socket = /var/run/dovecot/auth-client |
| 25399 | server_set_id = $auth1 |
| 25400 | |
| 25401 | dovecot_ntlm: |
| 25402 | driver = dovecot |
| 25403 | public_name = NTLM |
| 25404 | server_socket = /var/run/dovecot/auth-client |
| 25405 | server_set_id = $auth1 |
| 25406 | .endd |
| 25407 | If the SMTP connection is encrypted, or if &$sender_host_address$& is equal to |
| 25408 | &$received_ip_address$& (that is, the connection is local), the &"secured"& |
| 25409 | option is passed in the Dovecot authentication command. If, for a TLS |
| 25410 | connection, a client certificate has been verified, the &"valid-client-cert"& |
| 25411 | option is passed. When authentication succeeds, the identity of the user |
| 25412 | who authenticated is placed in &$auth1$&. |
| 25413 | .ecindex IIDdcotauth1 |
| 25414 | .ecindex IIDdcotauth2 |
| 25415 | |
| 25416 | |
| 25417 | . //////////////////////////////////////////////////////////////////////////// |
| 25418 | . //////////////////////////////////////////////////////////////////////////// |
| 25419 | .chapter "The gsasl authenticator" "CHAPgsasl" |
| 25420 | .scindex IIDgsaslauth1 "&(gsasl)& authenticator" |
| 25421 | .scindex IIDgsaslauth2 "authenticators" "&(gsasl)&" |
| 25422 | .cindex "authentication" "GNU SASL" |
| 25423 | .cindex "authentication" "SASL" |
| 25424 | .cindex "authentication" "EXTERNAL" |
| 25425 | .cindex "authentication" "ANONYMOUS" |
| 25426 | .cindex "authentication" "PLAIN" |
| 25427 | .cindex "authentication" "LOGIN" |
| 25428 | .cindex "authentication" "DIGEST-MD5" |
| 25429 | .cindex "authentication" "CRAM-MD5" |
| 25430 | .cindex "authentication" "SCRAM-SHA-1" |
| 25431 | The &(gsasl)& authenticator provides server integration for the GNU SASL |
| 25432 | library and the mechanisms it provides. This is new as of the 4.80 release |
| 25433 | and there are a few areas where the library does not let Exim smoothly |
| 25434 | scale to handle future authentication mechanisms, so no guarantee can be |
| 25435 | made that any particular new authentication mechanism will be supported |
| 25436 | without code changes in Exim. |
| 25437 | |
| 25438 | |
| 25439 | .option server_channelbinding gsasl boolean false |
| 25440 | Some authentication mechanisms are able to use external context at both ends |
| 25441 | of the session to bind the authentication to that context, and fail the |
| 25442 | authentication process if that context differs. Specifically, some TLS |
| 25443 | ciphersuites can provide identifying information about the cryptographic |
| 25444 | context. |
| 25445 | |
| 25446 | This means that certificate identity and verification becomes a non-issue, |
| 25447 | as a man-in-the-middle attack will cause the correct client and server to |
| 25448 | see different identifiers and authentication will fail. |
| 25449 | |
| 25450 | This is currently only supported when using the GnuTLS library. This is |
| 25451 | only usable by mechanisms which support "channel binding"; at time of |
| 25452 | writing, that's the SCRAM family. |
| 25453 | |
| 25454 | This defaults off to ensure smooth upgrade across Exim releases, in case |
| 25455 | this option causes some clients to start failing. Some future release |
| 25456 | of Exim may switch the default to be true. |
| 25457 | |
| 25458 | |
| 25459 | .option server_hostname gsasl string&!! "see below" |
| 25460 | This option selects the hostname that is used when communicating with the |
| 25461 | library. The default value is &`$primary_hostname`&. |
| 25462 | Some mechanisms will use this data. |
| 25463 | |
| 25464 | |
| 25465 | .option server_mech gsasl string "see below" |
| 25466 | This option selects the authentication mechanism this driver should use. The |
| 25467 | default is the value of the generic &%public_name%& option. This option allows |
| 25468 | you to use a different underlying mechanism from the advertised name. For |
| 25469 | example: |
| 25470 | .code |
| 25471 | sasl: |
| 25472 | driver = gsasl |
| 25473 | public_name = X-ANYTHING |
| 25474 | server_mech = CRAM-MD5 |
| 25475 | server_set_id = $auth1 |
| 25476 | .endd |
| 25477 | |
| 25478 | |
| 25479 | .option server_password gsasl string&!! unset |
| 25480 | Various mechanisms need access to the cleartext password on the server, so |
| 25481 | that proof-of-possession can be demonstrated on the wire, without sending |
| 25482 | the password itself. |
| 25483 | |
| 25484 | The data available for lookup varies per mechanism. |
| 25485 | In all cases, &$auth1$& is set to the &'authentication id'&. |
| 25486 | The &$auth2$& variable will always be the &'authorization id'& (&'authz'&) |
| 25487 | if available, else the empty string. |
| 25488 | The &$auth3$& variable will always be the &'realm'& if available, |
| 25489 | else the empty string. |
| 25490 | |
| 25491 | A forced failure will cause authentication to defer. |
| 25492 | |
| 25493 | If using this option, it may make sense to set the &%server_condition%& |
| 25494 | option to be simply "true". |
| 25495 | |
| 25496 | |
| 25497 | .option server_realm gsasl string&!! unset |
| 25498 | This specifies the SASL realm that the server claims to be in. |
| 25499 | Some mechanisms will use this data. |
| 25500 | |
| 25501 | |
| 25502 | .option server_scram_iter gsasl string&!! unset |
| 25503 | This option provides data for the SCRAM family of mechanisms. |
| 25504 | &$auth1$& is not available at evaluation time. |
| 25505 | (This may change, as we receive feedback on use) |
| 25506 | |
| 25507 | |
| 25508 | .option server_scram_salt gsasl string&!! unset |
| 25509 | This option provides data for the SCRAM family of mechanisms. |
| 25510 | &$auth1$& is not available at evaluation time. |
| 25511 | (This may change, as we receive feedback on use) |
| 25512 | |
| 25513 | |
| 25514 | .option server_service gsasl string &`smtp`& |
| 25515 | This is the SASL service that the server claims to implement. |
| 25516 | Some mechanisms will use this data. |
| 25517 | |
| 25518 | |
| 25519 | .section "&(gsasl)& auth variables" "SECTgsaslauthvar" |
| 25520 | .vindex "&$auth1$&, &$auth2$&, etc" |
| 25521 | These may be set when evaluating specific options, as detailed above. |
| 25522 | They will also be set when evaluating &%server_condition%&. |
| 25523 | |
| 25524 | Unless otherwise stated below, the &(gsasl)& integration will use the following |
| 25525 | meanings for these variables: |
| 25526 | |
| 25527 | .ilist |
| 25528 | .vindex "&$auth1$&" |
| 25529 | &$auth1$&: the &'authentication id'& |
| 25530 | .next |
| 25531 | .vindex "&$auth2$&" |
| 25532 | &$auth2$&: the &'authorization id'& |
| 25533 | .next |
| 25534 | .vindex "&$auth3$&" |
| 25535 | &$auth3$&: the &'realm'& |
| 25536 | .endlist |
| 25537 | |
| 25538 | On a per-mechanism basis: |
| 25539 | |
| 25540 | .ilist |
| 25541 | .cindex "authentication" "EXTERNAL" |
| 25542 | EXTERNAL: only &$auth1$& is set, to the possibly empty &'authorization id'&; |
| 25543 | the &%server_condition%& option must be present. |
| 25544 | .next |
| 25545 | .cindex "authentication" "ANONYMOUS" |
| 25546 | ANONYMOUS: only &$auth1$& is set, to the possibly empty &'anonymous token'&; |
| 25547 | the &%server_condition%& option must be present. |
| 25548 | .next |
| 25549 | .cindex "authentication" "GSSAPI" |
| 25550 | GSSAPI: &$auth1$& will be set to the &'GSSAPI Display Name'&; |
| 25551 | &$auth2$& will be set to the &'authorization id'&, |
| 25552 | the &%server_condition%& option must be present. |
| 25553 | .endlist |
| 25554 | |
| 25555 | An &'anonymous token'& is something passed along as an unauthenticated |
| 25556 | identifier; this is analogous to FTP anonymous authentication passing an |
| 25557 | email address, or software-identifier@, as the "password". |
| 25558 | |
| 25559 | |
| 25560 | An example showing the password having the realm specified in the callback |
| 25561 | and demonstrating a Cyrus SASL to GSASL migration approach is: |
| 25562 | .code |
| 25563 | gsasl_cyrusless_crammd5: |
| 25564 | driver = gsasl |
| 25565 | public_name = CRAM-MD5 |
| 25566 | server_realm = imap.example.org |
| 25567 | server_password = ${lookup{$auth1:$auth3:userPassword}\ |
| 25568 | dbmjz{/etc/sasldb2}{$value}fail} |
| 25569 | server_set_id = ${quote:$auth1} |
| 25570 | server_condition = yes |
| 25571 | .endd |
| 25572 | |
| 25573 | |
| 25574 | . //////////////////////////////////////////////////////////////////////////// |
| 25575 | . //////////////////////////////////////////////////////////////////////////// |
| 25576 | |
| 25577 | .chapter "The heimdal_gssapi authenticator" "CHAPheimdalgss" |
| 25578 | .scindex IIDheimdalgssauth1 "&(heimdal_gssapi)& authenticator" |
| 25579 | .scindex IIDheimdalgssauth2 "authenticators" "&(heimdal_gssapi)&" |
| 25580 | .cindex "authentication" "GSSAPI" |
| 25581 | .cindex "authentication" "Kerberos" |
| 25582 | The &(heimdal_gssapi)& authenticator provides server integration for the |
| 25583 | Heimdal GSSAPI/Kerberos library, permitting Exim to set a keytab pathname |
| 25584 | reliably. |
| 25585 | |
| 25586 | .option server_hostname heimdal_gssapi string&!! "see below" |
| 25587 | This option selects the hostname that is used, with &%server_service%&, |
| 25588 | for constructing the GSS server name, as a &'GSS_C_NT_HOSTBASED_SERVICE'& |
| 25589 | identifier. The default value is &`$primary_hostname`&. |
| 25590 | |
| 25591 | .option server_keytab heimdal_gssapi string&!! unset |
| 25592 | If set, then Heimdal will not use the system default keytab (typically |
| 25593 | &_/etc/krb5.keytab_&) but instead the pathname given in this option. |
| 25594 | The value should be a pathname, with no &"file:"& prefix. |
| 25595 | |
| 25596 | .option server_service heimdal_gssapi string&!! "smtp" |
| 25597 | This option specifies the service identifier used, in conjunction with |
| 25598 | &%server_hostname%&, for building the identifer for finding credentials |
| 25599 | from the keytab. |
| 25600 | |
| 25601 | |
| 25602 | .section "&(heimdal_gssapi)& auth variables" "SECTheimdalgssauthvar" |
| 25603 | Beware that these variables will typically include a realm, thus will appear |
| 25604 | to be roughly like an email address already. The &'authzid'& in &$auth2$& is |
| 25605 | not verified, so a malicious client can set it to anything. |
| 25606 | |
| 25607 | The &$auth1$& field should be safely trustable as a value from the Key |
| 25608 | Distribution Center. Note that these are not quite email addresses. |
| 25609 | Each identifier is for a role, and so the left-hand-side may include a |
| 25610 | role suffix. For instance, &"joe/admin@EXAMPLE.ORG"&. |
| 25611 | |
| 25612 | .vindex "&$auth1$&, &$auth2$&, etc" |
| 25613 | .ilist |
| 25614 | .vindex "&$auth1$&" |
| 25615 | &$auth1$&: the &'authentication id'&, set to the GSS Display Name. |
| 25616 | .next |
| 25617 | .vindex "&$auth2$&" |
| 25618 | &$auth2$&: the &'authorization id'&, sent within SASL encapsulation after |
| 25619 | authentication. If that was empty, this will also be set to the |
| 25620 | GSS Display Name. |
| 25621 | .endlist |
| 25622 | |
| 25623 | |
| 25624 | . //////////////////////////////////////////////////////////////////////////// |
| 25625 | . //////////////////////////////////////////////////////////////////////////// |
| 25626 | |
| 25627 | .chapter "The spa authenticator" "CHAPspa" |
| 25628 | .scindex IIDspaauth1 "&(spa)& authenticator" |
| 25629 | .scindex IIDspaauth2 "authenticators" "&(spa)&" |
| 25630 | .cindex "authentication" "Microsoft Secure Password" |
| 25631 | .cindex "authentication" "NTLM" |
| 25632 | .cindex "Microsoft Secure Password Authentication" |
| 25633 | .cindex "NTLM authentication" |
| 25634 | The &(spa)& authenticator provides client support for Microsoft's &'Secure |
| 25635 | Password Authentication'& mechanism, |
| 25636 | which is also sometimes known as NTLM (NT LanMan). The code for client side of |
| 25637 | this authenticator was contributed by Marc Prud'hommeaux, and much of it is |
| 25638 | taken from the Samba project (&url(http://www.samba.org)). The code for the |
| 25639 | server side was subsequently contributed by Tom Kistner. The mechanism works as |
| 25640 | follows: |
| 25641 | |
| 25642 | .ilist |
| 25643 | After the AUTH command has been accepted, the client sends an SPA |
| 25644 | authentication request based on the user name and optional domain. |
| 25645 | .next |
| 25646 | The server sends back a challenge. |
| 25647 | .next |
| 25648 | The client builds a challenge response which makes use of the user's password |
| 25649 | and sends it to the server, which then accepts or rejects it. |
| 25650 | .endlist |
| 25651 | |
| 25652 | Encryption is used to protect the password in transit. |
| 25653 | |
| 25654 | |
| 25655 | |
| 25656 | .section "Using spa as a server" "SECID179" |
| 25657 | .cindex "options" "&(spa)& authenticator (server)" |
| 25658 | The &(spa)& authenticator has just one server option: |
| 25659 | |
| 25660 | .option server_password spa string&!! unset |
| 25661 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &(spa)& authenticator" |
| 25662 | This option is expanded, and the result must be the cleartext password for the |
| 25663 | authenticating user, whose name is at this point in &$auth1$&. For |
| 25664 | compatibility with previous releases of Exim, the user name is also placed in |
| 25665 | &$1$&. However, the use of this variable for this purpose is now deprecated, as |
| 25666 | it can lead to confusion in string expansions that also use numeric variables |
| 25667 | for other things. For example: |
| 25668 | .code |
| 25669 | spa: |
| 25670 | driver = spa |
| 25671 | public_name = NTLM |
| 25672 | server_password = \ |
| 25673 | ${lookup{$auth1}lsearch{/etc/exim/spa_clearpass}{$value}fail} |
| 25674 | .endd |
| 25675 | If the expansion is forced to fail, authentication fails. Any other expansion |
| 25676 | failure causes a temporary error code to be returned. |
| 25677 | |
| 25678 | |
| 25679 | |
| 25680 | |
| 25681 | |
| 25682 | .section "Using spa as a client" "SECID180" |
| 25683 | .cindex "options" "&(spa)& authenticator (client)" |
| 25684 | The &(spa)& authenticator has the following client options: |
| 25685 | |
| 25686 | |
| 25687 | |
| 25688 | .option client_domain spa string&!! unset |
| 25689 | This option specifies an optional domain for the authentication. |
| 25690 | |
| 25691 | |
| 25692 | .option client_password spa string&!! unset |
| 25693 | This option specifies the user's password, and must be set. |
| 25694 | |
| 25695 | |
| 25696 | .option client_username spa string&!! unset |
| 25697 | This option specifies the user name, and must be set. Here is an example of a |
| 25698 | configuration of this authenticator for use with the mail servers at |
| 25699 | &'msn.com'&: |
| 25700 | .code |
| 25701 | msn: |
| 25702 | driver = spa |
| 25703 | public_name = MSN |
| 25704 | client_username = msn/msn_username |
| 25705 | client_password = msn_plaintext_password |
| 25706 | client_domain = DOMAIN_OR_UNSET |
| 25707 | .endd |
| 25708 | .ecindex IIDspaauth1 |
| 25709 | .ecindex IIDspaauth2 |
| 25710 | |
| 25711 | |
| 25712 | |
| 25713 | |
| 25714 | |
| 25715 | . //////////////////////////////////////////////////////////////////////////// |
| 25716 | . //////////////////////////////////////////////////////////////////////////// |
| 25717 | |
| 25718 | .chapter "Encrypted SMTP connections using TLS/SSL" "CHAPTLS" &&& |
| 25719 | "Encrypted SMTP connections" |
| 25720 | .scindex IIDencsmtp1 "encryption" "on SMTP connection" |
| 25721 | .scindex IIDencsmtp2 "SMTP" "encryption" |
| 25722 | .cindex "TLS" "on SMTP connection" |
| 25723 | .cindex "OpenSSL" |
| 25724 | .cindex "GnuTLS" |
| 25725 | Support for TLS (Transport Layer Security), formerly known as SSL (Secure |
| 25726 | Sockets Layer), is implemented by making use of the OpenSSL library or the |
| 25727 | GnuTLS library (Exim requires GnuTLS release 1.0 or later). There is no |
| 25728 | cryptographic code in the Exim distribution itself for implementing TLS. In |
| 25729 | order to use this feature you must install OpenSSL or GnuTLS, and then build a |
| 25730 | version of Exim that includes TLS support (see section &<<SECTinctlsssl>>&). |
| 25731 | You also need to understand the basic concepts of encryption at a managerial |
| 25732 | level, and in particular, the way that public keys, private keys, and |
| 25733 | certificates are used. |
| 25734 | |
| 25735 | RFC 3207 defines how SMTP connections can make use of encryption. Once a |
| 25736 | connection is established, the client issues a STARTTLS command. If the |
| 25737 | server accepts this, the client and the server negotiate an encryption |
| 25738 | mechanism. If the negotiation succeeds, the data that subsequently passes |
| 25739 | between them is encrypted. |
| 25740 | |
| 25741 | Exim's ACLs can detect whether the current SMTP session is encrypted or not, |
| 25742 | and if so, what cipher suite is in use, whether the client supplied a |
| 25743 | certificate, and whether or not that certificate was verified. This makes it |
| 25744 | possible for an Exim server to deny or accept certain commands based on the |
| 25745 | encryption state. |
| 25746 | |
| 25747 | &*Warning*&: Certain types of firewall and certain anti-virus products can |
| 25748 | disrupt TLS connections. You need to turn off SMTP scanning for these products |
| 25749 | in order to get TLS to work. |
| 25750 | |
| 25751 | |
| 25752 | |
| 25753 | .section "Support for the legacy &""ssmtp""& (aka &""smtps""&) protocol" &&& |
| 25754 | "SECID284" |
| 25755 | .cindex "ssmtp protocol" |
| 25756 | .cindex "smtps protocol" |
| 25757 | .cindex "SMTP" "ssmtp protocol" |
| 25758 | .cindex "SMTP" "smtps protocol" |
| 25759 | Early implementations of encrypted SMTP used a different TCP port from normal |
| 25760 | SMTP, and expected an encryption negotiation to start immediately, instead of |
| 25761 | waiting for a STARTTLS command from the client using the standard SMTP |
| 25762 | port. The protocol was called &"ssmtp"& or &"smtps"&, and port 465 was |
| 25763 | allocated for this purpose. |
| 25764 | |
| 25765 | This approach was abandoned when encrypted SMTP was standardized, but there are |
| 25766 | still some legacy clients that use it. Exim supports these clients by means of |
| 25767 | the &%tls_on_connect_ports%& global option. Its value must be a list of port |
| 25768 | numbers; the most common use is expected to be: |
| 25769 | .code |
| 25770 | tls_on_connect_ports = 465 |
| 25771 | .endd |
| 25772 | The port numbers specified by this option apply to all SMTP connections, both |
| 25773 | via the daemon and via &'inetd'&. You still need to specify all the ports that |
| 25774 | the daemon uses (by setting &%daemon_smtp_ports%& or &%local_interfaces%& or |
| 25775 | the &%-oX%& command line option) because &%tls_on_connect_ports%& does not add |
| 25776 | an extra port &-- rather, it specifies different behaviour on a port that is |
| 25777 | defined elsewhere. |
| 25778 | |
| 25779 | There is also a &%-tls-on-connect%& command line option. This overrides |
| 25780 | &%tls_on_connect_ports%&; it forces the legacy behaviour for all ports. |
| 25781 | |
| 25782 | |
| 25783 | |
| 25784 | |
| 25785 | |
| 25786 | |
| 25787 | .section "OpenSSL vs GnuTLS" "SECTopenvsgnu" |
| 25788 | .cindex "TLS" "OpenSSL &'vs'& GnuTLS" |
| 25789 | The first TLS support in Exim was implemented using OpenSSL. Support for GnuTLS |
| 25790 | followed later, when the first versions of GnuTLS were released. To build Exim |
| 25791 | to use GnuTLS, you need to set |
| 25792 | .code |
| 25793 | USE_GNUTLS=yes |
| 25794 | .endd |
| 25795 | in Local/Makefile, in addition to |
| 25796 | .code |
| 25797 | SUPPORT_TLS=yes |
| 25798 | .endd |
| 25799 | You must also set TLS_LIBS and TLS_INCLUDE appropriately, so that the |
| 25800 | include files and libraries for GnuTLS can be found. |
| 25801 | |
| 25802 | There are some differences in usage when using GnuTLS instead of OpenSSL: |
| 25803 | |
| 25804 | .ilist |
| 25805 | The &%tls_verify_certificates%& option must contain the name of a file, not the |
| 25806 | name of a directory (for OpenSSL it can be either). |
| 25807 | .next |
| 25808 | The default value for &%tls_dhparam%& differs for historical reasons. |
| 25809 | .next |
| 25810 | .vindex "&$tls_in_peerdn$&" |
| 25811 | .vindex "&$tls_out_peerdn$&" |
| 25812 | Distinguished Name (DN) strings reported by the OpenSSL library use a slash for |
| 25813 | separating fields; GnuTLS uses commas, in accordance with RFC 2253. This |
| 25814 | affects the value of the &$tls_in_peerdn$& and &$tls_out_peerdn$& variables. |
| 25815 | .next |
| 25816 | OpenSSL identifies cipher suites using hyphens as separators, for example: |
| 25817 | DES-CBC3-SHA. GnuTLS historically used underscores, for example: |
| 25818 | RSA_ARCFOUR_SHA. What is more, OpenSSL complains if underscores are present |
| 25819 | in a cipher list. To make life simpler, Exim changes underscores to hyphens |
| 25820 | for OpenSSL and passes the string unchanged to GnuTLS (expecting the library |
| 25821 | to handle its own older variants) when processing lists of cipher suites in the |
| 25822 | &%tls_require_ciphers%& options (the global option and the &(smtp)& transport |
| 25823 | option). |
| 25824 | .next |
| 25825 | The &%tls_require_ciphers%& options operate differently, as described in the |
| 25826 | sections &<<SECTreqciphssl>>& and &<<SECTreqciphgnu>>&. |
| 25827 | .next |
| 25828 | The &%tls_dh_min_bits%& SMTP transport option is only honoured by GnuTLS. |
| 25829 | When using OpenSSL, this option is ignored. |
| 25830 | (If an API is found to let OpenSSL be configured in this way, |
| 25831 | let the Exim Maintainers know and we'll likely use it). |
| 25832 | .next |
| 25833 | Some other recently added features may only be available in one or the other. |
| 25834 | This should be documented with the feature. If the documentation does not |
| 25835 | explicitly state that the feature is infeasible in the other TLS |
| 25836 | implementation, then patches are welcome. |
| 25837 | .endlist |
| 25838 | |
| 25839 | |
| 25840 | .section "GnuTLS parameter computation" "SECTgnutlsparam" |
| 25841 | This section only applies if &%tls_dhparam%& is set to &`historic`& or to |
| 25842 | an explicit path; if the latter, then the text about generation still applies, |
| 25843 | but not the chosen filename. |
| 25844 | By default, as of Exim 4.80 a hard-coded D-H prime is used. |
| 25845 | See the documentation of &%tls_dhparam%& for more information. |
| 25846 | |
| 25847 | GnuTLS uses D-H parameters that may take a substantial amount of time |
| 25848 | to compute. It is unreasonable to re-compute them for every TLS session. |
| 25849 | Therefore, Exim keeps this data in a file in its spool directory, called |
| 25850 | &_gnutls-params-NNNN_& for some value of NNNN, corresponding to the number |
| 25851 | of bits requested. |
| 25852 | The file is owned by the Exim user and is readable only by |
| 25853 | its owner. Every Exim process that start up GnuTLS reads the D-H |
| 25854 | parameters from this file. If the file does not exist, the first Exim process |
| 25855 | that needs it computes the data and writes it to a temporary file which is |
| 25856 | renamed once it is complete. It does not matter if several Exim processes do |
| 25857 | this simultaneously (apart from wasting a few resources). Once a file is in |
| 25858 | place, new Exim processes immediately start using it. |
| 25859 | |
| 25860 | For maximum security, the parameters that are stored in this file should be |
| 25861 | recalculated periodically, the frequency depending on your paranoia level. |
| 25862 | If you are avoiding using the fixed D-H primes published in RFCs, then you |
| 25863 | are concerned about some advanced attacks and will wish to do this; if you do |
| 25864 | not regenerate then you might as well stick to the standard primes. |
| 25865 | |
| 25866 | Arranging this is easy in principle; just delete the file when you want new |
| 25867 | values to be computed. However, there may be a problem. The calculation of new |
| 25868 | parameters needs random numbers, and these are obtained from &_/dev/random_&. |
| 25869 | If the system is not very active, &_/dev/random_& may delay returning data |
| 25870 | until enough randomness (entropy) is available. This may cause Exim to hang for |
| 25871 | a substantial amount of time, causing timeouts on incoming connections. |
| 25872 | |
| 25873 | The solution is to generate the parameters externally to Exim. They are stored |
| 25874 | in &_gnutls-params-N_& in PEM format, which means that they can be |
| 25875 | generated externally using the &(certtool)& command that is part of GnuTLS. |
| 25876 | |
| 25877 | To replace the parameters with new ones, instead of deleting the file |
| 25878 | and letting Exim re-create it, you can generate new parameters using |
| 25879 | &(certtool)& and, when this has been done, replace Exim's cache file by |
| 25880 | renaming. The relevant commands are something like this: |
| 25881 | .code |
| 25882 | # ls |
| 25883 | [ look for file; assume gnutls-params-2236 is the most recent ] |
| 25884 | # rm -f new-params |
| 25885 | # touch new-params |
| 25886 | # chown exim:exim new-params |
| 25887 | # chmod 0600 new-params |
| 25888 | # certtool --generate-dh-params --bits 2236 >>new-params |
| 25889 | # openssl dhparam -noout -text -in new-params | head |
| 25890 | [ check the first line, make sure it's not more than 2236; |
| 25891 | if it is, then go back to the start ("rm") and repeat |
| 25892 | until the size generated is at most the size requested ] |
| 25893 | # chmod 0400 new-params |
| 25894 | # mv new-params gnutls-params-2236 |
| 25895 | .endd |
| 25896 | If Exim never has to generate the parameters itself, the possibility of |
| 25897 | stalling is removed. |
| 25898 | |
| 25899 | The filename changed in Exim 4.80, to gain the -bits suffix. The value which |
| 25900 | Exim will choose depends upon the version of GnuTLS in use. For older GnuTLS, |
| 25901 | the value remains hard-coded in Exim as 1024. As of GnuTLS 2.12.x, there is |
| 25902 | a way for Exim to ask for the "normal" number of bits for D-H public-key usage, |
| 25903 | and Exim does so. This attempt to remove Exim from TLS policy decisions |
| 25904 | failed, as GnuTLS 2.12 returns a value higher than the current hard-coded limit |
| 25905 | of the NSS library. Thus Exim gains the &%tls_dh_max_bits%& global option, |
| 25906 | which applies to all D-H usage, client or server. If the value returned by |
| 25907 | GnuTLS is greater than &%tls_dh_max_bits%& then the value will be clamped down |
| 25908 | to &%tls_dh_max_bits%&. The default value has been set at the current NSS |
| 25909 | limit, which is still much higher than Exim historically used. |
| 25910 | |
| 25911 | The filename and bits used will change as the GnuTLS maintainers change the |
| 25912 | value for their parameter &`GNUTLS_SEC_PARAM_NORMAL`&, as clamped by |
| 25913 | &%tls_dh_max_bits%&. At the time of writing (mid 2012), GnuTLS 2.12 recommends |
| 25914 | 2432 bits, while NSS is limited to 2236 bits. |
| 25915 | |
| 25916 | In fact, the requested value will be *lower* than &%tls_dh_max_bits%&, to |
| 25917 | increase the chance of the generated prime actually being within acceptable |
| 25918 | bounds, as GnuTLS has been observed to overshoot. Note the check step in the |
| 25919 | procedure above. There is no sane procedure available to Exim to double-check |
| 25920 | the size of the generated prime, so it might still be too large. |
| 25921 | |
| 25922 | |
| 25923 | .section "Requiring specific ciphers in OpenSSL" "SECTreqciphssl" |
| 25924 | .cindex "TLS" "requiring specific ciphers (OpenSSL)" |
| 25925 | .oindex "&%tls_require_ciphers%&" "OpenSSL" |
| 25926 | There is a function in the OpenSSL library that can be passed a list of cipher |
| 25927 | suites before the cipher negotiation takes place. This specifies which ciphers |
| 25928 | are acceptable. The list is colon separated and may contain names like |
| 25929 | DES-CBC3-SHA. Exim passes the expanded value of &%tls_require_ciphers%& |
| 25930 | directly to this function call. |
| 25931 | Many systems will install the OpenSSL manual-pages, so you may have |
| 25932 | &'ciphers(1)'& available to you. |
| 25933 | The following quotation from the OpenSSL |
| 25934 | documentation specifies what forms of item are allowed in the cipher string: |
| 25935 | |
| 25936 | .ilist |
| 25937 | It can consist of a single cipher suite such as RC4-SHA. |
| 25938 | .next |
| 25939 | It can represent a list of cipher suites containing a certain algorithm, |
| 25940 | or cipher suites of a certain type. For example SHA1 represents all |
| 25941 | ciphers suites using the digest algorithm SHA1 and SSLv3 represents all |
| 25942 | SSL v3 algorithms. |
| 25943 | .next |
| 25944 | Lists of cipher suites can be combined in a single cipher string using |
| 25945 | the + character. This is used as a logical and operation. For example |
| 25946 | SHA1+DES represents all cipher suites containing the SHA1 and the DES |
| 25947 | algorithms. |
| 25948 | .endlist |
| 25949 | |
| 25950 | Each cipher string can be optionally preceded by one of the characters &`!`&, |
| 25951 | &`-`& or &`+`&. |
| 25952 | .ilist |
| 25953 | If &`!`& is used, the ciphers are permanently deleted from the list. The |
| 25954 | ciphers deleted can never reappear in the list even if they are explicitly |
| 25955 | stated. |
| 25956 | .next |
| 25957 | If &`-`& is used, the ciphers are deleted from the list, but some or all |
| 25958 | of the ciphers can be added again by later options. |
| 25959 | .next |
| 25960 | If &`+`& is used, the ciphers are moved to the end of the list. This |
| 25961 | option does not add any new ciphers; it just moves matching existing ones. |
| 25962 | .endlist |
| 25963 | |
| 25964 | If none of these characters is present, the string is interpreted as |
| 25965 | a list of ciphers to be appended to the current preference list. If the list |
| 25966 | includes any ciphers already present they will be ignored: that is, they will |
| 25967 | not be moved to the end of the list. |
| 25968 | .endlist |
| 25969 | |
| 25970 | The OpenSSL &'ciphers(1)'& command may be used to test the results of a given |
| 25971 | string: |
| 25972 | .code |
| 25973 | # note single-quotes to get ! past any shell history expansion |
| 25974 | $ openssl ciphers 'HIGH:!MD5:!SHA1' |
| 25975 | .endd |
| 25976 | |
| 25977 | This example will let the library defaults be permitted on the MX port, where |
| 25978 | there's probably no identity verification anyway, but ups the ante on the |
| 25979 | submission ports where the administrator might have some influence on the |
| 25980 | choice of clients used: |
| 25981 | .code |
| 25982 | # OpenSSL variant; see man ciphers(1) |
| 25983 | tls_require_ciphers = ${if =={$received_port}{25}\ |
| 25984 | {DEFAULT}\ |
| 25985 | {HIGH:!MD5:!SHA1}} |
| 25986 | .endd |
| 25987 | |
| 25988 | |
| 25989 | |
| 25990 | .section "Requiring specific ciphers or other parameters in GnuTLS" &&& |
| 25991 | "SECTreqciphgnu" |
| 25992 | .cindex "GnuTLS" "specifying parameters for" |
| 25993 | .cindex "TLS" "specifying ciphers (GnuTLS)" |
| 25994 | .cindex "TLS" "specifying key exchange methods (GnuTLS)" |
| 25995 | .cindex "TLS" "specifying MAC algorithms (GnuTLS)" |
| 25996 | .cindex "TLS" "specifying protocols (GnuTLS)" |
| 25997 | .cindex "TLS" "specifying priority string (GnuTLS)" |
| 25998 | .oindex "&%tls_require_ciphers%&" "GnuTLS" |
| 25999 | The GnuTLS library allows the caller to provide a "priority string", documented |
| 26000 | as part of the &[gnutls_priority_init]& function. This is very similar to the |
| 26001 | ciphersuite specification in OpenSSL. |
| 26002 | |
| 26003 | The &%tls_require_ciphers%& option is treated as the GnuTLS priority string. |
| 26004 | |
| 26005 | The &%tls_require_ciphers%& option is available both as an global option, |
| 26006 | controlling how Exim behaves as a server, and also as an option of the |
| 26007 | &(smtp)& transport, controlling how Exim behaves as a client. In both cases |
| 26008 | the value is string expanded. The resulting string is not an Exim list and |
| 26009 | the string is given to the GnuTLS library, so that Exim does not need to be |
| 26010 | aware of future feature enhancements of GnuTLS. |
| 26011 | |
| 26012 | Documentation of the strings accepted may be found in the GnuTLS manual, under |
| 26013 | "Priority strings". This is online as |
| 26014 | &url(http://www.gnutls.org/manual/html_node/Priority-Strings.html), |
| 26015 | but beware that this relates to GnuTLS 3, which may be newer than the version |
| 26016 | installed on your system. If you are using GnuTLS 3, |
| 26017 | &url(http://www.gnutls.org/manual/gnutls.html#Listing-the-ciphersuites-in-a-priority-string, then the example code) |
| 26018 | on that site can be used to test a given string. |
| 26019 | |
| 26020 | Prior to Exim 4.80, an older API of GnuTLS was used, and Exim supported three |
| 26021 | additional options, "&%gnutls_require_kx%&", "&%gnutls_require_mac%&" and |
| 26022 | "&%gnutls_require_protocols%&". &%tls_require_ciphers%& was an Exim list. |
| 26023 | |
| 26024 | This example will let the library defaults be permitted on the MX port, where |
| 26025 | there's probably no identity verification anyway, and lowers security further |
| 26026 | by increasing compatibility; but this ups the ante on the submission ports |
| 26027 | where the administrator might have some influence on the choice of clients |
| 26028 | used: |
| 26029 | .code |
| 26030 | # GnuTLS variant |
| 26031 | tls_require_ciphers = ${if =={$received_port}{25}\ |
| 26032 | {NORMAL:%COMPAT}\ |
| 26033 | {SECURE128}} |
| 26034 | .endd |
| 26035 | |
| 26036 | |
| 26037 | .section "Configuring an Exim server to use TLS" "SECID182" |
| 26038 | .cindex "TLS" "configuring an Exim server" |
| 26039 | When Exim has been built with TLS support, it advertises the availability of |
| 26040 | the STARTTLS command to client hosts that match &%tls_advertise_hosts%&, |
| 26041 | but not to any others. The default value of this option is unset, which means |
| 26042 | that STARTTLS is not advertised at all. This default is chosen because you |
| 26043 | need to set some other options in order to make TLS available, and also it is |
| 26044 | sensible for systems that want to use TLS only as a client. |
| 26045 | |
| 26046 | If a client issues a STARTTLS command and there is some configuration |
| 26047 | problem in the server, the command is rejected with a 454 error. If the client |
| 26048 | persists in trying to issue SMTP commands, all except QUIT are rejected |
| 26049 | with the error |
| 26050 | .code |
| 26051 | 554 Security failure |
| 26052 | .endd |
| 26053 | If a STARTTLS command is issued within an existing TLS session, it is |
| 26054 | rejected with a 554 error code. |
| 26055 | |
| 26056 | To enable TLS operations on a server, you must set &%tls_advertise_hosts%& to |
| 26057 | match some hosts. You can, of course, set it to * to match all hosts. |
| 26058 | However, this is not all you need to do. TLS sessions to a server won't work |
| 26059 | without some further configuration at the server end. |
| 26060 | |
| 26061 | It is rumoured that all existing clients that support TLS/SSL use RSA |
| 26062 | encryption. To make this work you need to set, in the server, |
| 26063 | .code |
| 26064 | tls_certificate = /some/file/name |
| 26065 | tls_privatekey = /some/file/name |
| 26066 | .endd |
| 26067 | These options are, in fact, expanded strings, so you can make them depend on |
| 26068 | the identity of the client that is connected if you wish. The first file |
| 26069 | contains the server's X509 certificate, and the second contains the private key |
| 26070 | that goes with it. These files need to be readable by the Exim user, and must |
| 26071 | always be given as full path names. They can be the same file if both the |
| 26072 | certificate and the key are contained within it. If &%tls_privatekey%& is not |
| 26073 | set, or if its expansion is forced to fail or results in an empty string, this |
| 26074 | is assumed to be the case. The certificate file may also contain intermediate |
| 26075 | certificates that need to be sent to the client to enable it to authenticate |
| 26076 | the server's certificate. |
| 26077 | |
| 26078 | If you do not understand about certificates and keys, please try to find a |
| 26079 | source of this background information, which is not Exim-specific. (There are a |
| 26080 | few comments below in section &<<SECTcerandall>>&.) |
| 26081 | |
| 26082 | &*Note*&: These options do not apply when Exim is operating as a client &-- |
| 26083 | they apply only in the case of a server. If you need to use a certificate in an |
| 26084 | Exim client, you must set the options of the same names in an &(smtp)& |
| 26085 | transport. |
| 26086 | |
| 26087 | With just these options, an Exim server will be able to use TLS. It does not |
| 26088 | require the client to have a certificate (but see below for how to insist on |
| 26089 | this). There is one other option that may be needed in other situations. If |
| 26090 | .code |
| 26091 | tls_dhparam = /some/file/name |
| 26092 | .endd |
| 26093 | is set, the SSL library is initialized for the use of Diffie-Hellman ciphers |
| 26094 | with the parameters contained in the file. |
| 26095 | Set this to &`none`& to disable use of DH entirely, by making no prime |
| 26096 | available: |
| 26097 | .code |
| 26098 | tls_dhparam = none |
| 26099 | .endd |
| 26100 | This may also be set to a string identifying a standard prime to be used for |
| 26101 | DH; if it is set to &`default`& or, for OpenSSL, is unset, then the prime |
| 26102 | used is &`ike23`&. There are a few standard primes available, see the |
| 26103 | documentation for &%tls_dhparam%& for the complete list. |
| 26104 | |
| 26105 | See the command |
| 26106 | .code |
| 26107 | openssl dhparam |
| 26108 | .endd |
| 26109 | for a way of generating file data. |
| 26110 | |
| 26111 | The strings supplied for these three options are expanded every time a client |
| 26112 | host connects. It is therefore possible to use different certificates and keys |
| 26113 | for different hosts, if you so wish, by making use of the client's IP address |
| 26114 | in &$sender_host_address$& to control the expansion. If a string expansion is |
| 26115 | forced to fail, Exim behaves as if the option is not set. |
| 26116 | |
| 26117 | .cindex "cipher" "logging" |
| 26118 | .cindex "log" "TLS cipher" |
| 26119 | .vindex "&$tls_in_cipher$&" |
| 26120 | The variable &$tls_in_cipher$& is set to the cipher suite that was negotiated for |
| 26121 | an incoming TLS connection. It is included in the &'Received:'& header of an |
| 26122 | incoming message (by default &-- you can, of course, change this), and it is |
| 26123 | also included in the log line that records a message's arrival, keyed by |
| 26124 | &"X="&, unless the &%tls_cipher%& log selector is turned off. The &%encrypted%& |
| 26125 | condition can be used to test for specific cipher suites in ACLs. |
| 26126 | |
| 26127 | Once TLS has been established, the ACLs that run for subsequent SMTP commands |
| 26128 | can check the name of the cipher suite and vary their actions accordingly. The |
| 26129 | cipher suite names vary, depending on which TLS library is being used. For |
| 26130 | example, OpenSSL uses the name DES-CBC3-SHA for the cipher suite which in other |
| 26131 | contexts is known as TLS_RSA_WITH_3DES_EDE_CBC_SHA. Check the OpenSSL or GnuTLS |
| 26132 | documentation for more details. |
| 26133 | |
| 26134 | For outgoing SMTP deliveries, &$tls_out_cipher$& is used and logged |
| 26135 | (again depending on the &%tls_cipher%& log selector). |
| 26136 | |
| 26137 | |
| 26138 | .section "Requesting and verifying client certificates" "SECID183" |
| 26139 | .cindex "certificate" "verification of client" |
| 26140 | .cindex "TLS" "client certificate verification" |
| 26141 | If you want an Exim server to request a certificate when negotiating a TLS |
| 26142 | session with a client, you must set either &%tls_verify_hosts%& or |
| 26143 | &%tls_try_verify_hosts%&. You can, of course, set either of them to * to |
| 26144 | apply to all TLS connections. For any host that matches one of these options, |
| 26145 | Exim requests a certificate as part of the setup of the TLS session. The |
| 26146 | contents of the certificate are verified by comparing it with a list of |
| 26147 | expected certificates. These must be available in a file or, |
| 26148 | for OpenSSL only (not GnuTLS), a directory, identified by |
| 26149 | &%tls_verify_certificates%&. |
| 26150 | |
| 26151 | A file can contain multiple certificates, concatenated end to end. If a |
| 26152 | directory is used |
| 26153 | (OpenSSL only), |
| 26154 | each certificate must be in a separate file, with a name (or a symbolic link) |
| 26155 | of the form <&'hash'&>.0, where <&'hash'&> is a hash value constructed from the |
| 26156 | certificate. You can compute the relevant hash by running the command |
| 26157 | .code |
| 26158 | openssl x509 -hash -noout -in /cert/file |
| 26159 | .endd |
| 26160 | where &_/cert/file_& contains a single certificate. |
| 26161 | |
| 26162 | The difference between &%tls_verify_hosts%& and &%tls_try_verify_hosts%& is |
| 26163 | what happens if the client does not supply a certificate, or if the certificate |
| 26164 | does not match any of the certificates in the collection named by |
| 26165 | &%tls_verify_certificates%&. If the client matches &%tls_verify_hosts%&, the |
| 26166 | attempt to set up a TLS session is aborted, and the incoming connection is |
| 26167 | dropped. If the client matches &%tls_try_verify_hosts%&, the (encrypted) SMTP |
| 26168 | session continues. ACLs that run for subsequent SMTP commands can detect the |
| 26169 | fact that no certificate was verified, and vary their actions accordingly. For |
| 26170 | example, you can insist on a certificate before accepting a message for |
| 26171 | relaying, but not when the message is destined for local delivery. |
| 26172 | |
| 26173 | .vindex "&$tls_in_peerdn$&" |
| 26174 | When a client supplies a certificate (whether it verifies or not), the value of |
| 26175 | the Distinguished Name of the certificate is made available in the variable |
| 26176 | &$tls_in_peerdn$& during subsequent processing of the message. |
| 26177 | |
| 26178 | .cindex "log" "distinguished name" |
| 26179 | Because it is often a long text string, it is not included in the log line or |
| 26180 | &'Received:'& header by default. You can arrange for it to be logged, keyed by |
| 26181 | &"DN="&, by setting the &%tls_peerdn%& log selector, and you can use |
| 26182 | &%received_header_text%& to change the &'Received:'& header. When no |
| 26183 | certificate is supplied, &$tls_in_peerdn$& is empty. |
| 26184 | |
| 26185 | |
| 26186 | .section "Revoked certificates" "SECID184" |
| 26187 | .cindex "TLS" "revoked certificates" |
| 26188 | .cindex "revocation list" |
| 26189 | .cindex "certificate" "revocation list" |
| 26190 | .cindex "OCSP" "stapling" |
| 26191 | Certificate issuing authorities issue Certificate Revocation Lists (CRLs) when |
| 26192 | certificates are revoked. If you have such a list, you can pass it to an Exim |
| 26193 | server using the global option called &%tls_crl%& and to an Exim client using |
| 26194 | an identically named option for the &(smtp)& transport. In each case, the value |
| 26195 | of the option is expanded and must then be the name of a file that contains a |
| 26196 | CRL in PEM format. |
| 26197 | The downside is that clients have to periodically re-download a potentially huge |
| 26198 | file from every certificate authority the know of. |
| 26199 | |
| 26200 | The way with most moving parts at query time is Online Certificate |
| 26201 | Status Protocol (OCSP), where the client verifies the certificate |
| 26202 | against an OCSP server run by the CA. This lets the CA track all |
| 26203 | usage of the certs. It requires running software with access to the |
| 26204 | private key of the CA, to sign the responses to the OCSP queries. OCSP |
| 26205 | is based on HTTP and can be proxied accordingly. |
| 26206 | |
| 26207 | The only widespread OCSP server implementation (known to this writer) |
| 26208 | comes as part of OpenSSL and aborts on an invalid request, such as |
| 26209 | connecting to the port and then disconnecting. This requires |
| 26210 | re-entering the passphrase each time some random client does this. |
| 26211 | |
| 26212 | The third way is OCSP Stapling; in this, the server using a certificate |
| 26213 | issued by the CA periodically requests an OCSP proof of validity from |
| 26214 | the OCSP server, then serves it up inline as part of the TLS |
| 26215 | negotiation. This approach adds no extra round trips, does not let the |
| 26216 | CA track users, scales well with number of certs issued by the CA and is |
| 26217 | resilient to temporary OCSP server failures, as long as the server |
| 26218 | starts retrying to fetch an OCSP proof some time before its current |
| 26219 | proof expires. The downside is that it requires server support. |
| 26220 | |
| 26221 | Unless Exim is built with the support disabled, |
| 26222 | or with GnuTLS earlier than version 3.1.3, |
| 26223 | support for OCSP stapling is included. |
| 26224 | |
| 26225 | There is a global option called &%tls_ocsp_file%&. |
| 26226 | The file specified therein is expected to be in DER format, and contain |
| 26227 | an OCSP proof. Exim will serve it as part of the TLS handshake. This |
| 26228 | option will be re-expanded for SNI, if the &%tls_certificate%& option |
| 26229 | contains &`tls_in_sni`&, as per other TLS options. |
| 26230 | |
| 26231 | Exim does not at this time implement any support for fetching a new OCSP |
| 26232 | proof. The burden is on the administrator to handle this, outside of |
| 26233 | Exim. The file specified should be replaced atomically, so that the |
| 26234 | contents are always valid. Exim will expand the &%tls_ocsp_file%& option |
| 26235 | on each connection, so a new file will be handled transparently on the |
| 26236 | next connection. |
| 26237 | |
| 26238 | When built with OpenSSL Exim will check for a valid next update timestamp |
| 26239 | in the OCSP proof; if not present, or if the proof has expired, it will be |
| 26240 | ignored. |
| 26241 | |
| 26242 | For the client to be able to verify the stapled OCSP the server must |
| 26243 | also supply, in its stapled information, any intermediate |
| 26244 | certificates for the chain leading to the OCSP proof from the signer |
| 26245 | of the server certificate. There may be zero or one such. These |
| 26246 | intermediate certificates should be added to the server OCSP stapling |
| 26247 | file named by &%tls_ocsp_file%&. |
| 26248 | |
| 26249 | Note that the proof only covers the terminal server certificate, |
| 26250 | not any of the chain from CA to it. |
| 26251 | |
| 26252 | .code |
| 26253 | A helper script "ocsp_fetch.pl" for fetching a proof from a CA |
| 26254 | OCSP server is supplied. The server URL may be included in the |
| 26255 | server certificate, if the CA is helpful. |
| 26256 | |
| 26257 | One failure mode seen was the OCSP Signer cert expiring before the end |
| 26258 | of validity of the OCSP proof. The checking done by Exim/OpenSSL |
| 26259 | noted this as invalid overall, but the re-fetch script did not. |
| 26260 | .endd |
| 26261 | |
| 26262 | |
| 26263 | |
| 26264 | |
| 26265 | .section "Configuring an Exim client to use TLS" "SECID185" |
| 26266 | .cindex "cipher" "logging" |
| 26267 | .cindex "log" "TLS cipher" |
| 26268 | .cindex "log" "distinguished name" |
| 26269 | .cindex "TLS" "configuring an Exim client" |
| 26270 | The &%tls_cipher%& and &%tls_peerdn%& log selectors apply to outgoing SMTP |
| 26271 | deliveries as well as to incoming, the latter one causing logging of the |
| 26272 | server certificate's DN. The remaining client configuration for TLS is all |
| 26273 | within the &(smtp)& transport. |
| 26274 | |
| 26275 | It is not necessary to set any options to have TLS work in the &(smtp)& |
| 26276 | transport. If Exim is built with TLS support, and TLS is advertised by a |
| 26277 | server, the &(smtp)& transport always tries to start a TLS session. However, |
| 26278 | this can be prevented by setting &%hosts_avoid_tls%& (an option of the |
| 26279 | transport) to a list of server hosts for which TLS should not be used. |
| 26280 | |
| 26281 | If you do not want Exim to attempt to send messages unencrypted when an attempt |
| 26282 | to set up an encrypted connection fails in any way, you can set |
| 26283 | &%hosts_require_tls%& to a list of hosts for which encryption is mandatory. For |
| 26284 | those hosts, delivery is always deferred if an encrypted connection cannot be |
| 26285 | set up. If there are any other hosts for the address, they are tried in the |
| 26286 | usual way. |
| 26287 | |
| 26288 | When the server host is not in &%hosts_require_tls%&, Exim may try to deliver |
| 26289 | the message unencrypted. It always does this if the response to STARTTLS is |
| 26290 | a 5&'xx'& code. For a temporary error code, or for a failure to negotiate a TLS |
| 26291 | session after a success response code, what happens is controlled by the |
| 26292 | &%tls_tempfail_tryclear%& option of the &(smtp)& transport. If it is false, |
| 26293 | delivery to this host is deferred, and other hosts (if available) are tried. If |
| 26294 | it is true, Exim attempts to deliver unencrypted after a 4&'xx'& response to |
| 26295 | STARTTLS, and if STARTTLS is accepted, but the subsequent TLS |
| 26296 | negotiation fails, Exim closes the current connection (because it is in an |
| 26297 | unknown state), opens a new one to the same host, and then tries the delivery |
| 26298 | unencrypted. |
| 26299 | |
| 26300 | The &%tls_certificate%& and &%tls_privatekey%& options of the &(smtp)& |
| 26301 | transport provide the client with a certificate, which is passed to the server |
| 26302 | if it requests it. If the server is Exim, it will request a certificate only if |
| 26303 | &%tls_verify_hosts%& or &%tls_try_verify_hosts%& matches the client. |
| 26304 | |
| 26305 | If the &%tls_verify_certificates%& option is set on the &(smtp)& transport, it |
| 26306 | must name a file or, |
| 26307 | for OpenSSL only (not GnuTLS), a directory, that contains a collection of |
| 26308 | expected server certificates. The client verifies the server's certificate |
| 26309 | against this collection, taking into account any revoked certificates that are |
| 26310 | in the list defined by &%tls_crl%&. |
| 26311 | Failure to verify fails the TLS connection unless either of the |
| 26312 | &%tls_verify_hosts%& or &%tls_try_verify_hosts%& options are set. |
| 26313 | |
| 26314 | The &%tls_verify_hosts%& and &%tls_try_verify_hosts%& options restrict |
| 26315 | certificate verification to the listed servers. Verification either must |
| 26316 | or need not succeed respectively. |
| 26317 | |
| 26318 | The &(smtp)& transport has two OCSP-related options: |
| 26319 | &%hosts_require_ocsp%&; a host-list for which a Certificate Status |
| 26320 | is requested and required for the connection to proceed. The default |
| 26321 | value is empty. |
| 26322 | &%hosts_request_ocsp%&; a host-list for which (additionally) |
| 26323 | a Certificate Status is requested (but not necessarily verified). The default |
| 26324 | value is "*" meaning that requests are made unless configured |
| 26325 | otherwise. |
| 26326 | |
| 26327 | The host(s) should also be in &%hosts_require_tls%&, and |
| 26328 | &%tls_verify_certificates%& configured for the transport, |
| 26329 | for OCSP to be relevant. |
| 26330 | |
| 26331 | If |
| 26332 | &%tls_require_ciphers%& is set on the &(smtp)& transport, it must contain a |
| 26333 | list of permitted cipher suites. If either of these checks fails, delivery to |
| 26334 | the current host is abandoned, and the &(smtp)& transport tries to deliver to |
| 26335 | alternative hosts, if any. |
| 26336 | |
| 26337 | &*Note*&: |
| 26338 | These options must be set in the &(smtp)& transport for Exim to use TLS when it |
| 26339 | is operating as a client. Exim does not assume that a server certificate (set |
| 26340 | by the global options of the same name) should also be used when operating as a |
| 26341 | client. |
| 26342 | |
| 26343 | .vindex "&$host$&" |
| 26344 | .vindex "&$host_address$&" |
| 26345 | All the TLS options in the &(smtp)& transport are expanded before use, with |
| 26346 | &$host$& and &$host_address$& containing the name and address of the server to |
| 26347 | which the client is connected. Forced failure of an expansion causes Exim to |
| 26348 | behave as if the relevant option were unset. |
| 26349 | |
| 26350 | .vindex &$tls_out_bits$& |
| 26351 | .vindex &$tls_out_cipher$& |
| 26352 | .vindex &$tls_out_peerdn$& |
| 26353 | .vindex &$tls_out_sni$& |
| 26354 | Before an SMTP connection is established, the |
| 26355 | &$tls_out_bits$&, &$tls_out_cipher$&, &$tls_out_peerdn$& and &$tls_out_sni$& |
| 26356 | variables are emptied. (Until the first connection, they contain the values |
| 26357 | that were set when the message was received.) If STARTTLS is subsequently |
| 26358 | successfully obeyed, these variables are set to the relevant values for the |
| 26359 | outgoing connection. |
| 26360 | |
| 26361 | |
| 26362 | |
| 26363 | .section "Use of TLS Server Name Indication" "SECTtlssni" |
| 26364 | .cindex "TLS" "Server Name Indication" |
| 26365 | .vindex "&$tls_in_sni$&" |
| 26366 | .oindex "&%tls_in_sni%&" |
| 26367 | With TLS1.0 or above, there is an extension mechanism by which extra |
| 26368 | information can be included at various points in the protocol. One of these |
| 26369 | extensions, documented in RFC 6066 (and before that RFC 4366) is |
| 26370 | &"Server Name Indication"&, commonly &"SNI"&. This extension is sent by the |
| 26371 | client in the initial handshake, so that the server can examine the servername |
| 26372 | within and possibly choose to use different certificates and keys (and more) |
| 26373 | for this session. |
| 26374 | |
| 26375 | This is analagous to HTTP's &"Host:"& header, and is the main mechanism by |
| 26376 | which HTTPS-enabled web-sites can be virtual-hosted, many sites to one IP |
| 26377 | address. |
| 26378 | |
| 26379 | With SMTP to MX, there are the same problems here as in choosing the identity |
| 26380 | against which to validate a certificate: you can't rely on insecure DNS to |
| 26381 | provide the identity which you then cryptographically verify. So this will |
| 26382 | be of limited use in that environment. |
| 26383 | |
| 26384 | With SMTP to Submission, there is a well-defined hostname which clients are |
| 26385 | connecting to and can validate certificates against. Thus clients &*can*& |
| 26386 | choose to include this information in the TLS negotiation. If this becomes |
| 26387 | wide-spread, then hosters can choose to present different certificates to |
| 26388 | different clients. Or even negotiate different cipher suites. |
| 26389 | |
| 26390 | The &%tls_sni%& option on an SMTP transport is an expanded string; the result, |
| 26391 | if not empty, will be sent on a TLS session as part of the handshake. There's |
| 26392 | nothing more to it. Choosing a sensible value not derived insecurely is the |
| 26393 | only point of caution. The &$tls_out_sni$& variable will be set to this string |
| 26394 | for the lifetime of the client connection (including during authentication). |
| 26395 | |
| 26396 | Except during SMTP client sessions, if &$tls_in_sni$& is set then it is a string |
| 26397 | received from a client. |
| 26398 | It can be logged with the &%log_selector%& item &`+tls_sni`&. |
| 26399 | |
| 26400 | If the string &`tls_in_sni`& appears in the main section's &%tls_certificate%& |
| 26401 | option (prior to expansion) then the following options will be re-expanded |
| 26402 | during TLS session handshake, to permit alternative values to be chosen: |
| 26403 | |
| 26404 | .ilist |
| 26405 | .vindex "&%tls_certificate%&" |
| 26406 | &%tls_certificate%& |
| 26407 | .next |
| 26408 | .vindex "&%tls_crl%&" |
| 26409 | &%tls_crl%& |
| 26410 | .next |
| 26411 | .vindex "&%tls_privatekey%&" |
| 26412 | &%tls_privatekey%& |
| 26413 | .next |
| 26414 | .vindex "&%tls_verify_certificates%&" |
| 26415 | &%tls_verify_certificates%& |
| 26416 | .next |
| 26417 | .vindex "&%tls_ocsp_file%&" |
| 26418 | &%tls_verify_certificates%& |
| 26419 | .endlist |
| 26420 | |
| 26421 | Great care should be taken to deal with matters of case, various injection |
| 26422 | attacks in the string (&`../`& or SQL), and ensuring that a valid filename |
| 26423 | can always be referenced; it is important to remember that &$tls_sni$& is |
| 26424 | arbitrary unverified data provided prior to authentication. |
| 26425 | |
| 26426 | The Exim developers are proceeding cautiously and so far no other TLS options |
| 26427 | are re-expanded. |
| 26428 | |
| 26429 | When Exim is built againt OpenSSL, OpenSSL must have been built with support |
| 26430 | for TLS Extensions. This holds true for OpenSSL 1.0.0+ and 0.9.8+ with |
| 26431 | enable-tlsext in EXTRACONFIGURE. If you invoke &(openssl s_client -h)& and |
| 26432 | see &`-servername`& in the output, then OpenSSL has support. |
| 26433 | |
| 26434 | When Exim is built against GnuTLS, SNI support is available as of GnuTLS |
| 26435 | 0.5.10. (Its presence predates the current API which Exim uses, so if Exim |
| 26436 | built, then you have SNI support). |
| 26437 | |
| 26438 | |
| 26439 | |
| 26440 | .section "Multiple messages on the same encrypted TCP/IP connection" &&& |
| 26441 | "SECTmulmessam" |
| 26442 | .cindex "multiple SMTP deliveries with TLS" |
| 26443 | .cindex "TLS" "multiple message deliveries" |
| 26444 | Exim sends multiple messages down the same TCP/IP connection by starting up |
| 26445 | an entirely new delivery process for each message, passing the socket from |
| 26446 | one process to the next. This implementation does not fit well with the use |
| 26447 | of TLS, because there is quite a lot of state information associated with a TLS |
| 26448 | connection, not just a socket identification. Passing all the state information |
| 26449 | to a new process is not feasible. Consequently, Exim shuts down an existing TLS |
| 26450 | session before passing the socket to a new process. The new process may then |
| 26451 | try to start a new TLS session, and if successful, may try to re-authenticate |
| 26452 | if AUTH is in use, before sending the next message. |
| 26453 | |
| 26454 | The RFC is not clear as to whether or not an SMTP session continues in clear |
| 26455 | after TLS has been shut down, or whether TLS may be restarted again later, as |
| 26456 | just described. However, if the server is Exim, this shutdown and |
| 26457 | reinitialization works. It is not known which (if any) other servers operate |
| 26458 | successfully if the client closes a TLS session and continues with unencrypted |
| 26459 | SMTP, but there are certainly some that do not work. For such servers, Exim |
| 26460 | should not pass the socket to another process, because the failure of the |
| 26461 | subsequent attempt to use it would cause Exim to record a temporary host error, |
| 26462 | and delay other deliveries to that host. |
| 26463 | |
| 26464 | To test for this case, Exim sends an EHLO command to the server after |
| 26465 | closing down the TLS session. If this fails in any way, the connection is |
| 26466 | closed instead of being passed to a new delivery process, but no retry |
| 26467 | information is recorded. |
| 26468 | |
| 26469 | There is also a manual override; you can set &%hosts_nopass_tls%& on the |
| 26470 | &(smtp)& transport to match those hosts for which Exim should not pass |
| 26471 | connections to new processes if TLS has been used. |
| 26472 | |
| 26473 | |
| 26474 | |
| 26475 | |
| 26476 | .section "Certificates and all that" "SECTcerandall" |
| 26477 | .cindex "certificate" "references to discussion" |
| 26478 | In order to understand fully how TLS works, you need to know about |
| 26479 | certificates, certificate signing, and certificate authorities. This is not the |
| 26480 | place to give a tutorial, especially as I do not know very much about it |
| 26481 | myself. Some helpful introduction can be found in the FAQ for the SSL addition |
| 26482 | to Apache, currently at |
| 26483 | .display |
| 26484 | &url(http://www.modssl.org/docs/2.7/ssl_faq.html#ToC24) |
| 26485 | .endd |
| 26486 | Other parts of the &'modssl'& documentation are also helpful, and have |
| 26487 | links to further files. |
| 26488 | Eric Rescorla's book, &'SSL and TLS'&, published by Addison-Wesley (ISBN |
| 26489 | 0-201-61598-3), contains both introductory and more in-depth descriptions. |
| 26490 | Some sample programs taken from the book are available from |
| 26491 | .display |
| 26492 | &url(http://www.rtfm.com/openssl-examples/) |
| 26493 | .endd |
| 26494 | |
| 26495 | |
| 26496 | .section "Certificate chains" "SECID186" |
| 26497 | The file named by &%tls_certificate%& may contain more than one |
| 26498 | certificate. This is useful in the case where the certificate that is being |
| 26499 | sent is validated by an intermediate certificate which the other end does |
| 26500 | not have. Multiple certificates must be in the correct order in the file. |
| 26501 | First the host's certificate itself, then the first intermediate |
| 26502 | certificate to validate the issuer of the host certificate, then the next |
| 26503 | intermediate certificate to validate the issuer of the first intermediate |
| 26504 | certificate, and so on, until finally (optionally) the root certificate. |
| 26505 | The root certificate must already be trusted by the recipient for |
| 26506 | validation to succeed, of course, but if it's not preinstalled, sending the |
| 26507 | root certificate along with the rest makes it available for the user to |
| 26508 | install if the receiving end is a client MUA that can interact with a user. |
| 26509 | |
| 26510 | Note that certificates using MD5 are unlikely to work on today's Internet; |
| 26511 | even if your libraries allow loading them for use in Exim when acting as a |
| 26512 | server, increasingly clients will not accept such certificates. The error |
| 26513 | diagnostics in such a case can be frustratingly vague. |
| 26514 | |
| 26515 | |
| 26516 | |
| 26517 | .section "Self-signed certificates" "SECID187" |
| 26518 | .cindex "certificate" "self-signed" |
| 26519 | You can create a self-signed certificate using the &'req'& command provided |
| 26520 | with OpenSSL, like this: |
| 26521 | . ==== Do not shorten the duration here without reading and considering |
| 26522 | . ==== the text below. Please leave it at 9999 days. |
| 26523 | .code |
| 26524 | openssl req -x509 -newkey rsa:1024 -keyout file1 -out file2 \ |
| 26525 | -days 9999 -nodes |
| 26526 | .endd |
| 26527 | &_file1_& and &_file2_& can be the same file; the key and the certificate are |
| 26528 | delimited and so can be identified independently. The &%-days%& option |
| 26529 | specifies a period for which the certificate is valid. The &%-nodes%& option is |
| 26530 | important: if you do not set it, the key is encrypted with a passphrase |
| 26531 | that you are prompted for, and any use that is made of the key causes more |
| 26532 | prompting for the passphrase. This is not helpful if you are going to use |
| 26533 | this certificate and key in an MTA, where prompting is not possible. |
| 26534 | |
| 26535 | . ==== I expect to still be working 26 years from now. The less technical |
| 26536 | . ==== debt I create, in terms of storing up trouble for my later years, the |
| 26537 | . ==== happier I will be then. We really have reached the point where we |
| 26538 | . ==== should start, at the very least, provoking thought and making folks |
| 26539 | . ==== pause before proceeding, instead of leaving all the fixes until two |
| 26540 | . ==== years before 2^31 seconds after the 1970 Unix epoch. |
| 26541 | . ==== -pdp, 2012 |
| 26542 | NB: we are now past the point where 9999 days takes us past the 32-bit Unix |
| 26543 | epoch. If your system uses unsigned time_t (most do) and is 32-bit, then |
| 26544 | the above command might produce a date in the past. Think carefully about |
| 26545 | the lifetime of the systems you're deploying, and either reduce the duration |
| 26546 | of the certificate or reconsider your platform deployment. (At time of |
| 26547 | writing, reducing the duration is the most likely choice, but the inexorable |
| 26548 | progression of time takes us steadily towards an era where this will not |
| 26549 | be a sensible resolution). |
| 26550 | |
| 26551 | A self-signed certificate made in this way is sufficient for testing, and |
| 26552 | may be adequate for all your requirements if you are mainly interested in |
| 26553 | encrypting transfers, and not in secure identification. |
| 26554 | |
| 26555 | However, many clients require that the certificate presented by the server be a |
| 26556 | user (also called &"leaf"& or &"site"&) certificate, and not a self-signed |
| 26557 | certificate. In this situation, the self-signed certificate described above |
| 26558 | must be installed on the client host as a trusted root &'certification |
| 26559 | authority'& (CA), and the certificate used by Exim must be a user certificate |
| 26560 | signed with that self-signed certificate. |
| 26561 | |
| 26562 | For information on creating self-signed CA certificates and using them to sign |
| 26563 | user certificates, see the &'General implementation overview'& chapter of the |
| 26564 | Open-source PKI book, available online at |
| 26565 | &url(http://ospkibook.sourceforge.net/). |
| 26566 | .ecindex IIDencsmtp1 |
| 26567 | .ecindex IIDencsmtp2 |
| 26568 | |
| 26569 | |
| 26570 | |
| 26571 | . //////////////////////////////////////////////////////////////////////////// |
| 26572 | . //////////////////////////////////////////////////////////////////////////// |
| 26573 | |
| 26574 | .chapter "Access control lists" "CHAPACL" |
| 26575 | .scindex IIDacl "&ACL;" "description" |
| 26576 | .cindex "control of incoming mail" |
| 26577 | .cindex "message" "controlling incoming" |
| 26578 | .cindex "policy control" "access control lists" |
| 26579 | Access Control Lists (ACLs) are defined in a separate section of the run time |
| 26580 | configuration file, headed by &"begin acl"&. Each ACL definition starts with a |
| 26581 | name, terminated by a colon. Here is a complete ACL section that contains just |
| 26582 | one very small ACL: |
| 26583 | .code |
| 26584 | begin acl |
| 26585 | small_acl: |
| 26586 | accept hosts = one.host.only |
| 26587 | .endd |
| 26588 | You can have as many lists as you like in the ACL section, and the order in |
| 26589 | which they appear does not matter. The lists are self-terminating. |
| 26590 | |
| 26591 | The majority of ACLs are used to control Exim's behaviour when it receives |
| 26592 | certain SMTP commands. This applies both to incoming TCP/IP connections, and |
| 26593 | when a local process submits a message using SMTP by specifying the &%-bs%& |
| 26594 | option. The most common use is for controlling which recipients are accepted |
| 26595 | in incoming messages. In addition, you can define an ACL that is used to check |
| 26596 | local non-SMTP messages. The default configuration file contains an example of |
| 26597 | a realistic ACL for checking RCPT commands. This is discussed in chapter |
| 26598 | &<<CHAPdefconfil>>&. |
| 26599 | |
| 26600 | |
| 26601 | .section "Testing ACLs" "SECID188" |
| 26602 | The &%-bh%& command line option provides a way of testing your ACL |
| 26603 | configuration locally by running a fake SMTP session with which you interact. |
| 26604 | The host &'relay-test.mail-abuse.org'& provides a service for checking your |
| 26605 | relaying configuration (see section &<<SECTcheralcon>>& for more details). |
| 26606 | |
| 26607 | |
| 26608 | |
| 26609 | .section "Specifying when ACLs are used" "SECID189" |
| 26610 | .cindex "&ACL;" "options for specifying" |
| 26611 | In order to cause an ACL to be used, you have to name it in one of the relevant |
| 26612 | options in the main part of the configuration. These options are: |
| 26613 | .cindex "AUTH" "ACL for" |
| 26614 | .cindex "DATA" "ACLs for" |
| 26615 | .cindex "ETRN" "ACL for" |
| 26616 | .cindex "EXPN" "ACL for" |
| 26617 | .cindex "HELO" "ACL for" |
| 26618 | .cindex "EHLO" "ACL for" |
| 26619 | .cindex "MAIL" "ACL for" |
| 26620 | .cindex "QUIT, ACL for" |
| 26621 | .cindex "RCPT" "ACL for" |
| 26622 | .cindex "STARTTLS, ACL for" |
| 26623 | .cindex "VRFY" "ACL for" |
| 26624 | .cindex "SMTP" "connection, ACL for" |
| 26625 | .cindex "non-SMTP messages" "ACLs for" |
| 26626 | .cindex "MIME content scanning" "ACL for" |
| 26627 | .cindex "PRDR" "ACL for" |
| 26628 | |
| 26629 | .table2 140pt |
| 26630 | .irow &%acl_not_smtp%& "ACL for non-SMTP messages" |
| 26631 | .irow &%acl_not_smtp_mime%& "ACL for non-SMTP MIME parts" |
| 26632 | .irow &%acl_not_smtp_start%& "ACL at start of non-SMTP message" |
| 26633 | .irow &%acl_smtp_auth%& "ACL for AUTH" |
| 26634 | .irow &%acl_smtp_connect%& "ACL for start of SMTP connection" |
| 26635 | .irow &%acl_smtp_data%& "ACL after DATA is complete" |
| 26636 | .irow &%acl_smtp_data_prdr%& "ACL for each recipient, after DATA is complete" |
| 26637 | .irow &%acl_smtp_etrn%& "ACL for ETRN" |
| 26638 | .irow &%acl_smtp_expn%& "ACL for EXPN" |
| 26639 | .irow &%acl_smtp_helo%& "ACL for HELO or EHLO" |
| 26640 | .irow &%acl_smtp_mail%& "ACL for MAIL" |
| 26641 | .irow &%acl_smtp_mailauth%& "ACL for the AUTH parameter of MAIL" |
| 26642 | .irow &%acl_smtp_mime%& "ACL for content-scanning MIME parts" |
| 26643 | .irow &%acl_smtp_notquit%& "ACL for non-QUIT terminations" |
| 26644 | .irow &%acl_smtp_predata%& "ACL at start of DATA command" |
| 26645 | .irow &%acl_smtp_quit%& "ACL for QUIT" |
| 26646 | .irow &%acl_smtp_rcpt%& "ACL for RCPT" |
| 26647 | .irow &%acl_smtp_starttls%& "ACL for STARTTLS" |
| 26648 | .irow &%acl_smtp_vrfy%& "ACL for VRFY" |
| 26649 | .endtable |
| 26650 | |
| 26651 | For example, if you set |
| 26652 | .code |
| 26653 | acl_smtp_rcpt = small_acl |
| 26654 | .endd |
| 26655 | the little ACL defined above is used whenever Exim receives a RCPT command |
| 26656 | in an SMTP dialogue. The majority of policy tests on incoming messages can be |
| 26657 | done when RCPT commands arrive. A rejection of RCPT should cause the |
| 26658 | sending MTA to give up on the recipient address contained in the RCPT |
| 26659 | command, whereas rejection at other times may cause the client MTA to keep on |
| 26660 | trying to deliver the message. It is therefore recommended that you do as much |
| 26661 | testing as possible at RCPT time. |
| 26662 | |
| 26663 | |
| 26664 | .section "The non-SMTP ACLs" "SECID190" |
| 26665 | .cindex "non-SMTP messages" "ACLs for" |
| 26666 | The non-SMTP ACLs apply to all non-interactive incoming messages, that is, they |
| 26667 | apply to batched SMTP as well as to non-SMTP messages. (Batched SMTP is not |
| 26668 | really SMTP.) Many of the ACL conditions (for example, host tests, and tests on |
| 26669 | the state of the SMTP connection such as encryption and authentication) are not |
| 26670 | relevant and are forbidden in these ACLs. However, the sender and recipients |
| 26671 | are known, so the &%senders%& and &%sender_domains%& conditions and the |
| 26672 | &$sender_address$& and &$recipients$& variables can be used. Variables such as |
| 26673 | &$authenticated_sender$& are also available. You can specify added header lines |
| 26674 | in any of these ACLs. |
| 26675 | |
| 26676 | The &%acl_not_smtp_start%& ACL is run right at the start of receiving a |
| 26677 | non-SMTP message, before any of the message has been read. (This is the |
| 26678 | analogue of the &%acl_smtp_predata%& ACL for SMTP input.) In the case of |
| 26679 | batched SMTP input, it runs after the DATA command has been reached. The |
| 26680 | result of this ACL is ignored; it cannot be used to reject a message. If you |
| 26681 | really need to, you could set a value in an ACL variable here and reject based |
| 26682 | on that in the &%acl_not_smtp%& ACL. However, this ACL can be used to set |
| 26683 | controls, and in particular, it can be used to set |
| 26684 | .code |
| 26685 | control = suppress_local_fixups |
| 26686 | .endd |
| 26687 | This cannot be used in the other non-SMTP ACLs because by the time they are |
| 26688 | run, it is too late. |
| 26689 | |
| 26690 | The &%acl_not_smtp_mime%& ACL is available only when Exim is compiled with the |
| 26691 | content-scanning extension. For details, see chapter &<<CHAPexiscan>>&. |
| 26692 | |
| 26693 | The &%acl_not_smtp%& ACL is run just before the &[local_scan()]& function. Any |
| 26694 | kind of rejection is treated as permanent, because there is no way of sending a |
| 26695 | temporary error for these kinds of message. |
| 26696 | |
| 26697 | |
| 26698 | .section "The SMTP connect ACL" "SECID191" |
| 26699 | .cindex "SMTP" "connection, ACL for" |
| 26700 | .oindex &%smtp_banner%& |
| 26701 | The ACL test specified by &%acl_smtp_connect%& happens at the start of an SMTP |
| 26702 | session, after the test specified by &%host_reject_connection%& (which is now |
| 26703 | an anomaly) and any TCP Wrappers testing (if configured). If the connection is |
| 26704 | accepted by an &%accept%& verb that has a &%message%& modifier, the contents of |
| 26705 | the message override the banner message that is otherwise specified by the |
| 26706 | &%smtp_banner%& option. |
| 26707 | |
| 26708 | |
| 26709 | .section "The EHLO/HELO ACL" "SECID192" |
| 26710 | .cindex "EHLO" "ACL for" |
| 26711 | .cindex "HELO" "ACL for" |
| 26712 | The ACL test specified by &%acl_smtp_helo%& happens when the client issues an |
| 26713 | EHLO or HELO command, after the tests specified by &%helo_accept_junk_hosts%&, |
| 26714 | &%helo_allow_chars%&, &%helo_verify_hosts%&, and &%helo_try_verify_hosts%&. |
| 26715 | Note that a client may issue more than one EHLO or HELO command in an SMTP |
| 26716 | session, and indeed is required to issue a new EHLO or HELO after successfully |
| 26717 | setting up encryption following a STARTTLS command. |
| 26718 | |
| 26719 | If the command is accepted by an &%accept%& verb that has a &%message%& |
| 26720 | modifier, the message may not contain more than one line (it will be truncated |
| 26721 | at the first newline and a panic logged if it does). Such a message cannot |
| 26722 | affect the EHLO options that are listed on the second and subsequent lines of |
| 26723 | an EHLO response. |
| 26724 | |
| 26725 | |
| 26726 | .section "The DATA ACLs" "SECID193" |
| 26727 | .cindex "DATA" "ACLs for" |
| 26728 | Two ACLs are associated with the DATA command, because it is two-stage |
| 26729 | command, with two responses being sent to the client. |
| 26730 | When the DATA command is received, the ACL defined by &%acl_smtp_predata%& |
| 26731 | is obeyed. This gives you control after all the RCPT commands, but before |
| 26732 | the message itself is received. It offers the opportunity to give a negative |
| 26733 | response to the DATA command before the data is transmitted. Header lines |
| 26734 | added by MAIL or RCPT ACLs are not visible at this time, but any that |
| 26735 | are defined here are visible when the &%acl_smtp_data%& ACL is run. |
| 26736 | |
| 26737 | You cannot test the contents of the message, for example, to verify addresses |
| 26738 | in the headers, at RCPT time or when the DATA command is received. Such |
| 26739 | tests have to appear in the ACL that is run after the message itself has been |
| 26740 | received, before the final response to the DATA command is sent. This is |
| 26741 | the ACL specified by &%acl_smtp_data%&, which is the second ACL that is |
| 26742 | associated with the DATA command. |
| 26743 | |
| 26744 | For both of these ACLs, it is not possible to reject individual recipients. An |
| 26745 | error response rejects the entire message. Unfortunately, it is known that some |
| 26746 | MTAs do not treat hard (5&'xx'&) responses to the DATA command (either |
| 26747 | before or after the data) correctly &-- they keep the message on their queues |
| 26748 | and try again later, but that is their problem, though it does waste some of |
| 26749 | your resources. |
| 26750 | |
| 26751 | The &%acl_smtp_data%& ACL is run after |
| 26752 | the &%acl_smtp_data_prdr%&, |
| 26753 | the &%acl_smtp_dkim%& |
| 26754 | and the &%acl_smtp_mime%& ACLs. |
| 26755 | |
| 26756 | .section "The SMTP DKIM ACL" "SECTDKIMACL" |
| 26757 | The &%acl_smtp_dkim%& ACL is available only when Exim is compiled with DKIM support |
| 26758 | enabled (which is the default). |
| 26759 | |
| 26760 | The ACL test specified by &%acl_smtp_dkim%& happens after a message has been |
| 26761 | received, and is executed for each DKIM signature found in a message. If not |
| 26762 | otherwise specified, the default action is to accept. |
| 26763 | |
| 26764 | This ACL is evaluated before &%acl_smtp_mime%& and &%acl_smtp_data%&. |
| 26765 | |
| 26766 | For details on the operation of DKIM, see chapter &<<CHAPdkim>>&. |
| 26767 | |
| 26768 | |
| 26769 | .section "The SMTP MIME ACL" "SECID194" |
| 26770 | The &%acl_smtp_mime%& option is available only when Exim is compiled with the |
| 26771 | content-scanning extension. For details, see chapter &<<CHAPexiscan>>&. |
| 26772 | |
| 26773 | This ACL is evaluated after &%acl_smtp_dkim%& but before &%acl_smtp_data%&. |
| 26774 | |
| 26775 | |
| 26776 | .section "The SMTP PRDR ACL" "SECTPRDRACL" |
| 26777 | .oindex "&%prdr_enable%&" |
| 26778 | The &%acl_smtp_data_prdr%& ACL is available only when Exim is compiled |
| 26779 | with PRDR support enabled (which is the default). |
| 26780 | It becomes active only when the PRDR feature is negotiated between |
| 26781 | client and server for a message, and more than one recipient |
| 26782 | has been accepted. |
| 26783 | |
| 26784 | The ACL test specfied by &%acl_smtp_data_prdr%& happens after a message |
| 26785 | has been recieved, and is executed for each recipient of the message. |
| 26786 | The test may accept or deny for inividual recipients. |
| 26787 | The &%acl_smtp_data%& will still be called after this ACL and |
| 26788 | can reject the message overall, even if this ACL has accepted it |
| 26789 | for some or all recipients. |
| 26790 | |
| 26791 | PRDR may be used to support per-user content filtering. Without it |
| 26792 | one must defer any recipient after the first that has a different |
| 26793 | content-filter configuration. With PRDR, the RCPT-time check |
| 26794 | for this can be disabled when the MAIL-time $smtp_command included |
| 26795 | "PRDR". Any required difference in behaviour of the main DATA-time |
| 26796 | ACL should however depend on the PRDR-time ACL having run, as Exim |
| 26797 | will avoid doing so in some situations (eg. single-recipient mails). |
| 26798 | |
| 26799 | See also the &%prdr_enable%& global option |
| 26800 | and the &%hosts_try_prdr%& smtp transport option. |
| 26801 | |
| 26802 | This ACL is evaluated after &%acl_smtp_dkim%& but before &%acl_smtp_data%&. |
| 26803 | If the ACL is not defined, processing completes as if |
| 26804 | the feature was not requested by the client. |
| 26805 | |
| 26806 | .section "The QUIT ACL" "SECTQUITACL" |
| 26807 | .cindex "QUIT, ACL for" |
| 26808 | The ACL for the SMTP QUIT command is anomalous, in that the outcome of the ACL |
| 26809 | does not affect the response code to QUIT, which is always 221. Thus, the ACL |
| 26810 | does not in fact control any access. For this reason, the only verbs that are |
| 26811 | permitted are &%accept%& and &%warn%&. |
| 26812 | |
| 26813 | This ACL can be used for tasks such as custom logging at the end of an SMTP |
| 26814 | session. For example, you can use ACL variables in other ACLs to count |
| 26815 | messages, recipients, etc., and log the totals at QUIT time using one or |
| 26816 | more &%logwrite%& modifiers on a &%warn%& verb. |
| 26817 | |
| 26818 | &*Warning*&: Only the &$acl_c$&&'x'& variables can be used for this, because |
| 26819 | the &$acl_m$&&'x'& variables are reset at the end of each incoming message. |
| 26820 | |
| 26821 | You do not need to have a final &%accept%&, but if you do, you can use a |
| 26822 | &%message%& modifier to specify custom text that is sent as part of the 221 |
| 26823 | response to QUIT. |
| 26824 | |
| 26825 | This ACL is run only for a &"normal"& QUIT. For certain kinds of disastrous |
| 26826 | failure (for example, failure to open a log file, or when Exim is bombing out |
| 26827 | because it has detected an unrecoverable error), all SMTP commands from the |
| 26828 | client are given temporary error responses until QUIT is received or the |
| 26829 | connection is closed. In these special cases, the QUIT ACL does not run. |
| 26830 | |
| 26831 | |
| 26832 | .section "The not-QUIT ACL" "SECTNOTQUITACL" |
| 26833 | .vindex &$acl_smtp_notquit$& |
| 26834 | The not-QUIT ACL, specified by &%acl_smtp_notquit%&, is run in most cases when |
| 26835 | an SMTP session ends without sending QUIT. However, when Exim itself is in bad |
| 26836 | trouble, such as being unable to write to its log files, this ACL is not run, |
| 26837 | because it might try to do things (such as write to log files) that make the |
| 26838 | situation even worse. |
| 26839 | |
| 26840 | Like the QUIT ACL, this ACL is provided to make it possible to do customized |
| 26841 | logging or to gather statistics, and its outcome is ignored. The &%delay%& |
| 26842 | modifier is forbidden in this ACL, and the only permitted verbs are &%accept%& |
| 26843 | and &%warn%&. |
| 26844 | |
| 26845 | .vindex &$smtp_notquit_reason$& |
| 26846 | When the not-QUIT ACL is running, the variable &$smtp_notquit_reason$& is set |
| 26847 | to a string that indicates the reason for the termination of the SMTP |
| 26848 | connection. The possible values are: |
| 26849 | .table2 |
| 26850 | .irow &`acl-drop`& "Another ACL issued a &%drop%& command" |
| 26851 | .irow &`bad-commands`& "Too many unknown or non-mail commands" |
| 26852 | .irow &`command-timeout`& "Timeout while reading SMTP commands" |
| 26853 | .irow &`connection-lost`& "The SMTP connection has been lost" |
| 26854 | .irow &`data-timeout`& "Timeout while reading message data" |
| 26855 | .irow &`local-scan-error`& "The &[local_scan()]& function crashed" |
| 26856 | .irow &`local-scan-timeout`& "The &[local_scan()]& function timed out" |
| 26857 | .irow &`signal-exit`& "SIGTERM or SIGINT" |
| 26858 | .irow &`synchronization-error`& "SMTP synchronization error" |
| 26859 | .irow &`tls-failed`& "TLS failed to start" |
| 26860 | .endtable |
| 26861 | In most cases when an SMTP connection is closed without having received QUIT, |
| 26862 | Exim sends an SMTP response message before actually closing the connection. |
| 26863 | With the exception of the &`acl-drop`& case, the default message can be |
| 26864 | overridden by the &%message%& modifier in the not-QUIT ACL. In the case of a |
| 26865 | &%drop%& verb in another ACL, it is the message from the other ACL that is |
| 26866 | used. |
| 26867 | |
| 26868 | |
| 26869 | .section "Finding an ACL to use" "SECID195" |
| 26870 | .cindex "&ACL;" "finding which to use" |
| 26871 | The value of an &%acl_smtp_%&&'xxx'& option is expanded before use, so |
| 26872 | you can use different ACLs in different circumstances. For example, |
| 26873 | .code |
| 26874 | acl_smtp_rcpt = ${if ={25}{$interface_port} \ |
| 26875 | {acl_check_rcpt} {acl_check_rcpt_submit} } |
| 26876 | .endd |
| 26877 | In the default configuration file there are some example settings for |
| 26878 | providing an RFC 4409 message submission service on port 587 and a |
| 26879 | non-standard &"smtps"& service on port 465. You can use a string |
| 26880 | expansion like this to choose an ACL for MUAs on these ports which is |
| 26881 | more appropriate for this purpose than the default ACL on port 25. |
| 26882 | |
| 26883 | The expanded string does not have to be the name of an ACL in the |
| 26884 | configuration file; there are other possibilities. Having expanded the |
| 26885 | string, Exim searches for an ACL as follows: |
| 26886 | |
| 26887 | .ilist |
| 26888 | If the string begins with a slash, Exim uses it as a file name, and reads its |
| 26889 | contents as an ACL. The lines are processed in the same way as lines in the |
| 26890 | Exim configuration file. In particular, continuation lines are supported, blank |
| 26891 | lines are ignored, as are lines whose first non-whitespace character is &"#"&. |
| 26892 | If the file does not exist or cannot be read, an error occurs (typically |
| 26893 | causing a temporary failure of whatever caused the ACL to be run). For example: |
| 26894 | .code |
| 26895 | acl_smtp_data = /etc/acls/\ |
| 26896 | ${lookup{$sender_host_address}lsearch\ |
| 26897 | {/etc/acllist}{$value}{default}} |
| 26898 | .endd |
| 26899 | This looks up an ACL file to use on the basis of the host's IP address, falling |
| 26900 | back to a default if the lookup fails. If an ACL is successfully read from a |
| 26901 | file, it is retained in memory for the duration of the Exim process, so that it |
| 26902 | can be re-used without having to re-read the file. |
| 26903 | .next |
| 26904 | If the string does not start with a slash, and does not contain any spaces, |
| 26905 | Exim searches the ACL section of the configuration for an ACL whose name |
| 26906 | matches the string. |
| 26907 | .next |
| 26908 | If no named ACL is found, or if the string contains spaces, Exim parses |
| 26909 | the string as an inline ACL. This can save typing in cases where you just |
| 26910 | want to have something like |
| 26911 | .code |
| 26912 | acl_smtp_vrfy = accept |
| 26913 | .endd |
| 26914 | in order to allow free use of the VRFY command. Such a string may contain |
| 26915 | newlines; it is processed in the same way as an ACL that is read from a file. |
| 26916 | .endlist |
| 26917 | |
| 26918 | |
| 26919 | |
| 26920 | |
| 26921 | .section "ACL return codes" "SECID196" |
| 26922 | .cindex "&ACL;" "return codes" |
| 26923 | Except for the QUIT ACL, which does not affect the SMTP return code (see |
| 26924 | section &<<SECTQUITACL>>& above), the result of running an ACL is either |
| 26925 | &"accept"& or &"deny"&, or, if some test cannot be completed (for example, if a |
| 26926 | database is down), &"defer"&. These results cause 2&'xx'&, 5&'xx'&, and 4&'xx'& |
| 26927 | return codes, respectively, to be used in the SMTP dialogue. A fourth return, |
| 26928 | &"error"&, occurs when there is an error such as invalid syntax in the ACL. |
| 26929 | This also causes a 4&'xx'& return code. |
| 26930 | |
| 26931 | For the non-SMTP ACL, &"defer"& and &"error"& are treated in the same way as |
| 26932 | &"deny"&, because there is no mechanism for passing temporary errors to the |
| 26933 | submitters of non-SMTP messages. |
| 26934 | |
| 26935 | |
| 26936 | ACLs that are relevant to message reception may also return &"discard"&. This |
| 26937 | has the effect of &"accept"&, but causes either the entire message or an |
| 26938 | individual recipient address to be discarded. In other words, it is a |
| 26939 | blackholing facility. Use it with care. |
| 26940 | |
| 26941 | If the ACL for MAIL returns &"discard"&, all recipients are discarded, and no |
| 26942 | ACL is run for subsequent RCPT commands. The effect of &"discard"& in a |
| 26943 | RCPT ACL is to discard just the one recipient address. If there are no |
| 26944 | recipients left when the message's data is received, the DATA ACL is not |
| 26945 | run. A &"discard"& return from the DATA or the non-SMTP ACL discards all the |
| 26946 | remaining recipients. The &"discard"& return is not permitted for the |
| 26947 | &%acl_smtp_predata%& ACL. |
| 26948 | |
| 26949 | |
| 26950 | .cindex "&[local_scan()]& function" "when all recipients discarded" |
| 26951 | The &[local_scan()]& function is always run, even if there are no remaining |
| 26952 | recipients; it may create new recipients. |
| 26953 | |
| 26954 | |
| 26955 | |
| 26956 | .section "Unset ACL options" "SECID197" |
| 26957 | .cindex "&ACL;" "unset options" |
| 26958 | The default actions when any of the &%acl_%&&'xxx'& options are unset are not |
| 26959 | all the same. &*Note*&: These defaults apply only when the relevant ACL is |
| 26960 | not defined at all. For any defined ACL, the default action when control |
| 26961 | reaches the end of the ACL statements is &"deny"&. |
| 26962 | |
| 26963 | For &%acl_smtp_quit%& and &%acl_not_smtp_start%& there is no default because |
| 26964 | these two are ACLs that are used only for their side effects. They cannot be |
| 26965 | used to accept or reject anything. |
| 26966 | |
| 26967 | For &%acl_not_smtp%&, &%acl_smtp_auth%&, &%acl_smtp_connect%&, |
| 26968 | &%acl_smtp_data%&, &%acl_smtp_helo%&, &%acl_smtp_mail%&, &%acl_smtp_mailauth%&, |
| 26969 | &%acl_smtp_mime%&, &%acl_smtp_predata%&, and &%acl_smtp_starttls%&, the action |
| 26970 | when the ACL is not defined is &"accept"&. |
| 26971 | |
| 26972 | For the others (&%acl_smtp_etrn%&, &%acl_smtp_expn%&, &%acl_smtp_rcpt%&, and |
| 26973 | &%acl_smtp_vrfy%&), the action when the ACL is not defined is &"deny"&. |
| 26974 | This means that &%acl_smtp_rcpt%& must be defined in order to receive any |
| 26975 | messages over an SMTP connection. For an example, see the ACL in the default |
| 26976 | configuration file. |
| 26977 | |
| 26978 | |
| 26979 | |
| 26980 | |
| 26981 | .section "Data for message ACLs" "SECID198" |
| 26982 | .cindex "&ACL;" "data for message ACL" |
| 26983 | .vindex &$domain$& |
| 26984 | .vindex &$local_part$& |
| 26985 | .vindex &$sender_address$& |
| 26986 | .vindex &$sender_host_address$& |
| 26987 | .vindex &$smtp_command$& |
| 26988 | When a MAIL or RCPT ACL, or either of the DATA ACLs, is running, the variables |
| 26989 | that contain information about the host and the message's sender (for example, |
| 26990 | &$sender_host_address$& and &$sender_address$&) are set, and can be used in ACL |
| 26991 | statements. In the case of RCPT (but not MAIL or DATA), &$domain$& and |
| 26992 | &$local_part$& are set from the argument address. The entire SMTP command |
| 26993 | is available in &$smtp_command$&. |
| 26994 | |
| 26995 | When an ACL for the AUTH parameter of MAIL is running, the variables that |
| 26996 | contain information about the host are set, but &$sender_address$& is not yet |
| 26997 | set. Section &<<SECTauthparamail>>& contains a discussion of this parameter and |
| 26998 | how it is used. |
| 26999 | |
| 27000 | .vindex "&$message_size$&" |
| 27001 | The &$message_size$& variable is set to the value of the SIZE parameter on |
| 27002 | the MAIL command at MAIL, RCPT and pre-data time, or to -1 if |
| 27003 | that parameter is not given. The value is updated to the true message size by |
| 27004 | the time the final DATA ACL is run (after the message data has been |
| 27005 | received). |
| 27006 | |
| 27007 | .vindex "&$rcpt_count$&" |
| 27008 | .vindex "&$recipients_count$&" |
| 27009 | The &$rcpt_count$& variable increases by one for each RCPT command received. |
| 27010 | The &$recipients_count$& variable increases by one each time a RCPT command is |
| 27011 | accepted, so while an ACL for RCPT is being processed, it contains the number |
| 27012 | of previously accepted recipients. At DATA time (for both the DATA ACLs), |
| 27013 | &$rcpt_count$& contains the total number of RCPT commands, and |
| 27014 | &$recipients_count$& contains the total number of accepted recipients. |
| 27015 | |
| 27016 | |
| 27017 | |
| 27018 | |
| 27019 | |
| 27020 | .section "Data for non-message ACLs" "SECTdatfornon" |
| 27021 | .cindex "&ACL;" "data for non-message ACL" |
| 27022 | .vindex &$smtp_command_argument$& |
| 27023 | .vindex &$smtp_command$& |
| 27024 | When an ACL is being run for AUTH, EHLO, ETRN, EXPN, HELO, STARTTLS, or VRFY, |
| 27025 | the remainder of the SMTP command line is placed in &$smtp_command_argument$&, |
| 27026 | and the entire SMTP command is available in &$smtp_command$&. |
| 27027 | These variables can be tested using a &%condition%& condition. For example, |
| 27028 | here is an ACL for use with AUTH, which insists that either the session is |
| 27029 | encrypted, or the CRAM-MD5 authentication method is used. In other words, it |
| 27030 | does not permit authentication methods that use cleartext passwords on |
| 27031 | unencrypted connections. |
| 27032 | .code |
| 27033 | acl_check_auth: |
| 27034 | accept encrypted = * |
| 27035 | accept condition = ${if eq{${uc:$smtp_command_argument}}\ |
| 27036 | {CRAM-MD5}} |
| 27037 | deny message = TLS encryption or CRAM-MD5 required |
| 27038 | .endd |
| 27039 | (Another way of applying this restriction is to arrange for the authenticators |
| 27040 | that use cleartext passwords not to be advertised when the connection is not |
| 27041 | encrypted. You can use the generic &%server_advertise_condition%& authenticator |
| 27042 | option to do this.) |
| 27043 | |
| 27044 | |
| 27045 | |
| 27046 | .section "Format of an ACL" "SECID199" |
| 27047 | .cindex "&ACL;" "format of" |
| 27048 | .cindex "&ACL;" "verbs, definition of" |
| 27049 | An individual ACL consists of a number of statements. Each statement starts |
| 27050 | with a verb, optionally followed by a number of conditions and &"modifiers"&. |
| 27051 | Modifiers can change the way the verb operates, define error and log messages, |
| 27052 | set variables, insert delays, and vary the processing of accepted messages. |
| 27053 | |
| 27054 | If all the conditions are met, the verb is obeyed. The same condition may be |
| 27055 | used (with different arguments) more than once in the same statement. This |
| 27056 | provides a means of specifying an &"and"& conjunction between conditions. For |
| 27057 | example: |
| 27058 | .code |
| 27059 | deny dnslists = list1.example |
| 27060 | dnslists = list2.example |
| 27061 | .endd |
| 27062 | If there are no conditions, the verb is always obeyed. Exim stops evaluating |
| 27063 | the conditions and modifiers when it reaches a condition that fails. What |
| 27064 | happens then depends on the verb (and in one case, on a special modifier). Not |
| 27065 | all the conditions make sense at every testing point. For example, you cannot |
| 27066 | test a sender address in the ACL that is run for a VRFY command. |
| 27067 | |
| 27068 | |
| 27069 | .section "ACL verbs" "SECID200" |
| 27070 | The ACL verbs are as follows: |
| 27071 | |
| 27072 | .ilist |
| 27073 | .cindex "&%accept%& ACL verb" |
| 27074 | &%accept%&: If all the conditions are met, the ACL returns &"accept"&. If any |
| 27075 | of the conditions are not met, what happens depends on whether &%endpass%& |
| 27076 | appears among the conditions (for syntax see below). If the failing condition |
| 27077 | is before &%endpass%&, control is passed to the next ACL statement; if it is |
| 27078 | after &%endpass%&, the ACL returns &"deny"&. Consider this statement, used to |
| 27079 | check a RCPT command: |
| 27080 | .code |
| 27081 | accept domains = +local_domains |
| 27082 | endpass |
| 27083 | verify = recipient |
| 27084 | .endd |
| 27085 | If the recipient domain does not match the &%domains%& condition, control |
| 27086 | passes to the next statement. If it does match, the recipient is verified, and |
| 27087 | the command is accepted if verification succeeds. However, if verification |
| 27088 | fails, the ACL yields &"deny"&, because the failing condition is after |
| 27089 | &%endpass%&. |
| 27090 | |
| 27091 | The &%endpass%& feature has turned out to be confusing to many people, so its |
| 27092 | use is not recommended nowadays. It is always possible to rewrite an ACL so |
| 27093 | that &%endpass%& is not needed, and it is no longer used in the default |
| 27094 | configuration. |
| 27095 | |
| 27096 | .cindex "&%message%& ACL modifier" "with &%accept%&" |
| 27097 | If a &%message%& modifier appears on an &%accept%& statement, its action |
| 27098 | depends on whether or not &%endpass%& is present. In the absence of &%endpass%& |
| 27099 | (when an &%accept%& verb either accepts or passes control to the next |
| 27100 | statement), &%message%& can be used to vary the message that is sent when an |
| 27101 | SMTP command is accepted. For example, in a RCPT ACL you could have: |
| 27102 | .display |
| 27103 | &`accept `&<&'some conditions'&> |
| 27104 | &` message = OK, I will allow you through today`& |
| 27105 | .endd |
| 27106 | You can specify an SMTP response code, optionally followed by an &"extended |
| 27107 | response code"& at the start of the message, but the first digit must be the |
| 27108 | same as would be sent by default, which is 2 for an &%accept%& verb. |
| 27109 | |
| 27110 | If &%endpass%& is present in an &%accept%& statement, &%message%& specifies |
| 27111 | an error message that is used when access is denied. This behaviour is retained |
| 27112 | for backward compatibility, but current &"best practice"& is to avoid the use |
| 27113 | of &%endpass%&. |
| 27114 | |
| 27115 | |
| 27116 | .next |
| 27117 | .cindex "&%defer%& ACL verb" |
| 27118 | &%defer%&: If all the conditions are true, the ACL returns &"defer"& which, in |
| 27119 | an SMTP session, causes a 4&'xx'& response to be given. For a non-SMTP ACL, |
| 27120 | &%defer%& is the same as &%deny%&, because there is no way of sending a |
| 27121 | temporary error. For a RCPT command, &%defer%& is much the same as using a |
| 27122 | &(redirect)& router and &`:defer:`& while verifying, but the &%defer%& verb can |
| 27123 | be used in any ACL, and even for a recipient it might be a simpler approach. |
| 27124 | |
| 27125 | |
| 27126 | .next |
| 27127 | .cindex "&%deny%& ACL verb" |
| 27128 | &%deny%&: If all the conditions are met, the ACL returns &"deny"&. If any of |
| 27129 | the conditions are not met, control is passed to the next ACL statement. For |
| 27130 | example, |
| 27131 | .code |
| 27132 | deny dnslists = blackholes.mail-abuse.org |
| 27133 | .endd |
| 27134 | rejects commands from hosts that are on a DNS black list. |
| 27135 | |
| 27136 | |
| 27137 | .next |
| 27138 | .cindex "&%discard%& ACL verb" |
| 27139 | &%discard%&: This verb behaves like &%accept%&, except that it returns |
| 27140 | &"discard"& from the ACL instead of &"accept"&. It is permitted only on ACLs |
| 27141 | that are concerned with receiving messages. When all the conditions are true, |
| 27142 | the sending entity receives a &"success"& response. However, &%discard%& causes |
| 27143 | recipients to be discarded. If it is used in an ACL for RCPT, just the one |
| 27144 | recipient is discarded; if used for MAIL, DATA or in the non-SMTP ACL, all the |
| 27145 | message's recipients are discarded. Recipients that are discarded before DATA |
| 27146 | do not appear in the log line when the &%received_recipients%& log selector is set. |
| 27147 | |
| 27148 | If the &%log_message%& modifier is set when &%discard%& operates, |
| 27149 | its contents are added to the line that is automatically written to the log. |
| 27150 | The &%message%& modifier operates exactly as it does for &%accept%&. |
| 27151 | |
| 27152 | |
| 27153 | .next |
| 27154 | .cindex "&%drop%& ACL verb" |
| 27155 | &%drop%&: This verb behaves like &%deny%&, except that an SMTP connection is |
| 27156 | forcibly closed after the 5&'xx'& error message has been sent. For example: |
| 27157 | .code |
| 27158 | drop message = I don't take more than 20 RCPTs |
| 27159 | condition = ${if > {$rcpt_count}{20}} |
| 27160 | .endd |
| 27161 | There is no difference between &%deny%& and &%drop%& for the connect-time ACL. |
| 27162 | The connection is always dropped after sending a 550 response. |
| 27163 | |
| 27164 | .next |
| 27165 | .cindex "&%require%& ACL verb" |
| 27166 | &%require%&: If all the conditions are met, control is passed to the next ACL |
| 27167 | statement. If any of the conditions are not met, the ACL returns &"deny"&. For |
| 27168 | example, when checking a RCPT command, |
| 27169 | .code |
| 27170 | require message = Sender did not verify |
| 27171 | verify = sender |
| 27172 | .endd |
| 27173 | passes control to subsequent statements only if the message's sender can be |
| 27174 | verified. Otherwise, it rejects the command. Note the positioning of the |
| 27175 | &%message%& modifier, before the &%verify%& condition. The reason for this is |
| 27176 | discussed in section &<<SECTcondmodproc>>&. |
| 27177 | |
| 27178 | .next |
| 27179 | .cindex "&%warn%& ACL verb" |
| 27180 | &%warn%&: If all the conditions are true, a line specified by the |
| 27181 | &%log_message%& modifier is written to Exim's main log. Control always passes |
| 27182 | to the next ACL statement. If any condition is false, the log line is not |
| 27183 | written. If an identical log line is requested several times in the same |
| 27184 | message, only one copy is actually written to the log. If you want to force |
| 27185 | duplicates to be written, use the &%logwrite%& modifier instead. |
| 27186 | |
| 27187 | If &%log_message%& is not present, a &%warn%& verb just checks its conditions |
| 27188 | and obeys any &"immediate"& modifiers (such as &%control%&, &%set%&, |
| 27189 | &%logwrite%&, &%add_header%&, and &%remove_header%&) that appear before the |
| 27190 | first failing condition. There is more about adding header lines in section |
| 27191 | &<<SECTaddheadacl>>&. |
| 27192 | |
| 27193 | If any condition on a &%warn%& statement cannot be completed (that is, there is |
| 27194 | some sort of defer), the log line specified by &%log_message%& is not written. |
| 27195 | This does not include the case of a forced failure from a lookup, which |
| 27196 | is considered to be a successful completion. After a defer, no further |
| 27197 | conditions or modifiers in the &%warn%& statement are processed. The incident |
| 27198 | is logged, and the ACL continues to be processed, from the next statement |
| 27199 | onwards. |
| 27200 | |
| 27201 | |
| 27202 | .vindex "&$acl_verify_message$&" |
| 27203 | When one of the &%warn%& conditions is an address verification that fails, the |
| 27204 | text of the verification failure message is in &$acl_verify_message$&. If you |
| 27205 | want this logged, you must set it up explicitly. For example: |
| 27206 | .code |
| 27207 | warn !verify = sender |
| 27208 | log_message = sender verify failed: $acl_verify_message |
| 27209 | .endd |
| 27210 | .endlist |
| 27211 | |
| 27212 | At the end of each ACL there is an implicit unconditional &%deny%&. |
| 27213 | |
| 27214 | As you can see from the examples above, the conditions and modifiers are |
| 27215 | written one to a line, with the first one on the same line as the verb, and |
| 27216 | subsequent ones on following lines. If you have a very long condition, you can |
| 27217 | continue it onto several physical lines by the usual backslash continuation |
| 27218 | mechanism. It is conventional to align the conditions vertically. |
| 27219 | |
| 27220 | |
| 27221 | |
| 27222 | .section "ACL variables" "SECTaclvariables" |
| 27223 | .cindex "&ACL;" "variables" |
| 27224 | There are some special variables that can be set during ACL processing. They |
| 27225 | can be used to pass information between different ACLs, different invocations |
| 27226 | of the same ACL in the same SMTP connection, and between ACLs and the routers, |
| 27227 | transports, and filters that are used to deliver a message. The names of these |
| 27228 | variables must begin with &$acl_c$& or &$acl_m$&, followed either by a digit or |
| 27229 | an underscore, but the remainder of the name can be any sequence of |
| 27230 | alphanumeric characters and underscores that you choose. There is no limit on |
| 27231 | the number of ACL variables. The two sets act as follows: |
| 27232 | .ilist |
| 27233 | The values of those variables whose names begin with &$acl_c$& persist |
| 27234 | throughout an SMTP connection. They are never reset. Thus, a value that is set |
| 27235 | while receiving one message is still available when receiving the next message |
| 27236 | on the same SMTP connection. |
| 27237 | .next |
| 27238 | The values of those variables whose names begin with &$acl_m$& persist only |
| 27239 | while a message is being received. They are reset afterwards. They are also |
| 27240 | reset by MAIL, RSET, EHLO, HELO, and after starting up a TLS session. |
| 27241 | .endlist |
| 27242 | |
| 27243 | When a message is accepted, the current values of all the ACL variables are |
| 27244 | preserved with the message and are subsequently made available at delivery |
| 27245 | time. The ACL variables are set by a modifier called &%set%&. For example: |
| 27246 | .code |
| 27247 | accept hosts = whatever |
| 27248 | set acl_m4 = some value |
| 27249 | accept authenticated = * |
| 27250 | set acl_c_auth = yes |
| 27251 | .endd |
| 27252 | &*Note*&: A leading dollar sign is not used when naming a variable that is to |
| 27253 | be set. If you want to set a variable without taking any action, you can use a |
| 27254 | &%warn%& verb without any other modifiers or conditions. |
| 27255 | |
| 27256 | .oindex &%strict_acl_vars%& |
| 27257 | What happens if a syntactically valid but undefined ACL variable is |
| 27258 | referenced depends on the setting of the &%strict_acl_vars%& option. If it is |
| 27259 | false (the default), an empty string is substituted; if it is true, an |
| 27260 | error is generated. |
| 27261 | |
| 27262 | Versions of Exim before 4.64 have a limited set of numbered variables, but |
| 27263 | their names are compatible, so there is no problem with upgrading. |
| 27264 | |
| 27265 | |
| 27266 | .section "Condition and modifier processing" "SECTcondmodproc" |
| 27267 | .cindex "&ACL;" "conditions; processing" |
| 27268 | .cindex "&ACL;" "modifiers; processing" |
| 27269 | An exclamation mark preceding a condition negates its result. For example: |
| 27270 | .code |
| 27271 | deny domains = *.dom.example |
| 27272 | !verify = recipient |
| 27273 | .endd |
| 27274 | causes the ACL to return &"deny"& if the recipient domain ends in |
| 27275 | &'dom.example'& and the recipient address cannot be verified. Sometimes |
| 27276 | negation can be used on the right-hand side of a condition. For example, these |
| 27277 | two statements are equivalent: |
| 27278 | .code |
| 27279 | deny hosts = !192.168.3.4 |
| 27280 | deny !hosts = 192.168.3.4 |
| 27281 | .endd |
| 27282 | However, for many conditions (&%verify%& being a good example), only left-hand |
| 27283 | side negation of the whole condition is possible. |
| 27284 | |
| 27285 | The arguments of conditions and modifiers are expanded. A forced failure |
| 27286 | of an expansion causes a condition to be ignored, that is, it behaves as if the |
| 27287 | condition is true. Consider these two statements: |
| 27288 | .code |
| 27289 | accept senders = ${lookup{$host_name}lsearch\ |
| 27290 | {/some/file}{$value}fail} |
| 27291 | accept senders = ${lookup{$host_name}lsearch\ |
| 27292 | {/some/file}{$value}{}} |
| 27293 | .endd |
| 27294 | Each attempts to look up a list of acceptable senders. If the lookup succeeds, |
| 27295 | the returned list is searched, but if the lookup fails the behaviour is |
| 27296 | different in the two cases. The &%fail%& in the first statement causes the |
| 27297 | condition to be ignored, leaving no further conditions. The &%accept%& verb |
| 27298 | therefore succeeds. The second statement, however, generates an empty list when |
| 27299 | the lookup fails. No sender can match an empty list, so the condition fails, |
| 27300 | and therefore the &%accept%& also fails. |
| 27301 | |
| 27302 | ACL modifiers appear mixed in with conditions in ACL statements. Some of them |
| 27303 | specify actions that are taken as the conditions for a statement are checked; |
| 27304 | others specify text for messages that are used when access is denied or a |
| 27305 | warning is generated. The &%control%& modifier affects the way an incoming |
| 27306 | message is handled. |
| 27307 | |
| 27308 | The positioning of the modifiers in an ACL statement is important, because the |
| 27309 | processing of a verb ceases as soon as its outcome is known. Only those |
| 27310 | modifiers that have already been encountered will take effect. For example, |
| 27311 | consider this use of the &%message%& modifier: |
| 27312 | .code |
| 27313 | require message = Can't verify sender |
| 27314 | verify = sender |
| 27315 | message = Can't verify recipient |
| 27316 | verify = recipient |
| 27317 | message = This message cannot be used |
| 27318 | .endd |
| 27319 | If sender verification fails, Exim knows that the result of the statement is |
| 27320 | &"deny"&, so it goes no further. The first &%message%& modifier has been seen, |
| 27321 | so its text is used as the error message. If sender verification succeeds, but |
| 27322 | recipient verification fails, the second message is used. If recipient |
| 27323 | verification succeeds, the third message becomes &"current"&, but is never used |
| 27324 | because there are no more conditions to cause failure. |
| 27325 | |
| 27326 | For the &%deny%& verb, on the other hand, it is always the last &%message%& |
| 27327 | modifier that is used, because all the conditions must be true for rejection to |
| 27328 | happen. Specifying more than one &%message%& modifier does not make sense, and |
| 27329 | the message can even be specified after all the conditions. For example: |
| 27330 | .code |
| 27331 | deny hosts = ... |
| 27332 | !senders = *@my.domain.example |
| 27333 | message = Invalid sender from client host |
| 27334 | .endd |
| 27335 | The &"deny"& result does not happen until the end of the statement is reached, |
| 27336 | by which time Exim has set up the message. |
| 27337 | |
| 27338 | |
| 27339 | |
| 27340 | .section "ACL modifiers" "SECTACLmodi" |
| 27341 | .cindex "&ACL;" "modifiers; list of" |
| 27342 | The ACL modifiers are as follows: |
| 27343 | |
| 27344 | .vlist |
| 27345 | .vitem &*add_header*&&~=&~<&'text'&> |
| 27346 | This modifier specifies one or more header lines that are to be added to an |
| 27347 | incoming message, assuming, of course, that the message is ultimately |
| 27348 | accepted. For details, see section &<<SECTaddheadacl>>&. |
| 27349 | |
| 27350 | .vitem &*continue*&&~=&~<&'text'&> |
| 27351 | .cindex "&%continue%& ACL modifier" |
| 27352 | .cindex "database" "updating in ACL" |
| 27353 | This modifier does nothing of itself, and processing of the ACL always |
| 27354 | continues with the next condition or modifier. The value of &%continue%& is in |
| 27355 | the side effects of expanding its argument. Typically this could be used to |
| 27356 | update a database. It is really just a syntactic tidiness, to avoid having to |
| 27357 | write rather ugly lines like this: |
| 27358 | .display |
| 27359 | &`condition = ${if eq{0}{`&<&'some expansion'&>&`}{true}{true}}`& |
| 27360 | .endd |
| 27361 | Instead, all you need is |
| 27362 | .display |
| 27363 | &`continue = `&<&'some expansion'&> |
| 27364 | .endd |
| 27365 | |
| 27366 | .vitem &*control*&&~=&~<&'text'&> |
| 27367 | .cindex "&%control%& ACL modifier" |
| 27368 | This modifier affects the subsequent processing of the SMTP connection or of an |
| 27369 | incoming message that is accepted. The effect of the first type of control |
| 27370 | lasts for the duration of the connection, whereas the effect of the second type |
| 27371 | lasts only until the current message has been received. The message-specific |
| 27372 | controls always apply to the whole message, not to individual recipients, |
| 27373 | even if the &%control%& modifier appears in a RCPT ACL. |
| 27374 | |
| 27375 | As there are now quite a few controls that can be applied, they are described |
| 27376 | separately in section &<<SECTcontrols>>&. The &%control%& modifier can be used |
| 27377 | in several different ways. For example: |
| 27378 | |
| 27379 | . ==== As this is a nested list, any displays it contains must be indented |
| 27380 | . ==== as otherwise they are too far to the left. That comment applies only |
| 27381 | . ==== when xmlto and fop are used; formatting with sdop gets it right either |
| 27382 | . ==== way. |
| 27383 | |
| 27384 | .ilist |
| 27385 | It can be at the end of an &%accept%& statement: |
| 27386 | .code |
| 27387 | accept ...some conditions |
| 27388 | control = queue_only |
| 27389 | .endd |
| 27390 | In this case, the control is applied when this statement yields &"accept"&, in |
| 27391 | other words, when the conditions are all true. |
| 27392 | |
| 27393 | .next |
| 27394 | It can be in the middle of an &%accept%& statement: |
| 27395 | .code |
| 27396 | accept ...some conditions... |
| 27397 | control = queue_only |
| 27398 | ...some more conditions... |
| 27399 | .endd |
| 27400 | If the first set of conditions are true, the control is applied, even if the |
| 27401 | statement does not accept because one of the second set of conditions is false. |
| 27402 | In this case, some subsequent statement must yield &"accept"& for the control |
| 27403 | to be relevant. |
| 27404 | |
| 27405 | .next |
| 27406 | It can be used with &%warn%& to apply the control, leaving the |
| 27407 | decision about accepting or denying to a subsequent verb. For |
| 27408 | example: |
| 27409 | .code |
| 27410 | warn ...some conditions... |
| 27411 | control = freeze |
| 27412 | accept ... |
| 27413 | .endd |
| 27414 | This example of &%warn%& does not contain &%message%&, &%log_message%&, or |
| 27415 | &%logwrite%&, so it does not add anything to the message and does not write a |
| 27416 | log entry. |
| 27417 | |
| 27418 | .next |
| 27419 | If you want to apply a control unconditionally, you can use it with a |
| 27420 | &%require%& verb. For example: |
| 27421 | .code |
| 27422 | require control = no_multiline_responses |
| 27423 | .endd |
| 27424 | .endlist |
| 27425 | |
| 27426 | .vitem &*delay*&&~=&~<&'time'&> |
| 27427 | .cindex "&%delay%& ACL modifier" |
| 27428 | .oindex "&%-bh%&" |
| 27429 | This modifier may appear in any ACL except notquit. It causes Exim to wait for |
| 27430 | the time interval before proceeding. However, when testing Exim using the |
| 27431 | &%-bh%& option, the delay is not actually imposed (an appropriate message is |
| 27432 | output instead). The time is given in the usual Exim notation, and the delay |
| 27433 | happens as soon as the modifier is processed. In an SMTP session, pending |
| 27434 | output is flushed before the delay is imposed. |
| 27435 | |
| 27436 | Like &%control%&, &%delay%& can be used with &%accept%& or &%deny%&, for |
| 27437 | example: |
| 27438 | .code |
| 27439 | deny ...some conditions... |
| 27440 | delay = 30s |
| 27441 | .endd |
| 27442 | The delay happens if all the conditions are true, before the statement returns |
| 27443 | &"deny"&. Compare this with: |
| 27444 | .code |
| 27445 | deny delay = 30s |
| 27446 | ...some conditions... |
| 27447 | .endd |
| 27448 | which waits for 30s before processing the conditions. The &%delay%& modifier |
| 27449 | can also be used with &%warn%& and together with &%control%&: |
| 27450 | .code |
| 27451 | warn ...some conditions... |
| 27452 | delay = 2m |
| 27453 | control = freeze |
| 27454 | accept ... |
| 27455 | .endd |
| 27456 | |
| 27457 | If &%delay%& is encountered when the SMTP PIPELINING extension is in use, |
| 27458 | responses to several commands are no longer buffered and sent in one packet (as |
| 27459 | they would normally be) because all output is flushed before imposing the |
| 27460 | delay. This optimization is disabled so that a number of small delays do not |
| 27461 | appear to the client as one large aggregated delay that might provoke an |
| 27462 | unwanted timeout. You can, however, disable output flushing for &%delay%& by |
| 27463 | using a &%control%& modifier to set &%no_delay_flush%&. |
| 27464 | |
| 27465 | |
| 27466 | .vitem &*endpass*& |
| 27467 | .cindex "&%endpass%& ACL modifier" |
| 27468 | This modifier, which has no argument, is recognized only in &%accept%& and |
| 27469 | &%discard%& statements. It marks the boundary between the conditions whose |
| 27470 | failure causes control to pass to the next statement, and the conditions whose |
| 27471 | failure causes the ACL to return &"deny"&. This concept has proved to be |
| 27472 | confusing to some people, so the use of &%endpass%& is no longer recommended as |
| 27473 | &"best practice"&. See the description of &%accept%& above for more details. |
| 27474 | |
| 27475 | |
| 27476 | .vitem &*log_message*&&~=&~<&'text'&> |
| 27477 | .cindex "&%log_message%& ACL modifier" |
| 27478 | This modifier sets up a message that is used as part of the log message if the |
| 27479 | ACL denies access or a &%warn%& statement's conditions are true. For example: |
| 27480 | .code |
| 27481 | require log_message = wrong cipher suite $tls_in_cipher |
| 27482 | encrypted = DES-CBC3-SHA |
| 27483 | .endd |
| 27484 | &%log_message%& is also used when recipients are discarded by &%discard%&. For |
| 27485 | example: |
| 27486 | .display |
| 27487 | &`discard `&<&'some conditions'&> |
| 27488 | &` log_message = Discarded $local_part@$domain because...`& |
| 27489 | .endd |
| 27490 | When access is denied, &%log_message%& adds to any underlying error message |
| 27491 | that may exist because of a condition failure. For example, while verifying a |
| 27492 | recipient address, a &':fail:'& redirection might have already set up a |
| 27493 | message. |
| 27494 | |
| 27495 | The message may be defined before the conditions to which it applies, because |
| 27496 | the string expansion does not happen until Exim decides that access is to be |
| 27497 | denied. This means that any variables that are set by the condition are |
| 27498 | available for inclusion in the message. For example, the &$dnslist_$&<&'xxx'&> |
| 27499 | variables are set after a DNS black list lookup succeeds. If the expansion of |
| 27500 | &%log_message%& fails, or if the result is an empty string, the modifier is |
| 27501 | ignored. |
| 27502 | |
| 27503 | .vindex "&$acl_verify_message$&" |
| 27504 | If you want to use a &%warn%& statement to log the result of an address |
| 27505 | verification, you can use &$acl_verify_message$& to include the verification |
| 27506 | error message. |
| 27507 | |
| 27508 | If &%log_message%& is used with a &%warn%& statement, &"Warning:"& is added to |
| 27509 | the start of the logged message. If the same warning log message is requested |
| 27510 | more than once while receiving a single email message, only one copy is |
| 27511 | actually logged. If you want to log multiple copies, use &%logwrite%& instead |
| 27512 | of &%log_message%&. In the absence of &%log_message%& and &%logwrite%&, nothing |
| 27513 | is logged for a successful &%warn%& statement. |
| 27514 | |
| 27515 | If &%log_message%& is not present and there is no underlying error message (for |
| 27516 | example, from the failure of address verification), but &%message%& is present, |
| 27517 | the &%message%& text is used for logging rejections. However, if any text for |
| 27518 | logging contains newlines, only the first line is logged. In the absence of |
| 27519 | both &%log_message%& and &%message%&, a default built-in message is used for |
| 27520 | logging rejections. |
| 27521 | |
| 27522 | |
| 27523 | .vitem "&*log_reject_target*&&~=&~<&'log name list'&>" |
| 27524 | .cindex "&%log_reject_target%& ACL modifier" |
| 27525 | .cindex "logging in ACL" "specifying which log" |
| 27526 | This modifier makes it possible to specify which logs are used for messages |
| 27527 | about ACL rejections. Its argument is a colon-separated list of words that can |
| 27528 | be &"main"&, &"reject"&, or &"panic"&. The default is &`main:reject`&. The list |
| 27529 | may be empty, in which case a rejection is not logged at all. For example, this |
| 27530 | ACL fragment writes no logging information when access is denied: |
| 27531 | .display |
| 27532 | &`deny `&<&'some conditions'&> |
| 27533 | &` log_reject_target =`& |
| 27534 | .endd |
| 27535 | This modifier can be used in SMTP and non-SMTP ACLs. It applies to both |
| 27536 | permanent and temporary rejections. Its effect lasts for the rest of the |
| 27537 | current ACL. |
| 27538 | |
| 27539 | |
| 27540 | .vitem &*logwrite*&&~=&~<&'text'&> |
| 27541 | .cindex "&%logwrite%& ACL modifier" |
| 27542 | .cindex "logging in ACL" "immediate" |
| 27543 | This modifier writes a message to a log file as soon as it is encountered when |
| 27544 | processing an ACL. (Compare &%log_message%&, which, except in the case of |
| 27545 | &%warn%& and &%discard%&, is used only if the ACL statement denies |
| 27546 | access.) The &%logwrite%& modifier can be used to log special incidents in |
| 27547 | ACLs. For example: |
| 27548 | .display |
| 27549 | &`accept `&<&'some special conditions'&> |
| 27550 | &` control = freeze`& |
| 27551 | &` logwrite = froze message because ...`& |
| 27552 | .endd |
| 27553 | By default, the message is written to the main log. However, it may begin |
| 27554 | with a colon, followed by a comma-separated list of log names, and then |
| 27555 | another colon, to specify exactly which logs are to be written. For |
| 27556 | example: |
| 27557 | .code |
| 27558 | logwrite = :main,reject: text for main and reject logs |
| 27559 | logwrite = :panic: text for panic log only |
| 27560 | .endd |
| 27561 | |
| 27562 | |
| 27563 | .vitem &*message*&&~=&~<&'text'&> |
| 27564 | .cindex "&%message%& ACL modifier" |
| 27565 | This modifier sets up a text string that is expanded and used as a response |
| 27566 | message when an ACL statement terminates the ACL with an &"accept"&, &"deny"&, |
| 27567 | or &"defer"& response. (In the case of the &%accept%& and &%discard%& verbs, |
| 27568 | there is some complication if &%endpass%& is involved; see the description of |
| 27569 | &%accept%& for details.) |
| 27570 | |
| 27571 | The expansion of the message happens at the time Exim decides that the ACL is |
| 27572 | to end, not at the time it processes &%message%&. If the expansion fails, or |
| 27573 | generates an empty string, the modifier is ignored. Here is an example where |
| 27574 | &%message%& must be specified first, because the ACL ends with a rejection if |
| 27575 | the &%hosts%& condition fails: |
| 27576 | .code |
| 27577 | require message = Host not recognized |
| 27578 | hosts = 10.0.0.0/8 |
| 27579 | .endd |
| 27580 | (Once a condition has failed, no further conditions or modifiers are |
| 27581 | processed.) |
| 27582 | |
| 27583 | .cindex "SMTP" "error codes" |
| 27584 | .oindex "&%smtp_banner%& |
| 27585 | For ACLs that are triggered by SMTP commands, the message is returned as part |
| 27586 | of the SMTP response. The use of &%message%& with &%accept%& (or &%discard%&) |
| 27587 | is meaningful only for SMTP, as no message is returned when a non-SMTP message |
| 27588 | is accepted. In the case of the connect ACL, accepting with a message modifier |
| 27589 | overrides the value of &%smtp_banner%&. For the EHLO/HELO ACL, a customized |
| 27590 | accept message may not contain more than one line (otherwise it will be |
| 27591 | truncated at the first newline and a panic logged), and it cannot affect the |
| 27592 | EHLO options. |
| 27593 | |
| 27594 | When SMTP is involved, the message may begin with an overriding response code, |
| 27595 | consisting of three digits optionally followed by an &"extended response code"& |
| 27596 | of the form &'n.n.n'&, each code being followed by a space. For example: |
| 27597 | .code |
| 27598 | deny message = 599 1.2.3 Host not welcome |
| 27599 | hosts = 192.168.34.0/24 |
| 27600 | .endd |
| 27601 | The first digit of the supplied response code must be the same as would be sent |
| 27602 | by default. A panic occurs if it is not. Exim uses a 550 code when it denies |
| 27603 | access, but for the predata ACL, note that the default success code is 354, not |
| 27604 | 2&'xx'&. |
| 27605 | |
| 27606 | Notwithstanding the previous paragraph, for the QUIT ACL, unlike the others, |
| 27607 | the message modifier cannot override the 221 response code. |
| 27608 | |
| 27609 | The text in a &%message%& modifier is literal; any quotes are taken as |
| 27610 | literals, but because the string is expanded, backslash escapes are processed |
| 27611 | anyway. If the message contains newlines, this gives rise to a multi-line SMTP |
| 27612 | response. |
| 27613 | |
| 27614 | .vindex "&$acl_verify_message$&" |
| 27615 | If &%message%& is used on a statement that verifies an address, the message |
| 27616 | specified overrides any message that is generated by the verification process. |
| 27617 | However, the original message is available in the variable |
| 27618 | &$acl_verify_message$&, so you can incorporate it into your message if you |
| 27619 | wish. In particular, if you want the text from &%:fail:%& items in &(redirect)& |
| 27620 | routers to be passed back as part of the SMTP response, you should either not |
| 27621 | use a &%message%& modifier, or make use of &$acl_verify_message$&. |
| 27622 | |
| 27623 | For compatibility with previous releases of Exim, a &%message%& modifier that |
| 27624 | is used with a &%warn%& verb behaves in a similar way to the &%add_header%& |
| 27625 | modifier, but this usage is now deprecated. However, &%message%& acts only when |
| 27626 | all the conditions are true, wherever it appears in an ACL command, whereas |
| 27627 | &%add_header%& acts as soon as it is encountered. If &%message%& is used with |
| 27628 | &%warn%& in an ACL that is not concerned with receiving a message, it has no |
| 27629 | effect. |
| 27630 | |
| 27631 | |
| 27632 | .vitem &*remove_header*&&~=&~<&'text'&> |
| 27633 | This modifier specifies one or more header names in a colon-separated list |
| 27634 | that are to be removed from an incoming message, assuming, of course, that |
| 27635 | the message is ultimately accepted. For details, see section &<<SECTremoveheadacl>>&. |
| 27636 | |
| 27637 | |
| 27638 | .vitem &*set*&&~<&'acl_name'&>&~=&~<&'value'&> |
| 27639 | .cindex "&%set%& ACL modifier" |
| 27640 | This modifier puts a value into one of the ACL variables (see section |
| 27641 | &<<SECTaclvariables>>&). |
| 27642 | |
| 27643 | |
| 27644 | .vitem &*udpsend*&&~=&~<&'parameters'&> |
| 27645 | This modifier sends a UDP packet, for purposes such as statistics |
| 27646 | collection or behaviour monitoring. The parameters are expanded, and |
| 27647 | the result of the expansion must be a colon-separated list consisting |
| 27648 | of a destination server, port number, and the packet contents. The |
| 27649 | server can be specified as a host name or IPv4 or IPv6 address. The |
| 27650 | separator can be changed with the usual angle bracket syntax. For |
| 27651 | example, you might want to collect information on which hosts connect |
| 27652 | when: |
| 27653 | .code |
| 27654 | udpsend = <; 2001:dB8::dead:beef ; 1234 ;\ |
| 27655 | $tod_zulu $sender_host_address |
| 27656 | .endd |
| 27657 | .endlist |
| 27658 | |
| 27659 | |
| 27660 | |
| 27661 | |
| 27662 | .section "Use of the control modifier" "SECTcontrols" |
| 27663 | .cindex "&%control%& ACL modifier" |
| 27664 | The &%control%& modifier supports the following settings: |
| 27665 | |
| 27666 | .vlist |
| 27667 | .vitem &*control&~=&~allow_auth_unadvertised*& |
| 27668 | This modifier allows a client host to use the SMTP AUTH command even when it |
| 27669 | has not been advertised in response to EHLO. Furthermore, because there are |
| 27670 | apparently some really broken clients that do this, Exim will accept AUTH after |
| 27671 | HELO (rather than EHLO) when this control is set. It should be used only if you |
| 27672 | really need it, and you should limit its use to those broken clients that do |
| 27673 | not work without it. For example: |
| 27674 | .code |
| 27675 | warn hosts = 192.168.34.25 |
| 27676 | control = allow_auth_unadvertised |
| 27677 | .endd |
| 27678 | Normally, when an Exim server receives an AUTH command, it checks the name of |
| 27679 | the authentication mechanism that is given in the command to ensure that it |
| 27680 | matches an advertised mechanism. When this control is set, the check that a |
| 27681 | mechanism has been advertised is bypassed. Any configured mechanism can be used |
| 27682 | by the client. This control is permitted only in the connection and HELO ACLs. |
| 27683 | |
| 27684 | |
| 27685 | .vitem &*control&~=&~caseful_local_part*& &&& |
| 27686 | &*control&~=&~caselower_local_part*& |
| 27687 | .cindex "&ACL;" "case of local part in" |
| 27688 | .cindex "case of local parts" |
| 27689 | .vindex "&$local_part$&" |
| 27690 | These two controls are permitted only in the ACL specified by &%acl_smtp_rcpt%& |
| 27691 | (that is, during RCPT processing). By default, the contents of &$local_part$& |
| 27692 | are lower cased before ACL processing. If &"caseful_local_part"& is specified, |
| 27693 | any uppercase letters in the original local part are restored in &$local_part$& |
| 27694 | for the rest of the ACL, or until a control that sets &"caselower_local_part"& |
| 27695 | is encountered. |
| 27696 | |
| 27697 | These controls affect only the current recipient. Moreover, they apply only to |
| 27698 | local part handling that takes place directly in the ACL (for example, as a key |
| 27699 | in lookups). If a test to verify the recipient is obeyed, the case-related |
| 27700 | handling of the local part during the verification is controlled by the router |
| 27701 | configuration (see the &%caseful_local_part%& generic router option). |
| 27702 | |
| 27703 | This facility could be used, for example, to add a spam score to local parts |
| 27704 | containing upper case letters. For example, using &$acl_m4$& to accumulate the |
| 27705 | spam score: |
| 27706 | .code |
| 27707 | warn control = caseful_local_part |
| 27708 | set acl_m4 = ${eval:\ |
| 27709 | $acl_m4 + \ |
| 27710 | ${if match{$local_part}{[A-Z]}{1}{0}}\ |
| 27711 | } |
| 27712 | control = caselower_local_part |
| 27713 | .endd |
| 27714 | Notice that we put back the lower cased version afterwards, assuming that |
| 27715 | is what is wanted for subsequent tests. |
| 27716 | |
| 27717 | |
| 27718 | .vitem &*control&~=&~cutthrough_delivery*& |
| 27719 | .cindex "&ACL;" "cutthrough routing" |
| 27720 | .cindex "cutthrough" "requesting" |
| 27721 | This option requests delivery be attempted while the item is being received. |
| 27722 | It is usable in the RCPT ACL and valid only for single-recipient mails forwarded |
| 27723 | from one SMTP connection to another. If a recipient-verify callout connection is |
| 27724 | requested in the same ACL it is held open and used for the data, otherwise one is made |
| 27725 | after the ACL completes. |
| 27726 | |
| 27727 | Note that routers are used in verify mode, |
| 27728 | and cannot depend on content of received headers. |
| 27729 | Note also that headers cannot be |
| 27730 | modified by any of the post-data ACLs (DATA, MIME and DKIM). |
| 27731 | Headers may be modified by routers (subject to the above) and transports. |
| 27732 | |
| 27733 | Cutthrough delivery is not supported via transport-filters or when DKIM signing |
| 27734 | of outgoing messages is done, because it sends data to the ultimate destination |
| 27735 | before the entire message has been received from the source. |
| 27736 | |
| 27737 | Should the ultimate destination system positively accept or reject the mail, |
| 27738 | a corresponding indication is given to the source system and nothing is queued. |
| 27739 | If there is a temporary error the item is queued for later delivery in the |
| 27740 | usual fashion. If the item is successfully delivered in cutthrough mode the log line |
| 27741 | is tagged with ">>" rather than "=>" and appears before the acceptance "<=" |
| 27742 | line. |
| 27743 | |
| 27744 | Delivery in this mode avoids the generation of a bounce mail to a (possibly faked) |
| 27745 | sender when the destination system is doing content-scan based rejection. |
| 27746 | |
| 27747 | |
| 27748 | .vitem &*control&~=&~debug/*&<&'options'&> |
| 27749 | .cindex "&ACL;" "enabling debug logging" |
| 27750 | .cindex "debugging" "enabling from an ACL" |
| 27751 | This control turns on debug logging, almost as though Exim had been invoked |
| 27752 | with &`-d`&, with the output going to a new logfile, by default called |
| 27753 | &'debuglog'&. The filename can be adjusted with the &'tag'& option, which |
| 27754 | may access any variables already defined. The logging may be adjusted with |
| 27755 | the &'opts'& option, which takes the same values as the &`-d`& command-line |
| 27756 | option. Some examples (which depend on variables that don't exist in all |
| 27757 | contexts): |
| 27758 | .code |
| 27759 | control = debug |
| 27760 | control = debug/tag=.$sender_host_address |
| 27761 | control = debug/opts=+expand+acl |
| 27762 | control = debug/tag=.$message_exim_id/opts=+expand |
| 27763 | .endd |
| 27764 | |
| 27765 | |
| 27766 | .vitem &*control&~=&~dkim_disable_verify*& |
| 27767 | .cindex "disable DKIM verify" |
| 27768 | .cindex "DKIM" "disable verify" |
| 27769 | This control turns off DKIM verification processing entirely. For details on |
| 27770 | the operation and configuration of DKIM, see chapter &<<CHAPdkim>>&. |
| 27771 | |
| 27772 | |
| 27773 | .vitem &*control&~=&~dscp/*&<&'value'&> |
| 27774 | .cindex "&ACL;" "setting DSCP value" |
| 27775 | .cindex "DSCP" "inbound" |
| 27776 | This option causes the DSCP value associated with the socket for the inbound |
| 27777 | connection to be adjusted to a given value, given as one of a number of fixed |
| 27778 | strings or to numeric value. |
| 27779 | The &%-bI:dscp%& option may be used to ask Exim which names it knows of. |
| 27780 | Common values include &`throughput`&, &`mincost`&, and on newer systems |
| 27781 | &`ef`&, &`af41`&, etc. Numeric values may be in the range 0 to 0x3F. |
| 27782 | |
| 27783 | The outbound packets from Exim will be marked with this value in the header |
| 27784 | (for IPv4, the TOS field; for IPv6, the TCLASS field); there is no guarantee |
| 27785 | that these values will have any effect, not be stripped by networking |
| 27786 | equipment, or do much of anything without cooperation with your Network |
| 27787 | Engineer and those of all network operators between the source and destination. |
| 27788 | |
| 27789 | |
| 27790 | .vitem &*control&~=&~enforce_sync*& &&& |
| 27791 | &*control&~=&~no_enforce_sync*& |
| 27792 | .cindex "SMTP" "synchronization checking" |
| 27793 | .cindex "synchronization checking in SMTP" |
| 27794 | These controls make it possible to be selective about when SMTP synchronization |
| 27795 | is enforced. The global option &%smtp_enforce_sync%& specifies the initial |
| 27796 | state of the switch (it is true by default). See the description of this option |
| 27797 | in chapter &<<CHAPmainconfig>>& for details of SMTP synchronization checking. |
| 27798 | |
| 27799 | The effect of these two controls lasts for the remainder of the SMTP |
| 27800 | connection. They can appear in any ACL except the one for the non-SMTP |
| 27801 | messages. The most straightforward place to put them is in the ACL defined by |
| 27802 | &%acl_smtp_connect%&, which is run at the start of an incoming SMTP connection, |
| 27803 | before the first synchronization check. The expected use is to turn off the |
| 27804 | synchronization checks for badly-behaved hosts that you nevertheless need to |
| 27805 | work with. |
| 27806 | |
| 27807 | |
| 27808 | .vitem &*control&~=&~fakedefer/*&<&'message'&> |
| 27809 | .cindex "fake defer" |
| 27810 | .cindex "defer, fake" |
| 27811 | This control works in exactly the same way as &%fakereject%& (described below) |
| 27812 | except that it causes an SMTP 450 response after the message data instead of a |
| 27813 | 550 response. You must take care when using &%fakedefer%& because it causes the |
| 27814 | messages to be duplicated when the sender retries. Therefore, you should not |
| 27815 | use &%fakedefer%& if the message is to be delivered normally. |
| 27816 | |
| 27817 | .vitem &*control&~=&~fakereject/*&<&'message'&> |
| 27818 | .cindex "fake rejection" |
| 27819 | .cindex "rejection, fake" |
| 27820 | This control is permitted only for the MAIL, RCPT, and DATA ACLs, in other |
| 27821 | words, only when an SMTP message is being received. If Exim accepts the |
| 27822 | message, instead the final 250 response, a 550 rejection message is sent. |
| 27823 | However, Exim proceeds to deliver the message as normal. The control applies |
| 27824 | only to the current message, not to any subsequent ones that may be received in |
| 27825 | the same SMTP connection. |
| 27826 | |
| 27827 | The text for the 550 response is taken from the &%control%& modifier. If no |
| 27828 | message is supplied, the following is used: |
| 27829 | .code |
| 27830 | 550-Your message has been rejected but is being |
| 27831 | 550-kept for evaluation. |
| 27832 | 550-If it was a legitimate message, it may still be |
| 27833 | 550 delivered to the target recipient(s). |
| 27834 | .endd |
| 27835 | This facility should be used with extreme caution. |
| 27836 | |
| 27837 | .vitem &*control&~=&~freeze*& |
| 27838 | .cindex "frozen messages" "forcing in ACL" |
| 27839 | This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs, in |
| 27840 | other words, only when a message is being received. If the message is accepted, |
| 27841 | it is placed on Exim's queue and frozen. The control applies only to the |
| 27842 | current message, not to any subsequent ones that may be received in the same |
| 27843 | SMTP connection. |
| 27844 | |
| 27845 | This modifier can optionally be followed by &`/no_tell`&. If the global option |
| 27846 | &%freeze_tell%& is set, it is ignored for the current message (that is, nobody |
| 27847 | is told about the freezing), provided all the &*control=freeze*& modifiers that |
| 27848 | are obeyed for the current message have the &`/no_tell`& option. |
| 27849 | |
| 27850 | .vitem &*control&~=&~no_delay_flush*& |
| 27851 | .cindex "SMTP" "output flushing, disabling for delay" |
| 27852 | Exim normally flushes SMTP output before implementing a delay in an ACL, to |
| 27853 | avoid unexpected timeouts in clients when the SMTP PIPELINING extension is in |
| 27854 | use. This control, as long as it is encountered before the &%delay%& modifier, |
| 27855 | disables such output flushing. |
| 27856 | |
| 27857 | .vitem &*control&~=&~no_callout_flush*& |
| 27858 | .cindex "SMTP" "output flushing, disabling for callout" |
| 27859 | Exim normally flushes SMTP output before performing a callout in an ACL, to |
| 27860 | avoid unexpected timeouts in clients when the SMTP PIPELINING extension is in |
| 27861 | use. This control, as long as it is encountered before the &%verify%& condition |
| 27862 | that causes the callout, disables such output flushing. |
| 27863 | |
| 27864 | .vitem &*control&~=&~no_mbox_unspool*& |
| 27865 | This control is available when Exim is compiled with the content scanning |
| 27866 | extension. Content scanning may require a copy of the current message, or parts |
| 27867 | of it, to be written in &"mbox format"& to a spool file, for passing to a virus |
| 27868 | or spam scanner. Normally, such copies are deleted when they are no longer |
| 27869 | needed. If this control is set, the copies are not deleted. The control applies |
| 27870 | only to the current message, not to any subsequent ones that may be received in |
| 27871 | the same SMTP connection. It is provided for debugging purposes and is unlikely |
| 27872 | to be useful in production. |
| 27873 | |
| 27874 | .vitem &*control&~=&~no_multiline_responses*& |
| 27875 | .cindex "multiline responses, suppressing" |
| 27876 | This control is permitted for any ACL except the one for non-SMTP messages. |
| 27877 | It seems that there are broken clients in use that cannot handle multiline |
| 27878 | SMTP responses, despite the fact that RFC 821 defined them over 20 years ago. |
| 27879 | |
| 27880 | If this control is set, multiline SMTP responses from ACL rejections are |
| 27881 | suppressed. One way of doing this would have been to put out these responses as |
| 27882 | one long line. However, RFC 2821 specifies a maximum of 512 bytes per response |
| 27883 | (&"use multiline responses for more"& it says &-- ha!), and some of the |
| 27884 | responses might get close to that. So this facility, which is after all only a |
| 27885 | sop to broken clients, is implemented by doing two very easy things: |
| 27886 | |
| 27887 | .ilist |
| 27888 | Extra information that is normally output as part of a rejection caused by |
| 27889 | sender verification failure is omitted. Only the final line (typically &"sender |
| 27890 | verification failed"&) is sent. |
| 27891 | .next |
| 27892 | If a &%message%& modifier supplies a multiline response, only the first |
| 27893 | line is output. |
| 27894 | .endlist |
| 27895 | |
| 27896 | The setting of the switch can, of course, be made conditional on the |
| 27897 | calling host. Its effect lasts until the end of the SMTP connection. |
| 27898 | |
| 27899 | .vitem &*control&~=&~no_pipelining*& |
| 27900 | .cindex "PIPELINING" "suppressing advertising" |
| 27901 | This control turns off the advertising of the PIPELINING extension to SMTP in |
| 27902 | the current session. To be useful, it must be obeyed before Exim sends its |
| 27903 | response to an EHLO command. Therefore, it should normally appear in an ACL |
| 27904 | controlled by &%acl_smtp_connect%& or &%acl_smtp_helo%&. See also |
| 27905 | &%pipelining_advertise_hosts%&. |
| 27906 | |
| 27907 | .vitem &*control&~=&~queue_only*& |
| 27908 | .oindex "&%queue_only%&" |
| 27909 | .cindex "queueing incoming messages" |
| 27910 | This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs, in |
| 27911 | other words, only when a message is being received. If the message is accepted, |
| 27912 | it is placed on Exim's queue and left there for delivery by a subsequent queue |
| 27913 | runner. No immediate delivery process is started. In other words, it has the |
| 27914 | effect as the &%queue_only%& global option. However, the control applies only |
| 27915 | to the current message, not to any subsequent ones that may be received in the |
| 27916 | same SMTP connection. |
| 27917 | |
| 27918 | .vitem &*control&~=&~submission/*&<&'options'&> |
| 27919 | .cindex "message" "submission" |
| 27920 | .cindex "submission mode" |
| 27921 | This control is permitted only for the MAIL, RCPT, and start of data ACLs (the |
| 27922 | latter is the one defined by &%acl_smtp_predata%&). Setting it tells Exim that |
| 27923 | the current message is a submission from a local MUA. In this case, Exim |
| 27924 | operates in &"submission mode"&, and applies certain fixups to the message if |
| 27925 | necessary. For example, it adds a &'Date:'& header line if one is not present. |
| 27926 | This control is not permitted in the &%acl_smtp_data%& ACL, because that is too |
| 27927 | late (the message has already been created). |
| 27928 | |
| 27929 | Chapter &<<CHAPmsgproc>>& describes the processing that Exim applies to |
| 27930 | messages. Section &<<SECTsubmodnon>>& covers the processing that happens in |
| 27931 | submission mode; the available options for this control are described there. |
| 27932 | The control applies only to the current message, not to any subsequent ones |
| 27933 | that may be received in the same SMTP connection. |
| 27934 | |
| 27935 | .vitem &*control&~=&~suppress_local_fixups*& |
| 27936 | .cindex "submission fixups, suppressing" |
| 27937 | This control applies to locally submitted (non TCP/IP) messages, and is the |
| 27938 | complement of &`control = submission`&. It disables the fixups that are |
| 27939 | normally applied to locally-submitted messages. Specifically: |
| 27940 | |
| 27941 | .ilist |
| 27942 | Any &'Sender:'& header line is left alone (in this respect, it is a |
| 27943 | dynamic version of &%local_sender_retain%&). |
| 27944 | .next |
| 27945 | No &'Message-ID:'&, &'From:'&, or &'Date:'& header lines are added. |
| 27946 | .next |
| 27947 | There is no check that &'From:'& corresponds to the actual sender. |
| 27948 | .endlist ilist |
| 27949 | |
| 27950 | This control may be useful when a remotely-originated message is accepted, |
| 27951 | passed to some scanning program, and then re-submitted for delivery. It can be |
| 27952 | used only in the &%acl_smtp_mail%&, &%acl_smtp_rcpt%&, &%acl_smtp_predata%&, |
| 27953 | and &%acl_not_smtp_start%& ACLs, because it has to be set before the message's |
| 27954 | data is read. |
| 27955 | |
| 27956 | &*Note:*& This control applies only to the current message, not to any others |
| 27957 | that are being submitted at the same time using &%-bs%& or &%-bS%&. |
| 27958 | .endlist vlist |
| 27959 | |
| 27960 | |
| 27961 | .section "Summary of message fixup control" "SECTsummesfix" |
| 27962 | All four possibilities for message fixups can be specified: |
| 27963 | |
| 27964 | .ilist |
| 27965 | Locally submitted, fixups applied: the default. |
| 27966 | .next |
| 27967 | Locally submitted, no fixups applied: use |
| 27968 | &`control = suppress_local_fixups`&. |
| 27969 | .next |
| 27970 | Remotely submitted, no fixups applied: the default. |
| 27971 | .next |
| 27972 | Remotely submitted, fixups applied: use &`control = submission`&. |
| 27973 | .endlist |
| 27974 | |
| 27975 | |
| 27976 | |
| 27977 | .section "Adding header lines in ACLs" "SECTaddheadacl" |
| 27978 | .cindex "header lines" "adding in an ACL" |
| 27979 | .cindex "header lines" "position of added lines" |
| 27980 | .cindex "&%add_header%& ACL modifier" |
| 27981 | The &%add_header%& modifier can be used to add one or more extra header lines |
| 27982 | to an incoming message, as in this example: |
| 27983 | .code |
| 27984 | warn dnslists = sbl.spamhaus.org : \ |
| 27985 | dialup.mail-abuse.org |
| 27986 | add_header = X-blacklisted-at: $dnslist_domain |
| 27987 | .endd |
| 27988 | The &%add_header%& modifier is permitted in the MAIL, RCPT, PREDATA, DATA, |
| 27989 | MIME, DKIM, and non-SMTP ACLs (in other words, those that are concerned with |
| 27990 | receiving a message). The message must ultimately be accepted for |
| 27991 | &%add_header%& to have any significant effect. You can use &%add_header%& with |
| 27992 | any ACL verb, including &%deny%& (though this is potentially useful only in a |
| 27993 | RCPT ACL). |
| 27994 | |
| 27995 | Headers will not be added to the message if the modifier is used in |
| 27996 | DATA, MIME or DKIM ACLs for messages delivered by cutthrough routing. |
| 27997 | |
| 27998 | Leading and trailing newlines are removed from |
| 27999 | the data for the &%add_header%& modifier; if it then |
| 28000 | contains one or more newlines that |
| 28001 | are not followed by a space or a tab, it is assumed to contain multiple header |
| 28002 | lines. Each one is checked for valid syntax; &`X-ACL-Warn:`& is added to the |
| 28003 | front of any line that is not a valid header line. |
| 28004 | |
| 28005 | Added header lines are accumulated during the MAIL, RCPT, and predata ACLs. |
| 28006 | They are added to the message before processing the DATA and MIME ACLs. |
| 28007 | However, if an identical header line is requested more than once, only one copy |
| 28008 | is actually added to the message. Further header lines may be accumulated |
| 28009 | during the DATA and MIME ACLs, after which they are added to the message, again |
| 28010 | with duplicates suppressed. Thus, it is possible to add two identical header |
| 28011 | lines to an SMTP message, but only if one is added before DATA and one after. |
| 28012 | In the case of non-SMTP messages, new headers are accumulated during the |
| 28013 | non-SMTP ACLs, and are added to the message after all the ACLs have run. If a |
| 28014 | message is rejected after DATA or by the non-SMTP ACL, all added header lines |
| 28015 | are included in the entry that is written to the reject log. |
| 28016 | |
| 28017 | .cindex "header lines" "added; visibility of" |
| 28018 | Header lines are not visible in string expansions |
| 28019 | of message headers |
| 28020 | until they are added to the |
| 28021 | message. It follows that header lines defined in the MAIL, RCPT, and predata |
| 28022 | ACLs are not visible until the DATA ACL and MIME ACLs are run. Similarly, |
| 28023 | header lines that are added by the DATA or MIME ACLs are not visible in those |
| 28024 | ACLs. Because of this restriction, you cannot use header lines as a way of |
| 28025 | passing data between (for example) the MAIL and RCPT ACLs. If you want to do |
| 28026 | this, you can use ACL variables, as described in section |
| 28027 | &<<SECTaclvariables>>&. |
| 28028 | |
| 28029 | The list of headers yet to be added is given by the &%$headers_added%& variable. |
| 28030 | |
| 28031 | The &%add_header%& modifier acts immediately as it is encountered during the |
| 28032 | processing of an ACL. Notice the difference between these two cases: |
| 28033 | .display |
| 28034 | &`accept add_header = ADDED: some text`& |
| 28035 | &` `&<&'some condition'&> |
| 28036 | |
| 28037 | &`accept `&<&'some condition'&> |
| 28038 | &` add_header = ADDED: some text`& |
| 28039 | .endd |
| 28040 | In the first case, the header line is always added, whether or not the |
| 28041 | condition is true. In the second case, the header line is added only if the |
| 28042 | condition is true. Multiple occurrences of &%add_header%& may occur in the same |
| 28043 | ACL statement. All those that are encountered before a condition fails are |
| 28044 | honoured. |
| 28045 | |
| 28046 | .cindex "&%warn%& ACL verb" |
| 28047 | For compatibility with previous versions of Exim, a &%message%& modifier for a |
| 28048 | &%warn%& verb acts in the same way as &%add_header%&, except that it takes |
| 28049 | effect only if all the conditions are true, even if it appears before some of |
| 28050 | them. Furthermore, only the last occurrence of &%message%& is honoured. This |
| 28051 | usage of &%message%& is now deprecated. If both &%add_header%& and &%message%& |
| 28052 | are present on a &%warn%& verb, both are processed according to their |
| 28053 | specifications. |
| 28054 | |
| 28055 | By default, new header lines are added to a message at the end of the existing |
| 28056 | header lines. However, you can specify that any particular header line should |
| 28057 | be added right at the start (before all the &'Received:'& lines), immediately |
| 28058 | after the first block of &'Received:'& lines, or immediately before any line |
| 28059 | that is not a &'Received:'& or &'Resent-something:'& header. |
| 28060 | |
| 28061 | This is done by specifying &":at_start:"&, &":after_received:"&, or |
| 28062 | &":at_start_rfc:"& (or, for completeness, &":at_end:"&) before the text of the |
| 28063 | header line, respectively. (Header text cannot start with a colon, as there has |
| 28064 | to be a header name first.) For example: |
| 28065 | .code |
| 28066 | warn add_header = \ |
| 28067 | :after_received:X-My-Header: something or other... |
| 28068 | .endd |
| 28069 | If more than one header line is supplied in a single &%add_header%& modifier, |
| 28070 | each one is treated independently and can therefore be placed differently. If |
| 28071 | you add more than one line at the start, or after the Received: block, they end |
| 28072 | up in reverse order. |
| 28073 | |
| 28074 | &*Warning*&: This facility currently applies only to header lines that are |
| 28075 | added in an ACL. It does NOT work for header lines that are added in a |
| 28076 | system filter or in a router or transport. |
| 28077 | |
| 28078 | |
| 28079 | |
| 28080 | .section "Removing header lines in ACLs" "SECTremoveheadacl" |
| 28081 | .cindex "header lines" "removing in an ACL" |
| 28082 | .cindex "header lines" "position of removed lines" |
| 28083 | .cindex "&%remove_header%& ACL modifier" |
| 28084 | The &%remove_header%& modifier can be used to remove one or more header lines |
| 28085 | from an incoming message, as in this example: |
| 28086 | .code |
| 28087 | warn message = Remove internal headers |
| 28088 | remove_header = x-route-mail1 : x-route-mail2 |
| 28089 | .endd |
| 28090 | The &%remove_header%& modifier is permitted in the MAIL, RCPT, PREDATA, DATA, |
| 28091 | MIME, DKIM, and non-SMTP ACLs (in other words, those that are concerned with |
| 28092 | receiving a message). The message must ultimately be accepted for |
| 28093 | &%remove_header%& to have any significant effect. You can use &%remove_header%& |
| 28094 | with any ACL verb, including &%deny%&, though this is really not useful for |
| 28095 | any verb that doesn't result in a delivered message. |
| 28096 | |
| 28097 | Headers will not be removed to the message if the modifier is used in |
| 28098 | DATA, MIME or DKIM ACLs for messages delivered by cutthrough routing. |
| 28099 | |
| 28100 | More than one header can be removed at the same time by using a colon separated |
| 28101 | list of header names. The header matching is case insensitive. Wildcards are |
| 28102 | not permitted, nor is list expansion performed, so you cannot use hostlists to |
| 28103 | create a list of headers, however both connection and message variable expansion |
| 28104 | are performed (&%$acl_c_*%& and &%$acl_m_*%&), illustrated in this example: |
| 28105 | .code |
| 28106 | warn hosts = +internal_hosts |
| 28107 | set acl_c_ihdrs = x-route-mail1 : x-route-mail2 |
| 28108 | warn message = Remove internal headers |
| 28109 | remove_header = $acl_c_ihdrs |
| 28110 | .endd |
| 28111 | Removed header lines are accumulated during the MAIL, RCPT, and predata ACLs. |
| 28112 | They are removed from the message before processing the DATA and MIME ACLs. |
| 28113 | There is no harm in attempting to remove the same header twice nor is removing |
| 28114 | a non-existent header. Further header lines to be removed may be accumulated |
| 28115 | during the DATA and MIME ACLs, after which they are removed from the message, |
| 28116 | if present. In the case of non-SMTP messages, headers to be removed are |
| 28117 | accumulated during the non-SMTP ACLs, and are removed from the message after |
| 28118 | all the ACLs have run. If a message is rejected after DATA or by the non-SMTP |
| 28119 | ACL, there really is no effect because there is no logging of what headers |
| 28120 | would have been removed. |
| 28121 | |
| 28122 | .cindex "header lines" "removed; visibility of" |
| 28123 | Header lines are not visible in string expansions until the DATA phase when it |
| 28124 | is received. Any header lines removed in the MAIL, RCPT, and predata ACLs are |
| 28125 | not visible in the DATA ACL and MIME ACLs. Similarly, header lines that are |
| 28126 | removed by the DATA or MIME ACLs are still visible in those ACLs. Because of |
| 28127 | this restriction, you cannot use header lines as a way of controlling data |
| 28128 | passed between (for example) the MAIL and RCPT ACLs. If you want to do this, |
| 28129 | you should instead use ACL variables, as described in section |
| 28130 | &<<SECTaclvariables>>&. |
| 28131 | |
| 28132 | The &%remove_header%& modifier acts immediately as it is encountered during the |
| 28133 | processing of an ACL. Notice the difference between these two cases: |
| 28134 | .display |
| 28135 | &`accept remove_header = X-Internal`& |
| 28136 | &` `&<&'some condition'&> |
| 28137 | |
| 28138 | &`accept `&<&'some condition'&> |
| 28139 | &` remove_header = X-Internal`& |
| 28140 | .endd |
| 28141 | In the first case, the header line is always removed, whether or not the |
| 28142 | condition is true. In the second case, the header line is removed only if the |
| 28143 | condition is true. Multiple occurrences of &%remove_header%& may occur in the |
| 28144 | same ACL statement. All those that are encountered before a condition fails |
| 28145 | are honoured. |
| 28146 | |
| 28147 | &*Warning*&: This facility currently applies only to header lines that are |
| 28148 | present during ACL processing. It does NOT remove header lines that are added |
| 28149 | in a system filter or in a router or transport. |
| 28150 | |
| 28151 | |
| 28152 | |
| 28153 | |
| 28154 | .section "ACL conditions" "SECTaclconditions" |
| 28155 | .cindex "&ACL;" "conditions; list of" |
| 28156 | Some of the conditions listed in this section are available only when Exim is |
| 28157 | compiled with the content-scanning extension. They are included here briefly |
| 28158 | for completeness. More detailed descriptions can be found in the discussion on |
| 28159 | content scanning in chapter &<<CHAPexiscan>>&. |
| 28160 | |
| 28161 | Not all conditions are relevant in all circumstances. For example, testing |
| 28162 | senders and recipients does not make sense in an ACL that is being run as the |
| 28163 | result of the arrival of an ETRN command, and checks on message headers can be |
| 28164 | done only in the ACLs specified by &%acl_smtp_data%& and &%acl_not_smtp%&. You |
| 28165 | can use the same condition (with different parameters) more than once in the |
| 28166 | same ACL statement. This provides a way of specifying an &"and"& conjunction. |
| 28167 | The conditions are as follows: |
| 28168 | |
| 28169 | |
| 28170 | .vlist |
| 28171 | .vitem &*acl&~=&~*&<&'name&~of&~acl&~or&~ACL&~string&~or&~file&~name&~'&> |
| 28172 | .cindex "&ACL;" "nested" |
| 28173 | .cindex "&ACL;" "indirect" |
| 28174 | .cindex "&ACL;" "arguments" |
| 28175 | .cindex "&%acl%& ACL condition" |
| 28176 | The possible values of the argument are the same as for the |
| 28177 | &%acl_smtp_%&&'xxx'& options. The named or inline ACL is run. If it returns |
| 28178 | &"accept"& the condition is true; if it returns &"deny"& the condition is |
| 28179 | false. If it returns &"defer"&, the current ACL returns &"defer"& unless the |
| 28180 | condition is on a &%warn%& verb. In that case, a &"defer"& return makes the |
| 28181 | condition false. This means that further processing of the &%warn%& verb |
| 28182 | ceases, but processing of the ACL continues. |
| 28183 | |
| 28184 | If the argument is a named ACL, up to nine space-separated optional values |
| 28185 | can be appended; they appear within the called ACL in $acl_arg1 to $acl_arg9, |
| 28186 | and $acl_narg is set to the count of values. |
| 28187 | Previous values of these variables are restored after the call returns. |
| 28188 | The name and values are expanded separately. |
| 28189 | |
| 28190 | If the nested &%acl%& returns &"drop"& and the outer condition denies access, |
| 28191 | the connection is dropped. If it returns &"discard"&, the verb must be |
| 28192 | &%accept%& or &%discard%&, and the action is taken immediately &-- no further |
| 28193 | conditions are tested. |
| 28194 | |
| 28195 | ACLs may be nested up to 20 deep; the limit exists purely to catch runaway |
| 28196 | loops. This condition allows you to use different ACLs in different |
| 28197 | circumstances. For example, different ACLs can be used to handle RCPT commands |
| 28198 | for different local users or different local domains. |
| 28199 | |
| 28200 | .vitem &*authenticated&~=&~*&<&'string&~list'&> |
| 28201 | .cindex "&%authenticated%& ACL condition" |
| 28202 | .cindex "authentication" "ACL checking" |
| 28203 | .cindex "&ACL;" "testing for authentication" |
| 28204 | If the SMTP connection is not authenticated, the condition is false. Otherwise, |
| 28205 | the name of the authenticator is tested against the list. To test for |
| 28206 | authentication by any authenticator, you can set |
| 28207 | .code |
| 28208 | authenticated = * |
| 28209 | .endd |
| 28210 | |
| 28211 | .vitem &*condition&~=&~*&<&'string'&> |
| 28212 | .cindex "&%condition%& ACL condition" |
| 28213 | .cindex "customizing" "ACL condition" |
| 28214 | .cindex "&ACL;" "customized test" |
| 28215 | .cindex "&ACL;" "testing, customized" |
| 28216 | This feature allows you to make up custom conditions. If the result of |
| 28217 | expanding the string is an empty string, the number zero, or one of the strings |
| 28218 | &"no"& or &"false"&, the condition is false. If the result is any non-zero |
| 28219 | number, or one of the strings &"yes"& or &"true"&, the condition is true. For |
| 28220 | any other value, some error is assumed to have occurred, and the ACL returns |
| 28221 | &"defer"&. However, if the expansion is forced to fail, the condition is |
| 28222 | ignored. The effect is to treat it as true, whether it is positive or |
| 28223 | negative. |
| 28224 | |
| 28225 | .vitem &*decode&~=&~*&<&'location'&> |
| 28226 | .cindex "&%decode%& ACL condition" |
| 28227 | This condition is available only when Exim is compiled with the |
| 28228 | content-scanning extension, and it is allowed only in the ACL defined by |
| 28229 | &%acl_smtp_mime%&. It causes the current MIME part to be decoded into a file. |
| 28230 | If all goes well, the condition is true. It is false only if there are |
| 28231 | problems such as a syntax error or a memory shortage. For more details, see |
| 28232 | chapter &<<CHAPexiscan>>&. |
| 28233 | |
| 28234 | .vitem &*demime&~=&~*&<&'extension&~list'&> |
| 28235 | .cindex "&%demime%& ACL condition" |
| 28236 | This condition is available only when Exim is compiled with the |
| 28237 | content-scanning extension. Its use is described in section |
| 28238 | &<<SECTdemimecond>>&. |
| 28239 | |
| 28240 | .vitem &*dnslists&~=&~*&<&'list&~of&~domain&~names&~and&~other&~data'&> |
| 28241 | .cindex "&%dnslists%& ACL condition" |
| 28242 | .cindex "DNS list" "in ACL" |
| 28243 | .cindex "black list (DNS)" |
| 28244 | .cindex "&ACL;" "testing a DNS list" |
| 28245 | This condition checks for entries in DNS black lists. These are also known as |
| 28246 | &"RBL lists"&, after the original Realtime Blackhole List, but note that the |
| 28247 | use of the lists at &'mail-abuse.org'& now carries a charge. There are too many |
| 28248 | different variants of this condition to describe briefly here. See sections |
| 28249 | &<<SECTmorednslists>>&&--&<<SECTmorednslistslast>>& for details. |
| 28250 | |
| 28251 | .vitem &*domains&~=&~*&<&'domain&~list'&> |
| 28252 | .cindex "&%domains%& ACL condition" |
| 28253 | .cindex "domain" "ACL checking" |
| 28254 | .cindex "&ACL;" "testing a recipient domain" |
| 28255 | .vindex "&$domain_data$&" |
| 28256 | This condition is relevant only after a RCPT command. It checks that the domain |
| 28257 | of the recipient address is in the domain list. If percent-hack processing is |
| 28258 | enabled, it is done before this test is done. If the check succeeds with a |
| 28259 | lookup, the result of the lookup is placed in &$domain_data$& until the next |
| 28260 | &%domains%& test. |
| 28261 | |
| 28262 | &*Note carefully*& (because many people seem to fall foul of this): you cannot |
| 28263 | use &%domains%& in a DATA ACL. |
| 28264 | |
| 28265 | |
| 28266 | .vitem &*encrypted&~=&~*&<&'string&~list'&> |
| 28267 | .cindex "&%encrypted%& ACL condition" |
| 28268 | .cindex "encryption" "checking in an ACL" |
| 28269 | .cindex "&ACL;" "testing for encryption" |
| 28270 | If the SMTP connection is not encrypted, the condition is false. Otherwise, the |
| 28271 | name of the cipher suite in use is tested against the list. To test for |
| 28272 | encryption without testing for any specific cipher suite(s), set |
| 28273 | .code |
| 28274 | encrypted = * |
| 28275 | .endd |
| 28276 | |
| 28277 | |
| 28278 | .vitem &*hosts&~=&~*&<&'host&~list'&> |
| 28279 | .cindex "&%hosts%& ACL condition" |
| 28280 | .cindex "host" "ACL checking" |
| 28281 | .cindex "&ACL;" "testing the client host" |
| 28282 | This condition tests that the calling host matches the host list. If you have |
| 28283 | name lookups or wildcarded host names and IP addresses in the same host list, |
| 28284 | you should normally put the IP addresses first. For example, you could have: |
| 28285 | .code |
| 28286 | accept hosts = 10.9.8.7 : dbm;/etc/friendly/hosts |
| 28287 | .endd |
| 28288 | The lookup in this example uses the host name for its key. This is implied by |
| 28289 | the lookup type &"dbm"&. (For a host address lookup you would use &"net-dbm"& |
| 28290 | and it wouldn't matter which way round you had these two items.) |
| 28291 | |
| 28292 | The reason for the problem with host names lies in the left-to-right way that |
| 28293 | Exim processes lists. It can test IP addresses without doing any DNS lookups, |
| 28294 | but when it reaches an item that requires a host name, it fails if it cannot |
| 28295 | find a host name to compare with the pattern. If the above list is given in the |
| 28296 | opposite order, the &%accept%& statement fails for a host whose name cannot be |
| 28297 | found, even if its IP address is 10.9.8.7. |
| 28298 | |
| 28299 | If you really do want to do the name check first, and still recognize the IP |
| 28300 | address even if the name lookup fails, you can rewrite the ACL like this: |
| 28301 | .code |
| 28302 | accept hosts = dbm;/etc/friendly/hosts |
| 28303 | accept hosts = 10.9.8.7 |
| 28304 | .endd |
| 28305 | The default action on failing to find the host name is to assume that the host |
| 28306 | is not in the list, so the first &%accept%& statement fails. The second |
| 28307 | statement can then check the IP address. |
| 28308 | |
| 28309 | .vindex "&$host_data$&" |
| 28310 | If a &%hosts%& condition is satisfied by means of a lookup, the result |
| 28311 | of the lookup is made available in the &$host_data$& variable. This |
| 28312 | allows you, for example, to set up a statement like this: |
| 28313 | .code |
| 28314 | deny hosts = net-lsearch;/some/file |
| 28315 | message = $host_data |
| 28316 | .endd |
| 28317 | which gives a custom error message for each denied host. |
| 28318 | |
| 28319 | .vitem &*local_parts&~=&~*&<&'local&~part&~list'&> |
| 28320 | .cindex "&%local_parts%& ACL condition" |
| 28321 | .cindex "local part" "ACL checking" |
| 28322 | .cindex "&ACL;" "testing a local part" |
| 28323 | .vindex "&$local_part_data$&" |
| 28324 | This condition is relevant only after a RCPT command. It checks that the local |
| 28325 | part of the recipient address is in the list. If percent-hack processing is |
| 28326 | enabled, it is done before this test. If the check succeeds with a lookup, the |
| 28327 | result of the lookup is placed in &$local_part_data$&, which remains set until |
| 28328 | the next &%local_parts%& test. |
| 28329 | |
| 28330 | .vitem &*malware&~=&~*&<&'option'&> |
| 28331 | .cindex "&%malware%& ACL condition" |
| 28332 | .cindex "&ACL;" "virus scanning" |
| 28333 | .cindex "&ACL;" "scanning for viruses" |
| 28334 | This condition is available only when Exim is compiled with the |
| 28335 | content-scanning extension. It causes the incoming message to be scanned for |
| 28336 | viruses. For details, see chapter &<<CHAPexiscan>>&. |
| 28337 | |
| 28338 | .vitem &*mime_regex&~=&~*&<&'list&~of&~regular&~expressions'&> |
| 28339 | .cindex "&%mime_regex%& ACL condition" |
| 28340 | .cindex "&ACL;" "testing by regex matching" |
| 28341 | This condition is available only when Exim is compiled with the |
| 28342 | content-scanning extension, and it is allowed only in the ACL defined by |
| 28343 | &%acl_smtp_mime%&. It causes the current MIME part to be scanned for a match |
| 28344 | with any of the regular expressions. For details, see chapter |
| 28345 | &<<CHAPexiscan>>&. |
| 28346 | |
| 28347 | .vitem &*ratelimit&~=&~*&<&'parameters'&> |
| 28348 | .cindex "rate limiting" |
| 28349 | This condition can be used to limit the rate at which a user or host submits |
| 28350 | messages. Details are given in section &<<SECTratelimiting>>&. |
| 28351 | |
| 28352 | .vitem &*recipients&~=&~*&<&'address&~list'&> |
| 28353 | .cindex "&%recipients%& ACL condition" |
| 28354 | .cindex "recipient" "ACL checking" |
| 28355 | .cindex "&ACL;" "testing a recipient" |
| 28356 | This condition is relevant only after a RCPT command. It checks the entire |
| 28357 | recipient address against a list of recipients. |
| 28358 | |
| 28359 | .vitem &*regex&~=&~*&<&'list&~of&~regular&~expressions'&> |
| 28360 | .cindex "&%regex%& ACL condition" |
| 28361 | .cindex "&ACL;" "testing by regex matching" |
| 28362 | This condition is available only when Exim is compiled with the |
| 28363 | content-scanning extension, and is available only in the DATA, MIME, and |
| 28364 | non-SMTP ACLs. It causes the incoming message to be scanned for a match with |
| 28365 | any of the regular expressions. For details, see chapter &<<CHAPexiscan>>&. |
| 28366 | |
| 28367 | .vitem &*sender_domains&~=&~*&<&'domain&~list'&> |
| 28368 | .cindex "&%sender_domains%& ACL condition" |
| 28369 | .cindex "sender" "ACL checking" |
| 28370 | .cindex "&ACL;" "testing a sender domain" |
| 28371 | .vindex "&$domain$&" |
| 28372 | .vindex "&$sender_address_domain$&" |
| 28373 | This condition tests the domain of the sender of the message against the given |
| 28374 | domain list. &*Note*&: The domain of the sender address is in |
| 28375 | &$sender_address_domain$&. It is &'not'& put in &$domain$& during the testing |
| 28376 | of this condition. This is an exception to the general rule for testing domain |
| 28377 | lists. It is done this way so that, if this condition is used in an ACL for a |
| 28378 | RCPT command, the recipient's domain (which is in &$domain$&) can be used to |
| 28379 | influence the sender checking. |
| 28380 | |
| 28381 | &*Warning*&: It is a bad idea to use this condition on its own as a control on |
| 28382 | relaying, because sender addresses are easily, and commonly, forged. |
| 28383 | |
| 28384 | .vitem &*senders&~=&~*&<&'address&~list'&> |
| 28385 | .cindex "&%senders%& ACL condition" |
| 28386 | .cindex "sender" "ACL checking" |
| 28387 | .cindex "&ACL;" "testing a sender" |
| 28388 | This condition tests the sender of the message against the given list. To test |
| 28389 | for a bounce message, which has an empty sender, set |
| 28390 | .code |
| 28391 | senders = : |
| 28392 | .endd |
| 28393 | &*Warning*&: It is a bad idea to use this condition on its own as a control on |
| 28394 | relaying, because sender addresses are easily, and commonly, forged. |
| 28395 | |
| 28396 | .vitem &*spam&~=&~*&<&'username'&> |
| 28397 | .cindex "&%spam%& ACL condition" |
| 28398 | .cindex "&ACL;" "scanning for spam" |
| 28399 | This condition is available only when Exim is compiled with the |
| 28400 | content-scanning extension. It causes the incoming message to be scanned by |
| 28401 | SpamAssassin. For details, see chapter &<<CHAPexiscan>>&. |
| 28402 | |
| 28403 | .vitem &*verify&~=&~certificate*& |
| 28404 | .cindex "&%verify%& ACL condition" |
| 28405 | .cindex "TLS" "client certificate verification" |
| 28406 | .cindex "certificate" "verification of client" |
| 28407 | .cindex "&ACL;" "certificate verification" |
| 28408 | .cindex "&ACL;" "testing a TLS certificate" |
| 28409 | This condition is true in an SMTP session if the session is encrypted, and a |
| 28410 | certificate was received from the client, and the certificate was verified. The |
| 28411 | server requests a certificate only if the client matches &%tls_verify_hosts%& |
| 28412 | or &%tls_try_verify_hosts%& (see chapter &<<CHAPTLS>>&). |
| 28413 | |
| 28414 | .vitem &*verify&~=&~csa*& |
| 28415 | .cindex "CSA verification" |
| 28416 | This condition checks whether the sending host (the client) is authorized to |
| 28417 | send email. Details of how this works are given in section |
| 28418 | &<<SECTverifyCSA>>&. |
| 28419 | |
| 28420 | .new |
| 28421 | .vitem &*verify&~=&~header_names_ascii*& |
| 28422 | .cindex "&%verify%& ACL condition" |
| 28423 | .cindex "&ACL;" "verifying header names only ASCII" |
| 28424 | .cindex "header lines" "verifying header names only ASCII" |
| 28425 | .cindex "verifying" "header names only ASCII" |
| 28426 | This condition is relevant only in an ACL that is run after a message has been |
| 28427 | received, that is, in an ACL specified by &%acl_smtp_data%& or |
| 28428 | &%acl_not_smtp%&. It checks all header names (not the content) to make sure |
| 28429 | there are no non-ASCII characters, also excluding control characters. The |
| 28430 | allowable characters are decimal ASCII values 33 through 126. |
| 28431 | |
| 28432 | Exim itself will handle headers with non-ASCII characters, but it can cause |
| 28433 | problems for downstream applications, so this option will allow their |
| 28434 | detection and rejection in the DATA ACL's. |
| 28435 | .wen |
| 28436 | |
| 28437 | .vitem &*verify&~=&~header_sender/*&<&'options'&> |
| 28438 | .cindex "&%verify%& ACL condition" |
| 28439 | .cindex "&ACL;" "verifying sender in the header" |
| 28440 | .cindex "header lines" "verifying the sender in" |
| 28441 | .cindex "sender" "verifying in header" |
| 28442 | .cindex "verifying" "sender in header" |
| 28443 | This condition is relevant only in an ACL that is run after a message has been |
| 28444 | received, that is, in an ACL specified by &%acl_smtp_data%& or |
| 28445 | &%acl_not_smtp%&. It checks that there is a verifiable address in at least one |
| 28446 | of the &'Sender:'&, &'Reply-To:'&, or &'From:'& header lines. Such an address |
| 28447 | is loosely thought of as a &"sender"& address (hence the name of the test). |
| 28448 | However, an address that appears in one of these headers need not be an address |
| 28449 | that accepts bounce messages; only sender addresses in envelopes are required |
| 28450 | to accept bounces. Therefore, if you use the callout option on this check, you |
| 28451 | might want to arrange for a non-empty address in the MAIL command. |
| 28452 | |
| 28453 | Details of address verification and the options are given later, starting at |
| 28454 | section &<<SECTaddressverification>>& (callouts are described in section |
| 28455 | &<<SECTcallver>>&). You can combine this condition with the &%senders%& |
| 28456 | condition to restrict it to bounce messages only: |
| 28457 | .code |
| 28458 | deny senders = : |
| 28459 | message = A valid sender header is required for bounces |
| 28460 | !verify = header_sender |
| 28461 | .endd |
| 28462 | |
| 28463 | .vitem &*verify&~=&~header_syntax*& |
| 28464 | .cindex "&%verify%& ACL condition" |
| 28465 | .cindex "&ACL;" "verifying header syntax" |
| 28466 | .cindex "header lines" "verifying syntax" |
| 28467 | .cindex "verifying" "header syntax" |
| 28468 | This condition is relevant only in an ACL that is run after a message has been |
| 28469 | received, that is, in an ACL specified by &%acl_smtp_data%& or |
| 28470 | &%acl_not_smtp%&. It checks the syntax of all header lines that can contain |
| 28471 | lists of addresses (&'Sender:'&, &'From:'&, &'Reply-To:'&, &'To:'&, &'Cc:'&, |
| 28472 | and &'Bcc:'&). Unqualified addresses (local parts without domains) are |
| 28473 | permitted only in locally generated messages and from hosts that match |
| 28474 | &%sender_unqualified_hosts%& or &%recipient_unqualified_hosts%&, as |
| 28475 | appropriate. |
| 28476 | |
| 28477 | Note that this condition is a syntax check only. However, a common spamming |
| 28478 | ploy used to be to send syntactically invalid headers such as |
| 28479 | .code |
| 28480 | To: @ |
| 28481 | .endd |
| 28482 | and this condition can be used to reject such messages, though they are not as |
| 28483 | common as they used to be. |
| 28484 | |
| 28485 | .vitem &*verify&~=&~helo*& |
| 28486 | .cindex "&%verify%& ACL condition" |
| 28487 | .cindex "&ACL;" "verifying HELO/EHLO" |
| 28488 | .cindex "HELO" "verifying" |
| 28489 | .cindex "EHLO" "verifying" |
| 28490 | .cindex "verifying" "EHLO" |
| 28491 | .cindex "verifying" "HELO" |
| 28492 | This condition is true if a HELO or EHLO command has been received from the |
| 28493 | client host, and its contents have been verified. If there has been no previous |
| 28494 | attempt to verify the HELO/EHLO contents, it is carried out when this |
| 28495 | condition is encountered. See the description of the &%helo_verify_hosts%& and |
| 28496 | &%helo_try_verify_hosts%& options for details of how to request verification |
| 28497 | independently of this condition. |
| 28498 | |
| 28499 | For SMTP input that does not come over TCP/IP (the &%-bs%& command line |
| 28500 | option), this condition is always true. |
| 28501 | |
| 28502 | |
| 28503 | .vitem &*verify&~=&~not_blind*& |
| 28504 | .cindex "verifying" "not blind" |
| 28505 | .cindex "bcc recipients, verifying none" |
| 28506 | This condition checks that there are no blind (bcc) recipients in the message. |
| 28507 | Every envelope recipient must appear either in a &'To:'& header line or in a |
| 28508 | &'Cc:'& header line for this condition to be true. Local parts are checked |
| 28509 | case-sensitively; domains are checked case-insensitively. If &'Resent-To:'& or |
| 28510 | &'Resent-Cc:'& header lines exist, they are also checked. This condition can be |
| 28511 | used only in a DATA or non-SMTP ACL. |
| 28512 | |
| 28513 | There are, of course, many legitimate messages that make use of blind (bcc) |
| 28514 | recipients. This check should not be used on its own for blocking messages. |
| 28515 | |
| 28516 | |
| 28517 | .vitem &*verify&~=&~recipient/*&<&'options'&> |
| 28518 | .cindex "&%verify%& ACL condition" |
| 28519 | .cindex "&ACL;" "verifying recipient" |
| 28520 | .cindex "recipient" "verifying" |
| 28521 | .cindex "verifying" "recipient" |
| 28522 | .vindex "&$address_data$&" |
| 28523 | This condition is relevant only after a RCPT command. It verifies the current |
| 28524 | recipient. Details of address verification are given later, starting at section |
| 28525 | &<<SECTaddressverification>>&. After a recipient has been verified, the value |
| 28526 | of &$address_data$& is the last value that was set while routing the address. |
| 28527 | This applies even if the verification fails. When an address that is being |
| 28528 | verified is redirected to a single address, verification continues with the new |
| 28529 | address, and in that case, the subsequent value of &$address_data$& is the |
| 28530 | value for the child address. |
| 28531 | |
| 28532 | .vitem &*verify&~=&~reverse_host_lookup*& |
| 28533 | .cindex "&%verify%& ACL condition" |
| 28534 | .cindex "&ACL;" "verifying host reverse lookup" |
| 28535 | .cindex "host" "verifying reverse lookup" |
| 28536 | This condition ensures that a verified host name has been looked up from the IP |
| 28537 | address of the client host. (This may have happened already if the host name |
| 28538 | was needed for checking a host list, or if the host matched &%host_lookup%&.) |
| 28539 | Verification ensures that the host name obtained from a reverse DNS lookup, or |
| 28540 | one of its aliases, does, when it is itself looked up in the DNS, yield the |
| 28541 | original IP address. |
| 28542 | |
| 28543 | If this condition is used for a locally generated message (that is, when there |
| 28544 | is no client host involved), it always succeeds. |
| 28545 | |
| 28546 | .vitem &*verify&~=&~sender/*&<&'options'&> |
| 28547 | .cindex "&%verify%& ACL condition" |
| 28548 | .cindex "&ACL;" "verifying sender" |
| 28549 | .cindex "sender" "verifying" |
| 28550 | .cindex "verifying" "sender" |
| 28551 | This condition is relevant only after a MAIL or RCPT command, or after a |
| 28552 | message has been received (the &%acl_smtp_data%& or &%acl_not_smtp%& ACLs). If |
| 28553 | the message's sender is empty (that is, this is a bounce message), the |
| 28554 | condition is true. Otherwise, the sender address is verified. |
| 28555 | |
| 28556 | .vindex "&$address_data$&" |
| 28557 | .vindex "&$sender_address_data$&" |
| 28558 | If there is data in the &$address_data$& variable at the end of routing, its |
| 28559 | value is placed in &$sender_address_data$& at the end of verification. This |
| 28560 | value can be used in subsequent conditions and modifiers in the same ACL |
| 28561 | statement. It does not persist after the end of the current statement. If you |
| 28562 | want to preserve the value for longer, you can save it in an ACL variable. |
| 28563 | |
| 28564 | Details of verification are given later, starting at section |
| 28565 | &<<SECTaddressverification>>&. Exim caches the result of sender verification, |
| 28566 | to avoid doing it more than once per message. |
| 28567 | |
| 28568 | .vitem &*verify&~=&~sender=*&<&'address'&>&*/*&<&'options'&> |
| 28569 | .cindex "&%verify%& ACL condition" |
| 28570 | This is a variation of the previous option, in which a modified address is |
| 28571 | verified as a sender. |
| 28572 | .endlist |
| 28573 | |
| 28574 | |
| 28575 | |
| 28576 | .section "Using DNS lists" "SECTmorednslists" |
| 28577 | .cindex "DNS list" "in ACL" |
| 28578 | .cindex "black list (DNS)" |
| 28579 | .cindex "&ACL;" "testing a DNS list" |
| 28580 | In its simplest form, the &%dnslists%& condition tests whether the calling host |
| 28581 | is on at least one of a number of DNS lists by looking up the inverted IP |
| 28582 | address in one or more DNS domains. (Note that DNS list domains are not mail |
| 28583 | domains, so the &`+`& syntax for named lists doesn't work - it is used for |
| 28584 | special options instead.) For example, if the calling host's IP |
| 28585 | address is 192.168.62.43, and the ACL statement is |
| 28586 | .code |
| 28587 | deny dnslists = blackholes.mail-abuse.org : \ |
| 28588 | dialups.mail-abuse.org |
| 28589 | .endd |
| 28590 | the following records are looked up: |
| 28591 | .code |
| 28592 | 43.62.168.192.blackholes.mail-abuse.org |
| 28593 | 43.62.168.192.dialups.mail-abuse.org |
| 28594 | .endd |
| 28595 | As soon as Exim finds an existing DNS record, processing of the list stops. |
| 28596 | Thus, multiple entries on the list provide an &"or"& conjunction. If you want |
| 28597 | to test that a host is on more than one list (an &"and"& conjunction), you can |
| 28598 | use two separate conditions: |
| 28599 | .code |
| 28600 | deny dnslists = blackholes.mail-abuse.org |
| 28601 | dnslists = dialups.mail-abuse.org |
| 28602 | .endd |
| 28603 | If a DNS lookup times out or otherwise fails to give a decisive answer, Exim |
| 28604 | behaves as if the host does not match the list item, that is, as if the DNS |
| 28605 | record does not exist. If there are further items in the DNS list, they are |
| 28606 | processed. |
| 28607 | |
| 28608 | This is usually the required action when &%dnslists%& is used with &%deny%& |
| 28609 | (which is the most common usage), because it prevents a DNS failure from |
| 28610 | blocking mail. However, you can change this behaviour by putting one of the |
| 28611 | following special items in the list: |
| 28612 | .display |
| 28613 | &`+include_unknown `& behave as if the item is on the list |
| 28614 | &`+exclude_unknown `& behave as if the item is not on the list (default) |
| 28615 | &`+defer_unknown `& give a temporary error |
| 28616 | .endd |
| 28617 | .cindex "&`+include_unknown`&" |
| 28618 | .cindex "&`+exclude_unknown`&" |
| 28619 | .cindex "&`+defer_unknown`&" |
| 28620 | Each of these applies to any subsequent items on the list. For example: |
| 28621 | .code |
| 28622 | deny dnslists = +defer_unknown : foo.bar.example |
| 28623 | .endd |
| 28624 | Testing the list of domains stops as soon as a match is found. If you want to |
| 28625 | warn for one list and block for another, you can use two different statements: |
| 28626 | .code |
| 28627 | deny dnslists = blackholes.mail-abuse.org |
| 28628 | warn message = X-Warn: sending host is on dialups list |
| 28629 | dnslists = dialups.mail-abuse.org |
| 28630 | .endd |
| 28631 | DNS list lookups are cached by Exim for the duration of the SMTP session, |
| 28632 | so a lookup based on the IP address is done at most once for any incoming |
| 28633 | connection. Exim does not share information between multiple incoming |
| 28634 | connections (but your local name server cache should be active). |
| 28635 | |
| 28636 | |
| 28637 | |
| 28638 | .section "Specifying the IP address for a DNS list lookup" "SECID201" |
| 28639 | .cindex "DNS list" "keyed by explicit IP address" |
| 28640 | By default, the IP address that is used in a DNS list lookup is the IP address |
| 28641 | of the calling host. However, you can specify another IP address by listing it |
| 28642 | after the domain name, introduced by a slash. For example: |
| 28643 | .code |
| 28644 | deny dnslists = black.list.tld/192.168.1.2 |
| 28645 | .endd |
| 28646 | This feature is not very helpful with explicit IP addresses; it is intended for |
| 28647 | use with IP addresses that are looked up, for example, the IP addresses of the |
| 28648 | MX hosts or nameservers of an email sender address. For an example, see section |
| 28649 | &<<SECTmulkeyfor>>& below. |
| 28650 | |
| 28651 | |
| 28652 | |
| 28653 | |
| 28654 | .section "DNS lists keyed on domain names" "SECID202" |
| 28655 | .cindex "DNS list" "keyed by domain name" |
| 28656 | There are some lists that are keyed on domain names rather than inverted IP |
| 28657 | addresses (see for example the &'domain based zones'& link at |
| 28658 | &url(http://www.rfc-ignorant.org/)). No reversing of components is used |
| 28659 | with these lists. You can change the name that is looked up in a DNS list by |
| 28660 | listing it after the domain name, introduced by a slash. For example, |
| 28661 | .code |
| 28662 | deny message = Sender's domain is listed at $dnslist_domain |
| 28663 | dnslists = dsn.rfc-ignorant.org/$sender_address_domain |
| 28664 | .endd |
| 28665 | This particular example is useful only in ACLs that are obeyed after the |
| 28666 | RCPT or DATA commands, when a sender address is available. If (for |
| 28667 | example) the message's sender is &'user@tld.example'& the name that is looked |
| 28668 | up by this example is |
| 28669 | .code |
| 28670 | tld.example.dsn.rfc-ignorant.org |
| 28671 | .endd |
| 28672 | A single &%dnslists%& condition can contain entries for both names and IP |
| 28673 | addresses. For example: |
| 28674 | .code |
| 28675 | deny dnslists = sbl.spamhaus.org : \ |
| 28676 | dsn.rfc-ignorant.org/$sender_address_domain |
| 28677 | .endd |
| 28678 | The first item checks the sending host's IP address; the second checks a domain |
| 28679 | name. The whole condition is true if either of the DNS lookups succeeds. |
| 28680 | |
| 28681 | |
| 28682 | |
| 28683 | |
| 28684 | .section "Multiple explicit keys for a DNS list" "SECTmulkeyfor" |
| 28685 | .cindex "DNS list" "multiple keys for" |
| 28686 | The syntax described above for looking up explicitly-defined values (either |
| 28687 | names or IP addresses) in a DNS blacklist is a simplification. After the domain |
| 28688 | name for the DNS list, what follows the slash can in fact be a list of items. |
| 28689 | As with all lists in Exim, the default separator is a colon. However, because |
| 28690 | this is a sublist within the list of DNS blacklist domains, it is necessary |
| 28691 | either to double the separators like this: |
| 28692 | .code |
| 28693 | dnslists = black.list.tld/name.1::name.2 |
| 28694 | .endd |
| 28695 | or to change the separator character, like this: |
| 28696 | .code |
| 28697 | dnslists = black.list.tld/<;name.1;name.2 |
| 28698 | .endd |
| 28699 | If an item in the list is an IP address, it is inverted before the DNS |
| 28700 | blacklist domain is appended. If it is not an IP address, no inversion |
| 28701 | occurs. Consider this condition: |
| 28702 | .code |
| 28703 | dnslists = black.list.tld/<;192.168.1.2;a.domain |
| 28704 | .endd |
| 28705 | The DNS lookups that occur are: |
| 28706 | .code |
| 28707 | 2.1.168.192.black.list.tld |
| 28708 | a.domain.black.list.tld |
| 28709 | .endd |
| 28710 | Once a DNS record has been found (that matches a specific IP return |
| 28711 | address, if specified &-- see section &<<SECTaddmatcon>>&), no further lookups |
| 28712 | are done. If there is a temporary DNS error, the rest of the sublist of domains |
| 28713 | or IP addresses is tried. A temporary error for the whole dnslists item occurs |
| 28714 | only if no other DNS lookup in this sublist succeeds. In other words, a |
| 28715 | successful lookup for any of the items in the sublist overrides a temporary |
| 28716 | error for a previous item. |
| 28717 | |
| 28718 | The ability to supply a list of items after the slash is in some sense just a |
| 28719 | syntactic convenience. These two examples have the same effect: |
| 28720 | .code |
| 28721 | dnslists = black.list.tld/a.domain : black.list.tld/b.domain |
| 28722 | dnslists = black.list.tld/a.domain::b.domain |
| 28723 | .endd |
| 28724 | However, when the data for the list is obtained from a lookup, the second form |
| 28725 | is usually much more convenient. Consider this example: |
| 28726 | .code |
| 28727 | deny message = The mail servers for the domain \ |
| 28728 | $sender_address_domain \ |
| 28729 | are listed at $dnslist_domain ($dnslist_value); \ |
| 28730 | see $dnslist_text. |
| 28731 | dnslists = sbl.spamhaus.org/<|${lookup dnsdb {>|a=<|\ |
| 28732 | ${lookup dnsdb {>|mxh=\ |
| 28733 | $sender_address_domain} }} } |
| 28734 | .endd |
| 28735 | Note the use of &`>|`& in the dnsdb lookup to specify the separator for |
| 28736 | multiple DNS records. The inner dnsdb lookup produces a list of MX hosts |
| 28737 | and the outer dnsdb lookup finds the IP addresses for these hosts. The result |
| 28738 | of expanding the condition might be something like this: |
| 28739 | .code |
| 28740 | dnslists = sbl.spahmaus.org/<|192.168.2.3|192.168.5.6|... |
| 28741 | .endd |
| 28742 | Thus, this example checks whether or not the IP addresses of the sender |
| 28743 | domain's mail servers are on the Spamhaus black list. |
| 28744 | |
| 28745 | The key that was used for a successful DNS list lookup is put into the variable |
| 28746 | &$dnslist_matched$& (see section &<<SECID204>>&). |
| 28747 | |
| 28748 | |
| 28749 | |
| 28750 | |
| 28751 | .section "Data returned by DNS lists" "SECID203" |
| 28752 | .cindex "DNS list" "data returned from" |
| 28753 | DNS lists are constructed using address records in the DNS. The original RBL |
| 28754 | just used the address 127.0.0.1 on the right hand side of each record, but the |
| 28755 | RBL+ list and some other lists use a number of values with different meanings. |
| 28756 | The values used on the RBL+ list are: |
| 28757 | .display |
| 28758 | 127.1.0.1 RBL |
| 28759 | 127.1.0.2 DUL |
| 28760 | 127.1.0.3 DUL and RBL |
| 28761 | 127.1.0.4 RSS |
| 28762 | 127.1.0.5 RSS and RBL |
| 28763 | 127.1.0.6 RSS and DUL |
| 28764 | 127.1.0.7 RSS and DUL and RBL |
| 28765 | .endd |
| 28766 | Section &<<SECTaddmatcon>>& below describes how you can distinguish between |
| 28767 | different values. Some DNS lists may return more than one address record; |
| 28768 | see section &<<SECThanmuldnsrec>>& for details of how they are checked. |
| 28769 | |
| 28770 | |
| 28771 | .section "Variables set from DNS lists" "SECID204" |
| 28772 | .cindex "expansion" "variables, set from DNS list" |
| 28773 | .cindex "DNS list" "variables set from" |
| 28774 | .vindex "&$dnslist_domain$&" |
| 28775 | .vindex "&$dnslist_matched$&" |
| 28776 | .vindex "&$dnslist_text$&" |
| 28777 | .vindex "&$dnslist_value$&" |
| 28778 | When an entry is found in a DNS list, the variable &$dnslist_domain$& contains |
| 28779 | the name of the overall domain that matched (for example, |
| 28780 | &`spamhaus.example`&), &$dnslist_matched$& contains the key within that domain |
| 28781 | (for example, &`192.168.5.3`&), and &$dnslist_value$& contains the data from |
| 28782 | the DNS record. When the key is an IP address, it is not reversed in |
| 28783 | &$dnslist_matched$& (though it is, of course, in the actual lookup). In simple |
| 28784 | cases, for example: |
| 28785 | .code |
| 28786 | deny dnslists = spamhaus.example |
| 28787 | .endd |
| 28788 | the key is also available in another variable (in this case, |
| 28789 | &$sender_host_address$&). In more complicated cases, however, this is not true. |
| 28790 | For example, using a data lookup (as described in section &<<SECTmulkeyfor>>&) |
| 28791 | might generate a dnslists lookup like this: |
| 28792 | .code |
| 28793 | deny dnslists = spamhaus.example/<|192.168.1.2|192.168.6.7|... |
| 28794 | .endd |
| 28795 | If this condition succeeds, the value in &$dnslist_matched$& might be |
| 28796 | &`192.168.6.7`& (for example). |
| 28797 | |
| 28798 | If more than one address record is returned by the DNS lookup, all the IP |
| 28799 | addresses are included in &$dnslist_value$&, separated by commas and spaces. |
| 28800 | The variable &$dnslist_text$& contains the contents of any associated TXT |
| 28801 | record. For lists such as RBL+ the TXT record for a merged entry is often not |
| 28802 | very meaningful. See section &<<SECTmordetinf>>& for a way of obtaining more |
| 28803 | information. |
| 28804 | |
| 28805 | You can use the DNS list variables in &%message%& or &%log_message%& modifiers |
| 28806 | &-- although these appear before the condition in the ACL, they are not |
| 28807 | expanded until after it has failed. For example: |
| 28808 | .code |
| 28809 | deny hosts = !+local_networks |
| 28810 | message = $sender_host_address is listed \ |
| 28811 | at $dnslist_domain |
| 28812 | dnslists = rbl-plus.mail-abuse.example |
| 28813 | .endd |
| 28814 | |
| 28815 | |
| 28816 | |
| 28817 | .section "Additional matching conditions for DNS lists" "SECTaddmatcon" |
| 28818 | .cindex "DNS list" "matching specific returned data" |
| 28819 | You can add an equals sign and an IP address after a &%dnslists%& domain name |
| 28820 | in order to restrict its action to DNS records with a matching right hand side. |
| 28821 | For example, |
| 28822 | .code |
| 28823 | deny dnslists = rblplus.mail-abuse.org=127.0.0.2 |
| 28824 | .endd |
| 28825 | rejects only those hosts that yield 127.0.0.2. Without this additional data, |
| 28826 | any address record is considered to be a match. For the moment, we assume |
| 28827 | that the DNS lookup returns just one record. Section &<<SECThanmuldnsrec>>& |
| 28828 | describes how multiple records are handled. |
| 28829 | |
| 28830 | More than one IP address may be given for checking, using a comma as a |
| 28831 | separator. These are alternatives &-- if any one of them matches, the |
| 28832 | &%dnslists%& condition is true. For example: |
| 28833 | .code |
| 28834 | deny dnslists = a.b.c=127.0.0.2,127.0.0.3 |
| 28835 | .endd |
| 28836 | If you want to specify a constraining address list and also specify names or IP |
| 28837 | addresses to be looked up, the constraining address list must be specified |
| 28838 | first. For example: |
| 28839 | .code |
| 28840 | deny dnslists = dsn.rfc-ignorant.org\ |
| 28841 | =127.0.0.2/$sender_address_domain |
| 28842 | .endd |
| 28843 | |
| 28844 | If the character &`&&`& is used instead of &`=`&, the comparison for each |
| 28845 | listed IP address is done by a bitwise &"and"& instead of by an equality test. |
| 28846 | In other words, the listed addresses are used as bit masks. The comparison is |
| 28847 | true if all the bits in the mask are present in the address that is being |
| 28848 | tested. For example: |
| 28849 | .code |
| 28850 | dnslists = a.b.c&0.0.0.3 |
| 28851 | .endd |
| 28852 | matches if the address is &'x.x.x.'&3, &'x.x.x.'&7, &'x.x.x.'&11, etc. If you |
| 28853 | want to test whether one bit or another bit is present (as opposed to both |
| 28854 | being present), you must use multiple values. For example: |
| 28855 | .code |
| 28856 | dnslists = a.b.c&0.0.0.1,0.0.0.2 |
| 28857 | .endd |
| 28858 | matches if the final component of the address is an odd number or two times |
| 28859 | an odd number. |
| 28860 | |
| 28861 | |
| 28862 | |
| 28863 | .section "Negated DNS matching conditions" "SECID205" |
| 28864 | You can supply a negative list of IP addresses as part of a &%dnslists%& |
| 28865 | condition. Whereas |
| 28866 | .code |
| 28867 | deny dnslists = a.b.c=127.0.0.2,127.0.0.3 |
| 28868 | .endd |
| 28869 | means &"deny if the host is in the black list at the domain &'a.b.c'& and the |
| 28870 | IP address yielded by the list is either 127.0.0.2 or 127.0.0.3"&, |
| 28871 | .code |
| 28872 | deny dnslists = a.b.c!=127.0.0.2,127.0.0.3 |
| 28873 | .endd |
| 28874 | means &"deny if the host is in the black list at the domain &'a.b.c'& and the |
| 28875 | IP address yielded by the list is not 127.0.0.2 and not 127.0.0.3"&. In other |
| 28876 | words, the result of the test is inverted if an exclamation mark appears before |
| 28877 | the &`=`& (or the &`&&`&) sign. |
| 28878 | |
| 28879 | &*Note*&: This kind of negation is not the same as negation in a domain, |
| 28880 | host, or address list (which is why the syntax is different). |
| 28881 | |
| 28882 | If you are using just one list, the negation syntax does not gain you much. The |
| 28883 | previous example is precisely equivalent to |
| 28884 | .code |
| 28885 | deny dnslists = a.b.c |
| 28886 | !dnslists = a.b.c=127.0.0.2,127.0.0.3 |
| 28887 | .endd |
| 28888 | However, if you are using multiple lists, the negation syntax is clearer. |
| 28889 | Consider this example: |
| 28890 | .code |
| 28891 | deny dnslists = sbl.spamhaus.org : \ |
| 28892 | list.dsbl.org : \ |
| 28893 | dnsbl.njabl.org!=127.0.0.3 : \ |
| 28894 | relays.ordb.org |
| 28895 | .endd |
| 28896 | Using only positive lists, this would have to be: |
| 28897 | .code |
| 28898 | deny dnslists = sbl.spamhaus.org : \ |
| 28899 | list.dsbl.org |
| 28900 | deny dnslists = dnsbl.njabl.org |
| 28901 | !dnslists = dnsbl.njabl.org=127.0.0.3 |
| 28902 | deny dnslists = relays.ordb.org |
| 28903 | .endd |
| 28904 | which is less clear, and harder to maintain. |
| 28905 | |
| 28906 | |
| 28907 | |
| 28908 | |
| 28909 | .section "Handling multiple DNS records from a DNS list" "SECThanmuldnsrec" |
| 28910 | A DNS lookup for a &%dnslists%& condition may return more than one DNS record, |
| 28911 | thereby providing more than one IP address. When an item in a &%dnslists%& list |
| 28912 | is followed by &`=`& or &`&&`& and a list of IP addresses, in order to restrict |
| 28913 | the match to specific results from the DNS lookup, there are two ways in which |
| 28914 | the checking can be handled. For example, consider the condition: |
| 28915 | .code |
| 28916 | dnslists = a.b.c=127.0.0.1 |
| 28917 | .endd |
| 28918 | What happens if the DNS lookup for the incoming IP address yields both |
| 28919 | 127.0.0.1 and 127.0.0.2 by means of two separate DNS records? Is the |
| 28920 | condition true because at least one given value was found, or is it false |
| 28921 | because at least one of the found values was not listed? And how does this |
| 28922 | affect negated conditions? Both possibilities are provided for with the help of |
| 28923 | additional separators &`==`& and &`=&&`&. |
| 28924 | |
| 28925 | .ilist |
| 28926 | If &`=`& or &`&&`& is used, the condition is true if any one of the looked up |
| 28927 | IP addresses matches one of the listed addresses. For the example above, the |
| 28928 | condition is true because 127.0.0.1 matches. |
| 28929 | .next |
| 28930 | If &`==`& or &`=&&`& is used, the condition is true only if every one of the |
| 28931 | looked up IP addresses matches one of the listed addresses. If the condition is |
| 28932 | changed to: |
| 28933 | .code |
| 28934 | dnslists = a.b.c==127.0.0.1 |
| 28935 | .endd |
| 28936 | and the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is |
| 28937 | false because 127.0.0.2 is not listed. You would need to have: |
| 28938 | .code |
| 28939 | dnslists = a.b.c==127.0.0.1,127.0.0.2 |
| 28940 | .endd |
| 28941 | for the condition to be true. |
| 28942 | .endlist |
| 28943 | |
| 28944 | When &`!`& is used to negate IP address matching, it inverts the result, giving |
| 28945 | the precise opposite of the behaviour above. Thus: |
| 28946 | .ilist |
| 28947 | If &`!=`& or &`!&&`& is used, the condition is true if none of the looked up IP |
| 28948 | addresses matches one of the listed addresses. Consider: |
| 28949 | .code |
| 28950 | dnslists = a.b.c!&0.0.0.1 |
| 28951 | .endd |
| 28952 | If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is |
| 28953 | false because 127.0.0.1 matches. |
| 28954 | .next |
| 28955 | If &`!==`& or &`!=&&`& is used, the condition is true if there is at least one |
| 28956 | looked up IP address that does not match. Consider: |
| 28957 | .code |
| 28958 | dnslists = a.b.c!=&0.0.0.1 |
| 28959 | .endd |
| 28960 | If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is |
| 28961 | true, because 127.0.0.2 does not match. You would need to have: |
| 28962 | .code |
| 28963 | dnslists = a.b.c!=&0.0.0.1,0.0.0.2 |
| 28964 | .endd |
| 28965 | for the condition to be false. |
| 28966 | .endlist |
| 28967 | When the DNS lookup yields only a single IP address, there is no difference |
| 28968 | between &`=`& and &`==`& and between &`&&`& and &`=&&`&. |
| 28969 | |
| 28970 | |
| 28971 | |
| 28972 | |
| 28973 | .section "Detailed information from merged DNS lists" "SECTmordetinf" |
| 28974 | .cindex "DNS list" "information from merged" |
| 28975 | When the facility for restricting the matching IP values in a DNS list is used, |
| 28976 | the text from the TXT record that is set in &$dnslist_text$& may not reflect |
| 28977 | the true reason for rejection. This happens when lists are merged and the IP |
| 28978 | address in the A record is used to distinguish them; unfortunately there is |
| 28979 | only one TXT record. One way round this is not to use merged lists, but that |
| 28980 | can be inefficient because it requires multiple DNS lookups where one would do |
| 28981 | in the vast majority of cases when the host of interest is not on any of the |
| 28982 | lists. |
| 28983 | |
| 28984 | A less inefficient way of solving this problem is available. If |
| 28985 | two domain names, comma-separated, are given, the second is used first to |
| 28986 | do an initial check, making use of any IP value restrictions that are set. |
| 28987 | If there is a match, the first domain is used, without any IP value |
| 28988 | restrictions, to get the TXT record. As a byproduct of this, there is also |
| 28989 | a check that the IP being tested is indeed on the first list. The first |
| 28990 | domain is the one that is put in &$dnslist_domain$&. For example: |
| 28991 | .code |
| 28992 | reject message = \ |
| 28993 | rejected because $sender_host_address is blacklisted \ |
| 28994 | at $dnslist_domain\n$dnslist_text |
| 28995 | dnslists = \ |
| 28996 | sbl.spamhaus.org,sbl-xbl.spamhaus.org=127.0.0.2 : \ |
| 28997 | dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10 |
| 28998 | .endd |
| 28999 | For the first blacklist item, this starts by doing a lookup in |
| 29000 | &'sbl-xbl.spamhaus.org'& and testing for a 127.0.0.2 return. If there is a |
| 29001 | match, it then looks in &'sbl.spamhaus.org'&, without checking the return |
| 29002 | value, and as long as something is found, it looks for the corresponding TXT |
| 29003 | record. If there is no match in &'sbl-xbl.spamhaus.org'&, nothing more is done. |
| 29004 | The second blacklist item is processed similarly. |
| 29005 | |
| 29006 | If you are interested in more than one merged list, the same list must be |
| 29007 | given several times, but because the results of the DNS lookups are cached, |
| 29008 | the DNS calls themselves are not repeated. For example: |
| 29009 | .code |
| 29010 | reject dnslists = \ |
| 29011 | http.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.2 : \ |
| 29012 | socks.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.3 : \ |
| 29013 | misc.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.4 : \ |
| 29014 | dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10 |
| 29015 | .endd |
| 29016 | In this case there is one lookup in &'dnsbl.sorbs.net'&, and if none of the IP |
| 29017 | values matches (or if no record is found), this is the only lookup that is |
| 29018 | done. Only if there is a match is one of the more specific lists consulted. |
| 29019 | |
| 29020 | |
| 29021 | |
| 29022 | .section "DNS lists and IPv6" "SECTmorednslistslast" |
| 29023 | .cindex "IPv6" "DNS black lists" |
| 29024 | .cindex "DNS list" "IPv6 usage" |
| 29025 | If Exim is asked to do a dnslist lookup for an IPv6 address, it inverts it |
| 29026 | nibble by nibble. For example, if the calling host's IP address is |
| 29027 | 3ffe:ffff:836f:0a00:000a:0800:200a:c031, Exim might look up |
| 29028 | .code |
| 29029 | 1.3.0.c.a.0.0.2.0.0.8.0.a.0.0.0.0.0.a.0.f.6.3.8. |
| 29030 | f.f.f.f.e.f.f.3.blackholes.mail-abuse.org |
| 29031 | .endd |
| 29032 | (split over two lines here to fit on the page). Unfortunately, some of the DNS |
| 29033 | lists contain wildcard records, intended for IPv4, that interact badly with |
| 29034 | IPv6. For example, the DNS entry |
| 29035 | .code |
| 29036 | *.3.some.list.example. A 127.0.0.1 |
| 29037 | .endd |
| 29038 | is probably intended to put the entire 3.0.0.0/8 IPv4 network on the list. |
| 29039 | Unfortunately, it also matches the entire 3::/4 IPv6 network. |
| 29040 | |
| 29041 | You can exclude IPv6 addresses from DNS lookups by making use of a suitable |
| 29042 | &%condition%& condition, as in this example: |
| 29043 | .code |
| 29044 | deny condition = ${if isip4{$sender_host_address}} |
| 29045 | dnslists = some.list.example |
| 29046 | .endd |
| 29047 | |
| 29048 | If an explicit key is being used for a DNS lookup and it may be an IPv6 |
| 29049 | address you should specify alternate list separators for both the outer |
| 29050 | (DNS list name) list and inner (lookup keys) list: |
| 29051 | .code |
| 29052 | dnslists = <; dnsbl.example.com/<|$acl_m_addrslist |
| 29053 | .endd |
| 29054 | |
| 29055 | .section "Rate limiting incoming messages" "SECTratelimiting" |
| 29056 | .cindex "rate limiting" "client sending" |
| 29057 | .cindex "limiting client sending rates" |
| 29058 | .oindex "&%smtp_ratelimit_*%&" |
| 29059 | The &%ratelimit%& ACL condition can be used to measure and control the rate at |
| 29060 | which clients can send email. This is more powerful than the |
| 29061 | &%smtp_ratelimit_*%& options, because those options control the rate of |
| 29062 | commands in a single SMTP session only, whereas the &%ratelimit%& condition |
| 29063 | works across all connections (concurrent and sequential) from the same client |
| 29064 | host. The syntax of the &%ratelimit%& condition is: |
| 29065 | .display |
| 29066 | &`ratelimit =`& <&'m'&> &`/`& <&'p'&> &`/`& <&'options'&> &`/`& <&'key'&> |
| 29067 | .endd |
| 29068 | If the average client sending rate is less than &'m'& messages per time |
| 29069 | period &'p'& then the condition is false; otherwise it is true. |
| 29070 | |
| 29071 | As a side-effect, the &%ratelimit%& condition sets the expansion variable |
| 29072 | &$sender_rate$& to the client's computed rate, &$sender_rate_limit$& to the |
| 29073 | configured value of &'m'&, and &$sender_rate_period$& to the configured value |
| 29074 | of &'p'&. |
| 29075 | |
| 29076 | The parameter &'p'& is the smoothing time constant, in the form of an Exim |
| 29077 | time interval, for example, &`8h`& for eight hours. A larger time constant |
| 29078 | means that it takes Exim longer to forget a client's past behaviour. The |
| 29079 | parameter &'m'& is the maximum number of messages that a client is permitted to |
| 29080 | send in each time interval. It also specifies the number of messages permitted |
| 29081 | in a fast burst. By increasing both &'m'& and &'p'& but keeping &'m/p'& |
| 29082 | constant, you can allow a client to send more messages in a burst without |
| 29083 | changing its long-term sending rate limit. Conversely, if &'m'& and &'p'& are |
| 29084 | both small, messages must be sent at an even rate. |
| 29085 | |
| 29086 | There is a script in &_util/ratelimit.pl_& which extracts sending rates from |
| 29087 | log files, to assist with choosing appropriate settings for &'m'& and &'p'& |
| 29088 | when deploying the &%ratelimit%& ACL condition. The script prints usage |
| 29089 | instructions when it is run with no arguments. |
| 29090 | |
| 29091 | The key is used to look up the data for calculating the client's average |
| 29092 | sending rate. This data is stored in Exim's spool directory, alongside the |
| 29093 | retry and other hints databases. The default key is &$sender_host_address$&, |
| 29094 | which means Exim computes the sending rate of each client host IP address. |
| 29095 | By changing the key you can change how Exim identifies clients for the purpose |
| 29096 | of ratelimiting. For example, to limit the sending rate of each authenticated |
| 29097 | user, independent of the computer they are sending from, set the key to |
| 29098 | &$authenticated_id$&. You must ensure that the lookup key is meaningful; for |
| 29099 | example, &$authenticated_id$& is only meaningful if the client has |
| 29100 | authenticated (which you can check with the &%authenticated%& ACL condition). |
| 29101 | |
| 29102 | The lookup key does not have to identify clients: If you want to limit the |
| 29103 | rate at which a recipient receives messages, you can use the key |
| 29104 | &`$local_part@$domain`& with the &%per_rcpt%& option (see below) in a RCPT |
| 29105 | ACL. |
| 29106 | |
| 29107 | Each &%ratelimit%& condition can have up to four options. A &%per_*%& option |
| 29108 | specifies what Exim measures the rate of, for example messages or recipients |
| 29109 | or bytes. You can adjust the measurement using the &%unique=%& and/or |
| 29110 | &%count=%& options. You can also control when Exim updates the recorded rate |
| 29111 | using a &%strict%&, &%leaky%&, or &%readonly%& option. The options are |
| 29112 | separated by a slash, like the other parameters. They may appear in any order. |
| 29113 | |
| 29114 | Internally, Exim appends the smoothing constant &'p'& onto the lookup key with |
| 29115 | any options that alter the meaning of the stored data. The limit &'m'& is not |
| 29116 | stored, so you can alter the configured maximum rate and Exim will still |
| 29117 | remember clients' past behaviour. If you change the &%per_*%& mode or add or |
| 29118 | remove the &%unique=%& option, the lookup key changes so Exim will forget past |
| 29119 | behaviour. The lookup key is not affected by changes to the update mode and |
| 29120 | the &%count=%& option. |
| 29121 | |
| 29122 | |
| 29123 | .section "Ratelimit options for what is being measured" "ratoptmea" |
| 29124 | .cindex "rate limiting" "per_* options" |
| 29125 | The &%per_conn%& option limits the client's connection rate. It is not |
| 29126 | normally used in the &%acl_not_smtp%&, &%acl_not_smtp_mime%&, or |
| 29127 | &%acl_not_smtp_start%& ACLs. |
| 29128 | |
| 29129 | The &%per_mail%& option limits the client's rate of sending messages. This is |
| 29130 | the default if none of the &%per_*%& options is specified. It can be used in |
| 29131 | &%acl_smtp_mail%&, &%acl_smtp_rcpt%&, &%acl_smtp_predata%&, &%acl_smtp_mime%&, |
| 29132 | &%acl_smtp_data%&, or &%acl_not_smtp%&. |
| 29133 | |
| 29134 | The &%per_byte%& option limits the sender's email bandwidth. It can be used in |
| 29135 | the same ACLs as the &%per_mail%& option, though it is best to use this option |
| 29136 | in the &%acl_smtp_mime%&, &%acl_smtp_data%& or &%acl_not_smtp%& ACLs; if it is |
| 29137 | used in an earlier ACL, Exim relies on the SIZE parameter given by the client |
| 29138 | in its MAIL command, which may be inaccurate or completely missing. You can |
| 29139 | follow the limit &'m'& in the configuration with K, M, or G to specify limits |
| 29140 | in kilobytes, megabytes, or gigabytes, respectively. |
| 29141 | |
| 29142 | The &%per_rcpt%& option causes Exim to limit the rate at which recipients are |
| 29143 | accepted. It can be used in the &%acl_smtp_rcpt%&, &%acl_smtp_predata%&, |
| 29144 | &%acl_smtp_mime%&, &%acl_smtp_data%&, or &%acl_smtp_rcpt%& ACLs. In |
| 29145 | &%acl_smtp_rcpt%& the rate is updated one recipient at a time; in the other |
| 29146 | ACLs the rate is updated with the total recipient count in one go. Note that |
| 29147 | in either case the rate limiting engine will see a message with many |
| 29148 | recipients as a large high-speed burst. |
| 29149 | |
| 29150 | The &%per_addr%& option is like the &%per_rcpt%& option, except it counts the |
| 29151 | number of different recipients that the client has sent messages to in the |
| 29152 | last time period. That is, if the client repeatedly sends messages to the same |
| 29153 | recipient, its measured rate is not increased. This option can only be used in |
| 29154 | &%acl_smtp_rcpt%&. |
| 29155 | |
| 29156 | The &%per_cmd%& option causes Exim to recompute the rate every time the |
| 29157 | condition is processed. This can be used to limit the rate of any SMTP |
| 29158 | command. If it is used in multiple ACLs it can limit the aggregate rate of |
| 29159 | multiple different commands. |
| 29160 | |
| 29161 | The &%count=%& option can be used to alter how much Exim adds to the client's |
| 29162 | measured rate. For example, the &%per_byte%& option is equivalent to |
| 29163 | &`per_mail/count=$message_size`&. If there is no &%count=%& option, Exim |
| 29164 | increases the measured rate by one (except for the &%per_rcpt%& option in ACLs |
| 29165 | other than &%acl_smtp_rcpt%&). The count does not have to be an integer. |
| 29166 | |
| 29167 | The &%unique=%& option is described in section &<<ratoptuniq>>& below. |
| 29168 | |
| 29169 | |
| 29170 | .section "Ratelimit update modes" "ratoptupd" |
| 29171 | .cindex "rate limiting" "reading data without updating" |
| 29172 | You can specify one of three options with the &%ratelimit%& condition to |
| 29173 | control when its database is updated. This section describes the &%readonly%& |
| 29174 | mode, and the next section describes the &%strict%& and &%leaky%& modes. |
| 29175 | |
| 29176 | If the &%ratelimit%& condition is used in &%readonly%& mode, Exim looks up a |
| 29177 | previously-computed rate to check against the limit. |
| 29178 | |
| 29179 | For example, you can test the client's sending rate and deny it access (when |
| 29180 | it is too fast) in the connect ACL. If the client passes this check then it |
| 29181 | can go on to send a message, in which case its recorded rate will be updated |
| 29182 | in the MAIL ACL. Subsequent connections from the same client will check this |
| 29183 | new rate. |
| 29184 | .code |
| 29185 | acl_check_connect: |
| 29186 | deny ratelimit = 100 / 5m / readonly |
| 29187 | log_message = RATE CHECK: $sender_rate/$sender_rate_period \ |
| 29188 | (max $sender_rate_limit) |
| 29189 | # ... |
| 29190 | acl_check_mail: |
| 29191 | warn ratelimit = 100 / 5m / strict |
| 29192 | log_message = RATE UPDATE: $sender_rate/$sender_rate_period \ |
| 29193 | (max $sender_rate_limit) |
| 29194 | .endd |
| 29195 | |
| 29196 | If Exim encounters multiple &%ratelimit%& conditions with the same key when |
| 29197 | processing a message then it may increase the client's measured rate more than |
| 29198 | it should. For example, this will happen if you check the &%per_rcpt%& option |
| 29199 | in both &%acl_smtp_rcpt%& and &%acl_smtp_data%&. However it's OK to check the |
| 29200 | same &%ratelimit%& condition multiple times in the same ACL. You can avoid any |
| 29201 | multiple update problems by using the &%readonly%& option on later ratelimit |
| 29202 | checks. |
| 29203 | |
| 29204 | The &%per_*%& options described above do not make sense in some ACLs. If you |
| 29205 | use a &%per_*%& option in an ACL where it is not normally permitted then the |
| 29206 | update mode defaults to &%readonly%& and you cannot specify the &%strict%& or |
| 29207 | &%leaky%& modes. In other ACLs the default update mode is &%leaky%& (see the |
| 29208 | next section) so you must specify the &%readonly%& option explicitly. |
| 29209 | |
| 29210 | |
| 29211 | .section "Ratelimit options for handling fast clients" "ratoptfast" |
| 29212 | .cindex "rate limiting" "strict and leaky modes" |
| 29213 | If a client's average rate is greater than the maximum, the rate limiting |
| 29214 | engine can react in two possible ways, depending on the presence of the |
| 29215 | &%strict%& or &%leaky%& update modes. This is independent of the other |
| 29216 | counter-measures (such as rejecting the message) that may be specified by the |
| 29217 | rest of the ACL. |
| 29218 | |
| 29219 | The &%leaky%& (default) option means that the client's recorded rate is not |
| 29220 | updated if it is above the limit. The effect of this is that Exim measures the |
| 29221 | client's average rate of successfully sent email, which cannot be greater than |
| 29222 | the maximum allowed. If the client is over the limit it may suffer some |
| 29223 | counter-measures (as specified in the ACL), but it will still be able to send |
| 29224 | email at the configured maximum rate, whatever the rate of its attempts. This |
| 29225 | is generally the better choice if you have clients that retry automatically. |
| 29226 | For example, it does not prevent a sender with an over-aggressive retry rate |
| 29227 | from getting any email through. |
| 29228 | |
| 29229 | The &%strict%& option means that the client's recorded rate is always |
| 29230 | updated. The effect of this is that Exim measures the client's average rate |
| 29231 | of attempts to send email, which can be much higher than the maximum it is |
| 29232 | actually allowed. If the client is over the limit it may be subjected to |
| 29233 | counter-measures by the ACL. It must slow down and allow sufficient time to |
| 29234 | pass that its computed rate falls below the maximum before it can send email |
| 29235 | again. The time (the number of smoothing periods) it must wait and not |
| 29236 | attempt to send mail can be calculated with this formula: |
| 29237 | .code |
| 29238 | ln(peakrate/maxrate) |
| 29239 | .endd |
| 29240 | |
| 29241 | |
| 29242 | .section "Limiting the rate of different events" "ratoptuniq" |
| 29243 | .cindex "rate limiting" "counting unique events" |
| 29244 | The &%ratelimit%& &%unique=%& option controls a mechanism for counting the |
| 29245 | rate of different events. For example, the &%per_addr%& option uses this |
| 29246 | mechanism to count the number of different recipients that the client has |
| 29247 | sent messages to in the last time period; it is equivalent to |
| 29248 | &`per_rcpt/unique=$local_part@$domain`&. You could use this feature to |
| 29249 | measure the rate that a client uses different sender addresses with the |
| 29250 | options &`per_mail/unique=$sender_address`&. |
| 29251 | |
| 29252 | For each &%ratelimit%& key Exim stores the set of &%unique=%& values that it |
| 29253 | has seen for that key. The whole set is thrown away when it is older than the |
| 29254 | rate smoothing period &'p'&, so each different event is counted at most once |
| 29255 | per period. In the &%leaky%& update mode, an event that causes the client to |
| 29256 | go over the limit is not added to the set, in the same way that the client's |
| 29257 | recorded rate is not updated in the same situation. |
| 29258 | |
| 29259 | When you combine the &%unique=%& and &%readonly%& options, the specific |
| 29260 | &%unique=%& value is ignored, and Exim just retrieves the client's stored |
| 29261 | rate. |
| 29262 | |
| 29263 | The &%unique=%& mechanism needs more space in the ratelimit database than the |
| 29264 | other &%ratelimit%& options in order to store the event set. The number of |
| 29265 | unique values is potentially as large as the rate limit, so the extra space |
| 29266 | required increases with larger limits. |
| 29267 | |
| 29268 | The uniqueification is not perfect: there is a small probability that Exim |
| 29269 | will think a new event has happened before. If the sender's rate is less than |
| 29270 | the limit, Exim should be more than 99.9% correct. However in &%strict%& mode |
| 29271 | the measured rate can go above the limit, in which case Exim may under-count |
| 29272 | events by a significant margin. Fortunately, if the rate is high enough (2.7 |
| 29273 | times the limit) that the false positive rate goes above 9%, then Exim will |
| 29274 | throw away the over-full event set before the measured rate falls below the |
| 29275 | limit. Therefore the only harm should be that exceptionally high sending rates |
| 29276 | are logged incorrectly; any countermeasures you configure will be as effective |
| 29277 | as intended. |
| 29278 | |
| 29279 | |
| 29280 | .section "Using rate limiting" "useratlim" |
| 29281 | Exim's other ACL facilities are used to define what counter-measures are taken |
| 29282 | when the rate limit is exceeded. This might be anything from logging a warning |
| 29283 | (for example, while measuring existing sending rates in order to define |
| 29284 | policy), through time delays to slow down fast senders, up to rejecting the |
| 29285 | message. For example: |
| 29286 | .code |
| 29287 | # Log all senders' rates |
| 29288 | warn ratelimit = 0 / 1h / strict |
| 29289 | log_message = Sender rate $sender_rate / $sender_rate_period |
| 29290 | |
| 29291 | # Slow down fast senders; note the need to truncate $sender_rate |
| 29292 | # at the decimal point. |
| 29293 | warn ratelimit = 100 / 1h / per_rcpt / strict |
| 29294 | delay = ${eval: ${sg{$sender_rate}{[.].*}{}} - \ |
| 29295 | $sender_rate_limit }s |
| 29296 | |
| 29297 | # Keep authenticated users under control |
| 29298 | deny authenticated = * |
| 29299 | ratelimit = 100 / 1d / strict / $authenticated_id |
| 29300 | |
| 29301 | # System-wide rate limit |
| 29302 | defer message = Sorry, too busy. Try again later. |
| 29303 | ratelimit = 10 / 1s / $primary_hostname |
| 29304 | |
| 29305 | # Restrict incoming rate from each host, with a default |
| 29306 | # set using a macro and special cases looked up in a table. |
| 29307 | defer message = Sender rate exceeds $sender_rate_limit \ |
| 29308 | messages per $sender_rate_period |
| 29309 | ratelimit = ${lookup {$sender_host_address} \ |
| 29310 | cdb {DB/ratelimits.cdb} \ |
| 29311 | {$value} {RATELIMIT} } |
| 29312 | .endd |
| 29313 | &*Warning*&: If you have a busy server with a lot of &%ratelimit%& tests, |
| 29314 | especially with the &%per_rcpt%& option, you may suffer from a performance |
| 29315 | bottleneck caused by locking on the ratelimit hints database. Apart from |
| 29316 | making your ACLs less complicated, you can reduce the problem by using a |
| 29317 | RAM disk for Exim's hints directory (usually &_/var/spool/exim/db/_&). However |
| 29318 | this means that Exim will lose its hints data after a reboot (including retry |
| 29319 | hints, the callout cache, and ratelimit data). |
| 29320 | |
| 29321 | |
| 29322 | |
| 29323 | .section "Address verification" "SECTaddressverification" |
| 29324 | .cindex "verifying address" "options for" |
| 29325 | .cindex "policy control" "address verification" |
| 29326 | Several of the &%verify%& conditions described in section |
| 29327 | &<<SECTaclconditions>>& cause addresses to be verified. Section |
| 29328 | &<<SECTsenaddver>>& discusses the reporting of sender verification failures. |
| 29329 | The verification conditions can be followed by options that modify the |
| 29330 | verification process. The options are separated from the keyword and from each |
| 29331 | other by slashes, and some of them contain parameters. For example: |
| 29332 | .code |
| 29333 | verify = sender/callout |
| 29334 | verify = recipient/defer_ok/callout=10s,defer_ok |
| 29335 | .endd |
| 29336 | The first stage of address verification, which always happens, is to run the |
| 29337 | address through the routers, in &"verify mode"&. Routers can detect the |
| 29338 | difference between verification and routing for delivery, and their actions can |
| 29339 | be varied by a number of generic options such as &%verify%& and &%verify_only%& |
| 29340 | (see chapter &<<CHAProutergeneric>>&). If routing fails, verification fails. |
| 29341 | The available options are as follows: |
| 29342 | |
| 29343 | .ilist |
| 29344 | If the &%callout%& option is specified, successful routing to one or more |
| 29345 | remote hosts is followed by a &"callout"& to those hosts as an additional |
| 29346 | check. Callouts and their sub-options are discussed in the next section. |
| 29347 | .next |
| 29348 | If there is a defer error while doing verification routing, the ACL |
| 29349 | normally returns &"defer"&. However, if you include &%defer_ok%& in the |
| 29350 | options, the condition is forced to be true instead. Note that this is a main |
| 29351 | verification option as well as a suboption for callouts. |
| 29352 | .next |
| 29353 | The &%no_details%& option is covered in section &<<SECTsenaddver>>&, which |
| 29354 | discusses the reporting of sender address verification failures. |
| 29355 | .next |
| 29356 | The &%success_on_redirect%& option causes verification always to succeed |
| 29357 | immediately after a successful redirection. By default, if a redirection |
| 29358 | generates just one address, that address is also verified. See further |
| 29359 | discussion in section &<<SECTredirwhilveri>>&. |
| 29360 | .endlist |
| 29361 | |
| 29362 | .cindex "verifying address" "differentiating failures" |
| 29363 | .vindex "&$recipient_verify_failure$&" |
| 29364 | .vindex "&$sender_verify_failure$&" |
| 29365 | .vindex "&$acl_verify_message$&" |
| 29366 | After an address verification failure, &$acl_verify_message$& contains the |
| 29367 | error message that is associated with the failure. It can be preserved by |
| 29368 | coding like this: |
| 29369 | .code |
| 29370 | warn !verify = sender |
| 29371 | set acl_m0 = $acl_verify_message |
| 29372 | .endd |
| 29373 | If you are writing your own custom rejection message or log message when |
| 29374 | denying access, you can use this variable to include information about the |
| 29375 | verification failure. |
| 29376 | |
| 29377 | In addition, &$sender_verify_failure$& or &$recipient_verify_failure$& (as |
| 29378 | appropriate) contains one of the following words: |
| 29379 | |
| 29380 | .ilist |
| 29381 | &%qualify%&: The address was unqualified (no domain), and the message |
| 29382 | was neither local nor came from an exempted host. |
| 29383 | .next |
| 29384 | &%route%&: Routing failed. |
| 29385 | .next |
| 29386 | &%mail%&: Routing succeeded, and a callout was attempted; rejection |
| 29387 | occurred at or before the MAIL command (that is, on initial |
| 29388 | connection, HELO, or MAIL). |
| 29389 | .next |
| 29390 | &%recipient%&: The RCPT command in a callout was rejected. |
| 29391 | .next |
| 29392 | &%postmaster%&: The postmaster check in a callout was rejected. |
| 29393 | .endlist |
| 29394 | |
| 29395 | The main use of these variables is expected to be to distinguish between |
| 29396 | rejections of MAIL and rejections of RCPT in callouts. |
| 29397 | |
| 29398 | |
| 29399 | |
| 29400 | |
| 29401 | .section "Callout verification" "SECTcallver" |
| 29402 | .cindex "verifying address" "by callout" |
| 29403 | .cindex "callout" "verification" |
| 29404 | .cindex "SMTP" "callout verification" |
| 29405 | For non-local addresses, routing verifies the domain, but is unable to do any |
| 29406 | checking of the local part. There are situations where some means of verifying |
| 29407 | the local part is desirable. One way this can be done is to make an SMTP |
| 29408 | &'callback'& to a delivery host for the sender address or a &'callforward'& to |
| 29409 | a subsequent host for a recipient address, to see if the host accepts the |
| 29410 | address. We use the term &'callout'& to cover both cases. Note that for a |
| 29411 | sender address, the callback is not to the client host that is trying to |
| 29412 | deliver the message, but to one of the hosts that accepts incoming mail for the |
| 29413 | sender's domain. |
| 29414 | |
| 29415 | Exim does not do callouts by default. If you want them to happen, you must |
| 29416 | request them by setting appropriate options on the &%verify%& condition, as |
| 29417 | described below. This facility should be used with care, because it can add a |
| 29418 | lot of resource usage to the cost of verifying an address. However, Exim does |
| 29419 | cache the results of callouts, which helps to reduce the cost. Details of |
| 29420 | caching are in section &<<SECTcallvercache>>&. |
| 29421 | |
| 29422 | Recipient callouts are usually used only between hosts that are controlled by |
| 29423 | the same administration. For example, a corporate gateway host could use |
| 29424 | callouts to check for valid recipients on an internal mailserver. A successful |
| 29425 | callout does not guarantee that a real delivery to the address would succeed; |
| 29426 | on the other hand, a failing callout does guarantee that a delivery would fail. |
| 29427 | |
| 29428 | If the &%callout%& option is present on a condition that verifies an address, a |
| 29429 | second stage of verification occurs if the address is successfully routed to |
| 29430 | one or more remote hosts. The usual case is routing by a &(dnslookup)& or a |
| 29431 | &(manualroute)& router, where the router specifies the hosts. However, if a |
| 29432 | router that does not set up hosts routes to an &(smtp)& transport with a |
| 29433 | &%hosts%& setting, the transport's hosts are used. If an &(smtp)& transport has |
| 29434 | &%hosts_override%& set, its hosts are always used, whether or not the router |
| 29435 | supplies a host list. |
| 29436 | Callouts are only supported on &(smtp)& transports. |
| 29437 | |
| 29438 | The port that is used is taken from the transport, if it is specified and is a |
| 29439 | remote transport. (For routers that do verification only, no transport need be |
| 29440 | specified.) Otherwise, the default SMTP port is used. If a remote transport |
| 29441 | specifies an outgoing interface, this is used; otherwise the interface is not |
| 29442 | specified. Likewise, the text that is used for the HELO command is taken from |
| 29443 | the transport's &%helo_data%& option; if there is no transport, the value of |
| 29444 | &$smtp_active_hostname$& is used. |
| 29445 | |
| 29446 | For a sender callout check, Exim makes SMTP connections to the remote hosts, to |
| 29447 | test whether a bounce message could be delivered to the sender address. The |
| 29448 | following SMTP commands are sent: |
| 29449 | .display |
| 29450 | &`HELO `&<&'local host name'&> |
| 29451 | &`MAIL FROM:<>`& |
| 29452 | &`RCPT TO:`&<&'the address to be tested'&> |
| 29453 | &`QUIT`& |
| 29454 | .endd |
| 29455 | LHLO is used instead of HELO if the transport's &%protocol%& option is |
| 29456 | set to &"lmtp"&. |
| 29457 | |
| 29458 | The callout may use EHLO, AUTH and/or STARTTLS given appropriate option |
| 29459 | settings. |
| 29460 | |
| 29461 | A recipient callout check is similar. By default, it also uses an empty address |
| 29462 | for the sender. This default is chosen because most hosts do not make use of |
| 29463 | the sender address when verifying a recipient. Using the same address means |
| 29464 | that a single cache entry can be used for each recipient. Some sites, however, |
| 29465 | do make use of the sender address when verifying. These are catered for by the |
| 29466 | &%use_sender%& and &%use_postmaster%& options, described in the next section. |
| 29467 | |
| 29468 | If the response to the RCPT command is a 2&'xx'& code, the verification |
| 29469 | succeeds. If it is 5&'xx'&, the verification fails. For any other condition, |
| 29470 | Exim tries the next host, if any. If there is a problem with all the remote |
| 29471 | hosts, the ACL yields &"defer"&, unless the &%defer_ok%& parameter of the |
| 29472 | &%callout%& option is given, in which case the condition is forced to succeed. |
| 29473 | |
| 29474 | .cindex "SMTP" "output flushing, disabling for callout" |
| 29475 | A callout may take a little time. For this reason, Exim normally flushes SMTP |
| 29476 | output before performing a callout in an ACL, to avoid unexpected timeouts in |
| 29477 | clients when the SMTP PIPELINING extension is in use. The flushing can be |
| 29478 | disabled by using a &%control%& modifier to set &%no_callout_flush%&. |
| 29479 | |
| 29480 | |
| 29481 | |
| 29482 | |
| 29483 | .section "Additional parameters for callouts" "CALLaddparcall" |
| 29484 | .cindex "callout" "additional parameters for" |
| 29485 | The &%callout%& option can be followed by an equals sign and a number of |
| 29486 | optional parameters, separated by commas. For example: |
| 29487 | .code |
| 29488 | verify = recipient/callout=10s,defer_ok |
| 29489 | .endd |
| 29490 | The old syntax, which had &%callout_defer_ok%& and &%check_postmaster%& as |
| 29491 | separate verify options, is retained for backwards compatibility, but is now |
| 29492 | deprecated. The additional parameters for &%callout%& are as follows: |
| 29493 | |
| 29494 | |
| 29495 | .vlist |
| 29496 | .vitem <&'a&~time&~interval'&> |
| 29497 | .cindex "callout" "timeout, specifying" |
| 29498 | This specifies the timeout that applies for the callout attempt to each host. |
| 29499 | For example: |
| 29500 | .code |
| 29501 | verify = sender/callout=5s |
| 29502 | .endd |
| 29503 | The default is 30 seconds. The timeout is used for each response from the |
| 29504 | remote host. It is also used for the initial connection, unless overridden by |
| 29505 | the &%connect%& parameter. |
| 29506 | |
| 29507 | |
| 29508 | .vitem &*connect&~=&~*&<&'time&~interval'&> |
| 29509 | .cindex "callout" "connection timeout, specifying" |
| 29510 | This parameter makes it possible to set a different (usually smaller) timeout |
| 29511 | for making the SMTP connection. For example: |
| 29512 | .code |
| 29513 | verify = sender/callout=5s,connect=1s |
| 29514 | .endd |
| 29515 | If not specified, this timeout defaults to the general timeout value. |
| 29516 | |
| 29517 | .vitem &*defer_ok*& |
| 29518 | .cindex "callout" "defer, action on" |
| 29519 | When this parameter is present, failure to contact any host, or any other kind |
| 29520 | of temporary error, is treated as success by the ACL. However, the cache is not |
| 29521 | updated in this circumstance. |
| 29522 | |
| 29523 | .vitem &*fullpostmaster*& |
| 29524 | .cindex "callout" "full postmaster check" |
| 29525 | This operates like the &%postmaster%& option (see below), but if the check for |
| 29526 | &'postmaster@domain'& fails, it tries just &'postmaster'&, without a domain, in |
| 29527 | accordance with the specification in RFC 2821. The RFC states that the |
| 29528 | unqualified address &'postmaster'& should be accepted. |
| 29529 | |
| 29530 | |
| 29531 | .vitem &*mailfrom&~=&~*&<&'email&~address'&> |
| 29532 | .cindex "callout" "sender when verifying header" |
| 29533 | When verifying addresses in header lines using the &%header_sender%& |
| 29534 | verification option, Exim behaves by default as if the addresses are envelope |
| 29535 | sender addresses from a message. Callout verification therefore tests to see |
| 29536 | whether a bounce message could be delivered, by using an empty address in the |
| 29537 | MAIL command. However, it is arguable that these addresses might never be used |
| 29538 | as envelope senders, and could therefore justifiably reject bounce messages |
| 29539 | (empty senders). The &%mailfrom%& callout parameter allows you to specify what |
| 29540 | address to use in the MAIL command. For example: |
| 29541 | .code |
| 29542 | require verify = header_sender/callout=mailfrom=abcd@x.y.z |
| 29543 | .endd |
| 29544 | This parameter is available only for the &%header_sender%& verification option. |
| 29545 | |
| 29546 | |
| 29547 | .vitem &*maxwait&~=&~*&<&'time&~interval'&> |
| 29548 | .cindex "callout" "overall timeout, specifying" |
| 29549 | This parameter sets an overall timeout for performing a callout verification. |
| 29550 | For example: |
| 29551 | .code |
| 29552 | verify = sender/callout=5s,maxwait=30s |
| 29553 | .endd |
| 29554 | This timeout defaults to four times the callout timeout for individual SMTP |
| 29555 | commands. The overall timeout applies when there is more than one host that can |
| 29556 | be tried. The timeout is checked before trying the next host. This prevents |
| 29557 | very long delays if there are a large number of hosts and all are timing out |
| 29558 | (for example, when network connections are timing out). |
| 29559 | |
| 29560 | |
| 29561 | .vitem &*no_cache*& |
| 29562 | .cindex "callout" "cache, suppressing" |
| 29563 | .cindex "caching callout, suppressing" |
| 29564 | When this parameter is given, the callout cache is neither read nor updated. |
| 29565 | |
| 29566 | .vitem &*postmaster*& |
| 29567 | .cindex "callout" "postmaster; checking" |
| 29568 | When this parameter is set, a successful callout check is followed by a similar |
| 29569 | check for the local part &'postmaster'& at the same domain. If this address is |
| 29570 | rejected, the callout fails (but see &%fullpostmaster%& above). The result of |
| 29571 | the postmaster check is recorded in a cache record; if it is a failure, this is |
| 29572 | used to fail subsequent callouts for the domain without a connection being |
| 29573 | made, until the cache record expires. |
| 29574 | |
| 29575 | .vitem &*postmaster_mailfrom&~=&~*&<&'email&~address'&> |
| 29576 | The postmaster check uses an empty sender in the MAIL command by default. |
| 29577 | You can use this parameter to do a postmaster check using a different address. |
| 29578 | For example: |
| 29579 | .code |
| 29580 | require verify = sender/callout=postmaster_mailfrom=abc@x.y.z |
| 29581 | .endd |
| 29582 | If both &%postmaster%& and &%postmaster_mailfrom%& are present, the rightmost |
| 29583 | one overrides. The &%postmaster%& parameter is equivalent to this example: |
| 29584 | .code |
| 29585 | require verify = sender/callout=postmaster_mailfrom= |
| 29586 | .endd |
| 29587 | &*Warning*&: The caching arrangements for postmaster checking do not take |
| 29588 | account of the sender address. It is assumed that either the empty address or |
| 29589 | a fixed non-empty address will be used. All that Exim remembers is that the |
| 29590 | postmaster check for the domain succeeded or failed. |
| 29591 | |
| 29592 | |
| 29593 | .vitem &*random*& |
| 29594 | .cindex "callout" "&""random""& check" |
| 29595 | When this parameter is set, before doing the normal callout check, Exim does a |
| 29596 | check for a &"random"& local part at the same domain. The local part is not |
| 29597 | really random &-- it is defined by the expansion of the option |
| 29598 | &%callout_random_local_part%&, which defaults to |
| 29599 | .code |
| 29600 | $primary_hostname-$tod_epoch-testing |
| 29601 | .endd |
| 29602 | The idea here is to try to determine whether the remote host accepts all local |
| 29603 | parts without checking. If it does, there is no point in doing callouts for |
| 29604 | specific local parts. If the &"random"& check succeeds, the result is saved in |
| 29605 | a cache record, and used to force the current and subsequent callout checks to |
| 29606 | succeed without a connection being made, until the cache record expires. |
| 29607 | |
| 29608 | .vitem &*use_postmaster*& |
| 29609 | .cindex "callout" "sender for recipient check" |
| 29610 | This parameter applies to recipient callouts only. For example: |
| 29611 | .code |
| 29612 | deny !verify = recipient/callout=use_postmaster |
| 29613 | .endd |
| 29614 | .vindex "&$qualify_domain$&" |
| 29615 | It causes a non-empty postmaster address to be used in the MAIL command when |
| 29616 | performing the callout for the recipient, and also for a &"random"& check if |
| 29617 | that is configured. The local part of the address is &`postmaster`& and the |
| 29618 | domain is the contents of &$qualify_domain$&. |
| 29619 | |
| 29620 | .vitem &*use_sender*& |
| 29621 | This option applies to recipient callouts only. For example: |
| 29622 | .code |
| 29623 | require verify = recipient/callout=use_sender |
| 29624 | .endd |
| 29625 | It causes the message's actual sender address to be used in the MAIL |
| 29626 | command when performing the callout, instead of an empty address. There is no |
| 29627 | need to use this option unless you know that the called hosts make use of the |
| 29628 | sender when checking recipients. If used indiscriminately, it reduces the |
| 29629 | usefulness of callout caching. |
| 29630 | .endlist |
| 29631 | |
| 29632 | If you use any of the parameters that set a non-empty sender for the MAIL |
| 29633 | command (&%mailfrom%&, &%postmaster_mailfrom%&, &%use_postmaster%&, or |
| 29634 | &%use_sender%&), you should think about possible loops. Recipient checking is |
| 29635 | usually done between two hosts that are under the same management, and the host |
| 29636 | that receives the callouts is not normally configured to do callouts itself. |
| 29637 | Therefore, it is normally safe to use &%use_postmaster%& or &%use_sender%& in |
| 29638 | these circumstances. |
| 29639 | |
| 29640 | However, if you use a non-empty sender address for a callout to an arbitrary |
| 29641 | host, there is the likelihood that the remote host will itself initiate a |
| 29642 | callout check back to your host. As it is checking what appears to be a message |
| 29643 | sender, it is likely to use an empty address in MAIL, thus avoiding a |
| 29644 | callout loop. However, to be on the safe side it would be best to set up your |
| 29645 | own ACLs so that they do not do sender verification checks when the recipient |
| 29646 | is the address you use for header sender or postmaster callout checking. |
| 29647 | |
| 29648 | Another issue to think about when using non-empty senders for callouts is |
| 29649 | caching. When you set &%mailfrom%& or &%use_sender%&, the cache record is keyed |
| 29650 | by the sender/recipient combination; thus, for any given recipient, many more |
| 29651 | actual callouts are performed than when an empty sender or postmaster is used. |
| 29652 | |
| 29653 | |
| 29654 | |
| 29655 | |
| 29656 | .section "Callout caching" "SECTcallvercache" |
| 29657 | .cindex "hints database" "callout cache" |
| 29658 | .cindex "callout" "cache, description of" |
| 29659 | .cindex "caching" "callout" |
| 29660 | Exim caches the results of callouts in order to reduce the amount of resources |
| 29661 | used, unless you specify the &%no_cache%& parameter with the &%callout%& |
| 29662 | option. A hints database called &"callout"& is used for the cache. Two |
| 29663 | different record types are used: one records the result of a callout check for |
| 29664 | a specific address, and the other records information that applies to the |
| 29665 | entire domain (for example, that it accepts the local part &'postmaster'&). |
| 29666 | |
| 29667 | When an original callout fails, a detailed SMTP error message is given about |
| 29668 | the failure. However, for subsequent failures use the cache data, this message |
| 29669 | is not available. |
| 29670 | |
| 29671 | The expiry times for negative and positive address cache records are |
| 29672 | independent, and can be set by the global options &%callout_negative_expire%& |
| 29673 | (default 2h) and &%callout_positive_expire%& (default 24h), respectively. |
| 29674 | |
| 29675 | If a host gives a negative response to an SMTP connection, or rejects any |
| 29676 | commands up to and including |
| 29677 | .code |
| 29678 | MAIL FROM:<> |
| 29679 | .endd |
| 29680 | (but not including the MAIL command with a non-empty address), |
| 29681 | any callout attempt is bound to fail. Exim remembers such failures in a |
| 29682 | domain cache record, which it uses to fail callouts for the domain without |
| 29683 | making new connections, until the domain record times out. There are two |
| 29684 | separate expiry times for domain cache records: |
| 29685 | &%callout_domain_negative_expire%& (default 3h) and |
| 29686 | &%callout_domain_positive_expire%& (default 7d). |
| 29687 | |
| 29688 | Domain records expire when the negative expiry time is reached if callouts |
| 29689 | cannot be made for the domain, or if the postmaster check failed. |
| 29690 | Otherwise, they expire when the positive expiry time is reached. This |
| 29691 | ensures that, for example, a host that stops accepting &"random"& local parts |
| 29692 | will eventually be noticed. |
| 29693 | |
| 29694 | The callout caching mechanism is based on the domain of the address that is |
| 29695 | being tested. If the domain routes to several hosts, it is assumed that their |
| 29696 | behaviour will be the same. |
| 29697 | |
| 29698 | |
| 29699 | |
| 29700 | .section "Sender address verification reporting" "SECTsenaddver" |
| 29701 | .cindex "verifying" "suppressing error details" |
| 29702 | See section &<<SECTaddressverification>>& for a general discussion of |
| 29703 | verification. When sender verification fails in an ACL, the details of the |
| 29704 | failure are given as additional output lines before the 550 response to the |
| 29705 | relevant SMTP command (RCPT or DATA). For example, if sender callout is in use, |
| 29706 | you might see: |
| 29707 | .code |
| 29708 | MAIL FROM:<xyz@abc.example> |
| 29709 | 250 OK |
| 29710 | RCPT TO:<pqr@def.example> |
| 29711 | 550-Verification failed for <xyz@abc.example> |
| 29712 | 550-Called: 192.168.34.43 |
| 29713 | 550-Sent: RCPT TO:<xyz@abc.example> |
| 29714 | 550-Response: 550 Unknown local part xyz in <xyz@abc.example> |
| 29715 | 550 Sender verification failed |
| 29716 | .endd |
| 29717 | If more than one RCPT command fails in the same way, the details are given |
| 29718 | only for the first of them. However, some administrators do not want to send |
| 29719 | out this much information. You can suppress the details by adding |
| 29720 | &`/no_details`& to the ACL statement that requests sender verification. For |
| 29721 | example: |
| 29722 | .code |
| 29723 | verify = sender/no_details |
| 29724 | .endd |
| 29725 | |
| 29726 | .section "Redirection while verifying" "SECTredirwhilveri" |
| 29727 | .cindex "verifying" "redirection while" |
| 29728 | .cindex "address redirection" "while verifying" |
| 29729 | A dilemma arises when a local address is redirected by aliasing or forwarding |
| 29730 | during verification: should the generated addresses themselves be verified, |
| 29731 | or should the successful expansion of the original address be enough to verify |
| 29732 | it? By default, Exim takes the following pragmatic approach: |
| 29733 | |
| 29734 | .ilist |
| 29735 | When an incoming address is redirected to just one child address, verification |
| 29736 | continues with the child address, and if that fails to verify, the original |
| 29737 | verification also fails. |
| 29738 | .next |
| 29739 | When an incoming address is redirected to more than one child address, |
| 29740 | verification does not continue. A success result is returned. |
| 29741 | .endlist |
| 29742 | |
| 29743 | This seems the most reasonable behaviour for the common use of aliasing as a |
| 29744 | way of redirecting different local parts to the same mailbox. It means, for |
| 29745 | example, that a pair of alias entries of the form |
| 29746 | .code |
| 29747 | A.Wol: aw123 |
| 29748 | aw123: :fail: Gone away, no forwarding address |
| 29749 | .endd |
| 29750 | work as expected, with both local parts causing verification failure. When a |
| 29751 | redirection generates more than one address, the behaviour is more like a |
| 29752 | mailing list, where the existence of the alias itself is sufficient for |
| 29753 | verification to succeed. |
| 29754 | |
| 29755 | It is possible, however, to change the default behaviour so that all successful |
| 29756 | redirections count as successful verifications, however many new addresses are |
| 29757 | generated. This is specified by the &%success_on_redirect%& verification |
| 29758 | option. For example: |
| 29759 | .code |
| 29760 | require verify = recipient/success_on_redirect/callout=10s |
| 29761 | .endd |
| 29762 | In this example, verification succeeds if a router generates a new address, and |
| 29763 | the callout does not occur, because no address was routed to a remote host. |
| 29764 | |
| 29765 | When verification is being tested via the &%-bv%& option, the treatment of |
| 29766 | redirections is as just described, unless the &%-v%& or any debugging option is |
| 29767 | also specified. In that case, full verification is done for every generated |
| 29768 | address and a report is output for each of them. |
| 29769 | |
| 29770 | |
| 29771 | |
| 29772 | .section "Client SMTP authorization (CSA)" "SECTverifyCSA" |
| 29773 | .cindex "CSA" "verifying" |
| 29774 | Client SMTP Authorization is a system that allows a site to advertise |
| 29775 | which machines are and are not permitted to send email. This is done by placing |
| 29776 | special SRV records in the DNS; these are looked up using the client's HELO |
| 29777 | domain. At the time of writing, CSA is still an Internet Draft. Client SMTP |
| 29778 | Authorization checks in Exim are performed by the ACL condition: |
| 29779 | .code |
| 29780 | verify = csa |
| 29781 | .endd |
| 29782 | This fails if the client is not authorized. If there is a DNS problem, or if no |
| 29783 | valid CSA SRV record is found, or if the client is authorized, the condition |
| 29784 | succeeds. These three cases can be distinguished using the expansion variable |
| 29785 | &$csa_status$&, which can take one of the values &"fail"&, &"defer"&, |
| 29786 | &"unknown"&, or &"ok"&. The condition does not itself defer because that would |
| 29787 | be likely to cause problems for legitimate email. |
| 29788 | |
| 29789 | The error messages produced by the CSA code include slightly more |
| 29790 | detail. If &$csa_status$& is &"defer"&, this may be because of problems |
| 29791 | looking up the CSA SRV record, or problems looking up the CSA target |
| 29792 | address record. There are four reasons for &$csa_status$& being &"fail"&: |
| 29793 | |
| 29794 | .ilist |
| 29795 | The client's host name is explicitly not authorized. |
| 29796 | .next |
| 29797 | The client's IP address does not match any of the CSA target IP addresses. |
| 29798 | .next |
| 29799 | The client's host name is authorized but it has no valid target IP addresses |
| 29800 | (for example, the target's addresses are IPv6 and the client is using IPv4). |
| 29801 | .next |
| 29802 | The client's host name has no CSA SRV record but a parent domain has asserted |
| 29803 | that all subdomains must be explicitly authorized. |
| 29804 | .endlist |
| 29805 | |
| 29806 | The &%csa%& verification condition can take an argument which is the domain to |
| 29807 | use for the DNS query. The default is: |
| 29808 | .code |
| 29809 | verify = csa/$sender_helo_name |
| 29810 | .endd |
| 29811 | This implementation includes an extension to CSA. If the query domain |
| 29812 | is an address literal such as [192.0.2.95], or if it is a bare IP |
| 29813 | address, Exim searches for CSA SRV records in the reverse DNS as if |
| 29814 | the HELO domain was (for example) &'95.2.0.192.in-addr.arpa'&. Therefore it is |
| 29815 | meaningful to say: |
| 29816 | .code |
| 29817 | verify = csa/$sender_host_address |
| 29818 | .endd |
| 29819 | In fact, this is the check that Exim performs if the client does not say HELO. |
| 29820 | This extension can be turned off by setting the main configuration option |
| 29821 | &%dns_csa_use_reverse%& to be false. |
| 29822 | |
| 29823 | If a CSA SRV record is not found for the domain itself, a search |
| 29824 | is performed through its parent domains for a record which might be |
| 29825 | making assertions about subdomains. The maximum depth of this search is limited |
| 29826 | using the main configuration option &%dns_csa_search_limit%&, which is 5 by |
| 29827 | default. Exim does not look for CSA SRV records in a top level domain, so the |
| 29828 | default settings handle HELO domains as long as seven |
| 29829 | (&'hostname.five.four.three.two.one.com'&). This encompasses the vast majority |
| 29830 | of legitimate HELO domains. |
| 29831 | |
| 29832 | The &'dnsdb'& lookup also has support for CSA. Although &'dnsdb'& also supports |
| 29833 | direct SRV lookups, this is not sufficient because of the extra parent domain |
| 29834 | search behaviour of CSA, and (as with PTR lookups) &'dnsdb'& also turns IP |
| 29835 | addresses into lookups in the reverse DNS space. The result of a successful |
| 29836 | lookup such as: |
| 29837 | .code |
| 29838 | ${lookup dnsdb {csa=$sender_helo_name}} |
| 29839 | .endd |
| 29840 | has two space-separated fields: an authorization code and a target host name. |
| 29841 | The authorization code can be &"Y"& for yes, &"N"& for no, &"X"& for explicit |
| 29842 | authorization required but absent, or &"?"& for unknown. |
| 29843 | |
| 29844 | |
| 29845 | |
| 29846 | |
| 29847 | .section "Bounce address tag validation" "SECTverifyPRVS" |
| 29848 | .cindex "BATV, verifying" |
| 29849 | Bounce address tag validation (BATV) is a scheme whereby the envelope senders |
| 29850 | of outgoing messages have a cryptographic, timestamped &"tag"& added to them. |
| 29851 | Genuine incoming bounce messages should therefore always be addressed to |
| 29852 | recipients that have a valid tag. This scheme is a way of detecting unwanted |
| 29853 | bounce messages caused by sender address forgeries (often called &"collateral |
| 29854 | spam"&), because the recipients of such messages do not include valid tags. |
| 29855 | |
| 29856 | There are two expansion items to help with the implementation of the BATV |
| 29857 | &"prvs"& (private signature) scheme in an Exim configuration. This scheme signs |
| 29858 | the original envelope sender address by using a simple key to add a hash of the |
| 29859 | address and some time-based randomizing information. The &%prvs%& expansion |
| 29860 | item creates a signed address, and the &%prvscheck%& expansion item checks one. |
| 29861 | The syntax of these expansion items is described in section |
| 29862 | &<<SECTexpansionitems>>&. |
| 29863 | |
| 29864 | As an example, suppose the secret per-address keys are stored in an MySQL |
| 29865 | database. A query to look up the key for an address could be defined as a macro |
| 29866 | like this: |
| 29867 | .code |
| 29868 | PRVSCHECK_SQL = ${lookup mysql{SELECT secret FROM batv_prvs \ |
| 29869 | WHERE sender='${quote_mysql:$prvscheck_address}'\ |
| 29870 | }{$value}} |
| 29871 | .endd |
| 29872 | Suppose also that the senders who make use of BATV are defined by an address |
| 29873 | list called &%batv_senders%&. Then, in the ACL for RCPT commands, you could |
| 29874 | use this: |
| 29875 | .code |
| 29876 | # Bounces: drop unsigned addresses for BATV senders |
| 29877 | deny message = This address does not send an unsigned reverse path |
| 29878 | senders = : |
| 29879 | recipients = +batv_senders |
| 29880 | |
| 29881 | # Bounces: In case of prvs-signed address, check signature. |
| 29882 | deny message = Invalid reverse path signature. |
| 29883 | senders = : |
| 29884 | condition = ${prvscheck {$local_part@$domain}\ |
| 29885 | {PRVSCHECK_SQL}{1}} |
| 29886 | !condition = $prvscheck_result |
| 29887 | .endd |
| 29888 | The first statement rejects recipients for bounce messages that are addressed |
| 29889 | to plain BATV sender addresses, because it is known that BATV senders do not |
| 29890 | send out messages with plain sender addresses. The second statement rejects |
| 29891 | recipients that are prvs-signed, but with invalid signatures (either because |
| 29892 | the key is wrong, or the signature has timed out). |
| 29893 | |
| 29894 | A non-prvs-signed address is not rejected by the second statement, because the |
| 29895 | &%prvscheck%& expansion yields an empty string if its first argument is not a |
| 29896 | prvs-signed address, thus causing the &%condition%& condition to be false. If |
| 29897 | the first argument is a syntactically valid prvs-signed address, the yield is |
| 29898 | the third string (in this case &"1"&), whether or not the cryptographic and |
| 29899 | timeout checks succeed. The &$prvscheck_result$& variable contains the result |
| 29900 | of the checks (empty for failure, &"1"& for success). |
| 29901 | |
| 29902 | There is one more issue you must consider when implementing prvs-signing: |
| 29903 | you have to ensure that the routers accept prvs-signed addresses and |
| 29904 | deliver them correctly. The easiest way to handle this is to use a &(redirect)& |
| 29905 | router to remove the signature with a configuration along these lines: |
| 29906 | .code |
| 29907 | batv_redirect: |
| 29908 | driver = redirect |
| 29909 | data = ${prvscheck {$local_part@$domain}{PRVSCHECK_SQL}} |
| 29910 | .endd |
| 29911 | This works because, if the third argument of &%prvscheck%& is empty, the result |
| 29912 | of the expansion of a prvs-signed address is the decoded value of the original |
| 29913 | address. This router should probably be the first of your routers that handles |
| 29914 | local addresses. |
| 29915 | |
| 29916 | To create BATV-signed addresses in the first place, a transport of this form |
| 29917 | can be used: |
| 29918 | .code |
| 29919 | external_smtp_batv: |
| 29920 | driver = smtp |
| 29921 | return_path = ${prvs {$return_path} \ |
| 29922 | {${lookup mysql{SELECT \ |
| 29923 | secret FROM batv_prvs WHERE \ |
| 29924 | sender='${quote_mysql:$sender_address}'} \ |
| 29925 | {$value}fail}}} |
| 29926 | .endd |
| 29927 | If no key can be found for the existing return path, no signing takes place. |
| 29928 | |
| 29929 | |
| 29930 | |
| 29931 | .section "Using an ACL to control relaying" "SECTrelaycontrol" |
| 29932 | .cindex "&ACL;" "relay control" |
| 29933 | .cindex "relaying" "control by ACL" |
| 29934 | .cindex "policy control" "relay control" |
| 29935 | An MTA is said to &'relay'& a message if it receives it from some host and |
| 29936 | delivers it directly to another host as a result of a remote address contained |
| 29937 | within it. Redirecting a local address via an alias or forward file and then |
| 29938 | passing the message on to another host is not relaying, |
| 29939 | .cindex "&""percent hack""&" |
| 29940 | but a redirection as a result of the &"percent hack"& is. |
| 29941 | |
| 29942 | Two kinds of relaying exist, which are termed &"incoming"& and &"outgoing"&. |
| 29943 | A host which is acting as a gateway or an MX backup is concerned with incoming |
| 29944 | relaying from arbitrary hosts to a specific set of domains. On the other hand, |
| 29945 | a host which is acting as a smart host for a number of clients is concerned |
| 29946 | with outgoing relaying from those clients to the Internet at large. Often the |
| 29947 | same host is fulfilling both functions, |
| 29948 | . /// |
| 29949 | . as illustrated in the diagram below, |
| 29950 | . /// |
| 29951 | but in principle these two kinds of relaying are entirely independent. What is |
| 29952 | not wanted is the transmission of mail from arbitrary remote hosts through your |
| 29953 | system to arbitrary domains. |
| 29954 | |
| 29955 | |
| 29956 | You can implement relay control by means of suitable statements in the ACL that |
| 29957 | runs for each RCPT command. For convenience, it is often easiest to use |
| 29958 | Exim's named list facility to define the domains and hosts involved. For |
| 29959 | example, suppose you want to do the following: |
| 29960 | |
| 29961 | .ilist |
| 29962 | Deliver a number of domains to mailboxes on the local host (or process them |
| 29963 | locally in some other way). Let's say these are &'my.dom1.example'& and |
| 29964 | &'my.dom2.example'&. |
| 29965 | .next |
| 29966 | Relay mail for a number of other domains for which you are the secondary MX. |
| 29967 | These might be &'friend1.example'& and &'friend2.example'&. |
| 29968 | .next |
| 29969 | Relay mail from the hosts on your local LAN, to whatever domains are involved. |
| 29970 | Suppose your LAN is 192.168.45.0/24. |
| 29971 | .endlist |
| 29972 | |
| 29973 | |
| 29974 | In the main part of the configuration, you put the following definitions: |
| 29975 | .code |
| 29976 | domainlist local_domains = my.dom1.example : my.dom2.example |
| 29977 | domainlist relay_to_domains = friend1.example : friend2.example |
| 29978 | hostlist relay_from_hosts = 192.168.45.0/24 |
| 29979 | .endd |
| 29980 | Now you can use these definitions in the ACL that is run for every RCPT |
| 29981 | command: |
| 29982 | .code |
| 29983 | acl_check_rcpt: |
| 29984 | accept domains = +local_domains : +relay_to_domains |
| 29985 | accept hosts = +relay_from_hosts |
| 29986 | .endd |
| 29987 | The first statement accepts any RCPT command that contains an address in |
| 29988 | the local or relay domains. For any other domain, control passes to the second |
| 29989 | statement, which accepts the command only if it comes from one of the relay |
| 29990 | hosts. In practice, you will probably want to make your ACL more sophisticated |
| 29991 | than this, for example, by including sender and recipient verification. The |
| 29992 | default configuration includes a more comprehensive example, which is described |
| 29993 | in chapter &<<CHAPdefconfil>>&. |
| 29994 | |
| 29995 | |
| 29996 | |
| 29997 | .section "Checking a relay configuration" "SECTcheralcon" |
| 29998 | .cindex "relaying" "checking control of" |
| 29999 | You can check the relay characteristics of your configuration in the same way |
| 30000 | that you can test any ACL behaviour for an incoming SMTP connection, by using |
| 30001 | the &%-bh%& option to run a fake SMTP session with which you interact. |
| 30002 | |
| 30003 | For specifically testing for unwanted relaying, the host |
| 30004 | &'relay-test.mail-abuse.org'& provides a useful service. If you telnet to this |
| 30005 | host from the host on which Exim is running, using the normal telnet port, you |
| 30006 | will see a normal telnet connection message and then quite a long delay. Be |
| 30007 | patient. The remote host is making an SMTP connection back to your host, and |
| 30008 | trying a number of common probes to test for open relay vulnerability. The |
| 30009 | results of the tests will eventually appear on your terminal. |
| 30010 | .ecindex IIDacl |
| 30011 | |
| 30012 | |
| 30013 | |
| 30014 | . //////////////////////////////////////////////////////////////////////////// |
| 30015 | . //////////////////////////////////////////////////////////////////////////// |
| 30016 | |
| 30017 | .chapter "Content scanning at ACL time" "CHAPexiscan" |
| 30018 | .scindex IIDcosca "content scanning" "at ACL time" |
| 30019 | The extension of Exim to include content scanning at ACL time, formerly known |
| 30020 | as &"exiscan"&, was originally implemented as a patch by Tom Kistner. The code |
| 30021 | was integrated into the main source for Exim release 4.50, and Tom continues to |
| 30022 | maintain it. Most of the wording of this chapter is taken from Tom's |
| 30023 | specification. |
| 30024 | |
| 30025 | It is also possible to scan the content of messages at other times. The |
| 30026 | &[local_scan()]& function (see chapter &<<CHAPlocalscan>>&) allows for content |
| 30027 | scanning after all the ACLs have run. A transport filter can be used to scan |
| 30028 | messages at delivery time (see the &%transport_filter%& option, described in |
| 30029 | chapter &<<CHAPtransportgeneric>>&). |
| 30030 | |
| 30031 | If you want to include the ACL-time content-scanning features when you compile |
| 30032 | Exim, you need to arrange for WITH_CONTENT_SCAN to be defined in your |
| 30033 | &_Local/Makefile_&. When you do that, the Exim binary is built with: |
| 30034 | |
| 30035 | .ilist |
| 30036 | Two additional ACLs (&%acl_smtp_mime%& and &%acl_not_smtp_mime%&) that are run |
| 30037 | for all MIME parts for SMTP and non-SMTP messages, respectively. |
| 30038 | .next |
| 30039 | Additional ACL conditions and modifiers: &%decode%&, &%malware%&, |
| 30040 | &%mime_regex%&, &%regex%&, and &%spam%&. These can be used in the ACL that is |
| 30041 | run at the end of message reception (the &%acl_smtp_data%& ACL). |
| 30042 | .next |
| 30043 | An additional control feature (&"no_mbox_unspool"&) that saves spooled copies |
| 30044 | of messages, or parts of messages, for debugging purposes. |
| 30045 | .next |
| 30046 | Additional expansion variables that are set in the new ACL and by the new |
| 30047 | conditions. |
| 30048 | .next |
| 30049 | Two new main configuration options: &%av_scanner%& and &%spamd_address%&. |
| 30050 | .endlist |
| 30051 | |
| 30052 | There is another content-scanning configuration option for &_Local/Makefile_&, |
| 30053 | called WITH_OLD_DEMIME. If this is set, the old, deprecated &%demime%& ACL |
| 30054 | condition is compiled, in addition to all the other content-scanning features. |
| 30055 | |
| 30056 | Content-scanning is continually evolving, and new features are still being |
| 30057 | added. While such features are still unstable and liable to incompatible |
| 30058 | changes, they are made available in Exim by setting options whose names begin |
| 30059 | EXPERIMENTAL_ in &_Local/Makefile_&. Such features are not documented in |
| 30060 | this manual. You can find out about them by reading the file called |
| 30061 | &_doc/experimental.txt_&. |
| 30062 | |
| 30063 | All the content-scanning facilities work on a MBOX copy of the message that is |
| 30064 | temporarily created in a file called: |
| 30065 | .display |
| 30066 | <&'spool_directory'&>&`/scan/`&<&'message_id'&>/<&'message_id'&>&`.eml`& |
| 30067 | .endd |
| 30068 | The &_.eml_& extension is a friendly hint to virus scanners that they can |
| 30069 | expect an MBOX-like structure inside that file. The file is created when the |
| 30070 | first content scanning facility is called. Subsequent calls to content |
| 30071 | scanning conditions open the same file again. The directory is recursively |
| 30072 | removed when the &%acl_smtp_data%& ACL has finished running, unless |
| 30073 | .code |
| 30074 | control = no_mbox_unspool |
| 30075 | .endd |
| 30076 | has been encountered. When the MIME ACL decodes files, they are put into the |
| 30077 | same directory by default. |
| 30078 | |
| 30079 | |
| 30080 | |
| 30081 | .section "Scanning for viruses" "SECTscanvirus" |
| 30082 | .cindex "virus scanning" |
| 30083 | .cindex "content scanning" "for viruses" |
| 30084 | .cindex "content scanning" "the &%malware%& condition" |
| 30085 | The &%malware%& ACL condition lets you connect virus scanner software to Exim. |
| 30086 | It supports a &"generic"& interface to scanners called via the shell, and |
| 30087 | specialized interfaces for &"daemon"& type virus scanners, which are resident |
| 30088 | in memory and thus are much faster. |
| 30089 | |
| 30090 | |
| 30091 | .oindex "&%av_scanner%&" |
| 30092 | You can set the &%av_scanner%& option in first part of the Exim configuration |
| 30093 | file to specify which scanner to use, together with any additional options that |
| 30094 | are needed. The basic syntax is as follows: |
| 30095 | .display |
| 30096 | &`av_scanner = <`&&'scanner-type'&&`>:<`&&'option1'&&`>:<`&&'option2'&&`>:[...]`& |
| 30097 | .endd |
| 30098 | If you do not set &%av_scanner%&, it defaults to |
| 30099 | .code |
| 30100 | av_scanner = sophie:/var/run/sophie |
| 30101 | .endd |
| 30102 | If the value of &%av_scanner%& starts with a dollar character, it is expanded |
| 30103 | before use. |
| 30104 | The usual list-parsing of the content (see &<<SECTlistconstruct>>&) applies. |
| 30105 | The following scanner types are supported in this release: |
| 30106 | |
| 30107 | .vlist |
| 30108 | .vitem &%aveserver%& |
| 30109 | .cindex "virus scanners" "Kaspersky" |
| 30110 | This is the scanner daemon of Kaspersky Version 5. You can get a trial version |
| 30111 | at &url(http://www.kaspersky.com). This scanner type takes one option, |
| 30112 | which is the path to the daemon's UNIX socket. The default is shown in this |
| 30113 | example: |
| 30114 | .code |
| 30115 | av_scanner = aveserver:/var/run/aveserver |
| 30116 | .endd |
| 30117 | |
| 30118 | |
| 30119 | .vitem &%clamd%& |
| 30120 | .cindex "virus scanners" "clamd" |
| 30121 | This daemon-type scanner is GPL and free. You can get it at |
| 30122 | &url(http://www.clamav.net/). Some older versions of clamd do not seem to |
| 30123 | unpack MIME containers, so it used to be recommended to unpack MIME attachments |
| 30124 | in the MIME ACL. This no longer believed to be necessary. One option is |
| 30125 | required: either the path and name of a UNIX socket file, or a hostname or IP |
| 30126 | number, and a port, separated by space, as in the second of these examples: |
| 30127 | .code |
| 30128 | av_scanner = clamd:/opt/clamd/socket |
| 30129 | av_scanner = clamd:192.0.2.3 1234 |
| 30130 | av_scanner = clamd:192.0.2.3 1234:local |
| 30131 | av_scanner = clamd:192.0.2.3 1234 : 192.0.2.4 1234 |
| 30132 | .endd |
| 30133 | If the value of av_scanner points to a UNIX socket file or contains the local |
| 30134 | keyword, then the ClamAV interface will pass a filename containing the data |
| 30135 | to be scanned, which will should normally result in less I/O happening and be |
| 30136 | more efficient. Normally in the TCP case, the data is streamed to ClamAV as |
| 30137 | Exim does not assume that there is a common filesystem with the remote host. |
| 30138 | There is an option WITH_OLD_CLAMAV_STREAM in &_src/EDITME_& available, should |
| 30139 | you be running a version of ClamAV prior to 0.95. |
| 30140 | |
| 30141 | The final example shows that multiple TCP targets can be specified. Exim will |
| 30142 | randomly use one for each incoming email (i.e. it load balances them). Note |
| 30143 | that only TCP targets may be used if specifying a list of scanners; a UNIX |
| 30144 | socket cannot be mixed in with TCP targets. If one of the servers becomes |
| 30145 | unavailable, Exim will try the remaining one(s) until it finds one that works. |
| 30146 | When a clamd server becomes unreachable, Exim will log a message. Exim does |
| 30147 | not keep track of scanner state between multiple messages, and the scanner |
| 30148 | selection is random, so the message will get logged in the mainlog for each |
| 30149 | email that the down scanner gets chosen first (message wrapped to be readable): |
| 30150 | .code |
| 30151 | 2013-10-09 14:30:39 1VTumd-0000Y8-BQ malware acl condition: |
| 30152 | clamd: connection to localhost, port 3310 failed |
| 30153 | (Connection refused) |
| 30154 | .endd |
| 30155 | |
| 30156 | If the option is unset, the default is &_/tmp/clamd_&. Thanks to David Saez for |
| 30157 | contributing the code for this scanner. |
| 30158 | |
| 30159 | .vitem &%cmdline%& |
| 30160 | .cindex "virus scanners" "command line interface" |
| 30161 | This is the keyword for the generic command line scanner interface. It can be |
| 30162 | used to attach virus scanners that are invoked from the shell. This scanner |
| 30163 | type takes 3 mandatory options: |
| 30164 | |
| 30165 | .olist |
| 30166 | The full path and name of the scanner binary, with all command line options, |
| 30167 | and a placeholder (&`%s`&) for the directory to scan. |
| 30168 | |
| 30169 | .next |
| 30170 | A regular expression to match against the STDOUT and STDERR output of the |
| 30171 | virus scanner. If the expression matches, a virus was found. You must make |
| 30172 | absolutely sure that this expression matches on &"virus found"&. This is called |
| 30173 | the &"trigger"& expression. |
| 30174 | |
| 30175 | .next |
| 30176 | Another regular expression, containing exactly one pair of parentheses, to |
| 30177 | match the name of the virus found in the scanners output. This is called the |
| 30178 | &"name"& expression. |
| 30179 | .endlist olist |
| 30180 | |
| 30181 | For example, Sophos Sweep reports a virus on a line like this: |
| 30182 | .code |
| 30183 | Virus 'W32/Magistr-B' found in file ./those.bat |
| 30184 | .endd |
| 30185 | For the trigger expression, we can match the phrase &"found in file"&. For the |
| 30186 | name expression, we want to extract the W32/Magistr-B string, so we can match |
| 30187 | for the single quotes left and right of it. Altogether, this makes the |
| 30188 | configuration setting: |
| 30189 | .code |
| 30190 | av_scanner = cmdline:\ |
| 30191 | /path/to/sweep -ss -all -rec -archive %s:\ |
| 30192 | found in file:'(.+)' |
| 30193 | .endd |
| 30194 | .vitem &%drweb%& |
| 30195 | .cindex "virus scanners" "DrWeb" |
| 30196 | The DrWeb daemon scanner (&url(http://www.sald.com/)) interface takes one |
| 30197 | argument, either a full path to a UNIX socket, or an IP address and port |
| 30198 | separated by white space, as in these examples: |
| 30199 | .code |
| 30200 | av_scanner = drweb:/var/run/drwebd.sock |
| 30201 | av_scanner = drweb:192.168.2.20 31337 |
| 30202 | .endd |
| 30203 | If you omit the argument, the default path &_/usr/local/drweb/run/drwebd.sock_& |
| 30204 | is used. Thanks to Alex Miller for contributing the code for this scanner. |
| 30205 | |
| 30206 | .vitem &%fsecure%& |
| 30207 | .cindex "virus scanners" "F-Secure" |
| 30208 | The F-Secure daemon scanner (&url(http://www.f-secure.com)) takes one |
| 30209 | argument which is the path to a UNIX socket. For example: |
| 30210 | .code |
| 30211 | av_scanner = fsecure:/path/to/.fsav |
| 30212 | .endd |
| 30213 | If no argument is given, the default is &_/var/run/.fsav_&. Thanks to Johan |
| 30214 | Thelmen for contributing the code for this scanner. |
| 30215 | |
| 30216 | .vitem &%kavdaemon%& |
| 30217 | .cindex "virus scanners" "Kaspersky" |
| 30218 | This is the scanner daemon of Kaspersky Version 4. This version of the |
| 30219 | Kaspersky scanner is outdated. Please upgrade (see &%aveserver%& above). This |
| 30220 | scanner type takes one option, which is the path to the daemon's UNIX socket. |
| 30221 | For example: |
| 30222 | .code |
| 30223 | av_scanner = kavdaemon:/opt/AVP/AvpCtl |
| 30224 | .endd |
| 30225 | The default path is &_/var/run/AvpCtl_&. |
| 30226 | |
| 30227 | .vitem &%mksd%& |
| 30228 | .cindex "virus scanners" "mksd" |
| 30229 | This is a daemon type scanner that is aimed mainly at Polish users, though some |
| 30230 | parts of documentation are now available in English. You can get it at |
| 30231 | &url(http://linux.mks.com.pl/). The only option for this scanner type is |
| 30232 | the maximum number of processes used simultaneously to scan the attachments, |
| 30233 | provided that the demime facility is employed and also provided that mksd has |
| 30234 | been run with at least the same number of child processes. For example: |
| 30235 | .code |
| 30236 | av_scanner = mksd:2 |
| 30237 | .endd |
| 30238 | You can safely omit this option (the default value is 1). |
| 30239 | |
| 30240 | .vitem &%sock%& |
| 30241 | .cindex "virus scanners" "simple socket-connected" |
| 30242 | This is a general-purpose way of talking to simple scanner daemons |
| 30243 | running on the local machine. |
| 30244 | There are four options: |
| 30245 | an address (which may be an IP addres and port, or the path of a Unix socket), |
| 30246 | a commandline to send (may include a single %s which will be replaced with |
| 30247 | the path to the mail file to be scanned), |
| 30248 | an RE to trigger on from the returned data, |
| 30249 | an RE to extract malware_name from the returned data. |
| 30250 | For example: |
| 30251 | .code |
| 30252 | av_scanner = sock:127.0.0.1 6001:%s:(SPAM|VIRUS):(.*)\$ |
| 30253 | .endd |
| 30254 | Default for the socket specifier is &_/tmp/malware.sock_&. |
| 30255 | Default for the commandline is &_%s\n_&. |
| 30256 | Both regular-expressions are required. |
| 30257 | |
| 30258 | .vitem &%sophie%& |
| 30259 | .cindex "virus scanners" "Sophos and Sophie" |
| 30260 | Sophie is a daemon that uses Sophos' &%libsavi%& library to scan for viruses. |
| 30261 | You can get Sophie at &url(http://www.clanfield.info/sophie/). The only option |
| 30262 | for this scanner type is the path to the UNIX socket that Sophie uses for |
| 30263 | client communication. For example: |
| 30264 | .code |
| 30265 | av_scanner = sophie:/tmp/sophie |
| 30266 | .endd |
| 30267 | The default path is &_/var/run/sophie_&, so if you are using this, you can omit |
| 30268 | the option. |
| 30269 | .endlist |
| 30270 | |
| 30271 | When &%av_scanner%& is correctly set, you can use the &%malware%& condition in |
| 30272 | the DATA ACL. &*Note*&: You cannot use the &%malware%& condition in the MIME |
| 30273 | ACL. |
| 30274 | |
| 30275 | The &%av_scanner%& option is expanded each time &%malware%& is called. This |
| 30276 | makes it possible to use different scanners. See further below for an example. |
| 30277 | The &%malware%& condition caches its results, so when you use it multiple times |
| 30278 | for the same message, the actual scanning process is only carried out once. |
| 30279 | However, using expandable items in &%av_scanner%& disables this caching, in |
| 30280 | which case each use of the &%malware%& condition causes a new scan of the |
| 30281 | message. |
| 30282 | |
| 30283 | The &%malware%& condition takes a right-hand argument that is expanded before |
| 30284 | use. It can then be one of |
| 30285 | |
| 30286 | .ilist |
| 30287 | &"true"&, &"*"&, or &"1"&, in which case the message is scanned for viruses. |
| 30288 | The condition succeeds if a virus was found, and fail otherwise. This is the |
| 30289 | recommended usage. |
| 30290 | .next |
| 30291 | &"false"& or &"0"& or an empty string, in which case no scanning is done and |
| 30292 | the condition fails immediately. |
| 30293 | .next |
| 30294 | A regular expression, in which case the message is scanned for viruses. The |
| 30295 | condition succeeds if a virus is found and its name matches the regular |
| 30296 | expression. This allows you to take special actions on certain types of virus. |
| 30297 | .endlist |
| 30298 | |
| 30299 | You can append &`/defer_ok`& to the &%malware%& condition to accept messages |
| 30300 | even if there is a problem with the virus scanner. Otherwise, such a problem |
| 30301 | causes the ACL to defer. |
| 30302 | |
| 30303 | .vindex "&$malware_name$&" |
| 30304 | When a virus is found, the condition sets up an expansion variable called |
| 30305 | &$malware_name$& that contains the name of the virus. You can use it in a |
| 30306 | &%message%& modifier that specifies the error returned to the sender, and/or in |
| 30307 | logging data. |
| 30308 | |
| 30309 | If your virus scanner cannot unpack MIME and TNEF containers itself, you should |
| 30310 | use the &%demime%& condition (see section &<<SECTdemimecond>>&) before the |
| 30311 | &%malware%& condition. |
| 30312 | |
| 30313 | Beware the interaction of Exim's &%message_size_limit%& with any size limits |
| 30314 | imposed by your anti-virus scanner. |
| 30315 | |
| 30316 | Here is a very simple scanning example: |
| 30317 | .code |
| 30318 | deny message = This message contains malware ($malware_name) |
| 30319 | demime = * |
| 30320 | malware = * |
| 30321 | .endd |
| 30322 | The next example accepts messages when there is a problem with the scanner: |
| 30323 | .code |
| 30324 | deny message = This message contains malware ($malware_name) |
| 30325 | demime = * |
| 30326 | malware = */defer_ok |
| 30327 | .endd |
| 30328 | The next example shows how to use an ACL variable to scan with both sophie and |
| 30329 | aveserver. It assumes you have set: |
| 30330 | .code |
| 30331 | av_scanner = $acl_m0 |
| 30332 | .endd |
| 30333 | in the main Exim configuration. |
| 30334 | .code |
| 30335 | deny message = This message contains malware ($malware_name) |
| 30336 | set acl_m0 = sophie |
| 30337 | malware = * |
| 30338 | |
| 30339 | deny message = This message contains malware ($malware_name) |
| 30340 | set acl_m0 = aveserver |
| 30341 | malware = * |
| 30342 | .endd |
| 30343 | |
| 30344 | |
| 30345 | .section "Scanning with SpamAssassin" "SECTscanspamass" |
| 30346 | .cindex "content scanning" "for spam" |
| 30347 | .cindex "spam scanning" |
| 30348 | .cindex "SpamAssassin" |
| 30349 | The &%spam%& ACL condition calls SpamAssassin's &%spamd%& daemon to get a spam |
| 30350 | score and a report for the message. You can get SpamAssassin at |
| 30351 | &url(http://www.spamassassin.org), or, if you have a working Perl |
| 30352 | installation, you can use CPAN by running: |
| 30353 | .code |
| 30354 | perl -MCPAN -e 'install Mail::SpamAssassin' |
| 30355 | .endd |
| 30356 | SpamAssassin has its own set of configuration files. Please review its |
| 30357 | documentation to see how you can tweak it. The default installation should work |
| 30358 | nicely, however. |
| 30359 | |
| 30360 | .oindex "&%spamd_address%&" |
| 30361 | After having installed and configured SpamAssassin, start the &%spamd%& daemon. |
| 30362 | By default, it listens on 127.0.0.1, TCP port 783. If you use another host or |
| 30363 | port for &%spamd%&, you must set the &%spamd_address%& option in the global |
| 30364 | part of the Exim configuration as follows (example): |
| 30365 | .code |
| 30366 | spamd_address = 192.168.99.45 387 |
| 30367 | .endd |
| 30368 | You do not need to set this option if you use the default. As of version 2.60, |
| 30369 | &%spamd%& also supports communication over UNIX sockets. If you want to use |
| 30370 | these, supply &%spamd_address%& with an absolute file name instead of a |
| 30371 | address/port pair: |
| 30372 | .code |
| 30373 | spamd_address = /var/run/spamd_socket |
| 30374 | .endd |
| 30375 | You can have multiple &%spamd%& servers to improve scalability. These can |
| 30376 | reside on other hardware reachable over the network. To specify multiple |
| 30377 | &%spamd%& servers, put multiple address/port pairs in the &%spamd_address%& |
| 30378 | option, separated with colons: |
| 30379 | .code |
| 30380 | spamd_address = 192.168.2.10 783 : \ |
| 30381 | 192.168.2.11 783 : \ |
| 30382 | 192.168.2.12 783 |
| 30383 | .endd |
| 30384 | Up to 32 &%spamd%& servers are supported. The servers are queried in a random |
| 30385 | fashion. When a server fails to respond to the connection attempt, all other |
| 30386 | servers are tried until one succeeds. If no server responds, the &%spam%& |
| 30387 | condition defers. |
| 30388 | |
| 30389 | &*Warning*&: It is not possible to use the UNIX socket connection method with |
| 30390 | multiple &%spamd%& servers. |
| 30391 | |
| 30392 | The &%spamd_address%& variable is expanded before use if it starts with |
| 30393 | a dollar sign. In this case, the expansion may return a string that is |
| 30394 | used as the list so that multiple spamd servers can be the result of an |
| 30395 | expansion. |
| 30396 | |
| 30397 | .section "Calling SpamAssassin from an Exim ACL" "SECID206" |
| 30398 | Here is a simple example of the use of the &%spam%& condition in a DATA ACL: |
| 30399 | .code |
| 30400 | deny message = This message was classified as SPAM |
| 30401 | spam = joe |
| 30402 | .endd |
| 30403 | The right-hand side of the &%spam%& condition specifies a name. This is |
| 30404 | relevant if you have set up multiple SpamAssassin profiles. If you do not want |
| 30405 | to scan using a specific profile, but rather use the SpamAssassin system-wide |
| 30406 | default profile, you can scan for an unknown name, or simply use &"nobody"&. |
| 30407 | However, you must put something on the right-hand side. |
| 30408 | |
| 30409 | The name allows you to use per-domain or per-user antispam profiles in |
| 30410 | principle, but this is not straightforward in practice, because a message may |
| 30411 | have multiple recipients, not necessarily all in the same domain. Because the |
| 30412 | &%spam%& condition has to be called from a DATA ACL in order to be able to |
| 30413 | read the contents of the message, the variables &$local_part$& and &$domain$& |
| 30414 | are not set. |
| 30415 | |
| 30416 | The right-hand side of the &%spam%& condition is expanded before being used, so |
| 30417 | you can put lookups or conditions there. When the right-hand side evaluates to |
| 30418 | &"0"& or &"false"&, no scanning is done and the condition fails immediately. |
| 30419 | |
| 30420 | |
| 30421 | Scanning with SpamAssassin uses a lot of resources. If you scan every message, |
| 30422 | large ones may cause significant performance degradation. As most spam messages |
| 30423 | are quite small, it is recommended that you do not scan the big ones. For |
| 30424 | example: |
| 30425 | .code |
| 30426 | deny message = This message was classified as SPAM |
| 30427 | condition = ${if < {$message_size}{10K}} |
| 30428 | spam = nobody |
| 30429 | .endd |
| 30430 | |
| 30431 | The &%spam%& condition returns true if the threshold specified in the user's |
| 30432 | SpamAssassin profile has been matched or exceeded. If you want to use the |
| 30433 | &%spam%& condition for its side effects (see the variables below), you can make |
| 30434 | it always return &"true"& by appending &`:true`& to the username. |
| 30435 | |
| 30436 | .cindex "spam scanning" "returned variables" |
| 30437 | When the &%spam%& condition is run, it sets up a number of expansion |
| 30438 | variables. These variables are saved with the received message, thus they are |
| 30439 | available for use at delivery time. |
| 30440 | |
| 30441 | .vlist |
| 30442 | .vitem &$spam_score$& |
| 30443 | The spam score of the message, for example &"3.4"& or &"30.5"&. This is useful |
| 30444 | for inclusion in log or reject messages. |
| 30445 | |
| 30446 | .vitem &$spam_score_int$& |
| 30447 | The spam score of the message, multiplied by ten, as an integer value. For |
| 30448 | example &"34"& or &"305"&. It may appear to disagree with &$spam_score$& |
| 30449 | because &$spam_score$& is rounded and &$spam_score_int$& is truncated. |
| 30450 | The integer value is useful for numeric comparisons in conditions. |
| 30451 | |
| 30452 | .vitem &$spam_bar$& |
| 30453 | A string consisting of a number of &"+"& or &"-"& characters, representing the |
| 30454 | integer part of the spam score value. A spam score of 4.4 would have a |
| 30455 | &$spam_bar$& value of &"++++"&. This is useful for inclusion in warning |
| 30456 | headers, since MUAs can match on such strings. |
| 30457 | |
| 30458 | .vitem &$spam_report$& |
| 30459 | A multiline text table, containing the full SpamAssassin report for the |
| 30460 | message. Useful for inclusion in headers or reject messages. |
| 30461 | .endlist |
| 30462 | |
| 30463 | The &%spam%& condition caches its results unless expansion in |
| 30464 | spamd_address was used. If you call it again with the same user name, it |
| 30465 | does not scan again, but rather returns the same values as before. |
| 30466 | |
| 30467 | The &%spam%& condition returns DEFER if there is any error while running |
| 30468 | the message through SpamAssassin or if the expansion of spamd_address |
| 30469 | failed. If you want to treat DEFER as FAIL (to pass on to the next ACL |
| 30470 | statement block), append &`/defer_ok`& to the right-hand side of the |
| 30471 | spam condition, like this: |
| 30472 | .code |
| 30473 | deny message = This message was classified as SPAM |
| 30474 | spam = joe/defer_ok |
| 30475 | .endd |
| 30476 | This causes messages to be accepted even if there is a problem with &%spamd%&. |
| 30477 | |
| 30478 | Here is a longer, commented example of the use of the &%spam%& |
| 30479 | condition: |
| 30480 | .code |
| 30481 | # put headers in all messages (no matter if spam or not) |
| 30482 | warn spam = nobody:true |
| 30483 | add_header = X-Spam-Score: $spam_score ($spam_bar) |
| 30484 | add_header = X-Spam-Report: $spam_report |
| 30485 | |
| 30486 | # add second subject line with *SPAM* marker when message |
| 30487 | # is over threshold |
| 30488 | warn spam = nobody |
| 30489 | add_header = Subject: *SPAM* $h_Subject: |
| 30490 | |
| 30491 | # reject spam at high scores (> 12) |
| 30492 | deny message = This message scored $spam_score spam points. |
| 30493 | spam = nobody:true |
| 30494 | condition = ${if >{$spam_score_int}{120}{1}{0}} |
| 30495 | .endd |
| 30496 | |
| 30497 | |
| 30498 | |
| 30499 | .section "Scanning MIME parts" "SECTscanmimepart" |
| 30500 | .cindex "content scanning" "MIME parts" |
| 30501 | .cindex "MIME content scanning" |
| 30502 | .oindex "&%acl_smtp_mime%&" |
| 30503 | .oindex "&%acl_not_smtp_mime%&" |
| 30504 | The &%acl_smtp_mime%& global option specifies an ACL that is called once for |
| 30505 | each MIME part of an SMTP message, including multipart types, in the sequence |
| 30506 | of their position in the message. Similarly, the &%acl_not_smtp_mime%& option |
| 30507 | specifies an ACL that is used for the MIME parts of non-SMTP messages. These |
| 30508 | options may both refer to the same ACL if you want the same processing in both |
| 30509 | cases. |
| 30510 | |
| 30511 | These ACLs are called (possibly many times) just before the &%acl_smtp_data%& |
| 30512 | ACL in the case of an SMTP message, or just before the &%acl_not_smtp%& ACL in |
| 30513 | the case of a non-SMTP message. However, a MIME ACL is called only if the |
| 30514 | message contains a &'Content-Type:'& header line. When a call to a MIME |
| 30515 | ACL does not yield &"accept"&, ACL processing is aborted and the appropriate |
| 30516 | result code is sent to the client. In the case of an SMTP message, the |
| 30517 | &%acl_smtp_data%& ACL is not called when this happens. |
| 30518 | |
| 30519 | You cannot use the &%malware%& or &%spam%& conditions in a MIME ACL; these can |
| 30520 | only be used in the DATA or non-SMTP ACLs. However, you can use the &%regex%& |
| 30521 | condition to match against the raw MIME part. You can also use the |
| 30522 | &%mime_regex%& condition to match against the decoded MIME part (see section |
| 30523 | &<<SECTscanregex>>&). |
| 30524 | |
| 30525 | At the start of a MIME ACL, a number of variables are set from the header |
| 30526 | information for the relevant MIME part. These are described below. The contents |
| 30527 | of the MIME part are not by default decoded into a disk file except for MIME |
| 30528 | parts whose content-type is &"message/rfc822"&. If you want to decode a MIME |
| 30529 | part into a disk file, you can use the &%decode%& condition. The general |
| 30530 | syntax is: |
| 30531 | .display |
| 30532 | &`decode = [/`&<&'path'&>&`/]`&<&'filename'&> |
| 30533 | .endd |
| 30534 | The right hand side is expanded before use. After expansion, |
| 30535 | the value can be: |
| 30536 | |
| 30537 | .olist |
| 30538 | &"0"& or &"false"&, in which case no decoding is done. |
| 30539 | .next |
| 30540 | The string &"default"&. In that case, the file is put in the temporary |
| 30541 | &"default"& directory <&'spool_directory'&>&_/scan/_&<&'message_id'&>&_/_& with |
| 30542 | a sequential file name consisting of the message id and a sequence number. The |
| 30543 | full path and name is available in &$mime_decoded_filename$& after decoding. |
| 30544 | .next |
| 30545 | A full path name starting with a slash. If the full name is an existing |
| 30546 | directory, it is used as a replacement for the default directory. The filename |
| 30547 | is then sequentially assigned. If the path does not exist, it is used as |
| 30548 | the full path and file name. |
| 30549 | .next |
| 30550 | If the string does not start with a slash, it is used as the |
| 30551 | filename, and the default path is then used. |
| 30552 | .endlist |
| 30553 | The &%decode%& condition normally succeeds. It is only false for syntax |
| 30554 | errors or unusual circumstances such as memory shortages. You can easily decode |
| 30555 | a file with its original, proposed filename using |
| 30556 | .code |
| 30557 | decode = $mime_filename |
| 30558 | .endd |
| 30559 | However, you should keep in mind that &$mime_filename$& might contain |
| 30560 | anything. If you place files outside of the default path, they are not |
| 30561 | automatically unlinked. |
| 30562 | |
| 30563 | For RFC822 attachments (these are messages attached to messages, with a |
| 30564 | content-type of &"message/rfc822"&), the ACL is called again in the same manner |
| 30565 | as for the primary message, only that the &$mime_is_rfc822$& expansion |
| 30566 | variable is set (see below). Attached messages are always decoded to disk |
| 30567 | before being checked, and the files are unlinked once the check is done. |
| 30568 | |
| 30569 | The MIME ACL supports the &%regex%& and &%mime_regex%& conditions. These can be |
| 30570 | used to match regular expressions against raw and decoded MIME parts, |
| 30571 | respectively. They are described in section &<<SECTscanregex>>&. |
| 30572 | |
| 30573 | .cindex "MIME content scanning" "returned variables" |
| 30574 | The following list describes all expansion variables that are |
| 30575 | available in the MIME ACL: |
| 30576 | |
| 30577 | .vlist |
| 30578 | .vitem &$mime_boundary$& |
| 30579 | If the current part is a multipart (see &$mime_is_multipart$&) below, it should |
| 30580 | have a boundary string, which is stored in this variable. If the current part |
| 30581 | has no boundary parameter in the &'Content-Type:'& header, this variable |
| 30582 | contains the empty string. |
| 30583 | |
| 30584 | .vitem &$mime_charset$& |
| 30585 | This variable contains the character set identifier, if one was found in the |
| 30586 | &'Content-Type:'& header. Examples for charset identifiers are: |
| 30587 | .code |
| 30588 | us-ascii |
| 30589 | gb2312 (Chinese) |
| 30590 | iso-8859-1 |
| 30591 | .endd |
| 30592 | Please note that this value is not normalized, so you should do matches |
| 30593 | case-insensitively. |
| 30594 | |
| 30595 | .vitem &$mime_content_description$& |
| 30596 | This variable contains the normalized content of the &'Content-Description:'& |
| 30597 | header. It can contain a human-readable description of the parts content. Some |
| 30598 | implementations repeat the filename for attachments here, but they are usually |
| 30599 | only used for display purposes. |
| 30600 | |
| 30601 | .vitem &$mime_content_disposition$& |
| 30602 | This variable contains the normalized content of the &'Content-Disposition:'& |
| 30603 | header. You can expect strings like &"attachment"& or &"inline"& here. |
| 30604 | |
| 30605 | .vitem &$mime_content_id$& |
| 30606 | This variable contains the normalized content of the &'Content-ID:'& header. |
| 30607 | This is a unique ID that can be used to reference a part from another part. |
| 30608 | |
| 30609 | .vitem &$mime_content_size$& |
| 30610 | This variable is set only after the &%decode%& modifier (see above) has been |
| 30611 | successfully run. It contains the size of the decoded part in kilobytes. The |
| 30612 | size is always rounded up to full kilobytes, so only a completely empty part |
| 30613 | has a &$mime_content_size$& of zero. |
| 30614 | |
| 30615 | .vitem &$mime_content_transfer_encoding$& |
| 30616 | This variable contains the normalized content of the |
| 30617 | &'Content-transfer-encoding:'& header. This is a symbolic name for an encoding |
| 30618 | type. Typical values are &"base64"& and &"quoted-printable"&. |
| 30619 | |
| 30620 | .vitem &$mime_content_type$& |
| 30621 | If the MIME part has a &'Content-Type:'& header, this variable contains its |
| 30622 | value, lowercased, and without any options (like &"name"& or &"charset"&). Here |
| 30623 | are some examples of popular MIME types, as they may appear in this variable: |
| 30624 | .code |
| 30625 | text/plain |
| 30626 | text/html |
| 30627 | application/octet-stream |
| 30628 | image/jpeg |
| 30629 | audio/midi |
| 30630 | .endd |
| 30631 | If the MIME part has no &'Content-Type:'& header, this variable contains the |
| 30632 | empty string. |
| 30633 | |
| 30634 | .vitem &$mime_decoded_filename$& |
| 30635 | This variable is set only after the &%decode%& modifier (see above) has been |
| 30636 | successfully run. It contains the full path and file name of the file |
| 30637 | containing the decoded data. |
| 30638 | .endlist |
| 30639 | |
| 30640 | .cindex "RFC 2047" |
| 30641 | .vlist |
| 30642 | .vitem &$mime_filename$& |
| 30643 | This is perhaps the most important of the MIME variables. It contains a |
| 30644 | proposed filename for an attachment, if one was found in either the |
| 30645 | &'Content-Type:'& or &'Content-Disposition:'& headers. The filename will be |
| 30646 | RFC2047 decoded, but no additional sanity checks are done. If no filename was |
| 30647 | found, this variable contains the empty string. |
| 30648 | |
| 30649 | .vitem &$mime_is_coverletter$& |
| 30650 | This variable attempts to differentiate the &"cover letter"& of an e-mail from |
| 30651 | attached data. It can be used to clamp down on flashy or unnecessarily encoded |
| 30652 | content in the cover letter, while not restricting attachments at all. |
| 30653 | |
| 30654 | The variable contains 1 (true) for a MIME part believed to be part of the |
| 30655 | cover letter, and 0 (false) for an attachment. At present, the algorithm is as |
| 30656 | follows: |
| 30657 | |
| 30658 | .olist |
| 30659 | The outermost MIME part of a message is always a cover letter. |
| 30660 | |
| 30661 | .next |
| 30662 | If a multipart/alternative or multipart/related MIME part is a cover letter, |
| 30663 | so are all MIME subparts within that multipart. |
| 30664 | |
| 30665 | .next |
| 30666 | If any other multipart is a cover letter, the first subpart is a cover letter, |
| 30667 | and the rest are attachments. |
| 30668 | |
| 30669 | .next |
| 30670 | All parts contained within an attachment multipart are attachments. |
| 30671 | .endlist olist |
| 30672 | |
| 30673 | As an example, the following will ban &"HTML mail"& (including that sent with |
| 30674 | alternative plain text), while allowing HTML files to be attached. HTML |
| 30675 | coverletter mail attached to non-HMTL coverletter mail will also be allowed: |
| 30676 | .code |
| 30677 | deny message = HTML mail is not accepted here |
| 30678 | !condition = $mime_is_rfc822 |
| 30679 | condition = $mime_is_coverletter |
| 30680 | condition = ${if eq{$mime_content_type}{text/html}{1}{0}} |
| 30681 | .endd |
| 30682 | .vitem &$mime_is_multipart$& |
| 30683 | This variable has the value 1 (true) when the current part has the main type |
| 30684 | &"multipart"&, for example &"multipart/alternative"& or &"multipart/mixed"&. |
| 30685 | Since multipart entities only serve as containers for other parts, you may not |
| 30686 | want to carry out specific actions on them. |
| 30687 | |
| 30688 | .vitem &$mime_is_rfc822$& |
| 30689 | This variable has the value 1 (true) if the current part is not a part of the |
| 30690 | checked message itself, but part of an attached message. Attached message |
| 30691 | decoding is fully recursive. |
| 30692 | |
| 30693 | .vitem &$mime_part_count$& |
| 30694 | This variable is a counter that is raised for each processed MIME part. It |
| 30695 | starts at zero for the very first part (which is usually a multipart). The |
| 30696 | counter is per-message, so it is reset when processing RFC822 attachments (see |
| 30697 | &$mime_is_rfc822$&). The counter stays set after &%acl_smtp_mime%& is |
| 30698 | complete, so you can use it in the DATA ACL to determine the number of MIME |
| 30699 | parts of a message. For non-MIME messages, this variable contains the value -1. |
| 30700 | .endlist |
| 30701 | |
| 30702 | |
| 30703 | |
| 30704 | .section "Scanning with regular expressions" "SECTscanregex" |
| 30705 | .cindex "content scanning" "with regular expressions" |
| 30706 | .cindex "regular expressions" "content scanning with" |
| 30707 | You can specify your own custom regular expression matches on the full body of |
| 30708 | the message, or on individual MIME parts. |
| 30709 | |
| 30710 | The &%regex%& condition takes one or more regular expressions as arguments and |
| 30711 | matches them against the full message (when called in the DATA ACL) or a raw |
| 30712 | MIME part (when called in the MIME ACL). The &%regex%& condition matches |
| 30713 | linewise, with a maximum line length of 32K characters. That means you cannot |
| 30714 | have multiline matches with the &%regex%& condition. |
| 30715 | |
| 30716 | The &%mime_regex%& condition can be called only in the MIME ACL. It matches up |
| 30717 | to 32K of decoded content (the whole content at once, not linewise). If the |
| 30718 | part has not been decoded with the &%decode%& modifier earlier in the ACL, it |
| 30719 | is decoded automatically when &%mime_regex%& is executed (using default path |
| 30720 | and filename values). If the decoded data is larger than 32K, only the first |
| 30721 | 32K characters are checked. |
| 30722 | |
| 30723 | The regular expressions are passed as a colon-separated list. To include a |
| 30724 | literal colon, you must double it. Since the whole right-hand side string is |
| 30725 | expanded before being used, you must also escape dollar signs and backslashes |
| 30726 | with more backslashes, or use the &`\N`& facility to disable expansion. |
| 30727 | Here is a simple example that contains two regular expressions: |
| 30728 | .code |
| 30729 | deny message = contains blacklisted regex ($regex_match_string) |
| 30730 | regex = [Mm]ortgage : URGENT BUSINESS PROPOSAL |
| 30731 | .endd |
| 30732 | The conditions returns true if any one of the regular expressions matches. The |
| 30733 | &$regex_match_string$& expansion variable is then set up and contains the |
| 30734 | matching regular expression. |
| 30735 | |
| 30736 | &*Warning*&: With large messages, these conditions can be fairly |
| 30737 | CPU-intensive. |
| 30738 | |
| 30739 | |
| 30740 | |
| 30741 | |
| 30742 | .section "The demime condition" "SECTdemimecond" |
| 30743 | .cindex "content scanning" "MIME checking" |
| 30744 | .cindex "MIME content scanning" |
| 30745 | The &%demime%& ACL condition provides MIME unpacking, sanity checking and file |
| 30746 | extension blocking. It is usable only in the DATA and non-SMTP ACLs. The |
| 30747 | &%demime%& condition uses a simpler interface to MIME decoding than the MIME |
| 30748 | ACL functionality, but provides no additional facilities. Please note that this |
| 30749 | condition is deprecated and kept only for backward compatibility. You must set |
| 30750 | the WITH_OLD_DEMIME option in &_Local/Makefile_& at build time to be able to |
| 30751 | use the &%demime%& condition. |
| 30752 | |
| 30753 | The &%demime%& condition unpacks MIME containers in the message. It detects |
| 30754 | errors in MIME containers and can match file extensions found in the message |
| 30755 | against a list. Using this facility produces files containing the unpacked MIME |
| 30756 | parts of the message in the temporary scan directory. If you do antivirus |
| 30757 | scanning, it is recommended that you use the &%demime%& condition before the |
| 30758 | antivirus (&%malware%&) condition. |
| 30759 | |
| 30760 | On the right-hand side of the &%demime%& condition you can pass a |
| 30761 | colon-separated list of file extensions that it should match against. For |
| 30762 | example: |
| 30763 | .code |
| 30764 | deny message = Found blacklisted file attachment |
| 30765 | demime = vbs:com:bat:pif:prf:lnk |
| 30766 | .endd |
| 30767 | If one of the file extensions is found, the condition is true, otherwise it is |
| 30768 | false. If there is a temporary error while demimeing (for example, &"disk |
| 30769 | full"&), the condition defers, and the message is temporarily rejected (unless |
| 30770 | the condition is on a &%warn%& verb). |
| 30771 | |
| 30772 | The right-hand side is expanded before being treated as a list, so you can have |
| 30773 | conditions and lookups there. If it expands to an empty string, &"false"&, or |
| 30774 | zero (&"0"&), no demimeing is done and the condition is false. |
| 30775 | |
| 30776 | The &%demime%& condition set the following variables: |
| 30777 | |
| 30778 | .vlist |
| 30779 | .vitem &$demime_errorlevel$& |
| 30780 | .vindex "&$demime_errorlevel$&" |
| 30781 | When an error is detected in a MIME container, this variable contains the |
| 30782 | severity of the error, as an integer number. The higher the value, the more |
| 30783 | severe the error (the current maximum value is 3). If this variable is unset or |
| 30784 | zero, no error occurred. |
| 30785 | |
| 30786 | .vitem &$demime_reason$& |
| 30787 | .vindex "&$demime_reason$&" |
| 30788 | When &$demime_errorlevel$& is greater than zero, this variable contains a |
| 30789 | human-readable text string describing the MIME error that occurred. |
| 30790 | .endlist |
| 30791 | |
| 30792 | .vlist |
| 30793 | .vitem &$found_extension$& |
| 30794 | .vindex "&$found_extension$&" |
| 30795 | When the &%demime%& condition is true, this variable contains the file |
| 30796 | extension it found. |
| 30797 | .endlist |
| 30798 | |
| 30799 | Both &$demime_errorlevel$& and &$demime_reason$& are set by the first call of |
| 30800 | the &%demime%& condition, and are not changed on subsequent calls. |
| 30801 | |
| 30802 | If you do not want to check for file extensions, but rather use the &%demime%& |
| 30803 | condition for unpacking or error checking purposes, pass &"*"& as the |
| 30804 | right-hand side value. Here is a more elaborate example of how to use this |
| 30805 | facility: |
| 30806 | .code |
| 30807 | # Reject messages with serious MIME container errors |
| 30808 | deny message = Found MIME error ($demime_reason). |
| 30809 | demime = * |
| 30810 | condition = ${if >{$demime_errorlevel}{2}{1}{0}} |
| 30811 | |
| 30812 | # Reject known virus spreading file extensions. |
| 30813 | # Accepting these is pretty much braindead. |
| 30814 | deny message = contains $found_extension file (blacklisted). |
| 30815 | demime = com:vbs:bat:pif:scr |
| 30816 | |
| 30817 | # Freeze .exe and .doc files. Postmaster can |
| 30818 | # examine them and eventually thaw them. |
| 30819 | deny log_message = Another $found_extension file. |
| 30820 | demime = exe:doc |
| 30821 | control = freeze |
| 30822 | .endd |
| 30823 | .ecindex IIDcosca |
| 30824 | |
| 30825 | |
| 30826 | |
| 30827 | |
| 30828 | . //////////////////////////////////////////////////////////////////////////// |
| 30829 | . //////////////////////////////////////////////////////////////////////////// |
| 30830 | |
| 30831 | .chapter "Adding a local scan function to Exim" "CHAPlocalscan" &&& |
| 30832 | "Local scan function" |
| 30833 | .scindex IIDlosca "&[local_scan()]& function" "description of" |
| 30834 | .cindex "customizing" "input scan using C function" |
| 30835 | .cindex "policy control" "by local scan function" |
| 30836 | In these days of email worms, viruses, and ever-increasing spam, some sites |
| 30837 | want to apply a lot of checking to messages before accepting them. |
| 30838 | |
| 30839 | The content scanning extension (chapter &<<CHAPexiscan>>&) has facilities for |
| 30840 | passing messages to external virus and spam scanning software. You can also do |
| 30841 | a certain amount in Exim itself through string expansions and the &%condition%& |
| 30842 | condition in the ACL that runs after the SMTP DATA command or the ACL for |
| 30843 | non-SMTP messages (see chapter &<<CHAPACL>>&), but this has its limitations. |
| 30844 | |
| 30845 | To allow for further customization to a site's own requirements, there is the |
| 30846 | possibility of linking Exim with a private message scanning function, written |
| 30847 | in C. If you want to run code that is written in something other than C, you |
| 30848 | can of course use a little C stub to call it. |
| 30849 | |
| 30850 | The local scan function is run once for every incoming message, at the point |
| 30851 | when Exim is just about to accept the message. |
| 30852 | It can therefore be used to control non-SMTP messages from local processes as |
| 30853 | well as messages arriving via SMTP. |
| 30854 | |
| 30855 | Exim applies a timeout to calls of the local scan function, and there is an |
| 30856 | option called &%local_scan_timeout%& for setting it. The default is 5 minutes. |
| 30857 | Zero means &"no timeout"&. |
| 30858 | Exim also sets up signal handlers for SIGSEGV, SIGILL, SIGFPE, and SIGBUS |
| 30859 | before calling the local scan function, so that the most common types of crash |
| 30860 | are caught. If the timeout is exceeded or one of those signals is caught, the |
| 30861 | incoming message is rejected with a temporary error if it is an SMTP message. |
| 30862 | For a non-SMTP message, the message is dropped and Exim ends with a non-zero |
| 30863 | code. The incident is logged on the main and reject logs. |
| 30864 | |
| 30865 | |
| 30866 | |
| 30867 | .section "Building Exim to use a local scan function" "SECID207" |
| 30868 | .cindex "&[local_scan()]& function" "building Exim to use" |
| 30869 | To make use of the local scan function feature, you must tell Exim where your |
| 30870 | function is before building Exim, by setting LOCAL_SCAN_SOURCE in your |
| 30871 | &_Local/Makefile_&. A recommended place to put it is in the &_Local_& |
| 30872 | directory, so you might set |
| 30873 | .code |
| 30874 | LOCAL_SCAN_SOURCE=Local/local_scan.c |
| 30875 | .endd |
| 30876 | for example. The function must be called &[local_scan()]&. It is called by |
| 30877 | Exim after it has received a message, when the success return code is about to |
| 30878 | be sent. This is after all the ACLs have been run. The return code from your |
| 30879 | function controls whether the message is actually accepted or not. There is a |
| 30880 | commented template function (that just accepts the message) in the file |
| 30881 | _src/local_scan.c_. |
| 30882 | |
| 30883 | If you want to make use of Exim's run time configuration file to set options |
| 30884 | for your &[local_scan()]& function, you must also set |
| 30885 | .code |
| 30886 | LOCAL_SCAN_HAS_OPTIONS=yes |
| 30887 | .endd |
| 30888 | in &_Local/Makefile_& (see section &<<SECTconoptloc>>& below). |
| 30889 | |
| 30890 | |
| 30891 | |
| 30892 | |
| 30893 | .section "API for local_scan()" "SECTapiforloc" |
| 30894 | .cindex "&[local_scan()]& function" "API description" |
| 30895 | You must include this line near the start of your code: |
| 30896 | .code |
| 30897 | #include "local_scan.h" |
| 30898 | .endd |
| 30899 | This header file defines a number of variables and other values, and the |
| 30900 | prototype for the function itself. Exim is coded to use unsigned char values |
| 30901 | almost exclusively, and one of the things this header defines is a shorthand |
| 30902 | for &`unsigned char`& called &`uschar`&. |
| 30903 | It also contains the following macro definitions, to simplify casting character |
| 30904 | strings and pointers to character strings: |
| 30905 | .code |
| 30906 | #define CS (char *) |
| 30907 | #define CCS (const char *) |
| 30908 | #define CSS (char **) |
| 30909 | #define US (unsigned char *) |
| 30910 | #define CUS (const unsigned char *) |
| 30911 | #define USS (unsigned char **) |
| 30912 | .endd |
| 30913 | The function prototype for &[local_scan()]& is: |
| 30914 | .code |
| 30915 | extern int local_scan(int fd, uschar **return_text); |
| 30916 | .endd |
| 30917 | The arguments are as follows: |
| 30918 | |
| 30919 | .ilist |
| 30920 | &%fd%& is a file descriptor for the file that contains the body of the message |
| 30921 | (the -D file). The file is open for reading and writing, but updating it is not |
| 30922 | recommended. &*Warning*&: You must &'not'& close this file descriptor. |
| 30923 | |
| 30924 | The descriptor is positioned at character 19 of the file, which is the first |
| 30925 | character of the body itself, because the first 19 characters are the message |
| 30926 | id followed by &`-D`& and a newline. If you rewind the file, you should use the |
| 30927 | macro SPOOL_DATA_START_OFFSET to reset to the start of the data, just in |
| 30928 | case this changes in some future version. |
| 30929 | .next |
| 30930 | &%return_text%& is an address which you can use to return a pointer to a text |
| 30931 | string at the end of the function. The value it points to on entry is NULL. |
| 30932 | .endlist |
| 30933 | |
| 30934 | The function must return an &%int%& value which is one of the following macros: |
| 30935 | |
| 30936 | .vlist |
| 30937 | .vitem &`LOCAL_SCAN_ACCEPT`& |
| 30938 | .vindex "&$local_scan_data$&" |
| 30939 | The message is accepted. If you pass back a string of text, it is saved with |
| 30940 | the message, and made available in the variable &$local_scan_data$&. No |
| 30941 | newlines are permitted (if there are any, they are turned into spaces) and the |
| 30942 | maximum length of text is 1000 characters. |
| 30943 | |
| 30944 | .vitem &`LOCAL_SCAN_ACCEPT_FREEZE`& |
| 30945 | This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is |
| 30946 | queued without immediate delivery, and is frozen. |
| 30947 | |
| 30948 | .vitem &`LOCAL_SCAN_ACCEPT_QUEUE`& |
| 30949 | This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is |
| 30950 | queued without immediate delivery. |
| 30951 | |
| 30952 | .vitem &`LOCAL_SCAN_REJECT`& |
| 30953 | The message is rejected; the returned text is used as an error message which is |
| 30954 | passed back to the sender and which is also logged. Newlines are permitted &-- |
| 30955 | they cause a multiline response for SMTP rejections, but are converted to |
| 30956 | &`\n`& in log lines. If no message is given, &"Administrative prohibition"& is |
| 30957 | used. |
| 30958 | |
| 30959 | .vitem &`LOCAL_SCAN_TEMPREJECT`& |
| 30960 | The message is temporarily rejected; the returned text is used as an error |
| 30961 | message as for LOCAL_SCAN_REJECT. If no message is given, &"Temporary local |
| 30962 | problem"& is used. |
| 30963 | |
| 30964 | .vitem &`LOCAL_SCAN_REJECT_NOLOGHDR`& |
| 30965 | This behaves as LOCAL_SCAN_REJECT, except that the header of the rejected |
| 30966 | message is not written to the reject log. It has the effect of unsetting the |
| 30967 | &%rejected_header%& log selector for just this rejection. If |
| 30968 | &%rejected_header%& is already unset (see the discussion of the |
| 30969 | &%log_selection%& option in section &<<SECTlogselector>>&), this code is the |
| 30970 | same as LOCAL_SCAN_REJECT. |
| 30971 | |
| 30972 | .vitem &`LOCAL_SCAN_TEMPREJECT_NOLOGHDR`& |
| 30973 | This code is a variation of LOCAL_SCAN_TEMPREJECT in the same way that |
| 30974 | LOCAL_SCAN_REJECT_NOLOGHDR is a variation of LOCAL_SCAN_REJECT. |
| 30975 | .endlist |
| 30976 | |
| 30977 | If the message is not being received by interactive SMTP, rejections are |
| 30978 | reported by writing to &%stderr%& or by sending an email, as configured by the |
| 30979 | &%-oe%& command line options. |
| 30980 | |
| 30981 | |
| 30982 | |
| 30983 | .section "Configuration options for local_scan()" "SECTconoptloc" |
| 30984 | .cindex "&[local_scan()]& function" "configuration options" |
| 30985 | It is possible to have option settings in the main configuration file |
| 30986 | that set values in static variables in the &[local_scan()]& module. If you |
| 30987 | want to do this, you must have the line |
| 30988 | .code |
| 30989 | LOCAL_SCAN_HAS_OPTIONS=yes |
| 30990 | .endd |
| 30991 | in your &_Local/Makefile_& when you build Exim. (This line is in |
| 30992 | &_OS/Makefile-Default_&, commented out). Then, in the &[local_scan()]& source |
| 30993 | file, you must define static variables to hold the option values, and a table |
| 30994 | to define them. |
| 30995 | |
| 30996 | The table must be a vector called &%local_scan_options%&, of type |
| 30997 | &`optionlist`&. Each entry is a triplet, consisting of a name, an option type, |
| 30998 | and a pointer to the variable that holds the value. The entries must appear in |
| 30999 | alphabetical order. Following &%local_scan_options%& you must also define a |
| 31000 | variable called &%local_scan_options_count%& that contains the number of |
| 31001 | entries in the table. Here is a short example, showing two kinds of option: |
| 31002 | .code |
| 31003 | static int my_integer_option = 42; |
| 31004 | static uschar *my_string_option = US"a default string"; |
| 31005 | |
| 31006 | optionlist local_scan_options[] = { |
| 31007 | { "my_integer", opt_int, &my_integer_option }, |
| 31008 | { "my_string", opt_stringptr, &my_string_option } |
| 31009 | }; |
| 31010 | |
| 31011 | int local_scan_options_count = |
| 31012 | sizeof(local_scan_options)/sizeof(optionlist); |
| 31013 | .endd |
| 31014 | The values of the variables can now be changed from Exim's runtime |
| 31015 | configuration file by including a local scan section as in this example: |
| 31016 | .code |
| 31017 | begin local_scan |
| 31018 | my_integer = 99 |
| 31019 | my_string = some string of text... |
| 31020 | .endd |
| 31021 | The available types of option data are as follows: |
| 31022 | |
| 31023 | .vlist |
| 31024 | .vitem &*opt_bool*& |
| 31025 | This specifies a boolean (true/false) option. The address should point to a |
| 31026 | variable of type &`BOOL`&, which will be set to TRUE or FALSE, which are macros |
| 31027 | that are defined as &"1"& and &"0"&, respectively. If you want to detect |
| 31028 | whether such a variable has been set at all, you can initialize it to |
| 31029 | TRUE_UNSET. (BOOL variables are integers underneath, so can hold more than two |
| 31030 | values.) |
| 31031 | |
| 31032 | .vitem &*opt_fixed*& |
| 31033 | This specifies a fixed point number, such as is used for load averages. |
| 31034 | The address should point to a variable of type &`int`&. The value is stored |
| 31035 | multiplied by 1000, so, for example, 1.4142 is truncated and stored as 1414. |
| 31036 | |
| 31037 | .vitem &*opt_int*& |
| 31038 | This specifies an integer; the address should point to a variable of type |
| 31039 | &`int`&. The value may be specified in any of the integer formats accepted by |
| 31040 | Exim. |
| 31041 | |
| 31042 | .vitem &*opt_mkint*& |
| 31043 | This is the same as &%opt_int%&, except that when such a value is output in a |
| 31044 | &%-bP%& listing, if it is an exact number of kilobytes or megabytes, it is |
| 31045 | printed with the suffix K or M. |
| 31046 | |
| 31047 | .vitem &*opt_octint*& |
| 31048 | This also specifies an integer, but the value is always interpreted as an |
| 31049 | octal integer, whether or not it starts with the digit zero, and it is |
| 31050 | always output in octal. |
| 31051 | |
| 31052 | .vitem &*opt_stringptr*& |
| 31053 | This specifies a string value; the address must be a pointer to a |
| 31054 | variable that points to a string (for example, of type &`uschar *`&). |
| 31055 | |
| 31056 | .vitem &*opt_time*& |
| 31057 | This specifies a time interval value. The address must point to a variable of |
| 31058 | type &`int`&. The value that is placed there is a number of seconds. |
| 31059 | .endlist |
| 31060 | |
| 31061 | If the &%-bP%& command line option is followed by &`local_scan`&, Exim prints |
| 31062 | out the values of all the &[local_scan()]& options. |
| 31063 | |
| 31064 | |
| 31065 | |
| 31066 | .section "Available Exim variables" "SECID208" |
| 31067 | .cindex "&[local_scan()]& function" "available Exim variables" |
| 31068 | The header &_local_scan.h_& gives you access to a number of C variables. These |
| 31069 | are the only ones that are guaranteed to be maintained from release to release. |
| 31070 | Note, however, that you can obtain the value of any Exim expansion variable, |
| 31071 | including &$recipients$&, by calling &'expand_string()'&. The exported |
| 31072 | C variables are as follows: |
| 31073 | |
| 31074 | .vlist |
| 31075 | .vitem &*int&~body_linecount*& |
| 31076 | This variable contains the number of lines in the message's body. |
| 31077 | |
| 31078 | .vitem &*int&~body_zerocount*& |
| 31079 | This variable contains the number of binary zero bytes in the message's body. |
| 31080 | |
| 31081 | .vitem &*unsigned&~int&~debug_selector*& |
| 31082 | This variable is set to zero when no debugging is taking place. Otherwise, it |
| 31083 | is a bitmap of debugging selectors. Two bits are identified for use in |
| 31084 | &[local_scan()]&; they are defined as macros: |
| 31085 | |
| 31086 | .ilist |
| 31087 | The &`D_v`& bit is set when &%-v%& was present on the command line. This is a |
| 31088 | testing option that is not privileged &-- any caller may set it. All the |
| 31089 | other selector bits can be set only by admin users. |
| 31090 | |
| 31091 | .next |
| 31092 | The &`D_local_scan`& bit is provided for use by &[local_scan()]&; it is set |
| 31093 | by the &`+local_scan`& debug selector. It is not included in the default set |
| 31094 | of debugging bits. |
| 31095 | .endlist ilist |
| 31096 | |
| 31097 | Thus, to write to the debugging output only when &`+local_scan`& has been |
| 31098 | selected, you should use code like this: |
| 31099 | .code |
| 31100 | if ((debug_selector & D_local_scan) != 0) |
| 31101 | debug_printf("xxx", ...); |
| 31102 | .endd |
| 31103 | .vitem &*uschar&~*expand_string_message*& |
| 31104 | After a failing call to &'expand_string()'& (returned value NULL), the |
| 31105 | variable &%expand_string_message%& contains the error message, zero-terminated. |
| 31106 | |
| 31107 | .vitem &*header_line&~*header_list*& |
| 31108 | A pointer to a chain of header lines. The &%header_line%& structure is |
| 31109 | discussed below. |
| 31110 | |
| 31111 | .vitem &*header_line&~*header_last*& |
| 31112 | A pointer to the last of the header lines. |
| 31113 | |
| 31114 | .vitem &*uschar&~*headers_charset*& |
| 31115 | The value of the &%headers_charset%& configuration option. |
| 31116 | |
| 31117 | .vitem &*BOOL&~host_checking*& |
| 31118 | This variable is TRUE during a host checking session that is initiated by the |
| 31119 | &%-bh%& command line option. |
| 31120 | |
| 31121 | .vitem &*uschar&~*interface_address*& |
| 31122 | The IP address of the interface that received the message, as a string. This |
| 31123 | is NULL for locally submitted messages. |
| 31124 | |
| 31125 | .vitem &*int&~interface_port*& |
| 31126 | The port on which this message was received. When testing with the &%-bh%& |
| 31127 | command line option, the value of this variable is -1 unless a port has been |
| 31128 | specified via the &%-oMi%& option. |
| 31129 | |
| 31130 | .vitem &*uschar&~*message_id*& |
| 31131 | This variable contains Exim's message id for the incoming message (the value of |
| 31132 | &$message_exim_id$&) as a zero-terminated string. |
| 31133 | |
| 31134 | .vitem &*uschar&~*received_protocol*& |
| 31135 | The name of the protocol by which the message was received. |
| 31136 | |
| 31137 | .vitem &*int&~recipients_count*& |
| 31138 | The number of accepted recipients. |
| 31139 | |
| 31140 | .vitem &*recipient_item&~*recipients_list*& |
| 31141 | .cindex "recipient" "adding in local scan" |
| 31142 | .cindex "recipient" "removing in local scan" |
| 31143 | The list of accepted recipients, held in a vector of length |
| 31144 | &%recipients_count%&. The &%recipient_item%& structure is discussed below. You |
| 31145 | can add additional recipients by calling &'receive_add_recipient()'& (see |
| 31146 | below). You can delete recipients by removing them from the vector and |
| 31147 | adjusting the value in &%recipients_count%&. In particular, by setting |
| 31148 | &%recipients_count%& to zero you remove all recipients. If you then return the |
| 31149 | value &`LOCAL_SCAN_ACCEPT`&, the message is accepted, but immediately |
| 31150 | blackholed. To replace the recipients, you can set &%recipients_count%& to zero |
| 31151 | and then call &'receive_add_recipient()'& as often as needed. |
| 31152 | |
| 31153 | .vitem &*uschar&~*sender_address*& |
| 31154 | The envelope sender address. For bounce messages this is the empty string. |
| 31155 | |
| 31156 | .vitem &*uschar&~*sender_host_address*& |
| 31157 | The IP address of the sending host, as a string. This is NULL for |
| 31158 | locally-submitted messages. |
| 31159 | |
| 31160 | .vitem &*uschar&~*sender_host_authenticated*& |
| 31161 | The name of the authentication mechanism that was used, or NULL if the message |
| 31162 | was not received over an authenticated SMTP connection. |
| 31163 | |
| 31164 | .vitem &*uschar&~*sender_host_name*& |
| 31165 | The name of the sending host, if known. |
| 31166 | |
| 31167 | .vitem &*int&~sender_host_port*& |
| 31168 | The port on the sending host. |
| 31169 | |
| 31170 | .vitem &*BOOL&~smtp_input*& |
| 31171 | This variable is TRUE for all SMTP input, including BSMTP. |
| 31172 | |
| 31173 | .vitem &*BOOL&~smtp_batched_input*& |
| 31174 | This variable is TRUE for BSMTP input. |
| 31175 | |
| 31176 | .vitem &*int&~store_pool*& |
| 31177 | The contents of this variable control which pool of memory is used for new |
| 31178 | requests. See section &<<SECTmemhanloc>>& for details. |
| 31179 | .endlist |
| 31180 | |
| 31181 | |
| 31182 | .section "Structure of header lines" "SECID209" |
| 31183 | The &%header_line%& structure contains the members listed below. |
| 31184 | You can add additional header lines by calling the &'header_add()'& function |
| 31185 | (see below). You can cause header lines to be ignored (deleted) by setting |
| 31186 | their type to *. |
| 31187 | |
| 31188 | |
| 31189 | .vlist |
| 31190 | .vitem &*struct&~header_line&~*next*& |
| 31191 | A pointer to the next header line, or NULL for the last line. |
| 31192 | |
| 31193 | .vitem &*int&~type*& |
| 31194 | A code identifying certain headers that Exim recognizes. The codes are printing |
| 31195 | characters, and are documented in chapter &<<CHAPspool>>& of this manual. |
| 31196 | Notice in particular that any header line whose type is * is not transmitted |
| 31197 | with the message. This flagging is used for header lines that have been |
| 31198 | rewritten, or are to be removed (for example, &'Envelope-sender:'& header |
| 31199 | lines.) Effectively, * means &"deleted"&. |
| 31200 | |
| 31201 | .vitem &*int&~slen*& |
| 31202 | The number of characters in the header line, including the terminating and any |
| 31203 | internal newlines. |
| 31204 | |
| 31205 | .vitem &*uschar&~*text*& |
| 31206 | A pointer to the text of the header. It always ends with a newline, followed by |
| 31207 | a zero byte. Internal newlines are preserved. |
| 31208 | .endlist |
| 31209 | |
| 31210 | |
| 31211 | |
| 31212 | .section "Structure of recipient items" "SECID210" |
| 31213 | The &%recipient_item%& structure contains these members: |
| 31214 | |
| 31215 | .vlist |
| 31216 | .vitem &*uschar&~*address*& |
| 31217 | This is a pointer to the recipient address as it was received. |
| 31218 | |
| 31219 | .vitem &*int&~pno*& |
| 31220 | This is used in later Exim processing when top level addresses are created by |
| 31221 | the &%one_time%& option. It is not relevant at the time &[local_scan()]& is run |
| 31222 | and must always contain -1 at this stage. |
| 31223 | |
| 31224 | .vitem &*uschar&~*errors_to*& |
| 31225 | If this value is not NULL, bounce messages caused by failing to deliver to the |
| 31226 | recipient are sent to the address it contains. In other words, it overrides the |
| 31227 | envelope sender for this one recipient. (Compare the &%errors_to%& generic |
| 31228 | router option.) If a &[local_scan()]& function sets an &%errors_to%& field to |
| 31229 | an unqualified address, Exim qualifies it using the domain from |
| 31230 | &%qualify_recipient%&. When &[local_scan()]& is called, the &%errors_to%& field |
| 31231 | is NULL for all recipients. |
| 31232 | .endlist |
| 31233 | |
| 31234 | |
| 31235 | |
| 31236 | .section "Available Exim functions" "SECID211" |
| 31237 | .cindex "&[local_scan()]& function" "available Exim functions" |
| 31238 | The header &_local_scan.h_& gives you access to a number of Exim functions. |
| 31239 | These are the only ones that are guaranteed to be maintained from release to |
| 31240 | release: |
| 31241 | |
| 31242 | .vlist |
| 31243 | .vitem "&*pid_t&~child_open(uschar&~**argv,&~uschar&~**envp,&~int&~newumask,&&& |
| 31244 | &~int&~*infdptr,&~int&~*outfdptr, &~&~BOOL&~make_leader)*&" |
| 31245 | |
| 31246 | This function creates a child process that runs the command specified by |
| 31247 | &%argv%&. The environment for the process is specified by &%envp%&, which can |
| 31248 | be NULL if no environment variables are to be passed. A new umask is supplied |
| 31249 | for the process in &%newumask%&. |
| 31250 | |
| 31251 | Pipes to the standard input and output of the new process are set up |
| 31252 | and returned to the caller via the &%infdptr%& and &%outfdptr%& arguments. The |
| 31253 | standard error is cloned to the standard output. If there are any file |
| 31254 | descriptors &"in the way"& in the new process, they are closed. If the final |
| 31255 | argument is TRUE, the new process is made into a process group leader. |
| 31256 | |
| 31257 | The function returns the pid of the new process, or -1 if things go wrong. |
| 31258 | |
| 31259 | .vitem &*int&~child_close(pid_t&~pid,&~int&~timeout)*& |
| 31260 | This function waits for a child process to terminate, or for a timeout (in |
| 31261 | seconds) to expire. A timeout value of zero means wait as long as it takes. The |
| 31262 | return value is as follows: |
| 31263 | |
| 31264 | .ilist |
| 31265 | >= 0 |
| 31266 | |
| 31267 | The process terminated by a normal exit and the value is the process |
| 31268 | ending status. |
| 31269 | |
| 31270 | .next |
| 31271 | < 0 and > &--256 |
| 31272 | |
| 31273 | The process was terminated by a signal and the value is the negation of the |
| 31274 | signal number. |
| 31275 | |
| 31276 | .next |
| 31277 | &--256 |
| 31278 | |
| 31279 | The process timed out. |
| 31280 | .next |
| 31281 | &--257 |
| 31282 | |
| 31283 | The was some other error in wait(); &%errno%& is still set. |
| 31284 | .endlist |
| 31285 | |
| 31286 | .vitem &*pid_t&~child_open_exim(int&~*fd)*& |
| 31287 | This function provide you with a means of submitting a new message to |
| 31288 | Exim. (Of course, you can also call &_/usr/sbin/sendmail_& yourself if you |
| 31289 | want, but this packages it all up for you.) The function creates a pipe, |
| 31290 | forks a subprocess that is running |
| 31291 | .code |
| 31292 | exim -t -oem -oi -f <> |
| 31293 | .endd |
| 31294 | and returns to you (via the &`int *`& argument) a file descriptor for the pipe |
| 31295 | that is connected to the standard input. The yield of the function is the PID |
| 31296 | of the subprocess. You can then write a message to the file descriptor, with |
| 31297 | recipients in &'To:'&, &'Cc:'&, and/or &'Bcc:'& header lines. |
| 31298 | |
| 31299 | When you have finished, call &'child_close()'& to wait for the process to |
| 31300 | finish and to collect its ending status. A timeout value of zero is usually |
| 31301 | fine in this circumstance. Unless you have made a mistake with the recipient |
| 31302 | addresses, you should get a return code of zero. |
| 31303 | |
| 31304 | |
| 31305 | .vitem &*pid_t&~child_open_exim2(int&~*fd,&~uschar&~*sender,&~uschar&~&&& |
| 31306 | *sender_authentication)*& |
| 31307 | This function is a more sophisticated version of &'child_open()'&. The command |
| 31308 | that it runs is: |
| 31309 | .display |
| 31310 | &`exim -t -oem -oi -f `&&'sender'&&` -oMas `&&'sender_authentication'& |
| 31311 | .endd |
| 31312 | The third argument may be NULL, in which case the &%-oMas%& option is omitted. |
| 31313 | |
| 31314 | |
| 31315 | .vitem &*void&~debug_printf(char&~*,&~...)*& |
| 31316 | This is Exim's debugging function, with arguments as for &'(printf()'&. The |
| 31317 | output is written to the standard error stream. If no debugging is selected, |
| 31318 | calls to &'debug_printf()'& have no effect. Normally, you should make calls |
| 31319 | conditional on the &`local_scan`& debug selector by coding like this: |
| 31320 | .code |
| 31321 | if ((debug_selector & D_local_scan) != 0) |
| 31322 | debug_printf("xxx", ...); |
| 31323 | .endd |
| 31324 | |
| 31325 | .vitem &*uschar&~*expand_string(uschar&~*string)*& |
| 31326 | This is an interface to Exim's string expansion code. The return value is the |
| 31327 | expanded string, or NULL if there was an expansion failure. |
| 31328 | The C variable &%expand_string_message%& contains an error message after an |
| 31329 | expansion failure. If expansion does not change the string, the return value is |
| 31330 | the pointer to the input string. Otherwise, the return value points to a new |
| 31331 | block of memory that was obtained by a call to &'store_get()'&. See section |
| 31332 | &<<SECTmemhanloc>>& below for a discussion of memory handling. |
| 31333 | |
| 31334 | .vitem &*void&~header_add(int&~type,&~char&~*format,&~...)*& |
| 31335 | This function allows you to an add additional header line at the end of the |
| 31336 | existing ones. The first argument is the type, and should normally be a space |
| 31337 | character. The second argument is a format string and any number of |
| 31338 | substitution arguments as for &[sprintf()]&. You may include internal newlines |
| 31339 | if you want, and you must ensure that the string ends with a newline. |
| 31340 | |
| 31341 | .vitem "&*void&~header_add_at_position(BOOL&~after,&~uschar&~*name,&~&&& |
| 31342 | BOOL&~topnot,&~int&~type,&~char&~*format, &~&~...)*&" |
| 31343 | This function adds a new header line at a specified point in the header |
| 31344 | chain. The header itself is specified as for &'header_add()'&. |
| 31345 | |
| 31346 | If &%name%& is NULL, the new header is added at the end of the chain if |
| 31347 | &%after%& is true, or at the start if &%after%& is false. If &%name%& is not |
| 31348 | NULL, the header lines are searched for the first non-deleted header that |
| 31349 | matches the name. If one is found, the new header is added before it if |
| 31350 | &%after%& is false. If &%after%& is true, the new header is added after the |
| 31351 | found header and any adjacent subsequent ones with the same name (even if |
| 31352 | marked &"deleted"&). If no matching non-deleted header is found, the &%topnot%& |
| 31353 | option controls where the header is added. If it is true, addition is at the |
| 31354 | top; otherwise at the bottom. Thus, to add a header after all the &'Received:'& |
| 31355 | headers, or at the top if there are no &'Received:'& headers, you could use |
| 31356 | .code |
| 31357 | header_add_at_position(TRUE, US"Received", TRUE, |
| 31358 | ' ', "X-xxx: ..."); |
| 31359 | .endd |
| 31360 | Normally, there is always at least one non-deleted &'Received:'& header, but |
| 31361 | there may not be if &%received_header_text%& expands to an empty string. |
| 31362 | |
| 31363 | |
| 31364 | .vitem &*void&~header_remove(int&~occurrence,&~uschar&~*name)*& |
| 31365 | This function removes header lines. If &%occurrence%& is zero or negative, all |
| 31366 | occurrences of the header are removed. If occurrence is greater than zero, that |
| 31367 | particular instance of the header is removed. If no header(s) can be found that |
| 31368 | match the specification, the function does nothing. |
| 31369 | |
| 31370 | |
| 31371 | .vitem "&*BOOL&~header_testname(header_line&~*hdr,&~uschar&~*name,&~&&& |
| 31372 | int&~length,&~BOOL&~notdel)*&" |
| 31373 | This function tests whether the given header has the given name. It is not just |
| 31374 | a string comparison, because white space is permitted between the name and the |
| 31375 | colon. If the &%notdel%& argument is true, a false return is forced for all |
| 31376 | &"deleted"& headers; otherwise they are not treated specially. For example: |
| 31377 | .code |
| 31378 | if (header_testname(h, US"X-Spam", 6, TRUE)) ... |
| 31379 | .endd |
| 31380 | .vitem &*uschar&~*lss_b64encode(uschar&~*cleartext,&~int&~length)*& |
| 31381 | .cindex "base64 encoding" "functions for &[local_scan()]& use" |
| 31382 | This function base64-encodes a string, which is passed by address and length. |
| 31383 | The text may contain bytes of any value, including zero. The result is passed |
| 31384 | back in dynamic memory that is obtained by calling &'store_get()'&. It is |
| 31385 | zero-terminated. |
| 31386 | |
| 31387 | .vitem &*int&~lss_b64decode(uschar&~*codetext,&~uschar&~**cleartext)*& |
| 31388 | This function decodes a base64-encoded string. Its arguments are a |
| 31389 | zero-terminated base64-encoded string and the address of a variable that is set |
| 31390 | to point to the result, which is in dynamic memory. The length of the decoded |
| 31391 | string is the yield of the function. If the input is invalid base64 data, the |
| 31392 | yield is -1. A zero byte is added to the end of the output string to make it |
| 31393 | easy to interpret as a C string (assuming it contains no zeros of its own). The |
| 31394 | added zero byte is not included in the returned count. |
| 31395 | |
| 31396 | .vitem &*int&~lss_match_domain(uschar&~*domain,&~uschar&~*list)*& |
| 31397 | This function checks for a match in a domain list. Domains are always |
| 31398 | matched caselessly. The return value is one of the following: |
| 31399 | .display |
| 31400 | &`OK `& match succeeded |
| 31401 | &`FAIL `& match failed |
| 31402 | &`DEFER `& match deferred |
| 31403 | .endd |
| 31404 | DEFER is usually caused by some kind of lookup defer, such as the |
| 31405 | inability to contact a database. |
| 31406 | |
| 31407 | .vitem "&*int&~lss_match_local_part(uschar&~*localpart,&~uschar&~*list,&~&&& |
| 31408 | BOOL&~caseless)*&" |
| 31409 | This function checks for a match in a local part list. The third argument |
| 31410 | controls case-sensitivity. The return values are as for |
| 31411 | &'lss_match_domain()'&. |
| 31412 | |
| 31413 | .vitem "&*int&~lss_match_address(uschar&~*address,&~uschar&~*list,&~&&& |
| 31414 | BOOL&~caseless)*&" |
| 31415 | This function checks for a match in an address list. The third argument |
| 31416 | controls the case-sensitivity of the local part match. The domain is always |
| 31417 | matched caselessly. The return values are as for &'lss_match_domain()'&. |
| 31418 | |
| 31419 | .vitem "&*int&~lss_match_host(uschar&~*host_name,&~uschar&~*host_address,&~&&& |
| 31420 | uschar&~*list)*&" |
| 31421 | This function checks for a match in a host list. The most common usage is |
| 31422 | expected to be |
| 31423 | .code |
| 31424 | lss_match_host(sender_host_name, sender_host_address, ...) |
| 31425 | .endd |
| 31426 | .vindex "&$sender_host_address$&" |
| 31427 | An empty address field matches an empty item in the host list. If the host name |
| 31428 | is NULL, the name corresponding to &$sender_host_address$& is automatically |
| 31429 | looked up if a host name is required to match an item in the list. The return |
| 31430 | values are as for &'lss_match_domain()'&, but in addition, &'lss_match_host()'& |
| 31431 | returns ERROR in the case when it had to look up a host name, but the lookup |
| 31432 | failed. |
| 31433 | |
| 31434 | .vitem "&*void&~log_write(unsigned&~int&~selector,&~int&~which,&~char&~&&& |
| 31435 | *format,&~...)*&" |
| 31436 | This function writes to Exim's log files. The first argument should be zero (it |
| 31437 | is concerned with &%log_selector%&). The second argument can be &`LOG_MAIN`& or |
| 31438 | &`LOG_REJECT`& or &`LOG_PANIC`& or the inclusive &"or"& of any combination of |
| 31439 | them. It specifies to which log or logs the message is written. The remaining |
| 31440 | arguments are a format and relevant insertion arguments. The string should not |
| 31441 | contain any newlines, not even at the end. |
| 31442 | |
| 31443 | |
| 31444 | .vitem &*void&~receive_add_recipient(uschar&~*address,&~int&~pno)*& |
| 31445 | This function adds an additional recipient to the message. The first argument |
| 31446 | is the recipient address. If it is unqualified (has no domain), it is qualified |
| 31447 | with the &%qualify_recipient%& domain. The second argument must always be -1. |
| 31448 | |
| 31449 | This function does not allow you to specify a private &%errors_to%& address (as |
| 31450 | described with the structure of &%recipient_item%& above), because it pre-dates |
| 31451 | the addition of that field to the structure. However, it is easy to add such a |
| 31452 | value afterwards. For example: |
| 31453 | .code |
| 31454 | receive_add_recipient(US"monitor@mydom.example", -1); |
| 31455 | recipients_list[recipients_count-1].errors_to = |
| 31456 | US"postmaster@mydom.example"; |
| 31457 | .endd |
| 31458 | |
| 31459 | .vitem &*BOOL&~receive_remove_recipient(uschar&~*recipient)*& |
| 31460 | This is a convenience function to remove a named recipient from the list of |
| 31461 | recipients. It returns true if a recipient was removed, and false if no |
| 31462 | matching recipient could be found. The argument must be a complete email |
| 31463 | address. |
| 31464 | .endlist |
| 31465 | |
| 31466 | |
| 31467 | .cindex "RFC 2047" |
| 31468 | .vlist |
| 31469 | .vitem "&*uschar&~rfc2047_decode(uschar&~*string,&~BOOL&~lencheck,&&& |
| 31470 | &~uschar&~*target,&~int&~zeroval,&~int&~*lenptr, &~&~uschar&~**error)*&" |
| 31471 | This function decodes strings that are encoded according to RFC 2047. Typically |
| 31472 | these are the contents of header lines. First, each &"encoded word"& is decoded |
| 31473 | from the Q or B encoding into a byte-string. Then, if provided with the name of |
| 31474 | a charset encoding, and if the &[iconv()]& function is available, an attempt is |
| 31475 | made to translate the result to the named character set. If this fails, the |
| 31476 | binary string is returned with an error message. |
| 31477 | |
| 31478 | The first argument is the string to be decoded. If &%lencheck%& is TRUE, the |
| 31479 | maximum MIME word length is enforced. The third argument is the target |
| 31480 | encoding, or NULL if no translation is wanted. |
| 31481 | |
| 31482 | .cindex "binary zero" "in RFC 2047 decoding" |
| 31483 | .cindex "RFC 2047" "binary zero in" |
| 31484 | If a binary zero is encountered in the decoded string, it is replaced by the |
| 31485 | contents of the &%zeroval%& argument. For use with Exim headers, the value must |
| 31486 | not be 0 because header lines are handled as zero-terminated strings. |
| 31487 | |
| 31488 | The function returns the result of processing the string, zero-terminated; if |
| 31489 | &%lenptr%& is not NULL, the length of the result is set in the variable to |
| 31490 | which it points. When &%zeroval%& is 0, &%lenptr%& should not be NULL. |
| 31491 | |
| 31492 | If an error is encountered, the function returns NULL and uses the &%error%& |
| 31493 | argument to return an error message. The variable pointed to by &%error%& is |
| 31494 | set to NULL if there is no error; it may be set non-NULL even when the function |
| 31495 | returns a non-NULL value if decoding was successful, but there was a problem |
| 31496 | with translation. |
| 31497 | |
| 31498 | |
| 31499 | .vitem &*int&~smtp_fflush(void)*& |
| 31500 | This function is used in conjunction with &'smtp_printf()'&, as described |
| 31501 | below. |
| 31502 | |
| 31503 | .vitem &*void&~smtp_printf(char&~*,&~...)*& |
| 31504 | The arguments of this function are like &[printf()]&; it writes to the SMTP |
| 31505 | output stream. You should use this function only when there is an SMTP output |
| 31506 | stream, that is, when the incoming message is being received via interactive |
| 31507 | SMTP. This is the case when &%smtp_input%& is TRUE and &%smtp_batched_input%& |
| 31508 | is FALSE. If you want to test for an incoming message from another host (as |
| 31509 | opposed to a local process that used the &%-bs%& command line option), you can |
| 31510 | test the value of &%sender_host_address%&, which is non-NULL when a remote host |
| 31511 | is involved. |
| 31512 | |
| 31513 | If an SMTP TLS connection is established, &'smtp_printf()'& uses the TLS |
| 31514 | output function, so it can be used for all forms of SMTP connection. |
| 31515 | |
| 31516 | Strings that are written by &'smtp_printf()'& from within &[local_scan()]& |
| 31517 | must start with an appropriate response code: 550 if you are going to return |
| 31518 | LOCAL_SCAN_REJECT, 451 if you are going to return |
| 31519 | LOCAL_SCAN_TEMPREJECT, and 250 otherwise. Because you are writing the |
| 31520 | initial lines of a multi-line response, the code must be followed by a hyphen |
| 31521 | to indicate that the line is not the final response line. You must also ensure |
| 31522 | that the lines you write terminate with CRLF. For example: |
| 31523 | .code |
| 31524 | smtp_printf("550-this is some extra info\r\n"); |
| 31525 | return LOCAL_SCAN_REJECT; |
| 31526 | .endd |
| 31527 | Note that you can also create multi-line responses by including newlines in |
| 31528 | the data returned via the &%return_text%& argument. The added value of using |
| 31529 | &'smtp_printf()'& is that, for instance, you could introduce delays between |
| 31530 | multiple output lines. |
| 31531 | |
| 31532 | The &'smtp_printf()'& function does not return any error indication, because it |
| 31533 | does not automatically flush pending output, and therefore does not test |
| 31534 | the state of the stream. (In the main code of Exim, flushing and error |
| 31535 | detection is done when Exim is ready for the next SMTP input command.) If |
| 31536 | you want to flush the output and check for an error (for example, the |
| 31537 | dropping of a TCP/IP connection), you can call &'smtp_fflush()'&, which has no |
| 31538 | arguments. It flushes the output stream, and returns a non-zero value if there |
| 31539 | is an error. |
| 31540 | |
| 31541 | .vitem &*void&~*store_get(int)*& |
| 31542 | This function accesses Exim's internal store (memory) manager. It gets a new |
| 31543 | chunk of memory whose size is given by the argument. Exim bombs out if it ever |
| 31544 | runs out of memory. See the next section for a discussion of memory handling. |
| 31545 | |
| 31546 | .vitem &*void&~*store_get_perm(int)*& |
| 31547 | This function is like &'store_get()'&, but it always gets memory from the |
| 31548 | permanent pool. See the next section for a discussion of memory handling. |
| 31549 | |
| 31550 | .vitem &*uschar&~*string_copy(uschar&~*string)*& |
| 31551 | See below. |
| 31552 | |
| 31553 | .vitem &*uschar&~*string_copyn(uschar&~*string,&~int&~length)*& |
| 31554 | See below. |
| 31555 | |
| 31556 | .vitem &*uschar&~*string_sprintf(char&~*format,&~...)*& |
| 31557 | These three functions create strings using Exim's dynamic memory facilities. |
| 31558 | The first makes a copy of an entire string. The second copies up to a maximum |
| 31559 | number of characters, indicated by the second argument. The third uses a format |
| 31560 | and insertion arguments to create a new string. In each case, the result is a |
| 31561 | pointer to a new string in the current memory pool. See the next section for |
| 31562 | more discussion. |
| 31563 | .endlist |
| 31564 | |
| 31565 | |
| 31566 | |
| 31567 | .section "More about Exim's memory handling" "SECTmemhanloc" |
| 31568 | .cindex "&[local_scan()]& function" "memory handling" |
| 31569 | No function is provided for freeing memory, because that is never needed. |
| 31570 | The dynamic memory that Exim uses when receiving a message is automatically |
| 31571 | recycled if another message is received by the same process (this applies only |
| 31572 | to incoming SMTP connections &-- other input methods can supply only one |
| 31573 | message at a time). After receiving the last message, a reception process |
| 31574 | terminates. |
| 31575 | |
| 31576 | Because it is recycled, the normal dynamic memory cannot be used for holding |
| 31577 | data that must be preserved over a number of incoming messages on the same SMTP |
| 31578 | connection. However, Exim in fact uses two pools of dynamic memory; the second |
| 31579 | one is not recycled, and can be used for this purpose. |
| 31580 | |
| 31581 | If you want to allocate memory that remains available for subsequent messages |
| 31582 | in the same SMTP connection, you should set |
| 31583 | .code |
| 31584 | store_pool = POOL_PERM |
| 31585 | .endd |
| 31586 | before calling the function that does the allocation. There is no need to |
| 31587 | restore the value if you do not need to; however, if you do want to revert to |
| 31588 | the normal pool, you can either restore the previous value of &%store_pool%& or |
| 31589 | set it explicitly to POOL_MAIN. |
| 31590 | |
| 31591 | The pool setting applies to all functions that get dynamic memory, including |
| 31592 | &'expand_string()'&, &'store_get()'&, and the &'string_xxx()'& functions. |
| 31593 | There is also a convenience function called &'store_get_perm()'& that gets a |
| 31594 | block of memory from the permanent pool while preserving the value of |
| 31595 | &%store_pool%&. |
| 31596 | .ecindex IIDlosca |
| 31597 | |
| 31598 | |
| 31599 | |
| 31600 | |
| 31601 | . //////////////////////////////////////////////////////////////////////////// |
| 31602 | . //////////////////////////////////////////////////////////////////////////// |
| 31603 | |
| 31604 | .chapter "System-wide message filtering" "CHAPsystemfilter" |
| 31605 | .scindex IIDsysfil1 "filter" "system filter" |
| 31606 | .scindex IIDsysfil2 "filtering all mail" |
| 31607 | .scindex IIDsysfil3 "system filter" |
| 31608 | The previous chapters (on ACLs and the local scan function) describe checks |
| 31609 | that can be applied to messages before they are accepted by a host. There is |
| 31610 | also a mechanism for checking messages once they have been received, but before |
| 31611 | they are delivered. This is called the &'system filter'&. |
| 31612 | |
| 31613 | The system filter operates in a similar manner to users' filter files, but it |
| 31614 | is run just once per message (however many recipients the message has). |
| 31615 | It should not normally be used as a substitute for routing, because &%deliver%& |
| 31616 | commands in a system router provide new envelope recipient addresses. |
| 31617 | The system filter must be an Exim filter. It cannot be a Sieve filter. |
| 31618 | |
| 31619 | The system filter is run at the start of a delivery attempt, before any routing |
| 31620 | is done. If a message fails to be completely delivered at the first attempt, |
| 31621 | the system filter is run again at the start of every retry. |
| 31622 | If you want your filter to do something only once per message, you can make use |
| 31623 | of the &%first_delivery%& condition in an &%if%& command in the filter to |
| 31624 | prevent it happening on retries. |
| 31625 | |
| 31626 | .vindex "&$domain$&" |
| 31627 | .vindex "&$local_part$&" |
| 31628 | &*Warning*&: Because the system filter runs just once, variables that are |
| 31629 | specific to individual recipient addresses, such as &$local_part$& and |
| 31630 | &$domain$&, are not set, and the &"personal"& condition is not meaningful. If |
| 31631 | you want to run a centrally-specified filter for each recipient address |
| 31632 | independently, you can do so by setting up a suitable &(redirect)& router, as |
| 31633 | described in section &<<SECTperaddfil>>& below. |
| 31634 | |
| 31635 | |
| 31636 | .section "Specifying a system filter" "SECID212" |
| 31637 | .cindex "uid (user id)" "system filter" |
| 31638 | .cindex "gid (group id)" "system filter" |
| 31639 | The name of the file that contains the system filter must be specified by |
| 31640 | setting &%system_filter%&. If you want the filter to run under a uid and gid |
| 31641 | other than root, you must also set &%system_filter_user%& and |
| 31642 | &%system_filter_group%& as appropriate. For example: |
| 31643 | .code |
| 31644 | system_filter = /etc/mail/exim.filter |
| 31645 | system_filter_user = exim |
| 31646 | .endd |
| 31647 | If a system filter generates any deliveries directly to files or pipes (via the |
| 31648 | &%save%& or &%pipe%& commands), transports to handle these deliveries must be |
| 31649 | specified by setting &%system_filter_file_transport%& and |
| 31650 | &%system_filter_pipe_transport%&, respectively. Similarly, |
| 31651 | &%system_filter_reply_transport%& must be set to handle any messages generated |
| 31652 | by the &%reply%& command. |
| 31653 | |
| 31654 | |
| 31655 | .section "Testing a system filter" "SECID213" |
| 31656 | You can run simple tests of a system filter in the same way as for a user |
| 31657 | filter, but you should use &%-bF%& rather than &%-bf%&, so that features that |
| 31658 | are permitted only in system filters are recognized. |
| 31659 | |
| 31660 | If you want to test the combined effect of a system filter and a user filter, |
| 31661 | you can use both &%-bF%& and &%-bf%& on the same command line. |
| 31662 | |
| 31663 | |
| 31664 | |
| 31665 | .section "Contents of a system filter" "SECID214" |
| 31666 | The language used to specify system filters is the same as for users' filter |
| 31667 | files. It is described in the separate end-user document &'Exim's interface to |
| 31668 | mail filtering'&. However, there are some additional features that are |
| 31669 | available only in system filters; these are described in subsequent sections. |
| 31670 | If they are encountered in a user's filter file or when testing with &%-bf%&, |
| 31671 | they cause errors. |
| 31672 | |
| 31673 | .cindex "frozen messages" "manual thaw; testing in filter" |
| 31674 | There are two special conditions which, though available in users' filter |
| 31675 | files, are designed for use in system filters. The condition &%first_delivery%& |
| 31676 | is true only for the first attempt at delivering a message, and |
| 31677 | &%manually_thawed%& is true only if the message has been frozen, and |
| 31678 | subsequently thawed by an admin user. An explicit forced delivery counts as a |
| 31679 | manual thaw, but thawing as a result of the &%auto_thaw%& setting does not. |
| 31680 | |
| 31681 | &*Warning*&: If a system filter uses the &%first_delivery%& condition to |
| 31682 | specify an &"unseen"& (non-significant) delivery, and that delivery does not |
| 31683 | succeed, it will not be tried again. |
| 31684 | If you want Exim to retry an unseen delivery until it succeeds, you should |
| 31685 | arrange to set it up every time the filter runs. |
| 31686 | |
| 31687 | When a system filter finishes running, the values of the variables &$n0$& &-- |
| 31688 | &$n9$& are copied into &$sn0$& &-- &$sn9$& and are thereby made available to |
| 31689 | users' filter files. Thus a system filter can, for example, set up &"scores"& |
| 31690 | to which users' filter files can refer. |
| 31691 | |
| 31692 | |
| 31693 | |
| 31694 | .section "Additional variable for system filters" "SECID215" |
| 31695 | .vindex "&$recipients$&" |
| 31696 | The expansion variable &$recipients$&, containing a list of all the recipients |
| 31697 | of the message (separated by commas and white space), is available in system |
| 31698 | filters. It is not available in users' filters for privacy reasons. |
| 31699 | |
| 31700 | |
| 31701 | |
| 31702 | .section "Defer, freeze, and fail commands for system filters" "SECID216" |
| 31703 | .cindex "freezing messages" |
| 31704 | .cindex "message" "freezing" |
| 31705 | .cindex "message" "forced failure" |
| 31706 | .cindex "&%fail%&" "in system filter" |
| 31707 | .cindex "&%freeze%& in system filter" |
| 31708 | .cindex "&%defer%& in system filter" |
| 31709 | There are three extra commands (&%defer%&, &%freeze%& and &%fail%&) which are |
| 31710 | always available in system filters, but are not normally enabled in users' |
| 31711 | filters. (See the &%allow_defer%&, &%allow_freeze%& and &%allow_fail%& options |
| 31712 | for the &(redirect)& router.) These commands can optionally be followed by the |
| 31713 | word &%text%& and a string containing an error message, for example: |
| 31714 | .code |
| 31715 | fail text "this message looks like spam to me" |
| 31716 | .endd |
| 31717 | The keyword &%text%& is optional if the next character is a double quote. |
| 31718 | |
| 31719 | The &%defer%& command defers delivery of the original recipients of the |
| 31720 | message. The &%fail%& command causes all the original recipients to be failed, |
| 31721 | and a bounce message to be created. The &%freeze%& command suspends all |
| 31722 | delivery attempts for the original recipients. In all cases, any new deliveries |
| 31723 | that are specified by the filter are attempted as normal after the filter has |
| 31724 | run. |
| 31725 | |
| 31726 | The &%freeze%& command is ignored if the message has been manually unfrozen and |
| 31727 | not manually frozen since. This means that automatic freezing by a system |
| 31728 | filter can be used as a way of checking out suspicious messages. If a message |
| 31729 | is found to be all right, manually unfreezing it allows it to be delivered. |
| 31730 | |
| 31731 | .cindex "log" "&%fail%& command log line" |
| 31732 | .cindex "&%fail%&" "log line; reducing" |
| 31733 | The text given with a fail command is used as part of the bounce message as |
| 31734 | well as being written to the log. If the message is quite long, this can fill |
| 31735 | up a lot of log space when such failures are common. To reduce the size of the |
| 31736 | log message, Exim interprets the text in a special way if it starts with the |
| 31737 | two characters &`<<`& and contains &`>>`& later. The text between these two |
| 31738 | strings is written to the log, and the rest of the text is used in the bounce |
| 31739 | message. For example: |
| 31740 | .code |
| 31741 | fail "<<filter test 1>>Your message is rejected \ |
| 31742 | because it contains attachments that we are \ |
| 31743 | not prepared to receive." |
| 31744 | .endd |
| 31745 | |
| 31746 | .cindex "loop" "caused by &%fail%&" |
| 31747 | Take great care with the &%fail%& command when basing the decision to fail on |
| 31748 | the contents of the message, because the bounce message will of course include |
| 31749 | the contents of the original message and will therefore trigger the &%fail%& |
| 31750 | command again (causing a mail loop) unless steps are taken to prevent this. |
| 31751 | Testing the &%error_message%& condition is one way to prevent this. You could |
| 31752 | use, for example |
| 31753 | .code |
| 31754 | if $message_body contains "this is spam" and not error_message |
| 31755 | then fail text "spam is not wanted here" endif |
| 31756 | .endd |
| 31757 | though of course that might let through unwanted bounce messages. The |
| 31758 | alternative is clever checking of the body and/or headers to detect bounces |
| 31759 | generated by the filter. |
| 31760 | |
| 31761 | The interpretation of a system filter file ceases after a |
| 31762 | &%defer%&, |
| 31763 | &%freeze%&, or &%fail%& command is obeyed. However, any deliveries that were |
| 31764 | set up earlier in the filter file are honoured, so you can use a sequence such |
| 31765 | as |
| 31766 | .code |
| 31767 | mail ... |
| 31768 | freeze |
| 31769 | .endd |
| 31770 | to send a specified message when the system filter is freezing (or deferring or |
| 31771 | failing) a message. The normal deliveries for the message do not, of course, |
| 31772 | take place. |
| 31773 | |
| 31774 | |
| 31775 | |
| 31776 | .section "Adding and removing headers in a system filter" "SECTaddremheasys" |
| 31777 | .cindex "header lines" "adding; in system filter" |
| 31778 | .cindex "header lines" "removing; in system filter" |
| 31779 | .cindex "filter" "header lines; adding/removing" |
| 31780 | Two filter commands that are available only in system filters are: |
| 31781 | .code |
| 31782 | headers add <string> |
| 31783 | headers remove <string> |
| 31784 | .endd |
| 31785 | The argument for the &%headers add%& is a string that is expanded and then |
| 31786 | added to the end of the message's headers. It is the responsibility of the |
| 31787 | filter maintainer to make sure it conforms to RFC 2822 syntax. Leading white |
| 31788 | space is ignored, and if the string is otherwise empty, or if the expansion is |
| 31789 | forced to fail, the command has no effect. |
| 31790 | |
| 31791 | You can use &"\n"& within the string, followed by white space, to specify |
| 31792 | continued header lines. More than one header may be added in one command by |
| 31793 | including &"\n"& within the string without any following white space. For |
| 31794 | example: |
| 31795 | .code |
| 31796 | headers add "X-header-1: ....\n \ |
| 31797 | continuation of X-header-1 ...\n\ |
| 31798 | X-header-2: ...." |
| 31799 | .endd |
| 31800 | Note that the header line continuation white space after the first newline must |
| 31801 | be placed before the backslash that continues the input string, because white |
| 31802 | space after input continuations is ignored. |
| 31803 | |
| 31804 | The argument for &%headers remove%& is a colon-separated list of header names. |
| 31805 | This command applies only to those headers that are stored with the message; |
| 31806 | those that are added at delivery time (such as &'Envelope-To:'& and |
| 31807 | &'Return-Path:'&) cannot be removed by this means. If there is more than one |
| 31808 | header with the same name, they are all removed. |
| 31809 | |
| 31810 | The &%headers%& command in a system filter makes an immediate change to the set |
| 31811 | of header lines that was received with the message (with possible additions |
| 31812 | from ACL processing). Subsequent commands in the system filter operate on the |
| 31813 | modified set, which also forms the basis for subsequent message delivery. |
| 31814 | Unless further modified during routing or transporting, this set of headers is |
| 31815 | used for all recipients of the message. |
| 31816 | |
| 31817 | During routing and transporting, the variables that refer to the contents of |
| 31818 | header lines refer only to those lines that are in this set. Thus, header lines |
| 31819 | that are added by a system filter are visible to users' filter files and to all |
| 31820 | routers and transports. This contrasts with the manipulation of header lines by |
| 31821 | routers and transports, which is not immediate, but which instead is saved up |
| 31822 | until the message is actually being written (see section |
| 31823 | &<<SECTheadersaddrem>>&). |
| 31824 | |
| 31825 | If the message is not delivered at the first attempt, header lines that were |
| 31826 | added by the system filter are stored with the message, and so are still |
| 31827 | present at the next delivery attempt. Header lines that were removed are still |
| 31828 | present, but marked &"deleted"& so that they are not transported with the |
| 31829 | message. For this reason, it is usual to make the &%headers%& command |
| 31830 | conditional on &%first_delivery%& so that the set of header lines is not |
| 31831 | modified more than once. |
| 31832 | |
| 31833 | Because header modification in a system filter acts immediately, you have to |
| 31834 | use an indirect approach if you want to modify the contents of a header line. |
| 31835 | For example: |
| 31836 | .code |
| 31837 | headers add "Old-Subject: $h_subject:" |
| 31838 | headers remove "Subject" |
| 31839 | headers add "Subject: new subject (was: $h_old-subject:)" |
| 31840 | headers remove "Old-Subject" |
| 31841 | .endd |
| 31842 | |
| 31843 | |
| 31844 | |
| 31845 | .section "Setting an errors address in a system filter" "SECID217" |
| 31846 | .cindex "envelope sender" |
| 31847 | In a system filter, if a &%deliver%& command is followed by |
| 31848 | .code |
| 31849 | errors_to <some address> |
| 31850 | .endd |
| 31851 | in order to change the envelope sender (and hence the error reporting) for that |
| 31852 | delivery, any address may be specified. (In a user filter, only the current |
| 31853 | user's address can be set.) For example, if some mail is being monitored, you |
| 31854 | might use |
| 31855 | .code |
| 31856 | unseen deliver monitor@spying.example errors_to root@local.example |
| 31857 | .endd |
| 31858 | to take a copy which would not be sent back to the normal error reporting |
| 31859 | address if its delivery failed. |
| 31860 | |
| 31861 | |
| 31862 | |
| 31863 | .section "Per-address filtering" "SECTperaddfil" |
| 31864 | .vindex "&$domain$&" |
| 31865 | .vindex "&$local_part$&" |
| 31866 | In contrast to the system filter, which is run just once per message for each |
| 31867 | delivery attempt, it is also possible to set up a system-wide filtering |
| 31868 | operation that runs once for each recipient address. In this case, variables |
| 31869 | such as &$local_part$& and &$domain$& can be used, and indeed, the choice of |
| 31870 | filter file could be made dependent on them. This is an example of a router |
| 31871 | which implements such a filter: |
| 31872 | .code |
| 31873 | central_filter: |
| 31874 | check_local_user |
| 31875 | driver = redirect |
| 31876 | domains = +local_domains |
| 31877 | file = /central/filters/$local_part |
| 31878 | no_verify |
| 31879 | allow_filter |
| 31880 | allow_freeze |
| 31881 | .endd |
| 31882 | The filter is run in a separate process under its own uid. Therefore, either |
| 31883 | &%check_local_user%& must be set (as above), in which case the filter is run as |
| 31884 | the local user, or the &%user%& option must be used to specify which user to |
| 31885 | use. If both are set, &%user%& overrides. |
| 31886 | |
| 31887 | Care should be taken to ensure that none of the commands in the filter file |
| 31888 | specify a significant delivery if the message is to go on to be delivered to |
| 31889 | its intended recipient. The router will not then claim to have dealt with the |
| 31890 | address, so it will be passed on to subsequent routers to be delivered in the |
| 31891 | normal way. |
| 31892 | .ecindex IIDsysfil1 |
| 31893 | .ecindex IIDsysfil2 |
| 31894 | .ecindex IIDsysfil3 |
| 31895 | |
| 31896 | |
| 31897 | |
| 31898 | |
| 31899 | |
| 31900 | |
| 31901 | . //////////////////////////////////////////////////////////////////////////// |
| 31902 | . //////////////////////////////////////////////////////////////////////////// |
| 31903 | |
| 31904 | .chapter "Message processing" "CHAPmsgproc" |
| 31905 | .scindex IIDmesproc "message" "general processing" |
| 31906 | Exim performs various transformations on the sender and recipient addresses of |
| 31907 | all messages that it handles, and also on the messages' header lines. Some of |
| 31908 | these are optional and configurable, while others always take place. All of |
| 31909 | this processing, except rewriting as a result of routing, and the addition or |
| 31910 | removal of header lines while delivering, happens when a message is received, |
| 31911 | before it is placed on Exim's queue. |
| 31912 | |
| 31913 | Some of the automatic processing takes place by default only for |
| 31914 | &"locally-originated"& messages. This adjective is used to describe messages |
| 31915 | that are not received over TCP/IP, but instead are passed to an Exim process on |
| 31916 | its standard input. This includes the interactive &"local SMTP"& case that is |
| 31917 | set up by the &%-bs%& command line option. |
| 31918 | |
| 31919 | &*Note*&: Messages received over TCP/IP on the loopback interface (127.0.0.1 |
| 31920 | or ::1) are not considered to be locally-originated. Exim does not treat the |
| 31921 | loopback interface specially in any way. |
| 31922 | |
| 31923 | If you want the loopback interface to be treated specially, you must ensure |
| 31924 | that there are appropriate entries in your ACLs. |
| 31925 | |
| 31926 | |
| 31927 | |
| 31928 | |
| 31929 | .section "Submission mode for non-local messages" "SECTsubmodnon" |
| 31930 | .cindex "message" "submission" |
| 31931 | .cindex "submission mode" |
| 31932 | Processing that happens automatically for locally-originated messages (unless |
| 31933 | &%suppress_local_fixups%& is set) can also be requested for messages that are |
| 31934 | received over TCP/IP. The term &"submission mode"& is used to describe this |
| 31935 | state. Submission mode is set by the modifier |
| 31936 | .code |
| 31937 | control = submission |
| 31938 | .endd |
| 31939 | in a MAIL, RCPT, or pre-data ACL for an incoming message (see sections |
| 31940 | &<<SECTACLmodi>>& and &<<SECTcontrols>>&). This makes Exim treat the message as |
| 31941 | a local submission, and is normally used when the source of the message is |
| 31942 | known to be an MUA running on a client host (as opposed to an MTA). For |
| 31943 | example, to set submission mode for messages originating on the IPv4 loopback |
| 31944 | interface, you could include the following in the MAIL ACL: |
| 31945 | .code |
| 31946 | warn hosts = 127.0.0.1 |
| 31947 | control = submission |
| 31948 | .endd |
| 31949 | .cindex "&%sender_retain%& submission option" |
| 31950 | There are some options that can be used when setting submission mode. A slash |
| 31951 | is used to separate options. For example: |
| 31952 | .code |
| 31953 | control = submission/sender_retain |
| 31954 | .endd |
| 31955 | Specifying &%sender_retain%& has the effect of setting &%local_sender_retain%& |
| 31956 | true and &%local_from_check%& false for the current incoming message. The first |
| 31957 | of these allows an existing &'Sender:'& header in the message to remain, and |
| 31958 | the second suppresses the check to ensure that &'From:'& matches the |
| 31959 | authenticated sender. With this setting, Exim still fixes up messages by adding |
| 31960 | &'Date:'& and &'Message-ID:'& header lines if they are missing, but makes no |
| 31961 | attempt to check sender authenticity in header lines. |
| 31962 | |
| 31963 | When &%sender_retain%& is not set, a submission mode setting may specify a |
| 31964 | domain to be used when generating a &'From:'& or &'Sender:'& header line. For |
| 31965 | example: |
| 31966 | .code |
| 31967 | control = submission/domain=some.domain |
| 31968 | .endd |
| 31969 | The domain may be empty. How this value is used is described in sections |
| 31970 | &<<SECTthefrohea>>& and &<<SECTthesenhea>>&. There is also a &%name%& option |
| 31971 | that allows you to specify the user's full name for inclusion in a created |
| 31972 | &'Sender:'& or &'From:'& header line. For example: |
| 31973 | .code |
| 31974 | accept authenticated = * |
| 31975 | control = submission/domain=wonderland.example/\ |
| 31976 | name=${lookup {$authenticated_id} \ |
| 31977 | lsearch {/etc/exim/namelist}} |
| 31978 | .endd |
| 31979 | Because the name may contain any characters, including slashes, the &%name%& |
| 31980 | option must be given last. The remainder of the string is used as the name. For |
| 31981 | the example above, if &_/etc/exim/namelist_& contains: |
| 31982 | .code |
| 31983 | bigegg: Humpty Dumpty |
| 31984 | .endd |
| 31985 | then when the sender has authenticated as &'bigegg'&, the generated &'Sender:'& |
| 31986 | line would be: |
| 31987 | .code |
| 31988 | Sender: Humpty Dumpty <bigegg@wonderland.example> |
| 31989 | .endd |
| 31990 | .cindex "return path" "in submission mode" |
| 31991 | By default, submission mode forces the return path to the same address as is |
| 31992 | used to create the &'Sender:'& header. However, if &%sender_retain%& is |
| 31993 | specified, the return path is also left unchanged. |
| 31994 | |
| 31995 | &*Note*&: The changes caused by submission mode take effect after the predata |
| 31996 | ACL. This means that any sender checks performed before the fix-ups use the |
| 31997 | untrusted sender address specified by the user, not the trusted sender address |
| 31998 | specified by submission mode. Although this might be slightly unexpected, it |
| 31999 | does mean that you can configure ACL checks to spot that a user is trying to |
| 32000 | spoof another's address. |
| 32001 | |
| 32002 | .section "Line endings" "SECTlineendings" |
| 32003 | .cindex "line endings" |
| 32004 | .cindex "carriage return" |
| 32005 | .cindex "linefeed" |
| 32006 | RFC 2821 specifies that CRLF (two characters: carriage-return, followed by |
| 32007 | linefeed) is the line ending for messages transmitted over the Internet using |
| 32008 | SMTP over TCP/IP. However, within individual operating systems, different |
| 32009 | conventions are used. For example, Unix-like systems use just LF, but others |
| 32010 | use CRLF or just CR. |
| 32011 | |
| 32012 | Exim was designed for Unix-like systems, and internally, it stores messages |
| 32013 | using the system's convention of a single LF as a line terminator. When |
| 32014 | receiving a message, all line endings are translated to this standard format. |
| 32015 | Originally, it was thought that programs that passed messages directly to an |
| 32016 | MTA within an operating system would use that system's convention. Experience |
| 32017 | has shown that this is not the case; for example, there are Unix applications |
| 32018 | that use CRLF in this circumstance. For this reason, and for compatibility with |
| 32019 | other MTAs, the way Exim handles line endings for all messages is now as |
| 32020 | follows: |
| 32021 | |
| 32022 | .ilist |
| 32023 | LF not preceded by CR is treated as a line ending. |
| 32024 | .next |
| 32025 | CR is treated as a line ending; if it is immediately followed by LF, the LF |
| 32026 | is ignored. |
| 32027 | .next |
| 32028 | The sequence &"CR, dot, CR"& does not terminate an incoming SMTP message, |
| 32029 | nor a local message in the state where a line containing only a dot is a |
| 32030 | terminator. |
| 32031 | .next |
| 32032 | If a bare CR is encountered within a header line, an extra space is added after |
| 32033 | the line terminator so as not to end the header line. The reasoning behind this |
| 32034 | is that bare CRs in header lines are most likely either to be mistakes, or |
| 32035 | people trying to play silly games. |
| 32036 | .next |
| 32037 | If the first header line received in a message ends with CRLF, a subsequent |
| 32038 | bare LF in a header line is treated in the same way as a bare CR in a header |
| 32039 | line. |
| 32040 | .endlist |
| 32041 | |
| 32042 | |
| 32043 | |
| 32044 | |
| 32045 | |
| 32046 | .section "Unqualified addresses" "SECID218" |
| 32047 | .cindex "unqualified addresses" |
| 32048 | .cindex "address" "qualification" |
| 32049 | By default, Exim expects every envelope address it receives from an external |
| 32050 | host to be fully qualified. Unqualified addresses cause negative responses to |
| 32051 | SMTP commands. However, because SMTP is used as a means of transporting |
| 32052 | messages from MUAs running on personal workstations, there is sometimes a |
| 32053 | requirement to accept unqualified addresses from specific hosts or IP networks. |
| 32054 | |
| 32055 | Exim has two options that separately control which hosts may send unqualified |
| 32056 | sender or recipient addresses in SMTP commands, namely |
| 32057 | &%sender_unqualified_hosts%& and &%recipient_unqualified_hosts%&. In both |
| 32058 | cases, if an unqualified address is accepted, it is qualified by adding the |
| 32059 | value of &%qualify_domain%& or &%qualify_recipient%&, as appropriate. |
| 32060 | |
| 32061 | .oindex "&%qualify_domain%&" |
| 32062 | .oindex "&%qualify_recipient%&" |
| 32063 | Unqualified addresses in header lines are automatically qualified for messages |
| 32064 | that are locally originated, unless the &%-bnq%& option is given on the command |
| 32065 | line. For messages received over SMTP, unqualified addresses in header lines |
| 32066 | are qualified only if unqualified addresses are permitted in SMTP commands. In |
| 32067 | other words, such qualification is also controlled by |
| 32068 | &%sender_unqualified_hosts%& and &%recipient_unqualified_hosts%&, |
| 32069 | |
| 32070 | |
| 32071 | |
| 32072 | |
| 32073 | .section "The UUCP From line" "SECID219" |
| 32074 | .cindex "&""From""& line" |
| 32075 | .cindex "UUCP" "&""From""& line" |
| 32076 | .cindex "sender" "address" |
| 32077 | .oindex "&%uucp_from_pattern%&" |
| 32078 | .oindex "&%uucp_from_sender%&" |
| 32079 | .cindex "envelope sender" |
| 32080 | .cindex "Sendmail compatibility" "&""From""& line" |
| 32081 | Messages that have come from UUCP (and some other applications) often begin |
| 32082 | with a line containing the envelope sender and a timestamp, following the word |
| 32083 | &"From"&. Examples of two common formats are: |
| 32084 | .code |
| 32085 | From a.oakley@berlin.mus Fri Jan 5 12:35 GMT 1996 |
| 32086 | From f.butler@berlin.mus Fri, 7 Jan 97 14:00:00 GMT |
| 32087 | .endd |
| 32088 | This line precedes the RFC 2822 header lines. For compatibility with Sendmail, |
| 32089 | Exim recognizes such lines at the start of messages that are submitted to it |
| 32090 | via the command line (that is, on the standard input). It does not recognize |
| 32091 | such lines in incoming SMTP messages, unless the sending host matches |
| 32092 | &%ignore_fromline_hosts%& or the &%-bs%& option was used for a local message |
| 32093 | and &%ignore_fromline_local%& is set. The recognition is controlled by a |
| 32094 | regular expression that is defined by the &%uucp_from_pattern%& option, whose |
| 32095 | default value matches the two common cases shown above and puts the address |
| 32096 | that follows &"From"& into &$1$&. |
| 32097 | |
| 32098 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &""From ""& line handling" |
| 32099 | When the caller of Exim for a non-SMTP message that contains a &"From"& line is |
| 32100 | a trusted user, the message's sender address is constructed by expanding the |
| 32101 | contents of &%uucp_sender_address%&, whose default value is &"$1"&. This is |
| 32102 | then parsed as an RFC 2822 address. If there is no domain, the local part is |
| 32103 | qualified with &%qualify_domain%& unless it is the empty string. However, if |
| 32104 | the command line &%-f%& option is used, it overrides the &"From"& line. |
| 32105 | |
| 32106 | If the caller of Exim is not trusted, the &"From"& line is recognized, but the |
| 32107 | sender address is not changed. This is also the case for incoming SMTP messages |
| 32108 | that are permitted to contain &"From"& lines. |
| 32109 | |
| 32110 | Only one &"From"& line is recognized. If there is more than one, the second is |
| 32111 | treated as a data line that starts the body of the message, as it is not valid |
| 32112 | as a header line. This also happens if a &"From"& line is present in an |
| 32113 | incoming SMTP message from a source that is not permitted to send them. |
| 32114 | |
| 32115 | |
| 32116 | |
| 32117 | .section "Resent- header lines" "SECID220" |
| 32118 | .cindex "&%Resent-%& header lines" |
| 32119 | RFC 2822 makes provision for sets of header lines starting with the string |
| 32120 | &`Resent-`& to be added to a message when it is resent by the original |
| 32121 | recipient to somebody else. These headers are &'Resent-Date:'&, |
| 32122 | &'Resent-From:'&, &'Resent-Sender:'&, &'Resent-To:'&, &'Resent-Cc:'&, |
| 32123 | &'Resent-Bcc:'& and &'Resent-Message-ID:'&. The RFC says: |
| 32124 | |
| 32125 | .blockquote |
| 32126 | &'Resent fields are strictly informational. They MUST NOT be used in the normal |
| 32127 | processing of replies or other such automatic actions on messages.'& |
| 32128 | .endblockquote |
| 32129 | |
| 32130 | This leaves things a bit vague as far as other processing actions such as |
| 32131 | address rewriting are concerned. Exim treats &%Resent-%& header lines as |
| 32132 | follows: |
| 32133 | |
| 32134 | .ilist |
| 32135 | A &'Resent-From:'& line that just contains the login id of the submitting user |
| 32136 | is automatically rewritten in the same way as &'From:'& (see below). |
| 32137 | .next |
| 32138 | If there's a rewriting rule for a particular header line, it is also applied to |
| 32139 | &%Resent-%& header lines of the same type. For example, a rule that rewrites |
| 32140 | &'From:'& also rewrites &'Resent-From:'&. |
| 32141 | .next |
| 32142 | For local messages, if &'Sender:'& is removed on input, &'Resent-Sender:'& is |
| 32143 | also removed. |
| 32144 | .next |
| 32145 | For a locally-submitted message, |
| 32146 | if there are any &%Resent-%& header lines but no &'Resent-Date:'&, |
| 32147 | &'Resent-From:'&, or &'Resent-Message-Id:'&, they are added as necessary. It is |
| 32148 | the contents of &'Resent-Message-Id:'& (rather than &'Message-Id:'&) which are |
| 32149 | included in log lines in this case. |
| 32150 | .next |
| 32151 | The logic for adding &'Sender:'& is duplicated for &'Resent-Sender:'& when any |
| 32152 | &%Resent-%& header lines are present. |
| 32153 | .endlist |
| 32154 | |
| 32155 | |
| 32156 | |
| 32157 | |
| 32158 | .section "The Auto-Submitted: header line" "SECID221" |
| 32159 | Whenever Exim generates an autoreply, a bounce, or a delay warning message, it |
| 32160 | includes the header line: |
| 32161 | .code |
| 32162 | Auto-Submitted: auto-replied |
| 32163 | .endd |
| 32164 | |
| 32165 | .section "The Bcc: header line" "SECID222" |
| 32166 | .cindex "&'Bcc:'& header line" |
| 32167 | If Exim is called with the &%-t%& option, to take recipient addresses from a |
| 32168 | message's header, it removes any &'Bcc:'& header line that may exist (after |
| 32169 | extracting its addresses). If &%-t%& is not present on the command line, any |
| 32170 | existing &'Bcc:'& is not removed. |
| 32171 | |
| 32172 | |
| 32173 | .section "The Date: header line" "SECID223" |
| 32174 | .cindex "&'Date:'& header line" |
| 32175 | If a locally-generated or submission-mode message has no &'Date:'& header line, |
| 32176 | Exim adds one, using the current date and time, unless the |
| 32177 | &%suppress_local_fixups%& control has been specified. |
| 32178 | |
| 32179 | .section "The Delivery-date: header line" "SECID224" |
| 32180 | .cindex "&'Delivery-date:'& header line" |
| 32181 | .oindex "&%delivery_date_remove%&" |
| 32182 | &'Delivery-date:'& header lines are not part of the standard RFC 2822 header |
| 32183 | set. Exim can be configured to add them to the final delivery of messages. (See |
| 32184 | the generic &%delivery_date_add%& transport option.) They should not be present |
| 32185 | in messages in transit. If the &%delivery_date_remove%& configuration option is |
| 32186 | set (the default), Exim removes &'Delivery-date:'& header lines from incoming |
| 32187 | messages. |
| 32188 | |
| 32189 | |
| 32190 | .section "The Envelope-to: header line" "SECID225" |
| 32191 | .cindex "&'Envelope-to:'& header line" |
| 32192 | .oindex "&%envelope_to_remove%&" |
| 32193 | &'Envelope-to:'& header lines are not part of the standard RFC 2822 header set. |
| 32194 | Exim can be configured to add them to the final delivery of messages. (See the |
| 32195 | generic &%envelope_to_add%& transport option.) They should not be present in |
| 32196 | messages in transit. If the &%envelope_to_remove%& configuration option is set |
| 32197 | (the default), Exim removes &'Envelope-to:'& header lines from incoming |
| 32198 | messages. |
| 32199 | |
| 32200 | |
| 32201 | .section "The From: header line" "SECTthefrohea" |
| 32202 | .cindex "&'From:'& header line" |
| 32203 | .cindex "Sendmail compatibility" "&""From""& line" |
| 32204 | .cindex "message" "submission" |
| 32205 | .cindex "submission mode" |
| 32206 | If a submission-mode message does not contain a &'From:'& header line, Exim |
| 32207 | adds one if either of the following conditions is true: |
| 32208 | |
| 32209 | .ilist |
| 32210 | The envelope sender address is not empty (that is, this is not a bounce |
| 32211 | message). The added header line copies the envelope sender address. |
| 32212 | .next |
| 32213 | .vindex "&$authenticated_id$&" |
| 32214 | The SMTP session is authenticated and &$authenticated_id$& is not empty. |
| 32215 | .olist |
| 32216 | .vindex "&$qualify_domain$&" |
| 32217 | If no domain is specified by the submission control, the local part is |
| 32218 | &$authenticated_id$& and the domain is &$qualify_domain$&. |
| 32219 | .next |
| 32220 | If a non-empty domain is specified by the submission control, the local |
| 32221 | part is &$authenticated_id$&, and the domain is the specified domain. |
| 32222 | .next |
| 32223 | If an empty domain is specified by the submission control, |
| 32224 | &$authenticated_id$& is assumed to be the complete address. |
| 32225 | .endlist |
| 32226 | .endlist |
| 32227 | |
| 32228 | A non-empty envelope sender takes precedence. |
| 32229 | |
| 32230 | If a locally-generated incoming message does not contain a &'From:'& header |
| 32231 | line, and the &%suppress_local_fixups%& control is not set, Exim adds one |
| 32232 | containing the sender's address. The calling user's login name and full name |
| 32233 | are used to construct the address, as described in section &<<SECTconstr>>&. |
| 32234 | They are obtained from the password data by calling &[getpwuid()]& (but see the |
| 32235 | &%unknown_login%& configuration option). The address is qualified with |
| 32236 | &%qualify_domain%&. |
| 32237 | |
| 32238 | For compatibility with Sendmail, if an incoming, non-SMTP message has a |
| 32239 | &'From:'& header line containing just the unqualified login name of the calling |
| 32240 | user, this is replaced by an address containing the user's login name and full |
| 32241 | name as described in section &<<SECTconstr>>&. |
| 32242 | |
| 32243 | |
| 32244 | .section "The Message-ID: header line" "SECID226" |
| 32245 | .cindex "&'Message-ID:'& header line" |
| 32246 | .cindex "message" "submission" |
| 32247 | .oindex "&%message_id_header_text%&" |
| 32248 | If a locally-generated or submission-mode incoming message does not contain a |
| 32249 | &'Message-ID:'& or &'Resent-Message-ID:'& header line, and the |
| 32250 | &%suppress_local_fixups%& control is not set, Exim adds a suitable header line |
| 32251 | to the message. If there are any &'Resent-:'& headers in the message, it |
| 32252 | creates &'Resent-Message-ID:'&. The id is constructed from Exim's internal |
| 32253 | message id, preceded by the letter E to ensure it starts with a letter, and |
| 32254 | followed by @ and the primary host name. Additional information can be included |
| 32255 | in this header line by setting the &%message_id_header_text%& and/or |
| 32256 | &%message_id_header_domain%& options. |
| 32257 | |
| 32258 | |
| 32259 | .section "The Received: header line" "SECID227" |
| 32260 | .cindex "&'Received:'& header line" |
| 32261 | A &'Received:'& header line is added at the start of every message. The |
| 32262 | contents are defined by the &%received_header_text%& configuration option, and |
| 32263 | Exim automatically adds a semicolon and a timestamp to the configured string. |
| 32264 | |
| 32265 | The &'Received:'& header is generated as soon as the message's header lines |
| 32266 | have been received. At this stage, the timestamp in the &'Received:'& header |
| 32267 | line is the time that the message started to be received. This is the value |
| 32268 | that is seen by the DATA ACL and by the &[local_scan()]& function. |
| 32269 | |
| 32270 | Once a message is accepted, the timestamp in the &'Received:'& header line is |
| 32271 | changed to the time of acceptance, which is (apart from a small delay while the |
| 32272 | -H spool file is written) the earliest time at which delivery could start. |
| 32273 | |
| 32274 | |
| 32275 | .section "The References: header line" "SECID228" |
| 32276 | .cindex "&'References:'& header line" |
| 32277 | Messages created by the &(autoreply)& transport include a &'References:'& |
| 32278 | header line. This is constructed according to the rules that are described in |
| 32279 | section 3.64 of RFC 2822 (which states that replies should contain such a |
| 32280 | header line), and section 3.14 of RFC 3834 (which states that automatic |
| 32281 | responses are not different in this respect). However, because some mail |
| 32282 | processing software does not cope well with very long header lines, no more |
| 32283 | than 12 message IDs are copied from the &'References:'& header line in the |
| 32284 | incoming message. If there are more than 12, the first one and then the final |
| 32285 | 11 are copied, before adding the message ID of the incoming message. |
| 32286 | |
| 32287 | |
| 32288 | |
| 32289 | .section "The Return-path: header line" "SECID229" |
| 32290 | .cindex "&'Return-path:'& header line" |
| 32291 | .oindex "&%return_path_remove%&" |
| 32292 | &'Return-path:'& header lines are defined as something an MTA may insert when |
| 32293 | it does the final delivery of messages. (See the generic &%return_path_add%& |
| 32294 | transport option.) Therefore, they should not be present in messages in |
| 32295 | transit. If the &%return_path_remove%& configuration option is set (the |
| 32296 | default), Exim removes &'Return-path:'& header lines from incoming messages. |
| 32297 | |
| 32298 | |
| 32299 | |
| 32300 | .section "The Sender: header line" "SECTthesenhea" |
| 32301 | .cindex "&'Sender:'& header line" |
| 32302 | .cindex "message" "submission" |
| 32303 | For a locally-originated message from an untrusted user, Exim may remove an |
| 32304 | existing &'Sender:'& header line, and it may add a new one. You can modify |
| 32305 | these actions by setting the &%local_sender_retain%& option true, the |
| 32306 | &%local_from_check%& option false, or by using the &%suppress_local_fixups%& |
| 32307 | control setting. |
| 32308 | |
| 32309 | When a local message is received from an untrusted user and |
| 32310 | &%local_from_check%& is true (the default), and the &%suppress_local_fixups%& |
| 32311 | control has not been set, a check is made to see if the address given in the |
| 32312 | &'From:'& header line is the correct (local) sender of the message. The address |
| 32313 | that is expected has the login name as the local part and the value of |
| 32314 | &%qualify_domain%& as the domain. Prefixes and suffixes for the local part can |
| 32315 | be permitted by setting &%local_from_prefix%& and &%local_from_suffix%& |
| 32316 | appropriately. If &'From:'& does not contain the correct sender, a &'Sender:'& |
| 32317 | line is added to the message. |
| 32318 | |
| 32319 | If you set &%local_from_check%& false, this checking does not occur. However, |
| 32320 | the removal of an existing &'Sender:'& line still happens, unless you also set |
| 32321 | &%local_sender_retain%& to be true. It is not possible to set both of these |
| 32322 | options true at the same time. |
| 32323 | |
| 32324 | .cindex "submission mode" |
| 32325 | By default, no processing of &'Sender:'& header lines is done for messages |
| 32326 | received over TCP/IP or for messages submitted by trusted users. However, when |
| 32327 | a message is received over TCP/IP in submission mode, and &%sender_retain%& is |
| 32328 | not specified on the submission control, the following processing takes place: |
| 32329 | |
| 32330 | .vindex "&$authenticated_id$&" |
| 32331 | First, any existing &'Sender:'& lines are removed. Then, if the SMTP session is |
| 32332 | authenticated, and &$authenticated_id$& is not empty, a sender address is |
| 32333 | created as follows: |
| 32334 | |
| 32335 | .ilist |
| 32336 | .vindex "&$qualify_domain$&" |
| 32337 | If no domain is specified by the submission control, the local part is |
| 32338 | &$authenticated_id$& and the domain is &$qualify_domain$&. |
| 32339 | .next |
| 32340 | If a non-empty domain is specified by the submission control, the local part |
| 32341 | is &$authenticated_id$&, and the domain is the specified domain. |
| 32342 | .next |
| 32343 | If an empty domain is specified by the submission control, |
| 32344 | &$authenticated_id$& is assumed to be the complete address. |
| 32345 | .endlist |
| 32346 | |
| 32347 | This address is compared with the address in the &'From:'& header line. If they |
| 32348 | are different, a &'Sender:'& header line containing the created address is |
| 32349 | added. Prefixes and suffixes for the local part in &'From:'& can be permitted |
| 32350 | by setting &%local_from_prefix%& and &%local_from_suffix%& appropriately. |
| 32351 | |
| 32352 | .cindex "return path" "created from &'Sender:'&" |
| 32353 | &*Note*&: Whenever a &'Sender:'& header line is created, the return path for |
| 32354 | the message (the envelope sender address) is changed to be the same address, |
| 32355 | except in the case of submission mode when &%sender_retain%& is specified. |
| 32356 | |
| 32357 | |
| 32358 | |
| 32359 | .section "Adding and removing header lines in routers and transports" &&& |
| 32360 | "SECTheadersaddrem" |
| 32361 | .cindex "header lines" "adding; in router or transport" |
| 32362 | .cindex "header lines" "removing; in router or transport" |
| 32363 | When a message is delivered, the addition and removal of header lines can be |
| 32364 | specified in a system filter, or on any of the routers and transports that |
| 32365 | process the message. Section &<<SECTaddremheasys>>& contains details about |
| 32366 | modifying headers in a system filter. Header lines can also be added in an ACL |
| 32367 | as a message is received (see section &<<SECTaddheadacl>>&). |
| 32368 | |
| 32369 | In contrast to what happens in a system filter, header modifications that are |
| 32370 | specified on routers and transports apply only to the particular recipient |
| 32371 | addresses that are being processed by those routers and transports. These |
| 32372 | changes do not actually take place until a copy of the message is being |
| 32373 | transported. Therefore, they do not affect the basic set of header lines, and |
| 32374 | they do not affect the values of the variables that refer to header lines. |
| 32375 | |
| 32376 | &*Note*&: In particular, this means that any expansions in the configuration of |
| 32377 | the transport cannot refer to the modified header lines, because such |
| 32378 | expansions all occur before the message is actually transported. |
| 32379 | |
| 32380 | For both routers and transports, the argument of a &%headers_add%& |
| 32381 | option must be in the form of one or more RFC 2822 header lines, separated by |
| 32382 | newlines (coded as &"\n"&). For example: |
| 32383 | .code |
| 32384 | headers_add = X-added-header: added by $primary_hostname\n\ |
| 32385 | X-added-second: another added header line |
| 32386 | .endd |
| 32387 | Exim does not check the syntax of these added header lines. |
| 32388 | |
| 32389 | Multiple &%headers_add%& options for a single router or transport can be |
| 32390 | specified; the values will append to a single list of header lines. |
| 32391 | Each header-line is separately expanded. |
| 32392 | |
| 32393 | The argument of a &%headers_remove%& option must consist of a colon-separated |
| 32394 | list of header names. This is confusing, because header names themselves are |
| 32395 | often terminated by colons. In this case, the colons are the list separators, |
| 32396 | not part of the names. For example: |
| 32397 | .code |
| 32398 | headers_remove = return-receipt-to:acknowledge-to |
| 32399 | .endd |
| 32400 | |
| 32401 | Multiple &%headers_remove%& options for a single router or transport can be |
| 32402 | specified; the arguments will append to a single header-names list. |
| 32403 | Each item is separately expanded. |
| 32404 | |
| 32405 | When &%headers_add%& or &%headers_remove%& is specified on a router, |
| 32406 | items are expanded at routing time, |
| 32407 | and then associated with all addresses that are |
| 32408 | accepted by that router, and also with any new addresses that it generates. If |
| 32409 | an address passes through several routers as a result of aliasing or |
| 32410 | forwarding, the changes are cumulative. |
| 32411 | |
| 32412 | .oindex "&%unseen%&" |
| 32413 | However, this does not apply to multiple routers that result from the use of |
| 32414 | the &%unseen%& option. Any header modifications that were specified by the |
| 32415 | &"unseen"& router or its predecessors apply only to the &"unseen"& delivery. |
| 32416 | |
| 32417 | Addresses that end up with different &%headers_add%& or &%headers_remove%& |
| 32418 | settings cannot be delivered together in a batch, so a transport is always |
| 32419 | dealing with a set of addresses that have the same header-processing |
| 32420 | requirements. |
| 32421 | |
| 32422 | The transport starts by writing the original set of header lines that arrived |
| 32423 | with the message, possibly modified by the system filter. As it writes out |
| 32424 | these lines, it consults the list of header names that were attached to the |
| 32425 | recipient address(es) by &%headers_remove%& options in routers, and it also |
| 32426 | consults the transport's own &%headers_remove%& option. Header lines whose |
| 32427 | names are on either of these lists are not written out. If there are multiple |
| 32428 | instances of any listed header, they are all skipped. |
| 32429 | |
| 32430 | After the remaining original header lines have been written, new header |
| 32431 | lines that were specified by routers' &%headers_add%& options are written, in |
| 32432 | the order in which they were attached to the address. These are followed by any |
| 32433 | header lines specified by the transport's &%headers_add%& option. |
| 32434 | |
| 32435 | This way of handling header line modifications in routers and transports has |
| 32436 | the following consequences: |
| 32437 | |
| 32438 | .ilist |
| 32439 | The original set of header lines, possibly modified by the system filter, |
| 32440 | remains &"visible"&, in the sense that the &$header_$&&'xxx'& variables refer |
| 32441 | to it, at all times. |
| 32442 | .next |
| 32443 | Header lines that are added by a router's |
| 32444 | &%headers_add%& option are not accessible by means of the &$header_$&&'xxx'& |
| 32445 | expansion syntax in subsequent routers or the transport. |
| 32446 | .next |
| 32447 | Conversely, header lines that are specified for removal by &%headers_remove%& |
| 32448 | in a router remain visible to subsequent routers and the transport. |
| 32449 | .next |
| 32450 | Headers added to an address by &%headers_add%& in a router cannot be removed by |
| 32451 | a later router or by a transport. |
| 32452 | .next |
| 32453 | An added header can refer to the contents of an original header that is to be |
| 32454 | removed, even it has the same name as the added header. For example: |
| 32455 | .code |
| 32456 | headers_remove = subject |
| 32457 | headers_add = Subject: new subject (was: $h_subject:) |
| 32458 | .endd |
| 32459 | .endlist |
| 32460 | |
| 32461 | &*Warning*&: The &%headers_add%& and &%headers_remove%& options cannot be used |
| 32462 | for a &(redirect)& router that has the &%one_time%& option set. |
| 32463 | |
| 32464 | |
| 32465 | |
| 32466 | |
| 32467 | |
| 32468 | .section "Constructed addresses" "SECTconstr" |
| 32469 | .cindex "address" "constructed" |
| 32470 | .cindex "constructed address" |
| 32471 | When Exim constructs a sender address for a locally-generated message, it uses |
| 32472 | the form |
| 32473 | .display |
| 32474 | <&'user name'&>&~&~<&'login'&&`@`&&'qualify_domain'&> |
| 32475 | .endd |
| 32476 | For example: |
| 32477 | .code |
| 32478 | Zaphod Beeblebrox <zaphod@end.univ.example> |
| 32479 | .endd |
| 32480 | The user name is obtained from the &%-F%& command line option if set, or |
| 32481 | otherwise by looking up the calling user by &[getpwuid()]& and extracting the |
| 32482 | &"gecos"& field from the password entry. If the &"gecos"& field contains an |
| 32483 | ampersand character, this is replaced by the login name with the first letter |
| 32484 | upper cased, as is conventional in a number of operating systems. See the |
| 32485 | &%gecos_name%& option for a way to tailor the handling of the &"gecos"& field. |
| 32486 | The &%unknown_username%& option can be used to specify user names in cases when |
| 32487 | there is no password file entry. |
| 32488 | |
| 32489 | .cindex "RFC 2047" |
| 32490 | In all cases, the user name is made to conform to RFC 2822 by quoting all or |
| 32491 | parts of it if necessary. In addition, if it contains any non-printing |
| 32492 | characters, it is encoded as described in RFC 2047, which defines a way of |
| 32493 | including non-ASCII characters in header lines. The value of the |
| 32494 | &%headers_charset%& option specifies the name of the encoding that is used (the |
| 32495 | characters are assumed to be in this encoding). The setting of |
| 32496 | &%print_topbitchars%& controls whether characters with the top bit set (that |
| 32497 | is, with codes greater than 127) count as printing characters or not. |
| 32498 | |
| 32499 | |
| 32500 | |
| 32501 | .section "Case of local parts" "SECID230" |
| 32502 | .cindex "case of local parts" |
| 32503 | .cindex "local part" "case of" |
| 32504 | RFC 2822 states that the case of letters in the local parts of addresses cannot |
| 32505 | be assumed to be non-significant. Exim preserves the case of local parts of |
| 32506 | addresses, but by default it uses a lower-cased form when it is routing, |
| 32507 | because on most Unix systems, usernames are in lower case and case-insensitive |
| 32508 | routing is required. However, any particular router can be made to use the |
| 32509 | original case for local parts by setting the &%caseful_local_part%& generic |
| 32510 | router option. |
| 32511 | |
| 32512 | .cindex "mixed-case login names" |
| 32513 | If you must have mixed-case user names on your system, the best way to proceed, |
| 32514 | assuming you want case-independent handling of incoming email, is to set up |
| 32515 | your first router to convert incoming local parts in your domains to the |
| 32516 | correct case by means of a file lookup. For example: |
| 32517 | .code |
| 32518 | correct_case: |
| 32519 | driver = redirect |
| 32520 | domains = +local_domains |
| 32521 | data = ${lookup{$local_part}cdb\ |
| 32522 | {/etc/usercased.cdb}{$value}fail}\ |
| 32523 | @$domain |
| 32524 | .endd |
| 32525 | For this router, the local part is forced to lower case by the default action |
| 32526 | (&%caseful_local_part%& is not set). The lower-cased local part is used to look |
| 32527 | up a new local part in the correct case. If you then set &%caseful_local_part%& |
| 32528 | on any subsequent routers which process your domains, they will operate on |
| 32529 | local parts with the correct case in a case-sensitive manner. |
| 32530 | |
| 32531 | |
| 32532 | |
| 32533 | .section "Dots in local parts" "SECID231" |
| 32534 | .cindex "dot" "in local part" |
| 32535 | .cindex "local part" "dots in" |
| 32536 | RFC 2822 forbids empty components in local parts. That is, an unquoted local |
| 32537 | part may not begin or end with a dot, nor have two consecutive dots in the |
| 32538 | middle. However, it seems that many MTAs do not enforce this, so Exim permits |
| 32539 | empty components for compatibility. |
| 32540 | |
| 32541 | |
| 32542 | |
| 32543 | .section "Rewriting addresses" "SECID232" |
| 32544 | .cindex "rewriting" "addresses" |
| 32545 | Rewriting of sender and recipient addresses, and addresses in headers, can |
| 32546 | happen automatically, or as the result of configuration options, as described |
| 32547 | in chapter &<<CHAPrewrite>>&. The headers that may be affected by this are |
| 32548 | &'Bcc:'&, &'Cc:'&, &'From:'&, &'Reply-To:'&, &'Sender:'&, and &'To:'&. |
| 32549 | |
| 32550 | Automatic rewriting includes qualification, as mentioned above. The other case |
| 32551 | in which it can happen is when an incomplete non-local domain is given. The |
| 32552 | routing process may cause this to be expanded into the full domain name. For |
| 32553 | example, a header such as |
| 32554 | .code |
| 32555 | To: hare@teaparty |
| 32556 | .endd |
| 32557 | might get rewritten as |
| 32558 | .code |
| 32559 | To: hare@teaparty.wonderland.fict.example |
| 32560 | .endd |
| 32561 | Rewriting as a result of routing is the one kind of message processing that |
| 32562 | does not happen at input time, as it cannot be done until the address has |
| 32563 | been routed. |
| 32564 | |
| 32565 | Strictly, one should not do &'any'& deliveries of a message until all its |
| 32566 | addresses have been routed, in case any of the headers get changed as a |
| 32567 | result of routing. However, doing this in practice would hold up many |
| 32568 | deliveries for unreasonable amounts of time, just because one address could not |
| 32569 | immediately be routed. Exim therefore does not delay other deliveries when |
| 32570 | routing of one or more addresses is deferred. |
| 32571 | .ecindex IIDmesproc |
| 32572 | |
| 32573 | |
| 32574 | |
| 32575 | . //////////////////////////////////////////////////////////////////////////// |
| 32576 | . //////////////////////////////////////////////////////////////////////////// |
| 32577 | |
| 32578 | .chapter "SMTP processing" "CHAPSMTP" |
| 32579 | .scindex IIDsmtpproc1 "SMTP" "processing details" |
| 32580 | .scindex IIDsmtpproc2 "LMTP" "processing details" |
| 32581 | Exim supports a number of different ways of using the SMTP protocol, and its |
| 32582 | LMTP variant, which is an interactive protocol for transferring messages into a |
| 32583 | closed mail store application. This chapter contains details of how SMTP is |
| 32584 | processed. For incoming mail, the following are available: |
| 32585 | |
| 32586 | .ilist |
| 32587 | SMTP over TCP/IP (Exim daemon or &'inetd'&); |
| 32588 | .next |
| 32589 | SMTP over the standard input and output (the &%-bs%& option); |
| 32590 | .next |
| 32591 | Batched SMTP on the standard input (the &%-bS%& option). |
| 32592 | .endlist |
| 32593 | |
| 32594 | For mail delivery, the following are available: |
| 32595 | |
| 32596 | .ilist |
| 32597 | SMTP over TCP/IP (the &(smtp)& transport); |
| 32598 | .next |
| 32599 | LMTP over TCP/IP (the &(smtp)& transport with the &%protocol%& option set to |
| 32600 | &"lmtp"&); |
| 32601 | .next |
| 32602 | LMTP over a pipe to a process running in the local host (the &(lmtp)& |
| 32603 | transport); |
| 32604 | .next |
| 32605 | Batched SMTP to a file or pipe (the &(appendfile)& and &(pipe)& transports with |
| 32606 | the &%use_bsmtp%& option set). |
| 32607 | .endlist |
| 32608 | |
| 32609 | &'Batched SMTP'& is the name for a process in which batches of messages are |
| 32610 | stored in or read from files (or pipes), in a format in which SMTP commands are |
| 32611 | used to contain the envelope information. |
| 32612 | |
| 32613 | |
| 32614 | |
| 32615 | .section "Outgoing SMTP and LMTP over TCP/IP" "SECToutSMTPTCP" |
| 32616 | .cindex "SMTP" "outgoing over TCP/IP" |
| 32617 | .cindex "outgoing SMTP over TCP/IP" |
| 32618 | .cindex "LMTP" "over TCP/IP" |
| 32619 | .cindex "outgoing LMTP over TCP/IP" |
| 32620 | .cindex "EHLO" |
| 32621 | .cindex "HELO" |
| 32622 | .cindex "SIZE option on MAIL command" |
| 32623 | Outgoing SMTP and LMTP over TCP/IP is implemented by the &(smtp)& transport. |
| 32624 | The &%protocol%& option selects which protocol is to be used, but the actual |
| 32625 | processing is the same in both cases. |
| 32626 | |
| 32627 | If, in response to its EHLO command, Exim is told that the SIZE |
| 32628 | parameter is supported, it adds SIZE=<&'n'&> to each subsequent MAIL |
| 32629 | command. The value of <&'n'&> is the message size plus the value of the |
| 32630 | &%size_addition%& option (default 1024) to allow for additions to the message |
| 32631 | such as per-transport header lines, or changes made in a |
| 32632 | .cindex "transport" "filter" |
| 32633 | .cindex "filter" "transport filter" |
| 32634 | transport filter. If &%size_addition%& is set negative, the use of SIZE is |
| 32635 | suppressed. |
| 32636 | |
| 32637 | If the remote server advertises support for PIPELINING, Exim uses the |
| 32638 | pipelining extension to SMTP (RFC 2197) to reduce the number of TCP/IP packets |
| 32639 | required for the transaction. |
| 32640 | |
| 32641 | If the remote server advertises support for the STARTTLS command, and Exim |
| 32642 | was built to support TLS encryption, it tries to start a TLS session unless the |
| 32643 | server matches &%hosts_avoid_tls%&. See chapter &<<CHAPTLS>>& for more details. |
| 32644 | Either a match in that or &%hosts_verify_avoid_tls%& apply when the transport |
| 32645 | is called for verification. |
| 32646 | |
| 32647 | If the remote server advertises support for the AUTH command, Exim scans |
| 32648 | the authenticators configuration for any suitable client settings, as described |
| 32649 | in chapter &<<CHAPSMTPAUTH>>&. |
| 32650 | |
| 32651 | .cindex "carriage return" |
| 32652 | .cindex "linefeed" |
| 32653 | Responses from the remote host are supposed to be terminated by CR followed by |
| 32654 | LF. However, there are known to be hosts that do not send CR characters, so in |
| 32655 | order to be able to interwork with such hosts, Exim treats LF on its own as a |
| 32656 | line terminator. |
| 32657 | |
| 32658 | If a message contains a number of different addresses, all those with the same |
| 32659 | characteristics (for example, the same envelope sender) that resolve to the |
| 32660 | same set of hosts, in the same order, are sent in a single SMTP transaction, |
| 32661 | even if they are for different domains, unless there are more than the setting |
| 32662 | of the &%max_rcpt%&s option in the &(smtp)& transport allows, in which case |
| 32663 | they are split into groups containing no more than &%max_rcpt%&s addresses |
| 32664 | each. If &%remote_max_parallel%& is greater than one, such groups may be sent |
| 32665 | in parallel sessions. The order of hosts with identical MX values is not |
| 32666 | significant when checking whether addresses can be batched in this way. |
| 32667 | |
| 32668 | When the &(smtp)& transport suffers a temporary failure that is not |
| 32669 | message-related, Exim updates its transport-specific database, which contains |
| 32670 | records indexed by host name that remember which messages are waiting for each |
| 32671 | particular host. It also updates the retry database with new retry times. |
| 32672 | |
| 32673 | .cindex "hints database" "retry keys" |
| 32674 | Exim's retry hints are based on host name plus IP address, so if one address of |
| 32675 | a multi-homed host is broken, it will soon be skipped most of the time. |
| 32676 | See the next section for more detail about error handling. |
| 32677 | |
| 32678 | .cindex "SMTP" "passed connection" |
| 32679 | .cindex "SMTP" "batching over TCP/IP" |
| 32680 | When a message is successfully delivered over a TCP/IP SMTP connection, Exim |
| 32681 | looks in the hints database for the transport to see if there are any queued |
| 32682 | messages waiting for the host to which it is connected. If it finds one, it |
| 32683 | creates a new Exim process using the &%-MC%& option (which can only be used by |
| 32684 | a process running as root or the Exim user) and passes the TCP/IP socket to it |
| 32685 | so that it can deliver another message using the same socket. The new process |
| 32686 | does only those deliveries that are routed to the connected host, and may in |
| 32687 | turn pass the socket on to a third process, and so on. |
| 32688 | |
| 32689 | The &%connection_max_messages%& option of the &(smtp)& transport can be used to |
| 32690 | limit the number of messages sent down a single TCP/IP connection. |
| 32691 | |
| 32692 | .cindex "asterisk" "after IP address" |
| 32693 | The second and subsequent messages delivered down an existing connection are |
| 32694 | identified in the main log by the addition of an asterisk after the closing |
| 32695 | square bracket of the IP address. |
| 32696 | |
| 32697 | |
| 32698 | |
| 32699 | |
| 32700 | .section "Errors in outgoing SMTP" "SECToutSMTPerr" |
| 32701 | .cindex "error" "in outgoing SMTP" |
| 32702 | .cindex "SMTP" "errors in outgoing" |
| 32703 | .cindex "host" "error" |
| 32704 | Three different kinds of error are recognized for outgoing SMTP: host errors, |
| 32705 | message errors, and recipient errors. |
| 32706 | |
| 32707 | .vlist |
| 32708 | .vitem "&*Host errors*&" |
| 32709 | A host error is not associated with a particular message or with a |
| 32710 | particular recipient of a message. The host errors are: |
| 32711 | |
| 32712 | .ilist |
| 32713 | Connection refused or timed out, |
| 32714 | .next |
| 32715 | Any error response code on connection, |
| 32716 | .next |
| 32717 | Any error response code to EHLO or HELO, |
| 32718 | .next |
| 32719 | Loss of connection at any time, except after &"."&, |
| 32720 | .next |
| 32721 | I/O errors at any time, |
| 32722 | .next |
| 32723 | Timeouts during the session, other than in response to MAIL, RCPT or |
| 32724 | the &"."& at the end of the data. |
| 32725 | .endlist ilist |
| 32726 | |
| 32727 | For a host error, a permanent error response on connection, or in response to |
| 32728 | EHLO, causes all addresses routed to the host to be failed. Any other host |
| 32729 | error causes all addresses to be deferred, and retry data to be created for the |
| 32730 | host. It is not tried again, for any message, until its retry time arrives. If |
| 32731 | the current set of addresses are not all delivered in this run (to some |
| 32732 | alternative host), the message is added to the list of those waiting for this |
| 32733 | host, so if it is still undelivered when a subsequent successful delivery is |
| 32734 | made to the host, it will be sent down the same SMTP connection. |
| 32735 | |
| 32736 | .vitem "&*Message errors*&" |
| 32737 | .cindex "message" "error" |
| 32738 | A message error is associated with a particular message when sent to a |
| 32739 | particular host, but not with a particular recipient of the message. The |
| 32740 | message errors are: |
| 32741 | |
| 32742 | .ilist |
| 32743 | Any error response code to MAIL, DATA, or the &"."& that terminates |
| 32744 | the data, |
| 32745 | .next |
| 32746 | Timeout after MAIL, |
| 32747 | .next |
| 32748 | Timeout or loss of connection after the &"."& that terminates the data. A |
| 32749 | timeout after the DATA command itself is treated as a host error, as is loss of |
| 32750 | connection at any other time. |
| 32751 | .endlist ilist |
| 32752 | |
| 32753 | For a message error, a permanent error response (5&'xx'&) causes all addresses |
| 32754 | to be failed, and a delivery error report to be returned to the sender. A |
| 32755 | temporary error response (4&'xx'&), or one of the timeouts, causes all |
| 32756 | addresses to be deferred. Retry data is not created for the host, but instead, |
| 32757 | a retry record for the combination of host plus message id is created. The |
| 32758 | message is not added to the list of those waiting for this host. This ensures |
| 32759 | that the failing message will not be sent to this host again until the retry |
| 32760 | time arrives. However, other messages that are routed to the host are not |
| 32761 | affected, so if it is some property of the message that is causing the error, |
| 32762 | it will not stop the delivery of other mail. |
| 32763 | |
| 32764 | If the remote host specified support for the SIZE parameter in its response |
| 32765 | to EHLO, Exim adds SIZE=&'nnn'& to the MAIL command, so an |
| 32766 | over-large message will cause a message error because the error arrives as a |
| 32767 | response to MAIL. |
| 32768 | |
| 32769 | .vitem "&*Recipient errors*&" |
| 32770 | .cindex "recipient" "error" |
| 32771 | A recipient error is associated with a particular recipient of a message. The |
| 32772 | recipient errors are: |
| 32773 | |
| 32774 | .ilist |
| 32775 | Any error response to RCPT, |
| 32776 | .next |
| 32777 | Timeout after RCPT. |
| 32778 | .endlist |
| 32779 | |
| 32780 | For a recipient error, a permanent error response (5&'xx'&) causes the |
| 32781 | recipient address to be failed, and a bounce message to be returned to the |
| 32782 | sender. A temporary error response (4&'xx'&) or a timeout causes the failing |
| 32783 | address to be deferred, and routing retry data to be created for it. This is |
| 32784 | used to delay processing of the address in subsequent queue runs, until its |
| 32785 | routing retry time arrives. This applies to all messages, but because it |
| 32786 | operates only in queue runs, one attempt will be made to deliver a new message |
| 32787 | to the failing address before the delay starts to operate. This ensures that, |
| 32788 | if the failure is really related to the message rather than the recipient |
| 32789 | (&"message too big for this recipient"& is a possible example), other messages |
| 32790 | have a chance of getting delivered. If a delivery to the address does succeed, |
| 32791 | the retry information gets cleared, so all stuck messages get tried again, and |
| 32792 | the retry clock is reset. |
| 32793 | |
| 32794 | The message is not added to the list of those waiting for this host. Use of the |
| 32795 | host for other messages is unaffected, and except in the case of a timeout, |
| 32796 | other recipients are processed independently, and may be successfully delivered |
| 32797 | in the current SMTP session. After a timeout it is of course impossible to |
| 32798 | proceed with the session, so all addresses get deferred. However, those other |
| 32799 | than the one that failed do not suffer any subsequent retry delays. Therefore, |
| 32800 | if one recipient is causing trouble, the others have a chance of getting |
| 32801 | through when a subsequent delivery attempt occurs before the failing |
| 32802 | recipient's retry time. |
| 32803 | .endlist |
| 32804 | |
| 32805 | In all cases, if there are other hosts (or IP addresses) available for the |
| 32806 | current set of addresses (for example, from multiple MX records), they are |
| 32807 | tried in this run for any undelivered addresses, subject of course to their |
| 32808 | own retry data. In other words, recipient error retry data does not take effect |
| 32809 | until the next delivery attempt. |
| 32810 | |
| 32811 | Some hosts have been observed to give temporary error responses to every |
| 32812 | MAIL command at certain times (&"insufficient space"& has been seen). It |
| 32813 | would be nice if such circumstances could be recognized, and defer data for the |
| 32814 | host itself created, but this is not possible within the current Exim design. |
| 32815 | What actually happens is that retry data for every (host, message) combination |
| 32816 | is created. |
| 32817 | |
| 32818 | The reason that timeouts after MAIL and RCPT are treated specially is that |
| 32819 | these can sometimes arise as a result of the remote host's verification |
| 32820 | procedures. Exim makes this assumption, and treats them as if a temporary error |
| 32821 | response had been received. A timeout after &"."& is treated specially because |
| 32822 | it is known that some broken implementations fail to recognize the end of the |
| 32823 | message if the last character of the last line is a binary zero. Thus, it is |
| 32824 | helpful to treat this case as a message error. |
| 32825 | |
| 32826 | Timeouts at other times are treated as host errors, assuming a problem with the |
| 32827 | host, or the connection to it. If a timeout after MAIL, RCPT, |
| 32828 | or &"."& is really a connection problem, the assumption is that at the next try |
| 32829 | the timeout is likely to occur at some other point in the dialogue, causing it |
| 32830 | then to be treated as a host error. |
| 32831 | |
| 32832 | There is experimental evidence that some MTAs drop the connection after the |
| 32833 | terminating &"."& if they do not like the contents of the message for some |
| 32834 | reason, in contravention of the RFC, which indicates that a 5&'xx'& response |
| 32835 | should be given. That is why Exim treats this case as a message rather than a |
| 32836 | host error, in order not to delay other messages to the same host. |
| 32837 | |
| 32838 | |
| 32839 | |
| 32840 | |
| 32841 | .section "Incoming SMTP messages over TCP/IP" "SECID233" |
| 32842 | .cindex "SMTP" "incoming over TCP/IP" |
| 32843 | .cindex "incoming SMTP over TCP/IP" |
| 32844 | .cindex "inetd" |
| 32845 | .cindex "daemon" |
| 32846 | Incoming SMTP messages can be accepted in one of two ways: by running a |
| 32847 | listening daemon, or by using &'inetd'&. In the latter case, the entry in |
| 32848 | &_/etc/inetd.conf_& should be like this: |
| 32849 | .code |
| 32850 | smtp stream tcp nowait exim /opt/exim/bin/exim in.exim -bs |
| 32851 | .endd |
| 32852 | Exim distinguishes between this case and the case of a locally running user |
| 32853 | agent using the &%-bs%& option by checking whether or not the standard input is |
| 32854 | a socket. When it is, either the port must be privileged (less than 1024), or |
| 32855 | the caller must be root or the Exim user. If any other user passes a socket |
| 32856 | with an unprivileged port number, Exim prints a message on the standard error |
| 32857 | stream and exits with an error code. |
| 32858 | |
| 32859 | By default, Exim does not make a log entry when a remote host connects or |
| 32860 | disconnects (either via the daemon or &'inetd'&), unless the disconnection is |
| 32861 | unexpected. It can be made to write such log entries by setting the |
| 32862 | &%smtp_connection%& log selector. |
| 32863 | |
| 32864 | .cindex "carriage return" |
| 32865 | .cindex "linefeed" |
| 32866 | Commands from the remote host are supposed to be terminated by CR followed by |
| 32867 | LF. However, there are known to be hosts that do not send CR characters. In |
| 32868 | order to be able to interwork with such hosts, Exim treats LF on its own as a |
| 32869 | line terminator. |
| 32870 | Furthermore, because common code is used for receiving messages from all |
| 32871 | sources, a CR on its own is also interpreted as a line terminator. However, the |
| 32872 | sequence &"CR, dot, CR"& does not terminate incoming SMTP data. |
| 32873 | |
| 32874 | .cindex "EHLO" "invalid data" |
| 32875 | .cindex "HELO" "invalid data" |
| 32876 | One area that sometimes gives rise to problems concerns the EHLO or |
| 32877 | HELO commands. Some clients send syntactically invalid versions of these |
| 32878 | commands, which Exim rejects by default. (This is nothing to do with verifying |
| 32879 | the data that is sent, so &%helo_verify_hosts%& is not relevant.) You can tell |
| 32880 | Exim not to apply a syntax check by setting &%helo_accept_junk_hosts%& to |
| 32881 | match the broken hosts that send invalid commands. |
| 32882 | |
| 32883 | .cindex "SIZE option on MAIL command" |
| 32884 | .cindex "MAIL" "SIZE option" |
| 32885 | The amount of disk space available is checked whenever SIZE is received on |
| 32886 | a MAIL command, independently of whether &%message_size_limit%& or |
| 32887 | &%check_spool_space%& is configured, unless &%smtp_check_spool_space%& is set |
| 32888 | false. A temporary error is given if there is not enough space. If |
| 32889 | &%check_spool_space%& is set, the check is for that amount of space plus the |
| 32890 | value given with SIZE, that is, it checks that the addition of the incoming |
| 32891 | message will not reduce the space below the threshold. |
| 32892 | |
| 32893 | When a message is successfully received, Exim includes the local message id in |
| 32894 | its response to the final &"."& that terminates the data. If the remote host |
| 32895 | logs this text it can help with tracing what has happened to a message. |
| 32896 | |
| 32897 | The Exim daemon can limit the number of simultaneous incoming connections it is |
| 32898 | prepared to handle (see the &%smtp_accept_max%& option). It can also limit the |
| 32899 | number of simultaneous incoming connections from a single remote host (see the |
| 32900 | &%smtp_accept_max_per_host%& option). Additional connection attempts are |
| 32901 | rejected using the SMTP temporary error code 421. |
| 32902 | |
| 32903 | The Exim daemon does not rely on the SIGCHLD signal to detect when a |
| 32904 | subprocess has finished, as this can get lost at busy times. Instead, it looks |
| 32905 | for completed subprocesses every time it wakes up. Provided there are other |
| 32906 | things happening (new incoming calls, starts of queue runs), completed |
| 32907 | processes will be noticed and tidied away. On very quiet systems you may |
| 32908 | sometimes see a &"defunct"& Exim process hanging about. This is not a problem; |
| 32909 | it will be noticed when the daemon next wakes up. |
| 32910 | |
| 32911 | When running as a daemon, Exim can reserve some SMTP slots for specific hosts, |
| 32912 | and can also be set up to reject SMTP calls from non-reserved hosts at times of |
| 32913 | high system load &-- for details see the &%smtp_accept_reserve%&, |
| 32914 | &%smtp_load_reserve%&, and &%smtp_reserve_hosts%& options. The load check |
| 32915 | applies in both the daemon and &'inetd'& cases. |
| 32916 | |
| 32917 | Exim normally starts a delivery process for each message received, though this |
| 32918 | can be varied by means of the &%-odq%& command line option and the |
| 32919 | &%queue_only%&, &%queue_only_file%&, and &%queue_only_load%& options. The |
| 32920 | number of simultaneously running delivery processes started in this way from |
| 32921 | SMTP input can be limited by the &%smtp_accept_queue%& and |
| 32922 | &%smtp_accept_queue_per_connection%& options. When either limit is reached, |
| 32923 | subsequently received messages are just put on the input queue without starting |
| 32924 | a delivery process. |
| 32925 | |
| 32926 | The controls that involve counts of incoming SMTP calls (&%smtp_accept_max%&, |
| 32927 | &%smtp_accept_queue%&, &%smtp_accept_reserve%&) are not available when Exim is |
| 32928 | started up from the &'inetd'& daemon, because in that case each connection is |
| 32929 | handled by an entirely independent Exim process. Control by load average is, |
| 32930 | however, available with &'inetd'&. |
| 32931 | |
| 32932 | Exim can be configured to verify addresses in incoming SMTP commands as they |
| 32933 | are received. See chapter &<<CHAPACL>>& for details. It can also be configured |
| 32934 | to rewrite addresses at this time &-- before any syntax checking is done. See |
| 32935 | section &<<SECTrewriteS>>&. |
| 32936 | |
| 32937 | Exim can also be configured to limit the rate at which a client host submits |
| 32938 | MAIL and RCPT commands in a single SMTP session. See the |
| 32939 | &%smtp_ratelimit_hosts%& option. |
| 32940 | |
| 32941 | |
| 32942 | |
| 32943 | .section "Unrecognized SMTP commands" "SECID234" |
| 32944 | .cindex "SMTP" "unrecognized commands" |
| 32945 | If Exim receives more than &%smtp_max_unknown_commands%& unrecognized SMTP |
| 32946 | commands during a single SMTP connection, it drops the connection after sending |
| 32947 | the error response to the last command. The default value for |
| 32948 | &%smtp_max_unknown_commands%& is 3. This is a defence against some kinds of |
| 32949 | abuse that subvert web servers into making connections to SMTP ports; in these |
| 32950 | circumstances, a number of non-SMTP lines are sent first. |
| 32951 | |
| 32952 | |
| 32953 | .section "Syntax and protocol errors in SMTP commands" "SECID235" |
| 32954 | .cindex "SMTP" "syntax errors" |
| 32955 | .cindex "SMTP" "protocol errors" |
| 32956 | A syntax error is detected if an SMTP command is recognized, but there is |
| 32957 | something syntactically wrong with its data, for example, a malformed email |
| 32958 | address in a RCPT command. Protocol errors include invalid command |
| 32959 | sequencing such as RCPT before MAIL. If Exim receives more than |
| 32960 | &%smtp_max_synprot_errors%& such commands during a single SMTP connection, it |
| 32961 | drops the connection after sending the error response to the last command. The |
| 32962 | default value for &%smtp_max_synprot_errors%& is 3. This is a defence against |
| 32963 | broken clients that loop sending bad commands (yes, it has been seen). |
| 32964 | |
| 32965 | |
| 32966 | |
| 32967 | .section "Use of non-mail SMTP commands" "SECID236" |
| 32968 | .cindex "SMTP" "non-mail commands" |
| 32969 | The &"non-mail"& SMTP commands are those other than MAIL, RCPT, and |
| 32970 | DATA. Exim counts such commands, and drops the connection if there are too |
| 32971 | many of them in a single SMTP session. This action catches some |
| 32972 | denial-of-service attempts and things like repeated failing AUTHs, or a mad |
| 32973 | client looping sending EHLO. The global option &%smtp_accept_max_nonmail%& |
| 32974 | defines what &"too many"& means. Its default value is 10. |
| 32975 | |
| 32976 | When a new message is expected, one occurrence of RSET is not counted. This |
| 32977 | allows a client to send one RSET between messages (this is not necessary, |
| 32978 | but some clients do it). Exim also allows one uncounted occurrence of HELO |
| 32979 | or EHLO, and one occurrence of STARTTLS between messages. After |
| 32980 | starting up a TLS session, another EHLO is expected, and so it too is not |
| 32981 | counted. |
| 32982 | |
| 32983 | The first occurrence of AUTH in a connection, or immediately following |
| 32984 | STARTTLS is also not counted. Otherwise, all commands other than MAIL, |
| 32985 | RCPT, DATA, and QUIT are counted. |
| 32986 | |
| 32987 | You can control which hosts are subject to the limit set by |
| 32988 | &%smtp_accept_max_nonmail%& by setting |
| 32989 | &%smtp_accept_max_nonmail_hosts%&. The default value is &`*`&, which makes |
| 32990 | the limit apply to all hosts. This option means that you can exclude any |
| 32991 | specific badly-behaved hosts that you have to live with. |
| 32992 | |
| 32993 | |
| 32994 | |
| 32995 | |
| 32996 | .section "The VRFY and EXPN commands" "SECID237" |
| 32997 | When Exim receives a VRFY or EXPN command on a TCP/IP connection, it |
| 32998 | runs the ACL specified by &%acl_smtp_vrfy%& or &%acl_smtp_expn%& (as |
| 32999 | appropriate) in order to decide whether the command should be accepted or not. |
| 33000 | If no ACL is defined, the command is rejected. |
| 33001 | |
| 33002 | .cindex "VRFY" "processing" |
| 33003 | When VRFY is accepted, it runs exactly the same code as when Exim is |
| 33004 | called with the &%-bv%& option. |
| 33005 | |
| 33006 | .cindex "EXPN" "processing" |
| 33007 | When EXPN is accepted, a single-level expansion of the address is done. |
| 33008 | EXPN is treated as an &"address test"& (similar to the &%-bt%& option) rather |
| 33009 | than a verification (the &%-bv%& option). If an unqualified local part is given |
| 33010 | as the argument to EXPN, it is qualified with &%qualify_domain%&. Rejections |
| 33011 | of VRFY and EXPN commands are logged on the main and reject logs, and |
| 33012 | VRFY verification failures are logged on the main log for consistency with |
| 33013 | RCPT failures. |
| 33014 | |
| 33015 | |
| 33016 | |
| 33017 | .section "The ETRN command" "SECTETRN" |
| 33018 | .cindex "ETRN" "processing" |
| 33019 | RFC 1985 describes an SMTP command called ETRN that is designed to |
| 33020 | overcome the security problems of the TURN command (which has fallen into |
| 33021 | disuse). When Exim receives an ETRN command on a TCP/IP connection, it runs |
| 33022 | the ACL specified by &%acl_smtp_etrn%& in order to decide whether the command |
| 33023 | should be accepted or not. If no ACL is defined, the command is rejected. |
| 33024 | |
| 33025 | The ETRN command is concerned with &"releasing"& messages that are awaiting |
| 33026 | delivery to certain hosts. As Exim does not organize its message queue by host, |
| 33027 | the only form of ETRN that is supported by default is the one where the |
| 33028 | text starts with the &"#"& prefix, in which case the remainder of the text is |
| 33029 | specific to the SMTP server. A valid ETRN command causes a run of Exim with |
| 33030 | the &%-R%& option to happen, with the remainder of the ETRN text as its |
| 33031 | argument. For example, |
| 33032 | .code |
| 33033 | ETRN #brigadoon |
| 33034 | .endd |
| 33035 | runs the command |
| 33036 | .code |
| 33037 | exim -R brigadoon |
| 33038 | .endd |
| 33039 | which causes a delivery attempt on all messages with undelivered addresses |
| 33040 | containing the text &"brigadoon"&. When &%smtp_etrn_serialize%& is set (the |
| 33041 | default), Exim prevents the simultaneous execution of more than one queue run |
| 33042 | for the same argument string as a result of an ETRN command. This stops |
| 33043 | a misbehaving client from starting more than one queue runner at once. |
| 33044 | |
| 33045 | .cindex "hints database" "ETRN serialization" |
| 33046 | Exim implements the serialization by means of a hints database in which a |
| 33047 | record is written whenever a process is started by ETRN, and deleted when |
| 33048 | the process completes. However, Exim does not keep the SMTP session waiting for |
| 33049 | the ETRN process to complete. Once ETRN is accepted, the client is sent |
| 33050 | a &"success"& return code. Obviously there is scope for hints records to get |
| 33051 | left lying around if there is a system or program crash. To guard against this, |
| 33052 | Exim ignores any records that are more than six hours old. |
| 33053 | |
| 33054 | .oindex "&%smtp_etrn_command%&" |
| 33055 | For more control over what ETRN does, the &%smtp_etrn_command%& option can |
| 33056 | used. This specifies a command that is run whenever ETRN is received, |
| 33057 | whatever the form of its argument. For |
| 33058 | example: |
| 33059 | .code |
| 33060 | smtp_etrn_command = /etc/etrn_command $domain \ |
| 33061 | $sender_host_address |
| 33062 | .endd |
| 33063 | .vindex "&$domain$&" |
| 33064 | The string is split up into arguments which are independently expanded. The |
| 33065 | expansion variable &$domain$& is set to the argument of the ETRN command, |
| 33066 | and no syntax checking is done on the contents of this argument. Exim does not |
| 33067 | wait for the command to complete, so its status code is not checked. Exim runs |
| 33068 | under its own uid and gid when receiving incoming SMTP, so it is not possible |
| 33069 | for it to change them before running the command. |
| 33070 | |
| 33071 | |
| 33072 | |
| 33073 | .section "Incoming local SMTP" "SECID238" |
| 33074 | .cindex "SMTP" "local incoming" |
| 33075 | Some user agents use SMTP to pass messages to their local MTA using the |
| 33076 | standard input and output, as opposed to passing the envelope on the command |
| 33077 | line and writing the message to the standard input. This is supported by the |
| 33078 | &%-bs%& option. This form of SMTP is handled in the same way as incoming |
| 33079 | messages over TCP/IP (including the use of ACLs), except that the envelope |
| 33080 | sender given in a MAIL command is ignored unless the caller is trusted. In |
| 33081 | an ACL you can detect this form of SMTP input by testing for an empty host |
| 33082 | identification. It is common to have this as the first line in the ACL that |
| 33083 | runs for RCPT commands: |
| 33084 | .code |
| 33085 | accept hosts = : |
| 33086 | .endd |
| 33087 | This accepts SMTP messages from local processes without doing any other tests. |
| 33088 | |
| 33089 | |
| 33090 | |
| 33091 | .section "Outgoing batched SMTP" "SECTbatchSMTP" |
| 33092 | .cindex "SMTP" "batched outgoing" |
| 33093 | .cindex "batched SMTP output" |
| 33094 | Both the &(appendfile)& and &(pipe)& transports can be used for handling |
| 33095 | batched SMTP. Each has an option called &%use_bsmtp%& which causes messages to |
| 33096 | be output in BSMTP format. No SMTP responses are possible for this form of |
| 33097 | delivery. All it is doing is using SMTP commands as a way of transmitting the |
| 33098 | envelope along with the message. |
| 33099 | |
| 33100 | The message is written to the file or pipe preceded by the SMTP commands |
| 33101 | MAIL and RCPT, and followed by a line containing a single dot. Lines in |
| 33102 | the message that start with a dot have an extra dot added. The SMTP command |
| 33103 | HELO is not normally used. If it is required, the &%message_prefix%& option |
| 33104 | can be used to specify it. |
| 33105 | |
| 33106 | Because &(appendfile)& and &(pipe)& are both local transports, they accept only |
| 33107 | one recipient address at a time by default. However, you can arrange for them |
| 33108 | to handle several addresses at once by setting the &%batch_max%& option. When |
| 33109 | this is done for BSMTP, messages may contain multiple RCPT commands. See |
| 33110 | chapter &<<CHAPbatching>>& for more details. |
| 33111 | |
| 33112 | .vindex "&$host$&" |
| 33113 | When one or more addresses are routed to a BSMTP transport by a router that |
| 33114 | sets up a host list, the name of the first host on the list is available to the |
| 33115 | transport in the variable &$host$&. Here is an example of such a transport and |
| 33116 | router: |
| 33117 | .code |
| 33118 | begin routers |
| 33119 | route_append: |
| 33120 | driver = manualroute |
| 33121 | transport = smtp_appendfile |
| 33122 | route_list = domain.example batch.host.example |
| 33123 | |
| 33124 | begin transports |
| 33125 | smtp_appendfile: |
| 33126 | driver = appendfile |
| 33127 | directory = /var/bsmtp/$host |
| 33128 | batch_max = 1000 |
| 33129 | use_bsmtp |
| 33130 | user = exim |
| 33131 | .endd |
| 33132 | This causes messages addressed to &'domain.example'& to be written in BSMTP |
| 33133 | format to &_/var/bsmtp/batch.host.example_&, with only a single copy of each |
| 33134 | message (unless there are more than 1000 recipients). |
| 33135 | |
| 33136 | |
| 33137 | |
| 33138 | .section "Incoming batched SMTP" "SECTincomingbatchedSMTP" |
| 33139 | .cindex "SMTP" "batched incoming" |
| 33140 | .cindex "batched SMTP input" |
| 33141 | The &%-bS%& command line option causes Exim to accept one or more messages by |
| 33142 | reading SMTP on the standard input, but to generate no responses. If the caller |
| 33143 | is trusted, the senders in the MAIL commands are believed; otherwise the |
| 33144 | sender is always the caller of Exim. Unqualified senders and receivers are not |
| 33145 | rejected (there seems little point) but instead just get qualified. HELO |
| 33146 | and EHLO act as RSET; VRFY, EXPN, ETRN and HELP, act |
| 33147 | as NOOP; QUIT quits. |
| 33148 | |
| 33149 | Minimal policy checking is done for BSMTP input. Only the non-SMTP |
| 33150 | ACL is run in the same way as for non-SMTP local input. |
| 33151 | |
| 33152 | If an error is detected while reading a message, including a missing &"."& at |
| 33153 | the end, Exim gives up immediately. It writes details of the error to the |
| 33154 | standard output in a stylized way that the calling program should be able to |
| 33155 | make some use of automatically, for example: |
| 33156 | .code |
| 33157 | 554 Unexpected end of file |
| 33158 | Transaction started in line 10 |
| 33159 | Error detected in line 14 |
| 33160 | .endd |
| 33161 | It writes a more verbose version, for human consumption, to the standard error |
| 33162 | file, for example: |
| 33163 | .code |
| 33164 | An error was detected while processing a file of BSMTP input. |
| 33165 | The error message was: |
| 33166 | |
| 33167 | 501 '>' missing at end of address |
| 33168 | |
| 33169 | The SMTP transaction started in line 10. |
| 33170 | The error was detected in line 12. |
| 33171 | The SMTP command at fault was: |
| 33172 | |
| 33173 | rcpt to:<malformed@in.com.plete |
| 33174 | |
| 33175 | 1 previous message was successfully processed. |
| 33176 | The rest of the batch was abandoned. |
| 33177 | .endd |
| 33178 | The return code from Exim is zero only if there were no errors. It is 1 if some |
| 33179 | messages were accepted before an error was detected, and 2 if no messages were |
| 33180 | accepted. |
| 33181 | .ecindex IIDsmtpproc1 |
| 33182 | .ecindex IIDsmtpproc2 |
| 33183 | |
| 33184 | |
| 33185 | |
| 33186 | . //////////////////////////////////////////////////////////////////////////// |
| 33187 | . //////////////////////////////////////////////////////////////////////////// |
| 33188 | |
| 33189 | .chapter "Customizing bounce and warning messages" "CHAPemsgcust" &&& |
| 33190 | "Customizing messages" |
| 33191 | When a message fails to be delivered, or remains on the queue for more than a |
| 33192 | configured amount of time, Exim sends a message to the original sender, or |
| 33193 | to an alternative configured address. The text of these messages is built into |
| 33194 | the code of Exim, but it is possible to change it, either by adding a single |
| 33195 | string, or by replacing each of the paragraphs by text supplied in a file. |
| 33196 | |
| 33197 | The &'From:'& and &'To:'& header lines are automatically generated; you can |
| 33198 | cause a &'Reply-To:'& line to be added by setting the &%errors_reply_to%& |
| 33199 | option. Exim also adds the line |
| 33200 | .code |
| 33201 | Auto-Submitted: auto-generated |
| 33202 | .endd |
| 33203 | to all warning and bounce messages, |
| 33204 | |
| 33205 | |
| 33206 | .section "Customizing bounce messages" "SECID239" |
| 33207 | .cindex "customizing" "bounce message" |
| 33208 | .cindex "bounce message" "customizing" |
| 33209 | If &%bounce_message_text%& is set, its contents are included in the default |
| 33210 | message immediately after &"This message was created automatically by mail |
| 33211 | delivery software."& The string is not expanded. It is not used if |
| 33212 | &%bounce_message_file%& is set. |
| 33213 | |
| 33214 | When &%bounce_message_file%& is set, it must point to a template file for |
| 33215 | constructing error messages. The file consists of a series of text items, |
| 33216 | separated by lines consisting of exactly four asterisks. If the file cannot be |
| 33217 | opened, default text is used and a message is written to the main and panic |
| 33218 | logs. If any text item in the file is empty, default text is used for that |
| 33219 | item. |
| 33220 | |
| 33221 | .vindex "&$bounce_recipient$&" |
| 33222 | .vindex "&$bounce_return_size_limit$&" |
| 33223 | Each item of text that is read from the file is expanded, and there are two |
| 33224 | expansion variables which can be of use here: &$bounce_recipient$& is set to |
| 33225 | the recipient of an error message while it is being created, and |
| 33226 | &$bounce_return_size_limit$& contains the value of the &%return_size_limit%& |
| 33227 | option, rounded to a whole number. |
| 33228 | |
| 33229 | The items must appear in the file in the following order: |
| 33230 | |
| 33231 | .ilist |
| 33232 | The first item is included in the headers, and should include at least a |
| 33233 | &'Subject:'& header. Exim does not check the syntax of these headers. |
| 33234 | .next |
| 33235 | The second item forms the start of the error message. After it, Exim lists the |
| 33236 | failing addresses with their error messages. |
| 33237 | .next |
| 33238 | The third item is used to introduce any text from pipe transports that is to be |
| 33239 | returned to the sender. It is omitted if there is no such text. |
| 33240 | .next |
| 33241 | The fourth item is used to introduce the copy of the message that is returned |
| 33242 | as part of the error report. |
| 33243 | .next |
| 33244 | The fifth item is added after the fourth one if the returned message is |
| 33245 | truncated because it is bigger than &%return_size_limit%&. |
| 33246 | .next |
| 33247 | The sixth item is added after the copy of the original message. |
| 33248 | .endlist |
| 33249 | |
| 33250 | The default state (&%bounce_message_file%& unset) is equivalent to the |
| 33251 | following file, in which the sixth item is empty. The &'Subject:'& and some |
| 33252 | other lines have been split in order to fit them on the page: |
| 33253 | .code |
| 33254 | Subject: Mail delivery failed |
| 33255 | ${if eq{$sender_address}{$bounce_recipient} |
| 33256 | {: returning message to sender}} |
| 33257 | **** |
| 33258 | This message was created automatically by mail delivery software. |
| 33259 | |
| 33260 | A message ${if eq{$sender_address}{$bounce_recipient} |
| 33261 | {that you sent }{sent by |
| 33262 | |
| 33263 | <$sender_address> |
| 33264 | |
| 33265 | }}could not be delivered to all of its recipients. |
| 33266 | This is a permanent error. The following address(es) failed: |
| 33267 | **** |
| 33268 | The following text was generated during the delivery attempt(s): |
| 33269 | **** |
| 33270 | ------ This is a copy of the message, including all the headers. |
| 33271 | ------ |
| 33272 | **** |
| 33273 | ------ The body of the message is $message_size characters long; |
| 33274 | only the first |
| 33275 | ------ $bounce_return_size_limit or so are included here. |
| 33276 | **** |
| 33277 | .endd |
| 33278 | .section "Customizing warning messages" "SECTcustwarn" |
| 33279 | .cindex "customizing" "warning message" |
| 33280 | .cindex "warning of delay" "customizing the message" |
| 33281 | The option &%warn_message_file%& can be pointed at a template file for use when |
| 33282 | warnings about message delays are created. In this case there are only three |
| 33283 | text sections: |
| 33284 | |
| 33285 | .ilist |
| 33286 | The first item is included in the headers, and should include at least a |
| 33287 | &'Subject:'& header. Exim does not check the syntax of these headers. |
| 33288 | .next |
| 33289 | The second item forms the start of the warning message. After it, Exim lists |
| 33290 | the delayed addresses. |
| 33291 | .next |
| 33292 | The third item then ends the message. |
| 33293 | .endlist |
| 33294 | |
| 33295 | The default state is equivalent to the following file, except that some lines |
| 33296 | have been split here, in order to fit them on the page: |
| 33297 | .code |
| 33298 | Subject: Warning: message $message_exim_id delayed |
| 33299 | $warn_message_delay |
| 33300 | **** |
| 33301 | This message was created automatically by mail delivery software. |
| 33302 | |
| 33303 | A message ${if eq{$sender_address}{$warn_message_recipients} |
| 33304 | {that you sent }{sent by |
| 33305 | |
| 33306 | <$sender_address> |
| 33307 | |
| 33308 | }}has not been delivered to all of its recipients after |
| 33309 | more than $warn_message_delay on the queue on $primary_hostname. |
| 33310 | |
| 33311 | The message identifier is: $message_exim_id |
| 33312 | The subject of the message is: $h_subject |
| 33313 | The date of the message is: $h_date |
| 33314 | |
| 33315 | The following address(es) have not yet been delivered: |
| 33316 | **** |
| 33317 | No action is required on your part. Delivery attempts will |
| 33318 | continue for some time, and this warning may be repeated at |
| 33319 | intervals if the message remains undelivered. Eventually the |
| 33320 | mail delivery software will give up, and when that happens, |
| 33321 | the message will be returned to you. |
| 33322 | .endd |
| 33323 | .vindex "&$warn_message_delay$&" |
| 33324 | .vindex "&$warn_message_recipients$&" |
| 33325 | However, in the default state the subject and date lines are omitted if no |
| 33326 | appropriate headers exist. During the expansion of this file, |
| 33327 | &$warn_message_delay$& is set to the delay time in one of the forms &"<&'n'&> |
| 33328 | minutes"& or &"<&'n'&> hours"&, and &$warn_message_recipients$& contains a list |
| 33329 | of recipients for the warning message. There may be more than one if there are |
| 33330 | multiple addresses with different &%errors_to%& settings on the routers that |
| 33331 | handled them. |
| 33332 | |
| 33333 | |
| 33334 | |
| 33335 | |
| 33336 | . //////////////////////////////////////////////////////////////////////////// |
| 33337 | . //////////////////////////////////////////////////////////////////////////// |
| 33338 | |
| 33339 | .chapter "Some common configuration settings" "CHAPcomconreq" |
| 33340 | This chapter discusses some configuration settings that seem to be fairly |
| 33341 | common. More examples and discussion can be found in the Exim book. |
| 33342 | |
| 33343 | |
| 33344 | |
| 33345 | .section "Sending mail to a smart host" "SECID240" |
| 33346 | .cindex "smart host" "example router" |
| 33347 | If you want to send all mail for non-local domains to a &"smart host"&, you |
| 33348 | should replace the default &(dnslookup)& router with a router which does the |
| 33349 | routing explicitly: |
| 33350 | .code |
| 33351 | send_to_smart_host: |
| 33352 | driver = manualroute |
| 33353 | route_list = !+local_domains smart.host.name |
| 33354 | transport = remote_smtp |
| 33355 | .endd |
| 33356 | You can use the smart host's IP address instead of the name if you wish. |
| 33357 | If you are using Exim only to submit messages to a smart host, and not for |
| 33358 | receiving incoming messages, you can arrange for it to do the submission |
| 33359 | synchronously by setting the &%mua_wrapper%& option (see chapter |
| 33360 | &<<CHAPnonqueueing>>&). |
| 33361 | |
| 33362 | |
| 33363 | |
| 33364 | |
| 33365 | .section "Using Exim to handle mailing lists" "SECTmailinglists" |
| 33366 | .cindex "mailing lists" |
| 33367 | Exim can be used to run simple mailing lists, but for large and/or complicated |
| 33368 | requirements, the use of additional specialized mailing list software such as |
| 33369 | Majordomo or Mailman is recommended. |
| 33370 | |
| 33371 | The &(redirect)& router can be used to handle mailing lists where each list |
| 33372 | is maintained in a separate file, which can therefore be managed by an |
| 33373 | independent manager. The &%domains%& router option can be used to run these |
| 33374 | lists in a separate domain from normal mail. For example: |
| 33375 | .code |
| 33376 | lists: |
| 33377 | driver = redirect |
| 33378 | domains = lists.example |
| 33379 | file = /usr/lists/$local_part |
| 33380 | forbid_pipe |
| 33381 | forbid_file |
| 33382 | errors_to = $local_part-request@lists.example |
| 33383 | no_more |
| 33384 | .endd |
| 33385 | This router is skipped for domains other than &'lists.example'&. For addresses |
| 33386 | in that domain, it looks for a file that matches the local part. If there is no |
| 33387 | such file, the router declines, but because &%no_more%& is set, no subsequent |
| 33388 | routers are tried, and so the whole delivery fails. |
| 33389 | |
| 33390 | The &%forbid_pipe%& and &%forbid_file%& options prevent a local part from being |
| 33391 | expanded into a file name or a pipe delivery, which is usually inappropriate in |
| 33392 | a mailing list. |
| 33393 | |
| 33394 | .oindex "&%errors_to%&" |
| 33395 | The &%errors_to%& option specifies that any delivery errors caused by addresses |
| 33396 | taken from a mailing list are to be sent to the given address rather than the |
| 33397 | original sender of the message. However, before acting on this, Exim verifies |
| 33398 | the error address, and ignores it if verification fails. |
| 33399 | |
| 33400 | For example, using the configuration above, mail sent to |
| 33401 | &'dicts@lists.example'& is passed on to those addresses contained in |
| 33402 | &_/usr/lists/dicts_&, with error reports directed to |
| 33403 | &'dicts-request@lists.example'&, provided that this address can be verified. |
| 33404 | There could be a file called &_/usr/lists/dicts-request_& containing |
| 33405 | the address(es) of this particular list's manager(s), but other approaches, |
| 33406 | such as setting up an earlier router (possibly using the &%local_part_prefix%& |
| 33407 | or &%local_part_suffix%& options) to handle addresses of the form |
| 33408 | &%owner-%&&'xxx'& or &%xxx-%&&'request'&, are also possible. |
| 33409 | |
| 33410 | |
| 33411 | |
| 33412 | .section "Syntax errors in mailing lists" "SECID241" |
| 33413 | .cindex "mailing lists" "syntax errors in" |
| 33414 | If an entry in redirection data contains a syntax error, Exim normally defers |
| 33415 | delivery of the original address. That means that a syntax error in a mailing |
| 33416 | list holds up all deliveries to the list. This may not be appropriate when a |
| 33417 | list is being maintained automatically from data supplied by users, and the |
| 33418 | addresses are not rigorously checked. |
| 33419 | |
| 33420 | If the &%skip_syntax_errors%& option is set, the &(redirect)& router just skips |
| 33421 | entries that fail to parse, noting the incident in the log. If in addition |
| 33422 | &%syntax_errors_to%& is set to a verifiable address, a message is sent to it |
| 33423 | whenever a broken address is skipped. It is usually appropriate to set |
| 33424 | &%syntax_errors_to%& to the same address as &%errors_to%&. |
| 33425 | |
| 33426 | |
| 33427 | |
| 33428 | .section "Re-expansion of mailing lists" "SECID242" |
| 33429 | .cindex "mailing lists" "re-expansion of" |
| 33430 | Exim remembers every individual address to which a message has been delivered, |
| 33431 | in order to avoid duplication, but it normally stores only the original |
| 33432 | recipient addresses with a message. If all the deliveries to a mailing list |
| 33433 | cannot be done at the first attempt, the mailing list is re-expanded when the |
| 33434 | delivery is next tried. This means that alterations to the list are taken into |
| 33435 | account at each delivery attempt, so addresses that have been added to |
| 33436 | the list since the message arrived will therefore receive a copy of the |
| 33437 | message, even though it pre-dates their subscription. |
| 33438 | |
| 33439 | If this behaviour is felt to be undesirable, the &%one_time%& option can be set |
| 33440 | on the &(redirect)& router. If this is done, any addresses generated by the |
| 33441 | router that fail to deliver at the first attempt are added to the message as |
| 33442 | &"top level"& addresses, and the parent address that generated them is marked |
| 33443 | &"delivered"&. Thus, expansion of the mailing list does not happen again at the |
| 33444 | subsequent delivery attempts. The disadvantage of this is that if any of the |
| 33445 | failing addresses are incorrect, correcting them in the file has no effect on |
| 33446 | pre-existing messages. |
| 33447 | |
| 33448 | The original top-level address is remembered with each of the generated |
| 33449 | addresses, and is output in any log messages. However, any intermediate parent |
| 33450 | addresses are not recorded. This makes a difference to the log only if the |
| 33451 | &%all_parents%& selector is set, but for mailing lists there is normally only |
| 33452 | one level of expansion anyway. |
| 33453 | |
| 33454 | |
| 33455 | |
| 33456 | .section "Closed mailing lists" "SECID243" |
| 33457 | .cindex "mailing lists" "closed" |
| 33458 | The examples so far have assumed open mailing lists, to which anybody may |
| 33459 | send mail. It is also possible to set up closed lists, where mail is accepted |
| 33460 | from specified senders only. This is done by making use of the generic |
| 33461 | &%senders%& option to restrict the router that handles the list. |
| 33462 | |
| 33463 | The following example uses the same file as a list of recipients and as a list |
| 33464 | of permitted senders. It requires three routers: |
| 33465 | .code |
| 33466 | lists_request: |
| 33467 | driver = redirect |
| 33468 | domains = lists.example |
| 33469 | local_part_suffix = -request |
| 33470 | file = /usr/lists/$local_part$local_part_suffix |
| 33471 | no_more |
| 33472 | |
| 33473 | lists_post: |
| 33474 | driver = redirect |
| 33475 | domains = lists.example |
| 33476 | senders = ${if exists {/usr/lists/$local_part}\ |
| 33477 | {lsearch;/usr/lists/$local_part}{*}} |
| 33478 | file = /usr/lists/$local_part |
| 33479 | forbid_pipe |
| 33480 | forbid_file |
| 33481 | errors_to = $local_part-request@lists.example |
| 33482 | no_more |
| 33483 | |
| 33484 | lists_closed: |
| 33485 | driver = redirect |
| 33486 | domains = lists.example |
| 33487 | allow_fail |
| 33488 | data = :fail: $local_part@lists.example is a closed mailing list |
| 33489 | .endd |
| 33490 | All three routers have the same &%domains%& setting, so for any other domains, |
| 33491 | they are all skipped. The first router runs only if the local part ends in |
| 33492 | &%-request%&. It handles messages to the list manager(s) by means of an open |
| 33493 | mailing list. |
| 33494 | |
| 33495 | The second router runs only if the &%senders%& precondition is satisfied. It |
| 33496 | checks for the existence of a list that corresponds to the local part, and then |
| 33497 | checks that the sender is on the list by means of a linear search. It is |
| 33498 | necessary to check for the existence of the file before trying to search it, |
| 33499 | because otherwise Exim thinks there is a configuration error. If the file does |
| 33500 | not exist, the expansion of &%senders%& is *, which matches all senders. This |
| 33501 | means that the router runs, but because there is no list, declines, and |
| 33502 | &%no_more%& ensures that no further routers are run. The address fails with an |
| 33503 | &"unrouteable address"& error. |
| 33504 | |
| 33505 | The third router runs only if the second router is skipped, which happens when |
| 33506 | a mailing list exists, but the sender is not on it. This router forcibly fails |
| 33507 | the address, giving a suitable error message. |
| 33508 | |
| 33509 | |
| 33510 | |
| 33511 | |
| 33512 | .section "Variable Envelope Return Paths (VERP)" "SECTverp" |
| 33513 | .cindex "VERP" |
| 33514 | .cindex "Variable Envelope Return Paths" |
| 33515 | .cindex "envelope sender" |
| 33516 | Variable Envelope Return Paths &-- see &url(http://cr.yp.to/proto/verp.txt) &-- |
| 33517 | are a way of helping mailing list administrators discover which subscription |
| 33518 | address is the cause of a particular delivery failure. The idea is to encode |
| 33519 | the original recipient address in the outgoing envelope sender address, so that |
| 33520 | if the message is forwarded by another host and then subsequently bounces, the |
| 33521 | original recipient can be extracted from the recipient address of the bounce. |
| 33522 | |
| 33523 | .oindex &%errors_to%& |
| 33524 | .oindex &%return_path%& |
| 33525 | Envelope sender addresses can be modified by Exim using two different |
| 33526 | facilities: the &%errors_to%& option on a router (as shown in previous mailing |
| 33527 | list examples), or the &%return_path%& option on a transport. The second of |
| 33528 | these is effective only if the message is successfully delivered to another |
| 33529 | host; it is not used for errors detected on the local host (see the description |
| 33530 | of &%return_path%& in chapter &<<CHAPtransportgeneric>>&). Here is an example |
| 33531 | of the use of &%return_path%& to implement VERP on an &(smtp)& transport: |
| 33532 | .code |
| 33533 | verp_smtp: |
| 33534 | driver = smtp |
| 33535 | max_rcpt = 1 |
| 33536 | return_path = \ |
| 33537 | ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\ |
| 33538 | {$1-request+$local_part=$domain@your.dom.example}fail} |
| 33539 | .endd |
| 33540 | This has the effect of rewriting the return path (envelope sender) on outgoing |
| 33541 | SMTP messages, if the local part of the original return path ends in |
| 33542 | &"-request"&, and the domain is &'your.dom.example'&. The rewriting inserts the |
| 33543 | local part and domain of the recipient into the return path. Suppose, for |
| 33544 | example, that a message whose return path has been set to |
| 33545 | &'somelist-request@your.dom.example'& is sent to |
| 33546 | &'subscriber@other.dom.example'&. In the transport, the return path is |
| 33547 | rewritten as |
| 33548 | .code |
| 33549 | somelist-request+subscriber=other.dom.example@your.dom.example |
| 33550 | .endd |
| 33551 | .vindex "&$local_part$&" |
| 33552 | For this to work, you must tell Exim to send multiple copies of messages that |
| 33553 | have more than one recipient, so that each copy has just one recipient. This is |
| 33554 | achieved by setting &%max_rcpt%& to 1. Without this, a single copy of a message |
| 33555 | might be sent to several different recipients in the same domain, in which case |
| 33556 | &$local_part$& is not available in the transport, because it is not unique. |
| 33557 | |
| 33558 | Unless your host is doing nothing but mailing list deliveries, you should |
| 33559 | probably use a separate transport for the VERP deliveries, so as not to use |
| 33560 | extra resources in making one-per-recipient copies for other deliveries. This |
| 33561 | can easily be done by expanding the &%transport%& option in the router: |
| 33562 | .code |
| 33563 | dnslookup: |
| 33564 | driver = dnslookup |
| 33565 | domains = ! +local_domains |
| 33566 | transport = \ |
| 33567 | ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\ |
| 33568 | {verp_smtp}{remote_smtp}} |
| 33569 | no_more |
| 33570 | .endd |
| 33571 | If you want to change the return path using &%errors_to%& in a router instead |
| 33572 | of using &%return_path%& in the transport, you need to set &%errors_to%& on all |
| 33573 | routers that handle mailing list addresses. This will ensure that all delivery |
| 33574 | errors, including those detected on the local host, are sent to the VERP |
| 33575 | address. |
| 33576 | |
| 33577 | On a host that does no local deliveries and has no manual routing, only the |
| 33578 | &(dnslookup)& router needs to be changed. A special transport is not needed for |
| 33579 | SMTP deliveries. Every mailing list recipient has its own return path value, |
| 33580 | and so Exim must hand them to the transport one at a time. Here is an example |
| 33581 | of a &(dnslookup)& router that implements VERP: |
| 33582 | .code |
| 33583 | verp_dnslookup: |
| 33584 | driver = dnslookup |
| 33585 | domains = ! +local_domains |
| 33586 | transport = remote_smtp |
| 33587 | errors_to = \ |
| 33588 | ${if match {$return_path}{^(.+?)-request@your.dom.example\$}} |
| 33589 | {$1-request+$local_part=$domain@your.dom.example}fail} |
| 33590 | no_more |
| 33591 | .endd |
| 33592 | Before you start sending out messages with VERPed return paths, you must also |
| 33593 | configure Exim to accept the bounce messages that come back to those paths. |
| 33594 | Typically this is done by setting a &%local_part_suffix%& option for a |
| 33595 | router, and using this to route the messages to wherever you want to handle |
| 33596 | them. |
| 33597 | |
| 33598 | The overhead incurred in using VERP depends very much on the size of the |
| 33599 | message, the number of recipient addresses that resolve to the same remote |
| 33600 | host, and the speed of the connection over which the message is being sent. If |
| 33601 | a lot of addresses resolve to the same host and the connection is slow, sending |
| 33602 | a separate copy of the message for each address may take substantially longer |
| 33603 | than sending a single copy with many recipients (for which VERP cannot be |
| 33604 | used). |
| 33605 | |
| 33606 | |
| 33607 | |
| 33608 | |
| 33609 | |
| 33610 | |
| 33611 | .section "Virtual domains" "SECTvirtualdomains" |
| 33612 | .cindex "virtual domains" |
| 33613 | .cindex "domain" "virtual" |
| 33614 | The phrase &'virtual domain'& is unfortunately used with two rather different |
| 33615 | meanings: |
| 33616 | |
| 33617 | .ilist |
| 33618 | A domain for which there are no real mailboxes; all valid local parts are |
| 33619 | aliases for other email addresses. Common examples are organizational |
| 33620 | top-level domains and &"vanity"& domains. |
| 33621 | .next |
| 33622 | One of a number of independent domains that are all handled by the same host, |
| 33623 | with mailboxes on that host, but where the mailbox owners do not necessarily |
| 33624 | have login accounts on that host. |
| 33625 | .endlist |
| 33626 | |
| 33627 | The first usage is probably more common, and does seem more &"virtual"& than |
| 33628 | the second. This kind of domain can be handled in Exim with a straightforward |
| 33629 | aliasing router. One approach is to create a separate alias file for each |
| 33630 | virtual domain. Exim can test for the existence of the alias file to determine |
| 33631 | whether the domain exists. The &(dsearch)& lookup type is useful here, leading |
| 33632 | to a router of this form: |
| 33633 | .code |
| 33634 | virtual: |
| 33635 | driver = redirect |
| 33636 | domains = dsearch;/etc/mail/virtual |
| 33637 | data = ${lookup{$local_part}lsearch{/etc/mail/virtual/$domain}} |
| 33638 | no_more |
| 33639 | .endd |
| 33640 | The &%domains%& option specifies that the router is to be skipped, unless there |
| 33641 | is a file in the &_/etc/mail/virtual_& directory whose name is the same as the |
| 33642 | domain that is being processed. When the router runs, it looks up the local |
| 33643 | part in the file to find a new address (or list of addresses). The &%no_more%& |
| 33644 | setting ensures that if the lookup fails (leading to &%data%& being an empty |
| 33645 | string), Exim gives up on the address without trying any subsequent routers. |
| 33646 | |
| 33647 | This one router can handle all the virtual domains because the alias file names |
| 33648 | follow a fixed pattern. Permissions can be arranged so that appropriate people |
| 33649 | can edit the different alias files. A successful aliasing operation results in |
| 33650 | a new envelope recipient address, which is then routed from scratch. |
| 33651 | |
| 33652 | The other kind of &"virtual"& domain can also be handled in a straightforward |
| 33653 | way. One approach is to create a file for each domain containing a list of |
| 33654 | valid local parts, and use it in a router like this: |
| 33655 | .code |
| 33656 | my_domains: |
| 33657 | driver = accept |
| 33658 | domains = dsearch;/etc/mail/domains |
| 33659 | local_parts = lsearch;/etc/mail/domains/$domain |
| 33660 | transport = my_mailboxes |
| 33661 | .endd |
| 33662 | The address is accepted if there is a file for the domain, and the local part |
| 33663 | can be found in the file. The &%domains%& option is used to check for the |
| 33664 | file's existence because &%domains%& is tested before the &%local_parts%& |
| 33665 | option (see section &<<SECTrouprecon>>&). You cannot use &%require_files%&, |
| 33666 | because that option is tested after &%local_parts%&. The transport is as |
| 33667 | follows: |
| 33668 | .code |
| 33669 | my_mailboxes: |
| 33670 | driver = appendfile |
| 33671 | file = /var/mail/$domain/$local_part |
| 33672 | user = mail |
| 33673 | .endd |
| 33674 | This uses a directory of mailboxes for each domain. The &%user%& setting is |
| 33675 | required, to specify which uid is to be used for writing to the mailboxes. |
| 33676 | |
| 33677 | The configuration shown here is just one example of how you might support this |
| 33678 | requirement. There are many other ways this kind of configuration can be set |
| 33679 | up, for example, by using a database instead of separate files to hold all the |
| 33680 | information about the domains. |
| 33681 | |
| 33682 | |
| 33683 | |
| 33684 | .section "Multiple user mailboxes" "SECTmulbox" |
| 33685 | .cindex "multiple mailboxes" |
| 33686 | .cindex "mailbox" "multiple" |
| 33687 | .cindex "local part" "prefix" |
| 33688 | .cindex "local part" "suffix" |
| 33689 | Heavy email users often want to operate with multiple mailboxes, into which |
| 33690 | incoming mail is automatically sorted. A popular way of handling this is to |
| 33691 | allow users to use multiple sender addresses, so that replies can easily be |
| 33692 | identified. Users are permitted to add prefixes or suffixes to their local |
| 33693 | parts for this purpose. The wildcard facility of the generic router options |
| 33694 | &%local_part_prefix%& and &%local_part_suffix%& can be used for this. For |
| 33695 | example, consider this router: |
| 33696 | .code |
| 33697 | userforward: |
| 33698 | driver = redirect |
| 33699 | check_local_user |
| 33700 | file = $home/.forward |
| 33701 | local_part_suffix = -* |
| 33702 | local_part_suffix_optional |
| 33703 | allow_filter |
| 33704 | .endd |
| 33705 | .vindex "&$local_part_suffix$&" |
| 33706 | It runs a user's &_.forward_& file for all local parts of the form |
| 33707 | &'username-*'&. Within the filter file the user can distinguish different |
| 33708 | cases by testing the variable &$local_part_suffix$&. For example: |
| 33709 | .code |
| 33710 | if $local_part_suffix contains -special then |
| 33711 | save /home/$local_part/Mail/special |
| 33712 | endif |
| 33713 | .endd |
| 33714 | If the filter file does not exist, or does not deal with such addresses, they |
| 33715 | fall through to subsequent routers, and, assuming no subsequent use of the |
| 33716 | &%local_part_suffix%& option is made, they presumably fail. Thus, users have |
| 33717 | control over which suffixes are valid. |
| 33718 | |
| 33719 | Alternatively, a suffix can be used to trigger the use of a different |
| 33720 | &_.forward_& file &-- which is the way a similar facility is implemented in |
| 33721 | another MTA: |
| 33722 | .code |
| 33723 | userforward: |
| 33724 | driver = redirect |
| 33725 | check_local_user |
| 33726 | file = $home/.forward$local_part_suffix |
| 33727 | local_part_suffix = -* |
| 33728 | local_part_suffix_optional |
| 33729 | allow_filter |
| 33730 | .endd |
| 33731 | If there is no suffix, &_.forward_& is used; if the suffix is &'-special'&, for |
| 33732 | example, &_.forward-special_& is used. Once again, if the appropriate file |
| 33733 | does not exist, or does not deal with the address, it is passed on to |
| 33734 | subsequent routers, which could, if required, look for an unqualified |
| 33735 | &_.forward_& file to use as a default. |
| 33736 | |
| 33737 | |
| 33738 | |
| 33739 | .section "Simplified vacation processing" "SECID244" |
| 33740 | .cindex "vacation processing" |
| 33741 | The traditional way of running the &'vacation'& program is for a user to set up |
| 33742 | a pipe command in a &_.forward_& file |
| 33743 | (see section &<<SECTspecitredli>>& for syntax details). |
| 33744 | This is prone to error by inexperienced users. There are two features of Exim |
| 33745 | that can be used to make this process simpler for users: |
| 33746 | |
| 33747 | .ilist |
| 33748 | A local part prefix such as &"vacation-"& can be specified on a router which |
| 33749 | can cause the message to be delivered directly to the &'vacation'& program, or |
| 33750 | alternatively can use Exim's &(autoreply)& transport. The contents of a user's |
| 33751 | &_.forward_& file are then much simpler. For example: |
| 33752 | .code |
| 33753 | spqr, vacation-spqr |
| 33754 | .endd |
| 33755 | .next |
| 33756 | The &%require_files%& generic router option can be used to trigger a |
| 33757 | vacation delivery by checking for the existence of a certain file in the |
| 33758 | user's home directory. The &%unseen%& generic option should also be used, to |
| 33759 | ensure that the original delivery also proceeds. In this case, all the user has |
| 33760 | to do is to create a file called, say, &_.vacation_&, containing a vacation |
| 33761 | message. |
| 33762 | .endlist |
| 33763 | |
| 33764 | Another advantage of both these methods is that they both work even when the |
| 33765 | use of arbitrary pipes by users is locked out. |
| 33766 | |
| 33767 | |
| 33768 | |
| 33769 | .section "Taking copies of mail" "SECID245" |
| 33770 | .cindex "message" "copying every" |
| 33771 | Some installations have policies that require archive copies of all messages to |
| 33772 | be made. A single copy of each message can easily be taken by an appropriate |
| 33773 | command in a system filter, which could, for example, use a different file for |
| 33774 | each day's messages. |
| 33775 | |
| 33776 | There is also a shadow transport mechanism that can be used to take copies of |
| 33777 | messages that are successfully delivered by local transports, one copy per |
| 33778 | delivery. This could be used, &'inter alia'&, to implement automatic |
| 33779 | notification of delivery by sites that insist on doing such things. |
| 33780 | |
| 33781 | |
| 33782 | |
| 33783 | .section "Intermittently connected hosts" "SECID246" |
| 33784 | .cindex "intermittently connected hosts" |
| 33785 | It has become quite common (because it is cheaper) for hosts to connect to the |
| 33786 | Internet periodically rather than remain connected all the time. The normal |
| 33787 | arrangement is that mail for such hosts accumulates on a system that is |
| 33788 | permanently connected. |
| 33789 | |
| 33790 | Exim was designed for use on permanently connected hosts, and so it is not |
| 33791 | particularly well-suited to use in an intermittently connected environment. |
| 33792 | Nevertheless there are some features that can be used. |
| 33793 | |
| 33794 | |
| 33795 | .section "Exim on the upstream server host" "SECID247" |
| 33796 | It is tempting to arrange for incoming mail for the intermittently connected |
| 33797 | host to remain on Exim's queue until the client connects. However, this |
| 33798 | approach does not scale very well. Two different kinds of waiting message are |
| 33799 | being mixed up in the same queue &-- those that cannot be delivered because of |
| 33800 | some temporary problem, and those that are waiting for their destination host |
| 33801 | to connect. This makes it hard to manage the queue, as well as wasting |
| 33802 | resources, because each queue runner scans the entire queue. |
| 33803 | |
| 33804 | A better approach is to separate off those messages that are waiting for an |
| 33805 | intermittently connected host. This can be done by delivering these messages |
| 33806 | into local files in batch SMTP, &"mailstore"&, or other envelope-preserving |
| 33807 | format, from where they are transmitted by other software when their |
| 33808 | destination connects. This makes it easy to collect all the mail for one host |
| 33809 | in a single directory, and to apply local timeout rules on a per-message basis |
| 33810 | if required. |
| 33811 | |
| 33812 | On a very small scale, leaving the mail on Exim's queue can be made to work. If |
| 33813 | you are doing this, you should configure Exim with a long retry period for the |
| 33814 | intermittent host. For example: |
| 33815 | .code |
| 33816 | cheshire.wonderland.fict.example * F,5d,24h |
| 33817 | .endd |
| 33818 | This stops a lot of failed delivery attempts from occurring, but Exim remembers |
| 33819 | which messages it has queued up for that host. Once the intermittent host comes |
| 33820 | online, forcing delivery of one message (either by using the &%-M%& or &%-R%& |
| 33821 | options, or by using the ETRN SMTP command (see section &<<SECTETRN>>&) |
| 33822 | causes all the queued up messages to be delivered, often down a single SMTP |
| 33823 | connection. While the host remains connected, any new messages get delivered |
| 33824 | immediately. |
| 33825 | |
| 33826 | If the connecting hosts do not have fixed IP addresses, that is, if a host is |
| 33827 | issued with a different IP address each time it connects, Exim's retry |
| 33828 | mechanisms on the holding host get confused, because the IP address is normally |
| 33829 | used as part of the key string for holding retry information. This can be |
| 33830 | avoided by unsetting &%retry_include_ip_address%& on the &(smtp)& transport. |
| 33831 | Since this has disadvantages for permanently connected hosts, it is best to |
| 33832 | arrange a separate transport for the intermittently connected ones. |
| 33833 | |
| 33834 | |
| 33835 | |
| 33836 | .section "Exim on the intermittently connected client host" "SECID248" |
| 33837 | The value of &%smtp_accept_queue_per_connection%& should probably be |
| 33838 | increased, or even set to zero (that is, disabled) on the intermittently |
| 33839 | connected host, so that all incoming messages down a single connection get |
| 33840 | delivered immediately. |
| 33841 | |
| 33842 | .cindex "SMTP" "passed connection" |
| 33843 | .cindex "SMTP" "multiple deliveries" |
| 33844 | .cindex "multiple SMTP deliveries" |
| 33845 | Mail waiting to be sent from an intermittently connected host will probably |
| 33846 | not have been routed, because without a connection DNS lookups are not |
| 33847 | possible. This means that if a normal queue run is done at connection time, |
| 33848 | each message is likely to be sent in a separate SMTP session. This can be |
| 33849 | avoided by starting the queue run with a command line option beginning with |
| 33850 | &%-qq%& instead of &%-q%&. In this case, the queue is scanned twice. In the |
| 33851 | first pass, routing is done but no deliveries take place. The second pass is a |
| 33852 | normal queue run; since all the messages have been previously routed, those |
| 33853 | destined for the same host are likely to get sent as multiple deliveries in a |
| 33854 | single SMTP connection. |
| 33855 | |
| 33856 | |
| 33857 | |
| 33858 | . //////////////////////////////////////////////////////////////////////////// |
| 33859 | . //////////////////////////////////////////////////////////////////////////// |
| 33860 | |
| 33861 | .chapter "Using Exim as a non-queueing client" "CHAPnonqueueing" &&& |
| 33862 | "Exim as a non-queueing client" |
| 33863 | .cindex "client, non-queueing" |
| 33864 | .cindex "smart host" "suppressing queueing" |
| 33865 | On a personal computer, it is a common requirement for all |
| 33866 | email to be sent to a &"smart host"&. There are plenty of MUAs that can be |
| 33867 | configured to operate that way, for all the popular operating systems. |
| 33868 | However, there are some MUAs for Unix-like systems that cannot be so |
| 33869 | configured: they submit messages using the command line interface of |
| 33870 | &_/usr/sbin/sendmail_&. Furthermore, utility programs such as &'cron'& submit |
| 33871 | messages this way. |
| 33872 | |
| 33873 | If the personal computer runs continuously, there is no problem, because it can |
| 33874 | run a conventional MTA that handles delivery to the smart host, and deal with |
| 33875 | any delays via its queueing mechanism. However, if the computer does not run |
| 33876 | continuously or runs different operating systems at different times, queueing |
| 33877 | email is not desirable. |
| 33878 | |
| 33879 | There is therefore a requirement for something that can provide the |
| 33880 | &_/usr/sbin/sendmail_& interface but deliver messages to a smart host without |
| 33881 | any queueing or retrying facilities. Furthermore, the delivery to the smart |
| 33882 | host should be synchronous, so that if it fails, the sending MUA is immediately |
| 33883 | informed. In other words, we want something that extends an MUA that submits |
| 33884 | to a local MTA via the command line so that it behaves like one that submits |
| 33885 | to a remote smart host using TCP/SMTP. |
| 33886 | |
| 33887 | There are a number of applications (for example, there is one called &'ssmtp'&) |
| 33888 | that do this job. However, people have found them to be lacking in various |
| 33889 | ways. For instance, you might want to allow aliasing and forwarding to be done |
| 33890 | before sending a message to the smart host. |
| 33891 | |
| 33892 | Exim already had the necessary infrastructure for doing this job. Just a few |
| 33893 | tweaks were needed to make it behave as required, though it is somewhat of an |
| 33894 | overkill to use a fully-featured MTA for this purpose. |
| 33895 | |
| 33896 | .oindex "&%mua_wrapper%&" |
| 33897 | There is a Boolean global option called &%mua_wrapper%&, defaulting false. |
| 33898 | Setting &%mua_wrapper%& true causes Exim to run in a special mode where it |
| 33899 | assumes that it is being used to &"wrap"& a command-line MUA in the manner |
| 33900 | just described. As well as setting &%mua_wrapper%&, you also need to provide a |
| 33901 | compatible router and transport configuration. Typically there will be just one |
| 33902 | router and one transport, sending everything to a smart host. |
| 33903 | |
| 33904 | When run in MUA wrapping mode, the behaviour of Exim changes in the |
| 33905 | following ways: |
| 33906 | |
| 33907 | .ilist |
| 33908 | A daemon cannot be run, nor will Exim accept incoming messages from &'inetd'&. |
| 33909 | In other words, the only way to submit messages is via the command line. |
| 33910 | .next |
| 33911 | Each message is synchronously delivered as soon as it is received (&%-odi%& is |
| 33912 | assumed). All queueing options (&%queue_only%&, &%queue_smtp_domains%&, |
| 33913 | &%control%& in an ACL, etc.) are quietly ignored. The Exim reception process |
| 33914 | does not finish until the delivery attempt is complete. If the delivery is |
| 33915 | successful, a zero return code is given. |
| 33916 | .next |
| 33917 | Address redirection is permitted, but the final routing for all addresses must |
| 33918 | be to the same remote transport, and to the same list of hosts. Furthermore, |
| 33919 | the return address (envelope sender) must be the same for all recipients, as |
| 33920 | must any added or deleted header lines. In other words, it must be possible to |
| 33921 | deliver the message in a single SMTP transaction, however many recipients there |
| 33922 | are. |
| 33923 | .next |
| 33924 | If these conditions are not met, or if routing any address results in a |
| 33925 | failure or defer status, or if Exim is unable to deliver all the recipients |
| 33926 | successfully to one of the smart hosts, delivery of the entire message fails. |
| 33927 | .next |
| 33928 | Because no queueing is allowed, all failures are treated as permanent; there |
| 33929 | is no distinction between 4&'xx'& and 5&'xx'& SMTP response codes from the |
| 33930 | smart host. Furthermore, because only a single yes/no response can be given to |
| 33931 | the caller, it is not possible to deliver to some recipients and not others. If |
| 33932 | there is an error (temporary or permanent) for any recipient, all are failed. |
| 33933 | .next |
| 33934 | If more than one smart host is listed, Exim will try another host after a |
| 33935 | connection failure or a timeout, in the normal way. However, if this kind of |
| 33936 | failure happens for all the hosts, the delivery fails. |
| 33937 | .next |
| 33938 | When delivery fails, an error message is written to the standard error stream |
| 33939 | (as well as to Exim's log), and Exim exits to the caller with a return code |
| 33940 | value 1. The message is expunged from Exim's spool files. No bounce messages |
| 33941 | are ever generated. |
| 33942 | .next |
| 33943 | No retry data is maintained, and any retry rules are ignored. |
| 33944 | .next |
| 33945 | A number of Exim options are overridden: &%deliver_drop_privilege%& is forced |
| 33946 | true, &%max_rcpt%& in the &(smtp)& transport is forced to &"unlimited"&, |
| 33947 | &%remote_max_parallel%& is forced to one, and fallback hosts are ignored. |
| 33948 | .endlist |
| 33949 | |
| 33950 | The overall effect is that Exim makes a single synchronous attempt to deliver |
| 33951 | the message, failing if there is any kind of problem. Because no local |
| 33952 | deliveries are done and no daemon can be run, Exim does not need root |
| 33953 | privilege. It should be possible to run it setuid to &'exim'& instead of setuid |
| 33954 | to &'root'&. See section &<<SECTrunexiwitpri>>& for a general discussion about |
| 33955 | the advantages and disadvantages of running without root privilege. |
| 33956 | |
| 33957 | |
| 33958 | |
| 33959 | |
| 33960 | . //////////////////////////////////////////////////////////////////////////// |
| 33961 | . //////////////////////////////////////////////////////////////////////////// |
| 33962 | |
| 33963 | .chapter "Log files" "CHAPlog" |
| 33964 | .scindex IIDloggen "log" "general description" |
| 33965 | .cindex "log" "types of" |
| 33966 | Exim writes three different logs, referred to as the main log, the reject log, |
| 33967 | and the panic log: |
| 33968 | |
| 33969 | .ilist |
| 33970 | .cindex "main log" |
| 33971 | The main log records the arrival of each message and each delivery in a single |
| 33972 | line in each case. The format is as compact as possible, in an attempt to keep |
| 33973 | down the size of log files. Two-character flag sequences make it easy to pick |
| 33974 | out these lines. A number of other events are recorded in the main log. Some of |
| 33975 | them are optional, in which case the &%log_selector%& option controls whether |
| 33976 | they are included or not. A Perl script called &'eximstats'&, which does simple |
| 33977 | analysis of main log files, is provided in the Exim distribution (see section |
| 33978 | &<<SECTmailstat>>&). |
| 33979 | .next |
| 33980 | .cindex "reject log" |
| 33981 | The reject log records information from messages that are rejected as a result |
| 33982 | of a configuration option (that is, for policy reasons). |
| 33983 | The first line of each rejection is a copy of the line that is also written to |
| 33984 | the main log. Then, if the message's header has been read at the time the log |
| 33985 | is written, its contents are written to this log. Only the original header |
| 33986 | lines are available; header lines added by ACLs are not logged. You can use the |
| 33987 | reject log to check that your policy controls are working correctly; on a busy |
| 33988 | host this may be easier than scanning the main log for rejection messages. You |
| 33989 | can suppress the writing of the reject log by setting &%write_rejectlog%& |
| 33990 | false. |
| 33991 | .next |
| 33992 | .cindex "panic log" |
| 33993 | .cindex "system log" |
| 33994 | When certain serious errors occur, Exim writes entries to its panic log. If the |
| 33995 | error is sufficiently disastrous, Exim bombs out afterwards. Panic log entries |
| 33996 | are usually written to the main log as well, but can get lost amid the mass of |
| 33997 | other entries. The panic log should be empty under normal circumstances. It is |
| 33998 | therefore a good idea to check it (or to have a &'cron'& script check it) |
| 33999 | regularly, in order to become aware of any problems. When Exim cannot open its |
| 34000 | panic log, it tries as a last resort to write to the system log (syslog). This |
| 34001 | is opened with LOG_PID+LOG_CONS and the facility code of LOG_MAIL. The |
| 34002 | message itself is written at priority LOG_CRIT. |
| 34003 | .endlist |
| 34004 | |
| 34005 | Every log line starts with a timestamp, in the format shown in the following |
| 34006 | example. Note that many of the examples shown in this chapter are line-wrapped. |
| 34007 | In the log file, this would be all on one line: |
| 34008 | .code |
| 34009 | 2001-09-16 16:09:47 SMTP connection from [127.0.0.1] closed |
| 34010 | by QUIT |
| 34011 | .endd |
| 34012 | By default, the timestamps are in the local timezone. There are two |
| 34013 | ways of changing this: |
| 34014 | |
| 34015 | .ilist |
| 34016 | You can set the &%timezone%& option to a different time zone; in particular, if |
| 34017 | you set |
| 34018 | .code |
| 34019 | timezone = UTC |
| 34020 | .endd |
| 34021 | the timestamps will be in UTC (aka GMT). |
| 34022 | .next |
| 34023 | If you set &%log_timezone%& true, the time zone is added to the timestamp, for |
| 34024 | example: |
| 34025 | .code |
| 34026 | 2003-04-25 11:17:07 +0100 Start queue run: pid=12762 |
| 34027 | .endd |
| 34028 | .endlist |
| 34029 | |
| 34030 | .cindex "log" "process ids in" |
| 34031 | .cindex "pid (process id)" "in log lines" |
| 34032 | Exim does not include its process id in log lines by default, but you can |
| 34033 | request that it does so by specifying the &`pid`& log selector (see section |
| 34034 | &<<SECTlogselector>>&). When this is set, the process id is output, in square |
| 34035 | brackets, immediately after the time and date. |
| 34036 | |
| 34037 | |
| 34038 | |
| 34039 | |
| 34040 | .section "Where the logs are written" "SECTwhelogwri" |
| 34041 | .cindex "log" "destination" |
| 34042 | .cindex "log" "to file" |
| 34043 | .cindex "log" "to syslog" |
| 34044 | .cindex "syslog" |
| 34045 | The logs may be written to local files, or to syslog, or both. However, it |
| 34046 | should be noted that many syslog implementations use UDP as a transport, and |
| 34047 | are therefore unreliable in the sense that messages are not guaranteed to |
| 34048 | arrive at the loghost, nor is the ordering of messages necessarily maintained. |
| 34049 | It has also been reported that on large log files (tens of megabytes) you may |
| 34050 | need to tweak syslog to prevent it syncing the file with each write &-- on |
| 34051 | Linux this has been seen to make syslog take 90% plus of CPU time. |
| 34052 | |
| 34053 | The destination for Exim's logs is configured by setting LOG_FILE_PATH in |
| 34054 | &_Local/Makefile_& or by setting &%log_file_path%& in the run time |
| 34055 | configuration. This latter string is expanded, so it can contain, for example, |
| 34056 | references to the host name: |
| 34057 | .code |
| 34058 | log_file_path = /var/log/$primary_hostname/exim_%slog |
| 34059 | .endd |
| 34060 | It is generally advisable, however, to set the string in &_Local/Makefile_& |
| 34061 | rather than at run time, because then the setting is available right from the |
| 34062 | start of Exim's execution. Otherwise, if there's something it wants to log |
| 34063 | before it has read the configuration file (for example, an error in the |
| 34064 | configuration file) it will not use the path you want, and may not be able to |
| 34065 | log at all. |
| 34066 | |
| 34067 | The value of LOG_FILE_PATH or &%log_file_path%& is a colon-separated |
| 34068 | list, currently limited to at most two items. This is one option where the |
| 34069 | facility for changing a list separator may not be used. The list must always be |
| 34070 | colon-separated. If an item in the list is &"syslog"& then syslog is used; |
| 34071 | otherwise the item must either be an absolute path, containing &`%s`& at the |
| 34072 | point where &"main"&, &"reject"&, or &"panic"& is to be inserted, or be empty, |
| 34073 | implying the use of a default path. |
| 34074 | |
| 34075 | When Exim encounters an empty item in the list, it searches the list defined by |
| 34076 | LOG_FILE_PATH, and uses the first item it finds that is neither empty nor |
| 34077 | &"syslog"&. This means that an empty item in &%log_file_path%& can be used to |
| 34078 | mean &"use the path specified at build time"&. It no such item exists, log |
| 34079 | files are written in the &_log_& subdirectory of the spool directory. This is |
| 34080 | equivalent to the setting: |
| 34081 | .code |
| 34082 | log_file_path = $spool_directory/log/%slog |
| 34083 | .endd |
| 34084 | If you do not specify anything at build time or run time, that is where the |
| 34085 | logs are written. |
| 34086 | |
| 34087 | A log file path may also contain &`%D`& or &`%M`& if datestamped log file names |
| 34088 | are in use &-- see section &<<SECTdatlogfil>>& below. |
| 34089 | |
| 34090 | Here are some examples of possible settings: |
| 34091 | .display |
| 34092 | &`LOG_FILE_PATH=syslog `& syslog only |
| 34093 | &`LOG_FILE_PATH=:syslog `& syslog and default path |
| 34094 | &`LOG_FILE_PATH=syslog : /usr/log/exim_%s `& syslog and specified path |
| 34095 | &`LOG_FILE_PATH=/usr/log/exim_%s `& specified path only |
| 34096 | .endd |
| 34097 | If there are more than two paths in the list, the first is used and a panic |
| 34098 | error is logged. |
| 34099 | |
| 34100 | |
| 34101 | |
| 34102 | .section "Logging to local files that are periodically &""cycled""&" "SECID285" |
| 34103 | .cindex "log" "cycling local files" |
| 34104 | .cindex "cycling logs" |
| 34105 | .cindex "&'exicyclog'&" |
| 34106 | .cindex "log" "local files; writing to" |
| 34107 | Some operating systems provide centralized and standardized methods for cycling |
| 34108 | log files. For those that do not, a utility script called &'exicyclog'& is |
| 34109 | provided (see section &<<SECTcyclogfil>>&). This renames and compresses the |
| 34110 | main and reject logs each time it is called. The maximum number of old logs to |
| 34111 | keep can be set. It is suggested this script is run as a daily &'cron'& job. |
| 34112 | |
| 34113 | An Exim delivery process opens the main log when it first needs to write to it, |
| 34114 | and it keeps the file open in case subsequent entries are required &-- for |
| 34115 | example, if a number of different deliveries are being done for the same |
| 34116 | message. However, remote SMTP deliveries can take a long time, and this means |
| 34117 | that the file may be kept open long after it is renamed if &'exicyclog'& or |
| 34118 | something similar is being used to rename log files on a regular basis. To |
| 34119 | ensure that a switch of log files is noticed as soon as possible, Exim calls |
| 34120 | &[stat()]& on the main log's name before reusing an open file, and if the file |
| 34121 | does not exist, or its inode has changed, the old file is closed and Exim |
| 34122 | tries to open the main log from scratch. Thus, an old log file may remain open |
| 34123 | for quite some time, but no Exim processes should write to it once it has been |
| 34124 | renamed. |
| 34125 | |
| 34126 | |
| 34127 | |
| 34128 | .section "Datestamped log files" "SECTdatlogfil" |
| 34129 | .cindex "log" "datestamped files" |
| 34130 | Instead of cycling the main and reject log files by renaming them |
| 34131 | periodically, some sites like to use files whose names contain a datestamp, |
| 34132 | for example, &_mainlog-20031225_&. The datestamp is in the form &_yyyymmdd_& or |
| 34133 | &_yyyymm_&. Exim has support for this way of working. It is enabled by setting |
| 34134 | the &%log_file_path%& option to a path that includes &`%D`& or &`%M`& at the |
| 34135 | point where the datestamp is required. For example: |
| 34136 | .code |
| 34137 | log_file_path = /var/spool/exim/log/%slog-%D |
| 34138 | log_file_path = /var/log/exim-%s-%D.log |
| 34139 | log_file_path = /var/spool/exim/log/%D-%slog |
| 34140 | log_file_path = /var/log/exim/%s.%M |
| 34141 | .endd |
| 34142 | As before, &`%s`& is replaced by &"main"& or &"reject"&; the following are |
| 34143 | examples of names generated by the above examples: |
| 34144 | .code |
| 34145 | /var/spool/exim/log/mainlog-20021225 |
| 34146 | /var/log/exim-reject-20021225.log |
| 34147 | /var/spool/exim/log/20021225-mainlog |
| 34148 | /var/log/exim/main.200212 |
| 34149 | .endd |
| 34150 | When this form of log file is specified, Exim automatically switches to new |
| 34151 | files at midnight. It does not make any attempt to compress old logs; you |
| 34152 | will need to write your own script if you require this. You should not |
| 34153 | run &'exicyclog'& with this form of logging. |
| 34154 | |
| 34155 | The location of the panic log is also determined by &%log_file_path%&, but it |
| 34156 | is not datestamped, because rotation of the panic log does not make sense. |
| 34157 | When generating the name of the panic log, &`%D`& or &`%M`& are removed from |
| 34158 | the string. In addition, if it immediately follows a slash, a following |
| 34159 | non-alphanumeric character is removed; otherwise a preceding non-alphanumeric |
| 34160 | character is removed. Thus, the four examples above would give these panic |
| 34161 | log names: |
| 34162 | .code |
| 34163 | /var/spool/exim/log/paniclog |
| 34164 | /var/log/exim-panic.log |
| 34165 | /var/spool/exim/log/paniclog |
| 34166 | /var/log/exim/panic |
| 34167 | .endd |
| 34168 | |
| 34169 | |
| 34170 | .section "Logging to syslog" "SECID249" |
| 34171 | .cindex "log" "syslog; writing to" |
| 34172 | The use of syslog does not change what Exim logs or the format of its messages, |
| 34173 | except in one respect. If &%syslog_timestamp%& is set false, the timestamps on |
| 34174 | Exim's log lines are omitted when these lines are sent to syslog. Apart from |
| 34175 | that, the same strings are written to syslog as to log files. The syslog |
| 34176 | &"facility"& is set to LOG_MAIL, and the program name to &"exim"& |
| 34177 | by default, but you can change these by setting the &%syslog_facility%& and |
| 34178 | &%syslog_processname%& options, respectively. If Exim was compiled with |
| 34179 | SYSLOG_LOG_PID set in &_Local/Makefile_& (this is the default in |
| 34180 | &_src/EDITME_&), then, on systems that permit it (all except ULTRIX), the |
| 34181 | LOG_PID flag is set so that the &[syslog()]& call adds the pid as well as |
| 34182 | the time and host name to each line. |
| 34183 | The three log streams are mapped onto syslog priorities as follows: |
| 34184 | |
| 34185 | .ilist |
| 34186 | &'mainlog'& is mapped to LOG_INFO |
| 34187 | .next |
| 34188 | &'rejectlog'& is mapped to LOG_NOTICE |
| 34189 | .next |
| 34190 | &'paniclog'& is mapped to LOG_ALERT |
| 34191 | .endlist |
| 34192 | |
| 34193 | Many log lines are written to both &'mainlog'& and &'rejectlog'&, and some are |
| 34194 | written to both &'mainlog'& and &'paniclog'&, so there will be duplicates if |
| 34195 | these are routed by syslog to the same place. You can suppress this duplication |
| 34196 | by setting &%syslog_duplication%& false. |
| 34197 | |
| 34198 | Exim's log lines can sometimes be very long, and some of its &'rejectlog'& |
| 34199 | entries contain multiple lines when headers are included. To cope with both |
| 34200 | these cases, entries written to syslog are split into separate &[syslog()]& |
| 34201 | calls at each internal newline, and also after a maximum of |
| 34202 | 870 data characters. (This allows for a total syslog line length of 1024, when |
| 34203 | additions such as timestamps are added.) If you are running a syslog |
| 34204 | replacement that can handle lines longer than the 1024 characters allowed by |
| 34205 | RFC 3164, you should set |
| 34206 | .code |
| 34207 | SYSLOG_LONG_LINES=yes |
| 34208 | .endd |
| 34209 | in &_Local/Makefile_& before building Exim. That stops Exim from splitting long |
| 34210 | lines, but it still splits at internal newlines in &'reject'& log entries. |
| 34211 | |
| 34212 | To make it easy to re-assemble split lines later, each component of a split |
| 34213 | entry starts with a string of the form [<&'n'&>/<&'m'&>] or [<&'n'&>\<&'m'&>] |
| 34214 | where <&'n'&> is the component number and <&'m'&> is the total number of |
| 34215 | components in the entry. The / delimiter is used when the line was split |
| 34216 | because it was too long; if it was split because of an internal newline, the \ |
| 34217 | delimiter is used. For example, supposing the length limit to be 50 instead of |
| 34218 | 870, the following would be the result of a typical rejection message to |
| 34219 | &'mainlog'& (LOG_INFO), each line in addition being preceded by the time, host |
| 34220 | name, and pid as added by syslog: |
| 34221 | .code |
| 34222 | [1/5] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected from |
| 34223 | [2/5] [127.0.0.1] (ph10): syntax error in 'From' header |
| 34224 | [3/5] when scanning for sender: missing or malformed lo |
| 34225 | [4/5] cal part in "<>" (envelope sender is <ph10@cam.exa |
| 34226 | [5/5] mple>) |
| 34227 | .endd |
| 34228 | The same error might cause the following lines to be written to &"rejectlog"& |
| 34229 | (LOG_NOTICE): |
| 34230 | .code |
| 34231 | [1/18] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected fro |
| 34232 | [2/18] m [127.0.0.1] (ph10): syntax error in 'From' head |
| 34233 | [3/18] er when scanning for sender: missing or malformed |
| 34234 | [4/18] local part in "<>" (envelope sender is <ph10@cam |
| 34235 | [5\18] .example>) |
| 34236 | [6\18] Recipients: ph10@some.domain.cam.example |
| 34237 | [7\18] P Received: from [127.0.0.1] (ident=ph10) |
| 34238 | [8\18] by xxxxx.cam.example with smtp (Exim 4.00) |
| 34239 | [9\18] id 16RdAL-0006pc-00 |
| 34240 | [10/18] for ph10@cam.example; Mon, 16 Sep 2002 16: |
| 34241 | [11\18] 09:43 +0100 |
| 34242 | [12\18] F From: <> |
| 34243 | [13\18] Subject: this is a test header |
| 34244 | [18\18] X-something: this is another header |
| 34245 | [15/18] I Message-Id: <E16RdAL-0006pc-00@xxxxx.cam.examp |
| 34246 | [16\18] le> |
| 34247 | [17\18] B Bcc: |
| 34248 | [18/18] Date: Mon, 16 Sep 2002 16:09:43 +0100 |
| 34249 | .endd |
| 34250 | Log lines that are neither too long nor contain newlines are written to syslog |
| 34251 | without modification. |
| 34252 | |
| 34253 | If only syslog is being used, the Exim monitor is unable to provide a log tail |
| 34254 | display, unless syslog is routing &'mainlog'& to a file on the local host and |
| 34255 | the environment variable EXIMON_LOG_FILE_PATH is set to tell the monitor |
| 34256 | where it is. |
| 34257 | |
| 34258 | |
| 34259 | |
| 34260 | .section "Log line flags" "SECID250" |
| 34261 | One line is written to the main log for each message received, and for each |
| 34262 | successful, unsuccessful, and delayed delivery. These lines can readily be |
| 34263 | picked out by the distinctive two-character flags that immediately follow the |
| 34264 | timestamp. The flags are: |
| 34265 | .display |
| 34266 | &`<=`& message arrival |
| 34267 | &`=>`& normal message delivery |
| 34268 | &`->`& additional address in same delivery |
| 34269 | &`>>`& cutthrough message delivery |
| 34270 | &`*>`& delivery suppressed by &%-N%& |
| 34271 | &`**`& delivery failed; address bounced |
| 34272 | &`==`& delivery deferred; temporary problem |
| 34273 | .endd |
| 34274 | |
| 34275 | |
| 34276 | .section "Logging message reception" "SECID251" |
| 34277 | .cindex "log" "reception line" |
| 34278 | The format of the single-line entry in the main log that is written for every |
| 34279 | message received is shown in the basic example below, which is split over |
| 34280 | several lines in order to fit it on the page: |
| 34281 | .code |
| 34282 | 2002-10-31 08:57:53 16ZCW1-0005MB-00 <= kryten@dwarf.fict.example |
| 34283 | H=mailer.fict.example [192.168.123.123] U=exim |
| 34284 | P=smtp S=5678 id=<incoming message id> |
| 34285 | .endd |
| 34286 | The address immediately following &"<="& is the envelope sender address. A |
| 34287 | bounce message is shown with the sender address &"<>"&, and if it is locally |
| 34288 | generated, this is followed by an item of the form |
| 34289 | .code |
| 34290 | R=<message id> |
| 34291 | .endd |
| 34292 | which is a reference to the message that caused the bounce to be sent. |
| 34293 | |
| 34294 | .cindex "HELO" |
| 34295 | .cindex "EHLO" |
| 34296 | For messages from other hosts, the H and U fields identify the remote host and |
| 34297 | record the RFC 1413 identity of the user that sent the message, if one was |
| 34298 | received. The number given in square brackets is the IP address of the sending |
| 34299 | host. If there is a single, unparenthesized host name in the H field, as |
| 34300 | above, it has been verified to correspond to the IP address (see the |
| 34301 | &%host_lookup%& option). If the name is in parentheses, it was the name quoted |
| 34302 | by the remote host in the SMTP HELO or EHLO command, and has not been |
| 34303 | verified. If verification yields a different name to that given for HELO or |
| 34304 | EHLO, the verified name appears first, followed by the HELO or EHLO |
| 34305 | name in parentheses. |
| 34306 | |
| 34307 | Misconfigured hosts (and mail forgers) sometimes put an IP address, with or |
| 34308 | without brackets, in the HELO or EHLO command, leading to entries in |
| 34309 | the log containing text like these examples: |
| 34310 | .code |
| 34311 | H=(10.21.32.43) [192.168.8.34] |
| 34312 | H=([10.21.32.43]) [192.168.8.34] |
| 34313 | .endd |
| 34314 | This can be confusing. Only the final address in square brackets can be relied |
| 34315 | on. |
| 34316 | |
| 34317 | For locally generated messages (that is, messages not received over TCP/IP), |
| 34318 | the H field is omitted, and the U field contains the login name of the caller |
| 34319 | of Exim. |
| 34320 | |
| 34321 | .cindex "authentication" "logging" |
| 34322 | .cindex "AUTH" "logging" |
| 34323 | For all messages, the P field specifies the protocol used to receive the |
| 34324 | message. This is the value that is stored in &$received_protocol$&. In the case |
| 34325 | of incoming SMTP messages, the value indicates whether or not any SMTP |
| 34326 | extensions (ESMTP), encryption, or authentication were used. If the SMTP |
| 34327 | session was encrypted, there is an additional X field that records the cipher |
| 34328 | suite that was used. |
| 34329 | |
| 34330 | The protocol is set to &"esmtpsa"& or &"esmtpa"& for messages received from |
| 34331 | hosts that have authenticated themselves using the SMTP AUTH command. The first |
| 34332 | value is used when the SMTP connection was encrypted (&"secure"&). In this case |
| 34333 | there is an additional item A= followed by the name of the authenticator that |
| 34334 | was used. If an authenticated identification was set up by the authenticator's |
| 34335 | &%server_set_id%& option, this is logged too, separated by a colon from the |
| 34336 | authenticator name. |
| 34337 | |
| 34338 | .cindex "size" "of message" |
| 34339 | The id field records the existing message id, if present. The size of the |
| 34340 | received message is given by the S field. When the message is delivered, |
| 34341 | headers may be removed or added, so that the size of delivered copies of the |
| 34342 | message may not correspond with this value (and indeed may be different to each |
| 34343 | other). |
| 34344 | |
| 34345 | The &%log_selector%& option can be used to request the logging of additional |
| 34346 | data when a message is received. See section &<<SECTlogselector>>& below. |
| 34347 | |
| 34348 | |
| 34349 | |
| 34350 | .section "Logging deliveries" "SECID252" |
| 34351 | .cindex "log" "delivery line" |
| 34352 | The format of the single-line entry in the main log that is written for every |
| 34353 | delivery is shown in one of the examples below, for local and remote |
| 34354 | deliveries, respectively. Each example has been split into two lines in order |
| 34355 | to fit it on the page: |
| 34356 | .code |
| 34357 | 2002-10-31 08:59:13 16ZCW1-0005MB-00 => marv |
| 34358 | <marv@hitch.fict.example> R=localuser T=local_delivery |
| 34359 | 2002-10-31 09:00:10 16ZCW1-0005MB-00 => |
| 34360 | monk@holistic.fict.example R=dnslookup T=remote_smtp |
| 34361 | H=holistic.fict.example [192.168.234.234] |
| 34362 | .endd |
| 34363 | For ordinary local deliveries, the original address is given in angle brackets |
| 34364 | after the final delivery address, which might be a pipe or a file. If |
| 34365 | intermediate address(es) exist between the original and the final address, the |
| 34366 | last of these is given in parentheses after the final address. The R and T |
| 34367 | fields record the router and transport that were used to process the address. |
| 34368 | |
| 34369 | If SMTP AUTH was used for the delivery there is an additional item A= |
| 34370 | followed by the name of the authenticator that was used. |
| 34371 | If an authenticated identification was set up by the authenticator's &%client_set_id%& |
| 34372 | option, this is logged too, separated by a colon from the authenticator name. |
| 34373 | |
| 34374 | If a shadow transport was run after a successful local delivery, the log line |
| 34375 | for the successful delivery has an item added on the end, of the form |
| 34376 | .display |
| 34377 | &`ST=<`&&'shadow transport name'&&`>`& |
| 34378 | .endd |
| 34379 | If the shadow transport did not succeed, the error message is put in |
| 34380 | parentheses afterwards. |
| 34381 | |
| 34382 | .cindex "asterisk" "after IP address" |
| 34383 | When more than one address is included in a single delivery (for example, two |
| 34384 | SMTP RCPT commands in one transaction) the second and subsequent addresses are |
| 34385 | flagged with &`->`& instead of &`=>`&. When two or more messages are delivered |
| 34386 | down a single SMTP connection, an asterisk follows the IP address in the log |
| 34387 | lines for the second and subsequent messages. |
| 34388 | |
| 34389 | .cindex "delivery" "cutthrough; logging" |
| 34390 | .cindex "cutthrough" "logging" |
| 34391 | When delivery is done in cutthrough mode it is flagged with &`>>`& and the log |
| 34392 | line precedes the reception line, since cutthrough waits for a possible |
| 34393 | rejection from the destination in case it can reject the sourced item. |
| 34394 | |
| 34395 | The generation of a reply message by a filter file gets logged as a |
| 34396 | &"delivery"& to the addressee, preceded by &">"&. |
| 34397 | |
| 34398 | The &%log_selector%& option can be used to request the logging of additional |
| 34399 | data when a message is delivered. See section &<<SECTlogselector>>& below. |
| 34400 | |
| 34401 | |
| 34402 | .section "Discarded deliveries" "SECID253" |
| 34403 | .cindex "discarded messages" |
| 34404 | .cindex "message" "discarded" |
| 34405 | .cindex "delivery" "discarded; logging" |
| 34406 | When a message is discarded as a result of the command &"seen finish"& being |
| 34407 | obeyed in a filter file which generates no deliveries, a log entry of the form |
| 34408 | .code |
| 34409 | 2002-12-10 00:50:49 16auJc-0001UB-00 => discarded |
| 34410 | <low.club@bridge.example> R=userforward |
| 34411 | .endd |
| 34412 | is written, to record why no deliveries are logged. When a message is discarded |
| 34413 | because it is aliased to &":blackhole:"& the log line is like this: |
| 34414 | .code |
| 34415 | 1999-03-02 09:44:33 10HmaX-0005vi-00 => :blackhole: |
| 34416 | <hole@nowhere.example> R=blackhole_router |
| 34417 | .endd |
| 34418 | |
| 34419 | |
| 34420 | .section "Deferred deliveries" "SECID254" |
| 34421 | When a delivery is deferred, a line of the following form is logged: |
| 34422 | .code |
| 34423 | 2002-12-19 16:20:23 16aiQz-0002Q5-00 == marvin@endrest.example |
| 34424 | R=dnslookup T=smtp defer (146): Connection refused |
| 34425 | .endd |
| 34426 | In the case of remote deliveries, the error is the one that was given for the |
| 34427 | last IP address that was tried. Details of individual SMTP failures are also |
| 34428 | written to the log, so the above line would be preceded by something like |
| 34429 | .code |
| 34430 | 2002-12-19 16:20:23 16aiQz-0002Q5-00 Failed to connect to |
| 34431 | mail1.endrest.example [192.168.239.239]: Connection refused |
| 34432 | .endd |
| 34433 | When a deferred address is skipped because its retry time has not been reached, |
| 34434 | a message is written to the log, but this can be suppressed by setting an |
| 34435 | appropriate value in &%log_selector%&. |
| 34436 | |
| 34437 | |
| 34438 | |
| 34439 | .section "Delivery failures" "SECID255" |
| 34440 | .cindex "delivery" "failure; logging" |
| 34441 | If a delivery fails because an address cannot be routed, a line of the |
| 34442 | following form is logged: |
| 34443 | .code |
| 34444 | 1995-12-19 16:20:23 0tRiQz-0002Q5-00 ** jim@trek99.example |
| 34445 | <jim@trek99.example>: unknown mail domain |
| 34446 | .endd |
| 34447 | If a delivery fails at transport time, the router and transport are shown, and |
| 34448 | the response from the remote host is included, as in this example: |
| 34449 | .code |
| 34450 | 2002-07-11 07:14:17 17SXDU-000189-00 ** ace400@pb.example |
| 34451 | R=dnslookup T=remote_smtp: SMTP error from remote mailer |
| 34452 | after pipelined RCPT TO:<ace400@pb.example>: host |
| 34453 | pbmail3.py.example [192.168.63.111]: 553 5.3.0 |
| 34454 | <ace400@pb.example>...Addressee unknown |
| 34455 | .endd |
| 34456 | The word &"pipelined"& indicates that the SMTP PIPELINING extension was being |
| 34457 | used. See &%hosts_avoid_esmtp%& in the &(smtp)& transport for a way of |
| 34458 | disabling PIPELINING. The log lines for all forms of delivery failure are |
| 34459 | flagged with &`**`&. |
| 34460 | |
| 34461 | |
| 34462 | |
| 34463 | .section "Fake deliveries" "SECID256" |
| 34464 | .cindex "delivery" "fake; logging" |
| 34465 | If a delivery does not actually take place because the &%-N%& option has been |
| 34466 | used to suppress it, a normal delivery line is written to the log, except that |
| 34467 | &"=>"& is replaced by &"*>"&. |
| 34468 | |
| 34469 | |
| 34470 | |
| 34471 | .section "Completion" "SECID257" |
| 34472 | A line of the form |
| 34473 | .code |
| 34474 | 2002-10-31 09:00:11 16ZCW1-0005MB-00 Completed |
| 34475 | .endd |
| 34476 | is written to the main log when a message is about to be removed from the spool |
| 34477 | at the end of its processing. |
| 34478 | |
| 34479 | |
| 34480 | |
| 34481 | |
| 34482 | .section "Summary of Fields in Log Lines" "SECID258" |
| 34483 | .cindex "log" "summary of fields" |
| 34484 | A summary of the field identifiers that are used in log lines is shown in |
| 34485 | the following table: |
| 34486 | .display |
| 34487 | &`A `& authenticator name (and optional id and sender) |
| 34488 | &`C `& SMTP confirmation on delivery |
| 34489 | &` `& command list for &"no mail in SMTP session"& |
| 34490 | &`CV `& certificate verification status |
| 34491 | &`D `& duration of &"no mail in SMTP session"& |
| 34492 | &`DN `& distinguished name from peer certificate |
| 34493 | &`DT `& on &`=>`& lines: time taken for a delivery |
| 34494 | &`F `& sender address (on delivery lines) |
| 34495 | &`H `& host name and IP address |
| 34496 | &`I `& local interface used |
| 34497 | &`id `& message id for incoming message |
| 34498 | &`P `& on &`<=`& lines: protocol used |
| 34499 | &` `& on &`=>`& and &`**`& lines: return path |
| 34500 | &`QT `& on &`=>`& lines: time spent on queue so far |
| 34501 | &` `& on &"Completed"& lines: time spent on queue |
| 34502 | &`R `& on &`<=`& lines: reference for local bounce |
| 34503 | &` `& on &`=>`& &`**`& and &`==`& lines: router name |
| 34504 | &`S `& size of message |
| 34505 | &`SNI `& server name indication from TLS client hello |
| 34506 | &`ST `& shadow transport name |
| 34507 | &`T `& on &`<=`& lines: message subject (topic) |
| 34508 | &` `& on &`=>`& &`**`& and &`==`& lines: transport name |
| 34509 | &`U `& local user or RFC 1413 identity |
| 34510 | &`X `& TLS cipher suite |
| 34511 | .endd |
| 34512 | |
| 34513 | |
| 34514 | .section "Other log entries" "SECID259" |
| 34515 | Various other types of log entry are written from time to time. Most should be |
| 34516 | self-explanatory. Among the more common are: |
| 34517 | |
| 34518 | .ilist |
| 34519 | .cindex "retry" "time not reached" |
| 34520 | &'retry time not reached'&&~&~An address previously suffered a temporary error |
| 34521 | during routing or local delivery, and the time to retry has not yet arrived. |
| 34522 | This message is not written to an individual message log file unless it happens |
| 34523 | during the first delivery attempt. |
| 34524 | .next |
| 34525 | &'retry time not reached for any host'&&~&~An address previously suffered |
| 34526 | temporary errors during remote delivery, and the retry time has not yet arrived |
| 34527 | for any of the hosts to which it is routed. |
| 34528 | .next |
| 34529 | .cindex "spool directory" "file locked" |
| 34530 | &'spool file locked'&&~&~An attempt to deliver a message cannot proceed because |
| 34531 | some other Exim process is already working on the message. This can be quite |
| 34532 | common if queue running processes are started at frequent intervals. The |
| 34533 | &'exiwhat'& utility script can be used to find out what Exim processes are |
| 34534 | doing. |
| 34535 | .next |
| 34536 | .cindex "error" "ignored" |
| 34537 | &'error ignored'&&~&~There are several circumstances that give rise to this |
| 34538 | message: |
| 34539 | .olist |
| 34540 | Exim failed to deliver a bounce message whose age was greater than |
| 34541 | &%ignore_bounce_errors_after%&. The bounce was discarded. |
| 34542 | .next |
| 34543 | A filter file set up a delivery using the &"noerror"& option, and the delivery |
| 34544 | failed. The delivery was discarded. |
| 34545 | .next |
| 34546 | A delivery set up by a router configured with |
| 34547 | . ==== As this is a nested list, any displays it contains must be indented |
| 34548 | . ==== as otherwise they are too far to the left. |
| 34549 | .code |
| 34550 | errors_to = <> |
| 34551 | .endd |
| 34552 | failed. The delivery was discarded. |
| 34553 | .endlist olist |
| 34554 | .endlist ilist |
| 34555 | |
| 34556 | |
| 34557 | |
| 34558 | |
| 34559 | |
| 34560 | .section "Reducing or increasing what is logged" "SECTlogselector" |
| 34561 | .cindex "log" "selectors" |
| 34562 | By setting the &%log_selector%& global option, you can disable some of Exim's |
| 34563 | default logging, or you can request additional logging. The value of |
| 34564 | &%log_selector%& is made up of names preceded by plus or minus characters. For |
| 34565 | example: |
| 34566 | .code |
| 34567 | log_selector = +arguments -retry_defer |
| 34568 | .endd |
| 34569 | The list of optional log items is in the following table, with the default |
| 34570 | selection marked by asterisks: |
| 34571 | .display |
| 34572 | &` 8bitmime `& received 8BITMIME status |
| 34573 | &`*acl_warn_skipped `& skipped &%warn%& statement in ACL |
| 34574 | &` address_rewrite `& address rewriting |
| 34575 | &` all_parents `& all parents in => lines |
| 34576 | &` arguments `& command line arguments |
| 34577 | &`*connection_reject `& connection rejections |
| 34578 | &`*delay_delivery `& immediate delivery delayed |
| 34579 | &` deliver_time `& time taken to perform delivery |
| 34580 | &` delivery_size `& add &`S=`&&'nnn'& to => lines |
| 34581 | &`*dnslist_defer `& defers of DNS list (aka RBL) lookups |
| 34582 | &`*etrn `& ETRN commands |
| 34583 | &`*host_lookup_failed `& as it says |
| 34584 | &` ident_timeout `& timeout for ident connection |
| 34585 | &` incoming_interface `& incoming interface on <= lines |
| 34586 | &` incoming_port `& incoming port on <= lines |
| 34587 | &`*lost_incoming_connection `& as it says (includes timeouts) |
| 34588 | &` outgoing_port `& add remote port to => lines |
| 34589 | &`*queue_run `& start and end queue runs |
| 34590 | &` queue_time `& time on queue for one recipient |
| 34591 | &` queue_time_overall `& time on queue for whole message |
| 34592 | &` pid `& Exim process id |
| 34593 | &` received_recipients `& recipients on <= lines |
| 34594 | &` received_sender `& sender on <= lines |
| 34595 | &`*rejected_header `& header contents on reject log |
| 34596 | &`*retry_defer `& &"retry time not reached"& |
| 34597 | &` return_path_on_delivery `& put return path on => and ** lines |
| 34598 | &` sender_on_delivery `& add sender to => lines |
| 34599 | &`*sender_verify_fail `& sender verification failures |
| 34600 | &`*size_reject `& rejection because too big |
| 34601 | &`*skip_delivery `& delivery skipped in a queue run |
| 34602 | &`*smtp_confirmation `& SMTP confirmation on => lines |
| 34603 | &` smtp_connection `& SMTP connections |
| 34604 | &` smtp_incomplete_transaction`& incomplete SMTP transactions |
| 34605 | &` smtp_mailauth `& AUTH argument to MAIL commands |
| 34606 | &` smtp_no_mail `& session with no MAIL commands |
| 34607 | &` smtp_protocol_error `& SMTP protocol errors |
| 34608 | &` smtp_syntax_error `& SMTP syntax errors |
| 34609 | &` subject `& contents of &'Subject:'& on <= lines |
| 34610 | &` tls_certificate_verified `& certificate verification status |
| 34611 | &`*tls_cipher `& TLS cipher suite on <= and => lines |
| 34612 | &` tls_peerdn `& TLS peer DN on <= and => lines |
| 34613 | &` tls_sni `& TLS SNI on <= lines |
| 34614 | &` unknown_in_list `& DNS lookup failed in list match |
| 34615 | |
| 34616 | &` all `& all of the above |
| 34617 | .endd |
| 34618 | More details on each of these items follows: |
| 34619 | |
| 34620 | .ilist |
| 34621 | .cindex "8BITMIME" |
| 34622 | .cindex "log" "8BITMIME" |
| 34623 | &%8bitmime%&: This causes Exim to log any 8BITMIME status of received messages, |
| 34624 | which may help in tracking down interoperability issues with ancient MTAs |
| 34625 | that are not 8bit clean. This is added to the &"<="& line, tagged with |
| 34626 | &`M8S=`& and a value of &`0`&, &`7`& or &`8`&, corresponding to "not given", |
| 34627 | &`7BIT`& and &`8BITMIME`& respectively. |
| 34628 | .next |
| 34629 | .cindex "&%warn%& ACL verb" "log when skipping" |
| 34630 | &%acl_warn_skipped%&: When an ACL &%warn%& statement is skipped because one of |
| 34631 | its conditions cannot be evaluated, a log line to this effect is written if |
| 34632 | this log selector is set. |
| 34633 | .next |
| 34634 | .cindex "log" "rewriting" |
| 34635 | .cindex "rewriting" "logging" |
| 34636 | &%address_rewrite%&: This applies both to global rewrites and per-transport |
| 34637 | rewrites, but not to rewrites in filters run as an unprivileged user (because |
| 34638 | such users cannot access the log). |
| 34639 | .next |
| 34640 | .cindex "log" "full parentage" |
| 34641 | &%all_parents%&: Normally only the original and final addresses are logged on |
| 34642 | delivery lines; with this selector, intermediate parents are given in |
| 34643 | parentheses between them. |
| 34644 | .next |
| 34645 | .cindex "log" "Exim arguments" |
| 34646 | .cindex "Exim arguments, logging" |
| 34647 | &%arguments%&: This causes Exim to write the arguments with which it was called |
| 34648 | to the main log, preceded by the current working directory. This is a debugging |
| 34649 | feature, added to make it easier to find out how certain MUAs call |
| 34650 | &_/usr/sbin/sendmail_&. The logging does not happen if Exim has given up root |
| 34651 | privilege because it was called with the &%-C%& or &%-D%& options. Arguments |
| 34652 | that are empty or that contain white space are quoted. Non-printing characters |
| 34653 | are shown as escape sequences. This facility cannot log unrecognized arguments, |
| 34654 | because the arguments are checked before the configuration file is read. The |
| 34655 | only way to log such cases is to interpose a script such as &_util/logargs.sh_& |
| 34656 | between the caller and Exim. |
| 34657 | .next |
| 34658 | .cindex "log" "connection rejections" |
| 34659 | &%connection_reject%&: A log entry is written whenever an incoming SMTP |
| 34660 | connection is rejected, for whatever reason. |
| 34661 | .next |
| 34662 | .cindex "log" "delayed delivery" |
| 34663 | .cindex "delayed delivery, logging" |
| 34664 | &%delay_delivery%&: A log entry is written whenever a delivery process is not |
| 34665 | started for an incoming message because the load is too high or too many |
| 34666 | messages were received on one connection. Logging does not occur if no delivery |
| 34667 | process is started because &%queue_only%& is set or &%-odq%& was used. |
| 34668 | .next |
| 34669 | .cindex "log" "delivery duration" |
| 34670 | &%deliver_time%&: For each delivery, the amount of real time it has taken to |
| 34671 | perform the actual delivery is logged as DT=<&'time'&>, for example, &`DT=1s`&. |
| 34672 | .next |
| 34673 | .cindex "log" "message size on delivery" |
| 34674 | .cindex "size" "of message" |
| 34675 | &%delivery_size%&: For each delivery, the size of message delivered is added to |
| 34676 | the &"=>"& line, tagged with S=. |
| 34677 | .next |
| 34678 | .cindex "log" "dnslist defer" |
| 34679 | .cindex "DNS list" "logging defer" |
| 34680 | .cindex "black list (DNS)" |
| 34681 | &%dnslist_defer%&: A log entry is written if an attempt to look up a host in a |
| 34682 | DNS black list suffers a temporary error. |
| 34683 | .next |
| 34684 | .cindex "log" "ETRN commands" |
| 34685 | .cindex "ETRN" "logging" |
| 34686 | &%etrn%&: Every valid ETRN command that is received is logged, before the ACL |
| 34687 | is run to determine whether or not it is actually accepted. An invalid ETRN |
| 34688 | command, or one received within a message transaction is not logged by this |
| 34689 | selector (see &%smtp_syntax_error%& and &%smtp_protocol_error%&). |
| 34690 | .next |
| 34691 | .cindex "log" "host lookup failure" |
| 34692 | &%host_lookup_failed%&: When a lookup of a host's IP addresses fails to find |
| 34693 | any addresses, or when a lookup of an IP address fails to find a host name, a |
| 34694 | log line is written. This logging does not apply to direct DNS lookups when |
| 34695 | routing email addresses, but it does apply to &"byname"& lookups. |
| 34696 | .next |
| 34697 | .cindex "log" "ident timeout" |
| 34698 | .cindex "RFC 1413" "logging timeout" |
| 34699 | &%ident_timeout%&: A log line is written whenever an attempt to connect to a |
| 34700 | client's ident port times out. |
| 34701 | .next |
| 34702 | .cindex "log" "incoming interface" |
| 34703 | .cindex "interface" "logging" |
| 34704 | &%incoming_interface%&: The interface on which a message was received is added |
| 34705 | to the &"<="& line as an IP address in square brackets, tagged by I= and |
| 34706 | followed by a colon and the port number. The local interface and port are also |
| 34707 | added to other SMTP log lines, for example &"SMTP connection from"&, and to |
| 34708 | rejection lines. |
| 34709 | .next |
| 34710 | .cindex "log" "incoming remote port" |
| 34711 | .cindex "port" "logging remote" |
| 34712 | .cindex "TCP/IP" "logging incoming remote port" |
| 34713 | .vindex "&$sender_fullhost$&" |
| 34714 | .vindex "&$sender_rcvhost$&" |
| 34715 | &%incoming_port%&: The remote port number from which a message was received is |
| 34716 | added to log entries and &'Received:'& header lines, following the IP address |
| 34717 | in square brackets, and separated from it by a colon. This is implemented by |
| 34718 | changing the value that is put in the &$sender_fullhost$& and |
| 34719 | &$sender_rcvhost$& variables. Recording the remote port number has become more |
| 34720 | important with the widening use of NAT (see RFC 2505). |
| 34721 | .next |
| 34722 | .cindex "log" "dropped connection" |
| 34723 | &%lost_incoming_connection%&: A log line is written when an incoming SMTP |
| 34724 | connection is unexpectedly dropped. |
| 34725 | .next |
| 34726 | .cindex "log" "outgoing remote port" |
| 34727 | .cindex "port" "logging outgoint remote" |
| 34728 | .cindex "TCP/IP" "logging ougtoing remote port" |
| 34729 | &%outgoing_port%&: The remote port number is added to delivery log lines (those |
| 34730 | containing => tags) following the IP address. This option is not included in |
| 34731 | the default setting, because for most ordinary configurations, the remote port |
| 34732 | number is always 25 (the SMTP port). |
| 34733 | .next |
| 34734 | .cindex "log" "process ids in" |
| 34735 | .cindex "pid (process id)" "in log lines" |
| 34736 | &%pid%&: The current process id is added to every log line, in square brackets, |
| 34737 | immediately after the time and date. |
| 34738 | .next |
| 34739 | .cindex "log" "queue run" |
| 34740 | .cindex "queue runner" "logging" |
| 34741 | &%queue_run%&: The start and end of every queue run are logged. |
| 34742 | .next |
| 34743 | .cindex "log" "queue time" |
| 34744 | &%queue_time%&: The amount of time the message has been in the queue on the |
| 34745 | local host is logged as QT=<&'time'&> on delivery (&`=>`&) lines, for example, |
| 34746 | &`QT=3m45s`&. The clock starts when Exim starts to receive the message, so it |
| 34747 | includes reception time as well as the delivery time for the current address. |
| 34748 | This means that it may be longer than the difference between the arrival and |
| 34749 | delivery log line times, because the arrival log line is not written until the |
| 34750 | message has been successfully received. |
| 34751 | .next |
| 34752 | &%queue_time_overall%&: The amount of time the message has been in the queue on |
| 34753 | the local host is logged as QT=<&'time'&> on &"Completed"& lines, for |
| 34754 | example, &`QT=3m45s`&. The clock starts when Exim starts to receive the |
| 34755 | message, so it includes reception time as well as the total delivery time. |
| 34756 | .next |
| 34757 | .cindex "log" "recipients" |
| 34758 | &%received_recipients%&: The recipients of a message are listed in the main log |
| 34759 | as soon as the message is received. The list appears at the end of the log line |
| 34760 | that is written when a message is received, preceded by the word &"for"&. The |
| 34761 | addresses are listed after they have been qualified, but before any rewriting |
| 34762 | has taken place. |
| 34763 | Recipients that were discarded by an ACL for MAIL or RCPT do not appear |
| 34764 | in the list. |
| 34765 | .next |
| 34766 | .cindex "log" "sender reception" |
| 34767 | &%received_sender%&: The unrewritten original sender of a message is added to |
| 34768 | the end of the log line that records the message's arrival, after the word |
| 34769 | &"from"& (before the recipients if &%received_recipients%& is also set). |
| 34770 | .next |
| 34771 | .cindex "log" "header lines for rejection" |
| 34772 | &%rejected_header%&: If a message's header has been received at the time a |
| 34773 | rejection is written to the reject log, the complete header is added to the |
| 34774 | log. Header logging can be turned off individually for messages that are |
| 34775 | rejected by the &[local_scan()]& function (see section &<<SECTapiforloc>>&). |
| 34776 | .next |
| 34777 | .cindex "log" "retry defer" |
| 34778 | &%retry_defer%&: A log line is written if a delivery is deferred because a |
| 34779 | retry time has not yet been reached. However, this &"retry time not reached"& |
| 34780 | message is always omitted from individual message logs after the first delivery |
| 34781 | attempt. |
| 34782 | .next |
| 34783 | .cindex "log" "return path" |
| 34784 | &%return_path_on_delivery%&: The return path that is being transmitted with |
| 34785 | the message is included in delivery and bounce lines, using the tag P=. |
| 34786 | This is omitted if no delivery actually happens, for example, if routing fails, |
| 34787 | or if delivery is to &_/dev/null_& or to &`:blackhole:`&. |
| 34788 | .next |
| 34789 | .cindex "log" "sender on delivery" |
| 34790 | &%sender_on_delivery%&: The message's sender address is added to every delivery |
| 34791 | and bounce line, tagged by F= (for &"from"&). |
| 34792 | This is the original sender that was received with the message; it is not |
| 34793 | necessarily the same as the outgoing return path. |
| 34794 | .next |
| 34795 | .cindex "log" "sender verify failure" |
| 34796 | &%sender_verify_fail%&: If this selector is unset, the separate log line that |
| 34797 | gives details of a sender verification failure is not written. Log lines for |
| 34798 | the rejection of SMTP commands contain just &"sender verify failed"&, so some |
| 34799 | detail is lost. |
| 34800 | .next |
| 34801 | .cindex "log" "size rejection" |
| 34802 | &%size_reject%&: A log line is written whenever a message is rejected because |
| 34803 | it is too big. |
| 34804 | .next |
| 34805 | .cindex "log" "frozen messages; skipped" |
| 34806 | .cindex "frozen messages" "logging skipping" |
| 34807 | &%skip_delivery%&: A log line is written whenever a message is skipped during a |
| 34808 | queue run because it is frozen or because another process is already delivering |
| 34809 | it. |
| 34810 | .cindex "&""spool file is locked""&" |
| 34811 | The message that is written is &"spool file is locked"&. |
| 34812 | .next |
| 34813 | .cindex "log" "smtp confirmation" |
| 34814 | .cindex "SMTP" "logging confirmation" |
| 34815 | .cindex "LMTP" "logging confirmation" |
| 34816 | &%smtp_confirmation%&: The response to the final &"."& in the SMTP or LMTP dialogue for |
| 34817 | outgoing messages is added to delivery log lines in the form &`C=`&<&'text'&>. |
| 34818 | A number of MTAs (including Exim) return an identifying string in this |
| 34819 | response. |
| 34820 | .next |
| 34821 | .cindex "log" "SMTP connections" |
| 34822 | .cindex "SMTP" "logging connections" |
| 34823 | &%smtp_connection%&: A log line is written whenever an SMTP connection is |
| 34824 | established or closed, unless the connection is from a host that matches |
| 34825 | &%hosts_connection_nolog%&. (In contrast, &%lost_incoming_connection%& applies |
| 34826 | only when the closure is unexpected.) This applies to connections from local |
| 34827 | processes that use &%-bs%& as well as to TCP/IP connections. If a connection is |
| 34828 | dropped in the middle of a message, a log line is always written, whether or |
| 34829 | not this selector is set, but otherwise nothing is written at the start and end |
| 34830 | of connections unless this selector is enabled. |
| 34831 | |
| 34832 | For TCP/IP connections to an Exim daemon, the current number of connections is |
| 34833 | included in the log message for each new connection, but note that the count is |
| 34834 | reset if the daemon is restarted. |
| 34835 | Also, because connections are closed (and the closure is logged) in |
| 34836 | subprocesses, the count may not include connections that have been closed but |
| 34837 | whose termination the daemon has not yet noticed. Thus, while it is possible to |
| 34838 | match up the opening and closing of connections in the log, the value of the |
| 34839 | logged counts may not be entirely accurate. |
| 34840 | .next |
| 34841 | .cindex "log" "SMTP transaction; incomplete" |
| 34842 | .cindex "SMTP" "logging incomplete transactions" |
| 34843 | &%smtp_incomplete_transaction%&: When a mail transaction is aborted by |
| 34844 | RSET, QUIT, loss of connection, or otherwise, the incident is logged, |
| 34845 | and the message sender plus any accepted recipients are included in the log |
| 34846 | line. This can provide evidence of dictionary attacks. |
| 34847 | .next |
| 34848 | .cindex "log" "non-MAIL SMTP sessions" |
| 34849 | .cindex "MAIL" "logging session without" |
| 34850 | &%smtp_no_mail%&: A line is written to the main log whenever an accepted SMTP |
| 34851 | connection terminates without having issued a MAIL command. This includes both |
| 34852 | the case when the connection is dropped, and the case when QUIT is used. It |
| 34853 | does not include cases where the connection is rejected right at the start (by |
| 34854 | an ACL, or because there are too many connections, or whatever). These cases |
| 34855 | already have their own log lines. |
| 34856 | |
| 34857 | The log line that is written contains the identity of the client in the usual |
| 34858 | way, followed by D= and a time, which records the duration of the connection. |
| 34859 | If the connection was authenticated, this fact is logged exactly as it is for |
| 34860 | an incoming message, with an A= item. If the connection was encrypted, CV=, |
| 34861 | DN=, and X= items may appear as they do for an incoming message, controlled by |
| 34862 | the same logging options. |
| 34863 | |
| 34864 | Finally, if any SMTP commands were issued during the connection, a C= item |
| 34865 | is added to the line, listing the commands that were used. For example, |
| 34866 | .code |
| 34867 | C=EHLO,QUIT |
| 34868 | .endd |
| 34869 | shows that the client issued QUIT straight after EHLO. If there were fewer |
| 34870 | than 20 commands, they are all listed. If there were more than 20 commands, |
| 34871 | the last 20 are listed, preceded by &"..."&. However, with the default |
| 34872 | setting of 10 for &%smtp_accep_max_nonmail%&, the connection will in any case |
| 34873 | have been aborted before 20 non-mail commands are processed. |
| 34874 | .next |
| 34875 | &%smtp_mailauth%&: A third subfield with the authenticated sender, |
| 34876 | colon-separated, is appended to the A= item for a message arrival or delivery |
| 34877 | log line, if an AUTH argument to the SMTP MAIL command (see &<<SECTauthparamail>>&) |
| 34878 | was accepted or used. |
| 34879 | .next |
| 34880 | .cindex "log" "SMTP protocol error" |
| 34881 | .cindex "SMTP" "logging protocol error" |
| 34882 | &%smtp_protocol_error%&: A log line is written for every SMTP protocol error |
| 34883 | encountered. Exim does not have perfect detection of all protocol errors |
| 34884 | because of transmission delays and the use of pipelining. If PIPELINING has |
| 34885 | been advertised to a client, an Exim server assumes that the client will use |
| 34886 | it, and therefore it does not count &"expected"& errors (for example, RCPT |
| 34887 | received after rejecting MAIL) as protocol errors. |
| 34888 | .next |
| 34889 | .cindex "SMTP" "logging syntax errors" |
| 34890 | .cindex "SMTP" "syntax errors; logging" |
| 34891 | .cindex "SMTP" "unknown command; logging" |
| 34892 | .cindex "log" "unknown SMTP command" |
| 34893 | .cindex "log" "SMTP syntax error" |
| 34894 | &%smtp_syntax_error%&: A log line is written for every SMTP syntax error |
| 34895 | encountered. An unrecognized command is treated as a syntax error. For an |
| 34896 | external connection, the host identity is given; for an internal connection |
| 34897 | using &%-bs%& the sender identification (normally the calling user) is given. |
| 34898 | .next |
| 34899 | .cindex "log" "subject" |
| 34900 | .cindex "subject, logging" |
| 34901 | &%subject%&: The subject of the message is added to the arrival log line, |
| 34902 | preceded by &"T="& (T for &"topic"&, since S is already used for &"size"&). |
| 34903 | Any MIME &"words"& in the subject are decoded. The &%print_topbitchars%& option |
| 34904 | specifies whether characters with values greater than 127 should be logged |
| 34905 | unchanged, or whether they should be rendered as escape sequences. |
| 34906 | .next |
| 34907 | .cindex "log" "certificate verification" |
| 34908 | &%tls_certificate_verified%&: An extra item is added to <= and => log lines |
| 34909 | when TLS is in use. The item is &`CV=yes`& if the peer's certificate was |
| 34910 | verified, and &`CV=no`& if not. |
| 34911 | .next |
| 34912 | .cindex "log" "TLS cipher" |
| 34913 | .cindex "TLS" "logging cipher" |
| 34914 | &%tls_cipher%&: When a message is sent or received over an encrypted |
| 34915 | connection, the cipher suite used is added to the log line, preceded by X=. |
| 34916 | .next |
| 34917 | .cindex "log" "TLS peer DN" |
| 34918 | .cindex "TLS" "logging peer DN" |
| 34919 | &%tls_peerdn%&: When a message is sent or received over an encrypted |
| 34920 | connection, and a certificate is supplied by the remote host, the peer DN is |
| 34921 | added to the log line, preceded by DN=. |
| 34922 | .next |
| 34923 | .cindex "log" "TLS SNI" |
| 34924 | .cindex "TLS" "logging SNI" |
| 34925 | &%tls_sni%&: When a message is received over an encrypted connection, and |
| 34926 | the remote host provided the Server Name Indication extension, the SNI is |
| 34927 | added to the log line, preceded by SNI=. |
| 34928 | .next |
| 34929 | .cindex "log" "DNS failure in list" |
| 34930 | &%unknown_in_list%&: This setting causes a log entry to be written when the |
| 34931 | result of a list match is failure because a DNS lookup failed. |
| 34932 | .endlist |
| 34933 | |
| 34934 | |
| 34935 | .section "Message log" "SECID260" |
| 34936 | .cindex "message" "log file for" |
| 34937 | .cindex "log" "message log; description of" |
| 34938 | .cindex "&_msglog_& directory" |
| 34939 | .oindex "&%preserve_message_logs%&" |
| 34940 | In addition to the general log files, Exim writes a log file for each message |
| 34941 | that it handles. The names of these per-message logs are the message ids, and |
| 34942 | they are kept in the &_msglog_& sub-directory of the spool directory. Each |
| 34943 | message log contains copies of the log lines that apply to the message. This |
| 34944 | makes it easier to inspect the status of an individual message without having |
| 34945 | to search the main log. A message log is deleted when processing of the message |
| 34946 | is complete, unless &%preserve_message_logs%& is set, but this should be used |
| 34947 | only with great care because they can fill up your disk very quickly. |
| 34948 | |
| 34949 | On a heavily loaded system, it may be desirable to disable the use of |
| 34950 | per-message logs, in order to reduce disk I/O. This can be done by setting the |
| 34951 | &%message_logs%& option false. |
| 34952 | .ecindex IIDloggen |
| 34953 | |
| 34954 | |
| 34955 | |
| 34956 | |
| 34957 | . //////////////////////////////////////////////////////////////////////////// |
| 34958 | . //////////////////////////////////////////////////////////////////////////// |
| 34959 | |
| 34960 | .chapter "Exim utilities" "CHAPutils" |
| 34961 | .scindex IIDutils "utilities" |
| 34962 | A number of utility scripts and programs are supplied with Exim and are |
| 34963 | described in this chapter. There is also the Exim Monitor, which is covered in |
| 34964 | the next chapter. The utilities described here are: |
| 34965 | |
| 34966 | .itable none 0 0 3 7* left 15* left 40* left |
| 34967 | .irow &<<SECTfinoutwha>>& &'exiwhat'& &&& |
| 34968 | "list what Exim processes are doing" |
| 34969 | .irow &<<SECTgreptheque>>& &'exiqgrep'& "grep the queue" |
| 34970 | .irow &<<SECTsumtheque>>& &'exiqsumm'& "summarize the queue" |
| 34971 | .irow &<<SECTextspeinf>>& &'exigrep'& "search the main log" |
| 34972 | .irow &<<SECTexipick>>& &'exipick'& "select messages on &&& |
| 34973 | various criteria" |
| 34974 | .irow &<<SECTcyclogfil>>& &'exicyclog'& "cycle (rotate) log files" |
| 34975 | .irow &<<SECTmailstat>>& &'eximstats'& &&& |
| 34976 | "extract statistics from the log" |
| 34977 | .irow &<<SECTcheckaccess>>& &'exim_checkaccess'& &&& |
| 34978 | "check address acceptance from given IP" |
| 34979 | .irow &<<SECTdbmbuild>>& &'exim_dbmbuild'& "build a DBM file" |
| 34980 | .irow &<<SECTfinindret>>& &'exinext'& "extract retry information" |
| 34981 | .irow &<<SECThindatmai>>& &'exim_dumpdb'& "dump a hints database" |
| 34982 | .irow &<<SECThindatmai>>& &'exim_tidydb'& "clean up a hints database" |
| 34983 | .irow &<<SECThindatmai>>& &'exim_fixdb'& "patch a hints database" |
| 34984 | .irow &<<SECTmailboxmaint>>& &'exim_lock'& "lock a mailbox file" |
| 34985 | .endtable |
| 34986 | |
| 34987 | Another utility that might be of use to sites with many MTAs is Tom Kistner's |
| 34988 | &'exilog'&. It provides log visualizations across multiple Exim servers. See |
| 34989 | &url(http://duncanthrax.net/exilog/) for details. |
| 34990 | |
| 34991 | |
| 34992 | |
| 34993 | |
| 34994 | .section "Finding out what Exim processes are doing (exiwhat)" "SECTfinoutwha" |
| 34995 | .cindex "&'exiwhat'&" |
| 34996 | .cindex "process, querying" |
| 34997 | .cindex "SIGUSR1" |
| 34998 | On operating systems that can restart a system call after receiving a signal |
| 34999 | (most modern OS), an Exim process responds to the SIGUSR1 signal by writing |
| 35000 | a line describing what it is doing to the file &_exim-process.info_& in the |
| 35001 | Exim spool directory. The &'exiwhat'& script sends the signal to all Exim |
| 35002 | processes it can find, having first emptied the file. It then waits for one |
| 35003 | second to allow the Exim processes to react before displaying the results. In |
| 35004 | order to run &'exiwhat'& successfully you have to have sufficient privilege to |
| 35005 | send the signal to the Exim processes, so it is normally run as root. |
| 35006 | |
| 35007 | &*Warning*&: This is not an efficient process. It is intended for occasional |
| 35008 | use by system administrators. It is not sensible, for example, to set up a |
| 35009 | script that sends SIGUSR1 signals to Exim processes at short intervals. |
| 35010 | |
| 35011 | |
| 35012 | Unfortunately, the &'ps'& command that &'exiwhat'& uses to find Exim processes |
| 35013 | varies in different operating systems. Not only are different options used, |
| 35014 | but the format of the output is different. For this reason, there are some |
| 35015 | system configuration options that configure exactly how &'exiwhat'& works. If |
| 35016 | it doesn't seem to be working for you, check the following compile-time |
| 35017 | options: |
| 35018 | .display |
| 35019 | &`EXIWHAT_PS_CMD `& the command for running &'ps'& |
| 35020 | &`EXIWHAT_PS_ARG `& the argument for &'ps'& |
| 35021 | &`EXIWHAT_EGREP_ARG `& the argument for &'egrep'& to select from &'ps'& output |
| 35022 | &`EXIWHAT_KILL_ARG `& the argument for the &'kill'& command |
| 35023 | .endd |
| 35024 | An example of typical output from &'exiwhat'& is |
| 35025 | .code |
| 35026 | 164 daemon: -q1h, listening on port 25 |
| 35027 | 10483 running queue: waiting for 0tAycK-0002ij-00 (10492) |
| 35028 | 10492 delivering 0tAycK-0002ij-00 to mail.ref.example |
| 35029 | [10.19.42.42] (editor@ref.example) |
| 35030 | 10592 handling incoming call from [192.168.243.242] |
| 35031 | 10628 accepting a local non-SMTP message |
| 35032 | .endd |
| 35033 | The first number in the output line is the process number. The third line has |
| 35034 | been split here, in order to fit it on the page. |
| 35035 | |
| 35036 | |
| 35037 | |
| 35038 | .section "Selective queue listing (exiqgrep)" "SECTgreptheque" |
| 35039 | .cindex "&'exiqgrep'&" |
| 35040 | .cindex "queue" "grepping" |
| 35041 | This utility is a Perl script contributed by Matt Hubbard. It runs |
| 35042 | .code |
| 35043 | exim -bpu |
| 35044 | .endd |
| 35045 | or (in case &*-a*& switch is specified) |
| 35046 | .code |
| 35047 | exim -bp |
| 35048 | .endd |
| 35049 | .new |
| 35050 | The &*-C*& option is used to specify an alternate &_exim.conf_& which might |
| 35051 | contain alternate exim configuration the queue management might be using. |
| 35052 | .wen |
| 35053 | |
| 35054 | to obtain a queue listing, and then greps the output to select messages |
| 35055 | that match given criteria. The following selection options are available: |
| 35056 | |
| 35057 | .vlist |
| 35058 | .vitem &*-f*&&~<&'regex'&> |
| 35059 | Match the sender address using a case-insensitive search. The field that is |
| 35060 | tested is enclosed in angle brackets, so you can test for bounce messages with |
| 35061 | .code |
| 35062 | exiqgrep -f '^<>$' |
| 35063 | .endd |
| 35064 | .vitem &*-r*&&~<&'regex'&> |
| 35065 | Match a recipient address using a case-insensitve search. The field that is |
| 35066 | tested is not enclosed in angle brackets. |
| 35067 | |
| 35068 | .vitem &*-s*&&~<&'regex'&> |
| 35069 | Match against the size field. |
| 35070 | |
| 35071 | .vitem &*-y*&&~<&'seconds'&> |
| 35072 | Match messages that are younger than the given time. |
| 35073 | |
| 35074 | .vitem &*-o*&&~<&'seconds'&> |
| 35075 | Match messages that are older than the given time. |
| 35076 | |
| 35077 | .vitem &*-z*& |
| 35078 | Match only frozen messages. |
| 35079 | |
| 35080 | .vitem &*-x*& |
| 35081 | Match only non-frozen messages. |
| 35082 | .endlist |
| 35083 | |
| 35084 | The following options control the format of the output: |
| 35085 | |
| 35086 | .vlist |
| 35087 | .vitem &*-c*& |
| 35088 | Display only the count of matching messages. |
| 35089 | |
| 35090 | .vitem &*-l*& |
| 35091 | Long format &-- display the full message information as output by Exim. This is |
| 35092 | the default. |
| 35093 | |
| 35094 | .vitem &*-i*& |
| 35095 | Display message ids only. |
| 35096 | |
| 35097 | .vitem &*-b*& |
| 35098 | Brief format &-- one line per message. |
| 35099 | |
| 35100 | .vitem &*-R*& |
| 35101 | Display messages in reverse order. |
| 35102 | |
| 35103 | .vitem &*-a*& |
| 35104 | Include delivered recipients in queue listing. |
| 35105 | .endlist |
| 35106 | |
| 35107 | There is one more option, &%-h%&, which outputs a list of options. |
| 35108 | |
| 35109 | |
| 35110 | |
| 35111 | .section "Summarizing the queue (exiqsumm)" "SECTsumtheque" |
| 35112 | .cindex "&'exiqsumm'&" |
| 35113 | .cindex "queue" "summary" |
| 35114 | The &'exiqsumm'& utility is a Perl script which reads the output of &`exim |
| 35115 | -bp`& and produces a summary of the messages on the queue. Thus, you use it by |
| 35116 | running a command such as |
| 35117 | .code |
| 35118 | exim -bp | exiqsumm |
| 35119 | .endd |
| 35120 | The output consists of one line for each domain that has messages waiting for |
| 35121 | it, as in the following example: |
| 35122 | .code |
| 35123 | 3 2322 74m 66m msn.com.example |
| 35124 | .endd |
| 35125 | Each line lists the number of pending deliveries for a domain, their total |
| 35126 | volume, and the length of time that the oldest and the newest messages have |
| 35127 | been waiting. Note that the number of pending deliveries is greater than the |
| 35128 | number of messages when messages have more than one recipient. |
| 35129 | |
| 35130 | A summary line is output at the end. By default the output is sorted on the |
| 35131 | domain name, but &'exiqsumm'& has the options &%-a%& and &%-c%&, which cause |
| 35132 | the output to be sorted by oldest message and by count of messages, |
| 35133 | respectively. There are also three options that split the messages for each |
| 35134 | domain into two or more subcounts: &%-b%& separates bounce messages, &%-f%& |
| 35135 | separates frozen messages, and &%-s%& separates messages according to their |
| 35136 | sender. |
| 35137 | |
| 35138 | The output of &'exim -bp'& contains the original addresses in the message, so |
| 35139 | this also applies to the output from &'exiqsumm'&. No domains from addresses |
| 35140 | generated by aliasing or forwarding are included (unless the &%one_time%& |
| 35141 | option of the &(redirect)& router has been used to convert them into &"top |
| 35142 | level"& addresses). |
| 35143 | |
| 35144 | |
| 35145 | |
| 35146 | |
| 35147 | .section "Extracting specific information from the log (exigrep)" &&& |
| 35148 | "SECTextspeinf" |
| 35149 | .cindex "&'exigrep'&" |
| 35150 | .cindex "log" "extracts; grepping for" |
| 35151 | The &'exigrep'& utility is a Perl script that searches one or more main log |
| 35152 | files for entries that match a given pattern. When it finds a match, it |
| 35153 | extracts all the log entries for the relevant message, not just those that |
| 35154 | match the pattern. Thus, &'exigrep'& can extract complete log entries for a |
| 35155 | given message, or all mail for a given user, or for a given host, for example. |
| 35156 | The input files can be in Exim log format or syslog format. |
| 35157 | If a matching log line is not associated with a specific message, it is |
| 35158 | included in &'exigrep'&'s output without any additional lines. The usage is: |
| 35159 | .display |
| 35160 | &`exigrep [-t<`&&'n'&&`>] [-I] [-l] [-v] <`&&'pattern'&&`> [<`&&'log file'&&`>] ...`& |
| 35161 | .endd |
| 35162 | If no log file names are given on the command line, the standard input is read. |
| 35163 | |
| 35164 | The &%-t%& argument specifies a number of seconds. It adds an additional |
| 35165 | condition for message selection. Messages that are complete are shown only if |
| 35166 | they spent more than <&'n'&> seconds on the queue. |
| 35167 | |
| 35168 | By default, &'exigrep'& does case-insensitive matching. The &%-I%& option |
| 35169 | makes it case-sensitive. This may give a performance improvement when searching |
| 35170 | large log files. Without &%-I%&, the Perl pattern matches use Perl's &`/i`& |
| 35171 | option; with &%-I%& they do not. In both cases it is possible to change the |
| 35172 | case sensitivity within the pattern by using &`(?i)`& or &`(?-i)`&. |
| 35173 | |
| 35174 | The &%-l%& option means &"literal"&, that is, treat all characters in the |
| 35175 | pattern as standing for themselves. Otherwise the pattern must be a Perl |
| 35176 | regular expression. |
| 35177 | |
| 35178 | The &%-v%& option inverts the matching condition. That is, a line is selected |
| 35179 | if it does &'not'& match the pattern. |
| 35180 | |
| 35181 | If the location of a &'zcat'& command is known from the definition of |
| 35182 | ZCAT_COMMAND in &_Local/Makefile_&, &'exigrep'& automatically passes any file |
| 35183 | whose name ends in COMPRESS_SUFFIX through &'zcat'& as it searches it. |
| 35184 | |
| 35185 | |
| 35186 | .section "Selecting messages by various criteria (exipick)" "SECTexipick" |
| 35187 | .cindex "&'exipick'&" |
| 35188 | John Jetmore's &'exipick'& utility is included in the Exim distribution. It |
| 35189 | lists messages from the queue according to a variety of criteria. For details |
| 35190 | of &'exipick'&'s facilities, visit the web page at |
| 35191 | &url(http://www.exim.org/eximwiki/ToolExipickManPage) or run &'exipick'& with |
| 35192 | the &%--help%& option. |
| 35193 | |
| 35194 | |
| 35195 | .section "Cycling log files (exicyclog)" "SECTcyclogfil" |
| 35196 | .cindex "log" "cycling local files" |
| 35197 | .cindex "cycling logs" |
| 35198 | .cindex "&'exicyclog'&" |
| 35199 | The &'exicyclog'& script can be used to cycle (rotate) &'mainlog'& and |
| 35200 | &'rejectlog'& files. This is not necessary if only syslog is being used, or if |
| 35201 | you are using log files with datestamps in their names (see section |
| 35202 | &<<SECTdatlogfil>>&). Some operating systems have their own standard mechanisms |
| 35203 | for log cycling, and these can be used instead of &'exicyclog'& if preferred. |
| 35204 | There are two command line options for &'exicyclog'&: |
| 35205 | .ilist |
| 35206 | &%-k%& <&'count'&> specifies the number of log files to keep, overriding the |
| 35207 | default that is set when Exim is built. The default default is 10. |
| 35208 | .next |
| 35209 | &%-l%& <&'path'&> specifies the log file path, in the same format as Exim's |
| 35210 | &%log_file_path%& option (for example, &`/var/log/exim_%slog`&), again |
| 35211 | overriding the script's default, which is to find the setting from Exim's |
| 35212 | configuration. |
| 35213 | .endlist |
| 35214 | |
| 35215 | Each time &'exicyclog'& is run the file names get &"shuffled down"& by one. If |
| 35216 | the main log file name is &_mainlog_& (the default) then when &'exicyclog'& is |
| 35217 | run &_mainlog_& becomes &_mainlog.01_&, the previous &_mainlog.01_& becomes |
| 35218 | &_mainlog.02_& and so on, up to the limit that is set in the script or by the |
| 35219 | &%-k%& option. Log files whose numbers exceed the limit are discarded. Reject |
| 35220 | logs are handled similarly. |
| 35221 | |
| 35222 | If the limit is greater than 99, the script uses 3-digit numbers such as |
| 35223 | &_mainlog.001_&, &_mainlog.002_&, etc. If you change from a number less than 99 |
| 35224 | to one that is greater, or &'vice versa'&, you will have to fix the names of |
| 35225 | any existing log files. |
| 35226 | |
| 35227 | If no &_mainlog_& file exists, the script does nothing. Files that &"drop off"& |
| 35228 | the end are deleted. All files with numbers greater than 01 are compressed, |
| 35229 | using a compression command which is configured by the COMPRESS_COMMAND |
| 35230 | setting in &_Local/Makefile_&. It is usual to run &'exicyclog'& daily from a |
| 35231 | root &%crontab%& entry of the form |
| 35232 | .code |
| 35233 | 1 0 * * * su exim -c /usr/exim/bin/exicyclog |
| 35234 | .endd |
| 35235 | assuming you have used the name &"exim"& for the Exim user. You can run |
| 35236 | &'exicyclog'& as root if you wish, but there is no need. |
| 35237 | |
| 35238 | |
| 35239 | |
| 35240 | .section "Mail statistics (eximstats)" "SECTmailstat" |
| 35241 | .cindex "statistics" |
| 35242 | .cindex "&'eximstats'&" |
| 35243 | A Perl script called &'eximstats'& is provided for extracting statistical |
| 35244 | information from log files. The output is either plain text, or HTML. |
| 35245 | Exim log files are also supported by the &'Lire'& system produced by the |
| 35246 | LogReport Foundation &url(http://www.logreport.org). |
| 35247 | |
| 35248 | The &'eximstats'& script has been hacked about quite a bit over time. The |
| 35249 | latest version is the result of some extensive revision by Steve Campbell. A |
| 35250 | lot of information is given by default, but there are options for suppressing |
| 35251 | various parts of it. Following any options, the arguments to the script are a |
| 35252 | list of files, which should be main log files. For example: |
| 35253 | .code |
| 35254 | eximstats -nr /var/spool/exim/log/mainlog.01 |
| 35255 | .endd |
| 35256 | By default, &'eximstats'& extracts information about the number and volume of |
| 35257 | messages received from or delivered to various hosts. The information is sorted |
| 35258 | both by message count and by volume, and the top fifty hosts in each category |
| 35259 | are listed on the standard output. Similar information, based on email |
| 35260 | addresses or domains instead of hosts can be requested by means of various |
| 35261 | options. For messages delivered and received locally, similar statistics are |
| 35262 | also produced per user. |
| 35263 | |
| 35264 | The output also includes total counts and statistics about delivery errors, and |
| 35265 | histograms showing the number of messages received and deliveries made in each |
| 35266 | hour of the day. A delivery with more than one address in its envelope (for |
| 35267 | example, an SMTP transaction with more than one RCPT command) is counted |
| 35268 | as a single delivery by &'eximstats'&. |
| 35269 | |
| 35270 | Though normally more deliveries than receipts are reported (as messages may |
| 35271 | have multiple recipients), it is possible for &'eximstats'& to report more |
| 35272 | messages received than delivered, even though the queue is empty at the start |
| 35273 | and end of the period in question. If an incoming message contains no valid |
| 35274 | recipients, no deliveries are recorded for it. A bounce message is handled as |
| 35275 | an entirely separate message. |
| 35276 | |
| 35277 | &'eximstats'& always outputs a grand total summary giving the volume and number |
| 35278 | of messages received and deliveries made, and the number of hosts involved in |
| 35279 | each case. It also outputs the number of messages that were delayed (that is, |
| 35280 | not completely delivered at the first attempt), and the number that had at |
| 35281 | least one address that failed. |
| 35282 | |
| 35283 | The remainder of the output is in sections that can be independently disabled |
| 35284 | or modified by various options. It consists of a summary of deliveries by |
| 35285 | transport, histograms of messages received and delivered per time interval |
| 35286 | (default per hour), information about the time messages spent on the queue, |
| 35287 | a list of relayed messages, lists of the top fifty sending hosts, local |
| 35288 | senders, destination hosts, and destination local users by count and by volume, |
| 35289 | and a list of delivery errors that occurred. |
| 35290 | |
| 35291 | The relay information lists messages that were actually relayed, that is, they |
| 35292 | came from a remote host and were directly delivered to some other remote host, |
| 35293 | without being processed (for example, for aliasing or forwarding) locally. |
| 35294 | |
| 35295 | There are quite a few options for &'eximstats'& to control exactly what it |
| 35296 | outputs. These are documented in the Perl script itself, and can be extracted |
| 35297 | by running the command &(perldoc)& on the script. For example: |
| 35298 | .code |
| 35299 | perldoc /usr/exim/bin/eximstats |
| 35300 | .endd |
| 35301 | |
| 35302 | .section "Checking access policy (exim_checkaccess)" "SECTcheckaccess" |
| 35303 | .cindex "&'exim_checkaccess'&" |
| 35304 | .cindex "policy control" "checking access" |
| 35305 | .cindex "checking access" |
| 35306 | The &%-bh%& command line argument allows you to run a fake SMTP session with |
| 35307 | debugging output, in order to check what Exim is doing when it is applying |
| 35308 | policy controls to incoming SMTP mail. However, not everybody is sufficiently |
| 35309 | familiar with the SMTP protocol to be able to make full use of &%-bh%&, and |
| 35310 | sometimes you just want to answer the question &"Does this address have |
| 35311 | access?"& without bothering with any further details. |
| 35312 | |
| 35313 | The &'exim_checkaccess'& utility is a &"packaged"& version of &%-bh%&. It takes |
| 35314 | two arguments, an IP address and an email address: |
| 35315 | .code |
| 35316 | exim_checkaccess 10.9.8.7 A.User@a.domain.example |
| 35317 | .endd |
| 35318 | The utility runs a call to Exim with the &%-bh%& option, to test whether the |
| 35319 | given email address would be accepted in a RCPT command in a TCP/IP |
| 35320 | connection from the host with the given IP address. The output of the utility |
| 35321 | is either the word &"accepted"&, or the SMTP error response, for example: |
| 35322 | .code |
| 35323 | Rejected: |
| 35324 | 550 Relay not permitted |
| 35325 | .endd |
| 35326 | When running this test, the utility uses &`<>`& as the envelope sender address |
| 35327 | for the MAIL command, but you can change this by providing additional |
| 35328 | options. These are passed directly to the Exim command. For example, to specify |
| 35329 | that the test is to be run with the sender address &'himself@there.example'& |
| 35330 | you can use: |
| 35331 | .code |
| 35332 | exim_checkaccess 10.9.8.7 A.User@a.domain.example \ |
| 35333 | -f himself@there.example |
| 35334 | .endd |
| 35335 | Note that these additional Exim command line items must be given after the two |
| 35336 | mandatory arguments. |
| 35337 | |
| 35338 | Because the &%exim_checkaccess%& uses &%-bh%&, it does not perform callouts |
| 35339 | while running its checks. You can run checks that include callouts by using |
| 35340 | &%-bhc%&, but this is not yet available in a &"packaged"& form. |
| 35341 | |
| 35342 | |
| 35343 | |
| 35344 | .section "Making DBM files (exim_dbmbuild)" "SECTdbmbuild" |
| 35345 | .cindex "DBM" "building dbm files" |
| 35346 | .cindex "building DBM files" |
| 35347 | .cindex "&'exim_dbmbuild'&" |
| 35348 | .cindex "lower casing" |
| 35349 | .cindex "binary zero" "in lookup key" |
| 35350 | The &'exim_dbmbuild'& program reads an input file containing keys and data in |
| 35351 | the format used by the &(lsearch)& lookup (see section |
| 35352 | &<<SECTsinglekeylookups>>&). It writes a DBM file using the lower-cased alias |
| 35353 | names as keys and the remainder of the information as data. The lower-casing |
| 35354 | can be prevented by calling the program with the &%-nolc%& option. |
| 35355 | |
| 35356 | A terminating zero is included as part of the key string. This is expected by |
| 35357 | the &(dbm)& lookup type. However, if the option &%-nozero%& is given, |
| 35358 | &'exim_dbmbuild'& creates files without terminating zeroes in either the key |
| 35359 | strings or the data strings. The &(dbmnz)& lookup type can be used with such |
| 35360 | files. |
| 35361 | |
| 35362 | The program requires two arguments: the name of the input file (which can be a |
| 35363 | single hyphen to indicate the standard input), and the name of the output file. |
| 35364 | It creates the output under a temporary name, and then renames it if all went |
| 35365 | well. |
| 35366 | |
| 35367 | .cindex "USE_DB" |
| 35368 | If the native DB interface is in use (USE_DB is set in a compile-time |
| 35369 | configuration file &-- this is common in free versions of Unix) the two file |
| 35370 | names must be different, because in this mode the Berkeley DB functions create |
| 35371 | a single output file using exactly the name given. For example, |
| 35372 | .code |
| 35373 | exim_dbmbuild /etc/aliases /etc/aliases.db |
| 35374 | .endd |
| 35375 | reads the system alias file and creates a DBM version of it in |
| 35376 | &_/etc/aliases.db_&. |
| 35377 | |
| 35378 | In systems that use the &'ndbm'& routines (mostly proprietary versions of |
| 35379 | Unix), two files are used, with the suffixes &_.dir_& and &_.pag_&. In this |
| 35380 | environment, the suffixes are added to the second argument of |
| 35381 | &'exim_dbmbuild'&, so it can be the same as the first. This is also the case |
| 35382 | when the Berkeley functions are used in compatibility mode (though this is not |
| 35383 | recommended), because in that case it adds a &_.db_& suffix to the file name. |
| 35384 | |
| 35385 | If a duplicate key is encountered, the program outputs a warning, and when it |
| 35386 | finishes, its return code is 1 rather than zero, unless the &%-noduperr%& |
| 35387 | option is used. By default, only the first of a set of duplicates is used &-- |
| 35388 | this makes it compatible with &(lsearch)& lookups. There is an option |
| 35389 | &%-lastdup%& which causes it to use the data for the last duplicate instead. |
| 35390 | There is also an option &%-nowarn%&, which stops it listing duplicate keys to |
| 35391 | &%stderr%&. For other errors, where it doesn't actually make a new file, the |
| 35392 | return code is 2. |
| 35393 | |
| 35394 | |
| 35395 | |
| 35396 | |
| 35397 | .section "Finding individual retry times (exinext)" "SECTfinindret" |
| 35398 | .cindex "retry" "times" |
| 35399 | .cindex "&'exinext'&" |
| 35400 | A utility called &'exinext'& (mostly a Perl script) provides the ability to |
| 35401 | fish specific information out of the retry database. Given a mail domain (or a |
| 35402 | complete address), it looks up the hosts for that domain, and outputs any retry |
| 35403 | information for the hosts or for the domain. At present, the retry information |
| 35404 | is obtained by running &'exim_dumpdb'& (see below) and post-processing the |
| 35405 | output. For example: |
| 35406 | .code |
| 35407 | $ exinext piglet@milne.fict.example |
| 35408 | kanga.milne.example:192.168.8.1 error 146: Connection refused |
| 35409 | first failed: 21-Feb-1996 14:57:34 |
| 35410 | last tried: 21-Feb-1996 14:57:34 |
| 35411 | next try at: 21-Feb-1996 15:02:34 |
| 35412 | roo.milne.example:192.168.8.3 error 146: Connection refused |
| 35413 | first failed: 20-Jan-1996 13:12:08 |
| 35414 | last tried: 21-Feb-1996 11:42:03 |
| 35415 | next try at: 21-Feb-1996 19:42:03 |
| 35416 | past final cutoff time |
| 35417 | .endd |
| 35418 | You can also give &'exinext'& a local part, without a domain, and it |
| 35419 | will give any retry information for that local part in your default domain. |
| 35420 | A message id can be used to obtain retry information pertaining to a specific |
| 35421 | message. This exists only when an attempt to deliver a message to a remote host |
| 35422 | suffers a message-specific error (see section &<<SECToutSMTPerr>>&). |
| 35423 | &'exinext'& is not particularly efficient, but then it is not expected to be |
| 35424 | run very often. |
| 35425 | |
| 35426 | The &'exinext'& utility calls Exim to find out information such as the location |
| 35427 | of the spool directory. The utility has &%-C%& and &%-D%& options, which are |
| 35428 | passed on to the &'exim'& commands. The first specifies an alternate Exim |
| 35429 | configuration file, and the second sets macros for use within the configuration |
| 35430 | file. These features are mainly to help in testing, but might also be useful in |
| 35431 | environments where more than one configuration file is in use. |
| 35432 | |
| 35433 | |
| 35434 | |
| 35435 | .section "Hints database maintenance" "SECThindatmai" |
| 35436 | .cindex "hints database" "maintenance" |
| 35437 | .cindex "maintaining Exim's hints database" |
| 35438 | Three utility programs are provided for maintaining the DBM files that Exim |
| 35439 | uses to contain its delivery hint information. Each program requires two |
| 35440 | arguments. The first specifies the name of Exim's spool directory, and the |
| 35441 | second is the name of the database it is to operate on. These are as follows: |
| 35442 | |
| 35443 | .ilist |
| 35444 | &'retry'&: the database of retry information |
| 35445 | .next |
| 35446 | &'wait-'&<&'transport name'&>: databases of information about messages waiting |
| 35447 | for remote hosts |
| 35448 | .next |
| 35449 | &'callout'&: the callout cache |
| 35450 | .next |
| 35451 | &'ratelimit'&: the data for implementing the ratelimit ACL condition |
| 35452 | .next |
| 35453 | &'misc'&: other hints data |
| 35454 | .endlist |
| 35455 | |
| 35456 | The &'misc'& database is used for |
| 35457 | |
| 35458 | .ilist |
| 35459 | Serializing ETRN runs (when &%smtp_etrn_serialize%& is set) |
| 35460 | .next |
| 35461 | Serializing delivery to a specific host (when &%serialize_hosts%& is set in an |
| 35462 | &(smtp)& transport) |
| 35463 | .endlist |
| 35464 | |
| 35465 | |
| 35466 | |
| 35467 | .section "exim_dumpdb" "SECID261" |
| 35468 | .cindex "&'exim_dumpdb'&" |
| 35469 | The entire contents of a database are written to the standard output by the |
| 35470 | &'exim_dumpdb'& program, which has no options or arguments other than the |
| 35471 | spool and database names. For example, to dump the retry database: |
| 35472 | .code |
| 35473 | exim_dumpdb /var/spool/exim retry |
| 35474 | .endd |
| 35475 | Two lines of output are produced for each entry: |
| 35476 | .code |
| 35477 | T:mail.ref.example:192.168.242.242 146 77 Connection refused |
| 35478 | 31-Oct-1995 12:00:12 02-Nov-1995 12:21:39 02-Nov-1995 20:21:39 * |
| 35479 | .endd |
| 35480 | The first item on the first line is the key of the record. It starts with one |
| 35481 | of the letters R, or T, depending on whether it refers to a routing or |
| 35482 | transport retry. For a local delivery, the next part is the local address; for |
| 35483 | a remote delivery it is the name of the remote host, followed by its failing IP |
| 35484 | address (unless &%retry_include_ip_address%& is set false on the &(smtp)& |
| 35485 | transport). If the remote port is not the standard one (port 25), it is added |
| 35486 | to the IP address. Then there follows an error code, an additional error code, |
| 35487 | and a textual description of the error. |
| 35488 | |
| 35489 | The three times on the second line are the time of first failure, the time of |
| 35490 | the last delivery attempt, and the computed time for the next attempt. The line |
| 35491 | ends with an asterisk if the cutoff time for the last retry rule has been |
| 35492 | exceeded. |
| 35493 | |
| 35494 | Each output line from &'exim_dumpdb'& for the &'wait-xxx'& databases |
| 35495 | consists of a host name followed by a list of ids for messages that are or were |
| 35496 | waiting to be delivered to that host. If there are a very large number for any |
| 35497 | one host, continuation records, with a sequence number added to the host name, |
| 35498 | may be seen. The data in these records is often out of date, because a message |
| 35499 | may be routed to several alternative hosts, and Exim makes no effort to keep |
| 35500 | cross-references. |
| 35501 | |
| 35502 | |
| 35503 | |
| 35504 | .section "exim_tidydb" "SECID262" |
| 35505 | .cindex "&'exim_tidydb'&" |
| 35506 | The &'exim_tidydb'& utility program is used to tidy up the contents of a hints |
| 35507 | database. If run with no options, it removes all records that are more than 30 |
| 35508 | days old. The age is calculated from the date and time that the record was last |
| 35509 | updated. Note that, in the case of the retry database, it is &'not'& the time |
| 35510 | since the first delivery failure. Information about a host that has been down |
| 35511 | for more than 30 days will remain in the database, provided that the record is |
| 35512 | updated sufficiently often. |
| 35513 | |
| 35514 | The cutoff date can be altered by means of the &%-t%& option, which must be |
| 35515 | followed by a time. For example, to remove all records older than a week from |
| 35516 | the retry database: |
| 35517 | .code |
| 35518 | exim_tidydb -t 7d /var/spool/exim retry |
| 35519 | .endd |
| 35520 | Both the &'wait-xxx'& and &'retry'& databases contain items that involve |
| 35521 | message ids. In the former these appear as data in records keyed by host &-- |
| 35522 | they were messages that were waiting for that host &-- and in the latter they |
| 35523 | are the keys for retry information for messages that have suffered certain |
| 35524 | types of error. When &'exim_tidydb'& is run, a check is made to ensure that |
| 35525 | message ids in database records are those of messages that are still on the |
| 35526 | queue. Message ids for messages that no longer exist are removed from |
| 35527 | &'wait-xxx'& records, and if this leaves any records empty, they are deleted. |
| 35528 | For the &'retry'& database, records whose keys are non-existent message ids are |
| 35529 | removed. The &'exim_tidydb'& utility outputs comments on the standard output |
| 35530 | whenever it removes information from the database. |
| 35531 | |
| 35532 | Certain records are automatically removed by Exim when they are no longer |
| 35533 | needed, but others are not. For example, if all the MX hosts for a domain are |
| 35534 | down, a retry record is created for each one. If the primary MX host comes back |
| 35535 | first, its record is removed when Exim successfully delivers to it, but the |
| 35536 | records for the others remain because Exim has not tried to use those hosts. |
| 35537 | |
| 35538 | It is important, therefore, to run &'exim_tidydb'& periodically on all the |
| 35539 | hints databases. You should do this at a quiet time of day, because it requires |
| 35540 | a database to be locked (and therefore inaccessible to Exim) while it does its |
| 35541 | work. Removing records from a DBM file does not normally make the file smaller, |
| 35542 | but all the common DBM libraries are able to re-use the space that is released. |
| 35543 | After an initial phase of increasing in size, the databases normally reach a |
| 35544 | point at which they no longer get any bigger, as long as they are regularly |
| 35545 | tidied. |
| 35546 | |
| 35547 | &*Warning*&: If you never run &'exim_tidydb'&, the space used by the hints |
| 35548 | databases is likely to keep on increasing. |
| 35549 | |
| 35550 | |
| 35551 | |
| 35552 | |
| 35553 | .section "exim_fixdb" "SECID263" |
| 35554 | .cindex "&'exim_fixdb'&" |
| 35555 | The &'exim_fixdb'& program is a utility for interactively modifying databases. |
| 35556 | Its main use is for testing Exim, but it might also be occasionally useful for |
| 35557 | getting round problems in a live system. It has no options, and its interface |
| 35558 | is somewhat crude. On entry, it prompts for input with a right angle-bracket. A |
| 35559 | key of a database record can then be entered, and the data for that record is |
| 35560 | displayed. |
| 35561 | |
| 35562 | If &"d"& is typed at the next prompt, the entire record is deleted. For all |
| 35563 | except the &'retry'& database, that is the only operation that can be carried |
| 35564 | out. For the &'retry'& database, each field is output preceded by a number, and |
| 35565 | data for individual fields can be changed by typing the field number followed |
| 35566 | by new data, for example: |
| 35567 | .code |
| 35568 | > 4 951102:1000 |
| 35569 | .endd |
| 35570 | resets the time of the next delivery attempt. Time values are given as a |
| 35571 | sequence of digit pairs for year, month, day, hour, and minute. Colons can be |
| 35572 | used as optional separators. |
| 35573 | |
| 35574 | |
| 35575 | |
| 35576 | |
| 35577 | .section "Mailbox maintenance (exim_lock)" "SECTmailboxmaint" |
| 35578 | .cindex "mailbox" "maintenance" |
| 35579 | .cindex "&'exim_lock'&" |
| 35580 | .cindex "locking mailboxes" |
| 35581 | The &'exim_lock'& utility locks a mailbox file using the same algorithm as |
| 35582 | Exim. For a discussion of locking issues, see section &<<SECTopappend>>&. |
| 35583 | &'Exim_lock'& can be used to prevent any modification of a mailbox by Exim or |
| 35584 | a user agent while investigating a problem. The utility requires the name of |
| 35585 | the file as its first argument. If the locking is successful, the second |
| 35586 | argument is run as a command (using C's &[system()]& function); if there is no |
| 35587 | second argument, the value of the SHELL environment variable is used; if this |
| 35588 | is unset or empty, &_/bin/sh_& is run. When the command finishes, the mailbox |
| 35589 | is unlocked and the utility ends. The following options are available: |
| 35590 | |
| 35591 | .vlist |
| 35592 | .vitem &%-fcntl%& |
| 35593 | Use &[fcntl()]& locking on the open mailbox. |
| 35594 | |
| 35595 | .vitem &%-flock%& |
| 35596 | Use &[flock()]& locking on the open mailbox, provided the operating system |
| 35597 | supports it. |
| 35598 | |
| 35599 | .vitem &%-interval%& |
| 35600 | This must be followed by a number, which is a number of seconds; it sets the |
| 35601 | interval to sleep between retries (default 3). |
| 35602 | |
| 35603 | .vitem &%-lockfile%& |
| 35604 | Create a lock file before opening the mailbox. |
| 35605 | |
| 35606 | .vitem &%-mbx%& |
| 35607 | Lock the mailbox using MBX rules. |
| 35608 | |
| 35609 | .vitem &%-q%& |
| 35610 | Suppress verification output. |
| 35611 | |
| 35612 | .vitem &%-retries%& |
| 35613 | This must be followed by a number; it sets the number of times to try to get |
| 35614 | the lock (default 10). |
| 35615 | |
| 35616 | .vitem &%-restore_time%& |
| 35617 | This option causes &%exim_lock%& to restore the modified and read times to the |
| 35618 | locked file before exiting. This allows you to access a locked mailbox (for |
| 35619 | example, to take a backup copy) without disturbing the times that the user |
| 35620 | subsequently sees. |
| 35621 | |
| 35622 | .vitem &%-timeout%& |
| 35623 | This must be followed by a number, which is a number of seconds; it sets a |
| 35624 | timeout to be used with a blocking &[fcntl()]& lock. If it is not set (the |
| 35625 | default), a non-blocking call is used. |
| 35626 | |
| 35627 | .vitem &%-v%& |
| 35628 | Generate verbose output. |
| 35629 | .endlist |
| 35630 | |
| 35631 | If none of &%-fcntl%&, &%-flock%&, &%-lockfile%& or &%-mbx%& are given, the |
| 35632 | default is to create a lock file and also to use &[fcntl()]& locking on the |
| 35633 | mailbox, which is the same as Exim's default. The use of &%-flock%& or |
| 35634 | &%-fcntl%& requires that the file be writeable; the use of &%-lockfile%& |
| 35635 | requires that the directory containing the file be writeable. Locking by lock |
| 35636 | file does not last for ever; Exim assumes that a lock file is expired if it is |
| 35637 | more than 30 minutes old. |
| 35638 | |
| 35639 | The &%-mbx%& option can be used with either or both of &%-fcntl%& or |
| 35640 | &%-flock%&. It assumes &%-fcntl%& by default. MBX locking causes a shared lock |
| 35641 | to be taken out on the open mailbox, and an exclusive lock on the file |
| 35642 | &_/tmp/.n.m_& where &'n'& and &'m'& are the device number and inode |
| 35643 | number of the mailbox file. When the locking is released, if an exclusive lock |
| 35644 | can be obtained for the mailbox, the file in &_/tmp_& is deleted. |
| 35645 | |
| 35646 | The default output contains verification of the locking that takes place. The |
| 35647 | &%-v%& option causes some additional information to be given. The &%-q%& option |
| 35648 | suppresses all output except error messages. |
| 35649 | |
| 35650 | A command such as |
| 35651 | .code |
| 35652 | exim_lock /var/spool/mail/spqr |
| 35653 | .endd |
| 35654 | runs an interactive shell while the file is locked, whereas |
| 35655 | .display |
| 35656 | &`exim_lock -q /var/spool/mail/spqr <<End`& |
| 35657 | <&'some commands'&> |
| 35658 | &`End`& |
| 35659 | .endd |
| 35660 | runs a specific non-interactive sequence of commands while the file is locked, |
| 35661 | suppressing all verification output. A single command can be run by a command |
| 35662 | such as |
| 35663 | .code |
| 35664 | exim_lock -q /var/spool/mail/spqr \ |
| 35665 | "cp /var/spool/mail/spqr /some/where" |
| 35666 | .endd |
| 35667 | Note that if a command is supplied, it must be entirely contained within the |
| 35668 | second argument &-- hence the quotes. |
| 35669 | .ecindex IIDutils |
| 35670 | |
| 35671 | |
| 35672 | . //////////////////////////////////////////////////////////////////////////// |
| 35673 | . //////////////////////////////////////////////////////////////////////////// |
| 35674 | |
| 35675 | .chapter "The Exim monitor" "CHAPeximon" |
| 35676 | .scindex IIDeximon "Exim monitor" "description" |
| 35677 | .cindex "X-windows" |
| 35678 | .cindex "&'eximon'&" |
| 35679 | .cindex "Local/eximon.conf" |
| 35680 | .cindex "&_exim_monitor/EDITME_&" |
| 35681 | The Exim monitor is an application which displays in an X window information |
| 35682 | about the state of Exim's queue and what Exim is doing. An admin user can |
| 35683 | perform certain operations on messages from this GUI interface; however all |
| 35684 | such facilities are also available from the command line, and indeed, the |
| 35685 | monitor itself makes use of the command line to perform any actions requested. |
| 35686 | |
| 35687 | |
| 35688 | |
| 35689 | .section "Running the monitor" "SECID264" |
| 35690 | The monitor is started by running the script called &'eximon'&. This is a shell |
| 35691 | script that sets up a number of environment variables, and then runs the |
| 35692 | binary called &_eximon.bin_&. The default appearance of the monitor window can |
| 35693 | be changed by editing the &_Local/eximon.conf_& file created by editing |
| 35694 | &_exim_monitor/EDITME_&. Comments in that file describe what the various |
| 35695 | parameters are for. |
| 35696 | |
| 35697 | The parameters that get built into the &'eximon'& script can be overridden for |
| 35698 | a particular invocation by setting up environment variables of the same names, |
| 35699 | preceded by &`EXIMON_`&. For example, a shell command such as |
| 35700 | .code |
| 35701 | EXIMON_LOG_DEPTH=400 eximon |
| 35702 | .endd |
| 35703 | (in a Bourne-compatible shell) runs &'eximon'& with an overriding setting of |
| 35704 | the LOG_DEPTH parameter. If EXIMON_LOG_FILE_PATH is set in the environment, it |
| 35705 | overrides the Exim log file configuration. This makes it possible to have |
| 35706 | &'eximon'& tailing log data that is written to syslog, provided that MAIL.INFO |
| 35707 | syslog messages are routed to a file on the local host. |
| 35708 | |
| 35709 | X resources can be used to change the appearance of the window in the normal |
| 35710 | way. For example, a resource setting of the form |
| 35711 | .code |
| 35712 | Eximon*background: gray94 |
| 35713 | .endd |
| 35714 | changes the colour of the background to light grey rather than white. The |
| 35715 | stripcharts are drawn with both the data lines and the reference lines in |
| 35716 | black. This means that the reference lines are not visible when on top of the |
| 35717 | data. However, their colour can be changed by setting a resource called |
| 35718 | &"highlight"& (an odd name, but that's what the Athena stripchart widget uses). |
| 35719 | For example, if your X server is running Unix, you could set up lighter |
| 35720 | reference lines in the stripcharts by obeying |
| 35721 | .code |
| 35722 | xrdb -merge <<End |
| 35723 | Eximon*highlight: gray |
| 35724 | End |
| 35725 | .endd |
| 35726 | .cindex "admin user" |
| 35727 | In order to see the contents of messages on the queue, and to operate on them, |
| 35728 | &'eximon'& must either be run as root or by an admin user. |
| 35729 | |
| 35730 | The command-line parameters of &'eximon'& are passed to &_eximon.bin_& and may |
| 35731 | contain X11 resource parameters interpreted by the X11 library. In addition, |
| 35732 | if the first parameter starts with the string "gdb" then it is removed and the |
| 35733 | binary is invoked under gdb (the parameter is used as the gdb command-name, so |
| 35734 | versioned variants of gdb can be invoked). |
| 35735 | |
| 35736 | The monitor's window is divided into three parts. The first contains one or |
| 35737 | more stripcharts and two action buttons, the second contains a &"tail"& of the |
| 35738 | main log file, and the third is a display of the queue of messages awaiting |
| 35739 | delivery, with two more action buttons. The following sections describe these |
| 35740 | different parts of the display. |
| 35741 | |
| 35742 | |
| 35743 | |
| 35744 | |
| 35745 | .section "The stripcharts" "SECID265" |
| 35746 | .cindex "stripchart" |
| 35747 | The first stripchart is always a count of messages on the queue. Its name can |
| 35748 | be configured by setting QUEUE_STRIPCHART_NAME in the |
| 35749 | &_Local/eximon.conf_& file. The remaining stripcharts are defined in the |
| 35750 | configuration script by regular expression matches on log file entries, making |
| 35751 | it possible to display, for example, counts of messages delivered to certain |
| 35752 | hosts or using certain transports. The supplied defaults display counts of |
| 35753 | received and delivered messages, and of local and SMTP deliveries. The default |
| 35754 | period between stripchart updates is one minute; this can be adjusted by a |
| 35755 | parameter in the &_Local/eximon.conf_& file. |
| 35756 | |
| 35757 | The stripchart displays rescale themselves automatically as the value they are |
| 35758 | displaying changes. There are always 10 horizontal lines in each chart; the |
| 35759 | title string indicates the value of each division when it is greater than one. |
| 35760 | For example, &"x2"& means that each division represents a value of 2. |
| 35761 | |
| 35762 | It is also possible to have a stripchart which shows the percentage fullness of |
| 35763 | a particular disk partition, which is useful when local deliveries are confined |
| 35764 | to a single partition. |
| 35765 | |
| 35766 | .cindex "&%statvfs%& function" |
| 35767 | This relies on the availability of the &[statvfs()]& function or equivalent in |
| 35768 | the operating system. Most, but not all versions of Unix that support Exim have |
| 35769 | this. For this particular stripchart, the top of the chart always represents |
| 35770 | 100%, and the scale is given as &"x10%"&. This chart is configured by setting |
| 35771 | SIZE_STRIPCHART and (optionally) SIZE_STRIPCHART_NAME in the |
| 35772 | &_Local/eximon.conf_& file. |
| 35773 | |
| 35774 | |
| 35775 | |
| 35776 | |
| 35777 | .section "Main action buttons" "SECID266" |
| 35778 | .cindex "size" "of monitor window" |
| 35779 | .cindex "Exim monitor" "window size" |
| 35780 | .cindex "window size" |
| 35781 | Below the stripcharts there is an action button for quitting the monitor. Next |
| 35782 | to this is another button marked &"Size"&. They are placed here so that |
| 35783 | shrinking the window to its default minimum size leaves just the queue count |
| 35784 | stripchart and these two buttons visible. Pressing the &"Size"& button causes |
| 35785 | the window to expand to its maximum size, unless it is already at the maximum, |
| 35786 | in which case it is reduced to its minimum. |
| 35787 | |
| 35788 | When expanding to the maximum, if the window cannot be fully seen where it |
| 35789 | currently is, it is moved back to where it was the last time it was at full |
| 35790 | size. When it is expanding from its minimum size, the old position is |
| 35791 | remembered, and next time it is reduced to the minimum it is moved back there. |
| 35792 | |
| 35793 | The idea is that you can keep a reduced window just showing one or two |
| 35794 | stripcharts at a convenient place on your screen, easily expand it to show |
| 35795 | the full window when required, and just as easily put it back to what it was. |
| 35796 | The idea is copied from what the &'twm'& window manager does for its |
| 35797 | &'f.fullzoom'& action. The minimum size of the window can be changed by setting |
| 35798 | the MIN_HEIGHT and MIN_WIDTH values in &_Local/eximon.conf_&. |
| 35799 | |
| 35800 | Normally, the monitor starts up with the window at its full size, but it can be |
| 35801 | built so that it starts up with the window at its smallest size, by setting |
| 35802 | START_SMALL=yes in &_Local/eximon.conf_&. |
| 35803 | |
| 35804 | |
| 35805 | |
| 35806 | .section "The log display" "SECID267" |
| 35807 | .cindex "log" "tail of; in monitor" |
| 35808 | The second section of the window is an area in which a display of the tail of |
| 35809 | the main log is maintained. |
| 35810 | To save space on the screen, the timestamp on each log line is shortened by |
| 35811 | removing the date and, if &%log_timezone%& is set, the timezone. |
| 35812 | The log tail is not available when the only destination for logging data is |
| 35813 | syslog, unless the syslog lines are routed to a local file whose name is passed |
| 35814 | to &'eximon'& via the EXIMON_LOG_FILE_PATH environment variable. |
| 35815 | |
| 35816 | The log sub-window has a scroll bar at its lefthand side which can be used to |
| 35817 | move back to look at earlier text, and the up and down arrow keys also have a |
| 35818 | scrolling effect. The amount of log that is kept depends on the setting of |
| 35819 | LOG_BUFFER in &_Local/eximon.conf_&, which specifies the amount of memory |
| 35820 | to use. When this is full, the earlier 50% of data is discarded &-- this is |
| 35821 | much more efficient than throwing it away line by line. The sub-window also has |
| 35822 | a horizontal scroll bar for accessing the ends of long log lines. This is the |
| 35823 | only means of horizontal scrolling; the right and left arrow keys are not |
| 35824 | available. Text can be cut from this part of the window using the mouse in the |
| 35825 | normal way. The size of this subwindow is controlled by parameters in the |
| 35826 | configuration file &_Local/eximon.conf_&. |
| 35827 | |
| 35828 | Searches of the text in the log window can be carried out by means of the ^R |
| 35829 | and ^S keystrokes, which default to a reverse and a forward search, |
| 35830 | respectively. The search covers only the text that is displayed in the window. |
| 35831 | It cannot go further back up the log. |
| 35832 | |
| 35833 | The point from which the search starts is indicated by a caret marker. This is |
| 35834 | normally at the end of the text in the window, but can be positioned explicitly |
| 35835 | by pointing and clicking with the left mouse button, and is moved automatically |
| 35836 | by a successful search. If new text arrives in the window when it is scrolled |
| 35837 | back, the caret remains where it is, but if the window is not scrolled back, |
| 35838 | the caret is moved to the end of the new text. |
| 35839 | |
| 35840 | Pressing ^R or ^S pops up a window into which the search text can be typed. |
| 35841 | There are buttons for selecting forward or reverse searching, for carrying out |
| 35842 | the search, and for cancelling. If the &"Search"& button is pressed, the search |
| 35843 | happens and the window remains so that further searches can be done. If the |
| 35844 | &"Return"& key is pressed, a single search is done and the window is closed. If |
| 35845 | ^C is typed the search is cancelled. |
| 35846 | |
| 35847 | The searching facility is implemented using the facilities of the Athena text |
| 35848 | widget. By default this pops up a window containing both &"search"& and |
| 35849 | &"replace"& options. In order to suppress the unwanted &"replace"& portion for |
| 35850 | eximon, a modified version of the &%TextPop%& widget is distributed with Exim. |
| 35851 | However, the linkers in BSDI and HP-UX seem unable to handle an externally |
| 35852 | provided version of &%TextPop%& when the remaining parts of the text widget |
| 35853 | come from the standard libraries. The compile-time option EXIMON_TEXTPOP can be |
| 35854 | unset to cut out the modified &%TextPop%&, making it possible to build Eximon |
| 35855 | on these systems, at the expense of having unwanted items in the search popup |
| 35856 | window. |
| 35857 | |
| 35858 | |
| 35859 | |
| 35860 | .section "The queue display" "SECID268" |
| 35861 | .cindex "queue" "display in monitor" |
| 35862 | The bottom section of the monitor window contains a list of all messages that |
| 35863 | are on the queue, which includes those currently being received or delivered, |
| 35864 | as well as those awaiting delivery. The size of this subwindow is controlled by |
| 35865 | parameters in the configuration file &_Local/eximon.conf_&, and the frequency |
| 35866 | at which it is updated is controlled by another parameter in the same file &-- |
| 35867 | the default is 5 minutes, since queue scans can be quite expensive. However, |
| 35868 | there is an &"Update"& action button just above the display which can be used |
| 35869 | to force an update of the queue display at any time. |
| 35870 | |
| 35871 | When a host is down for some time, a lot of pending mail can build up for it, |
| 35872 | and this can make it hard to deal with other messages on the queue. To help |
| 35873 | with this situation there is a button next to &"Update"& called &"Hide"&. If |
| 35874 | pressed, a dialogue box called &"Hide addresses ending with"& is put up. If you |
| 35875 | type anything in here and press &"Return"&, the text is added to a chain of |
| 35876 | such texts, and if every undelivered address in a message matches at least one |
| 35877 | of the texts, the message is not displayed. |
| 35878 | |
| 35879 | If there is an address that does not match any of the texts, all the addresses |
| 35880 | are displayed as normal. The matching happens on the ends of addresses so, for |
| 35881 | example, &'cam.ac.uk'& specifies all addresses in Cambridge, while |
| 35882 | &'xxx@foo.com.example'& specifies just one specific address. When any hiding |
| 35883 | has been set up, a button called &"Unhide"& is displayed. If pressed, it |
| 35884 | cancels all hiding. Also, to ensure that hidden messages do not get forgotten, |
| 35885 | a hide request is automatically cancelled after one hour. |
| 35886 | |
| 35887 | While the dialogue box is displayed, you can't press any buttons or do anything |
| 35888 | else to the monitor window. For this reason, if you want to cut text from the |
| 35889 | queue display to use in the dialogue box, you have to do the cutting before |
| 35890 | pressing the &"Hide"& button. |
| 35891 | |
| 35892 | The queue display contains, for each unhidden queued message, the length of |
| 35893 | time it has been on the queue, the size of the message, the message id, the |
| 35894 | message sender, and the first undelivered recipient, all on one line. If it is |
| 35895 | a bounce message, the sender is shown as &"<>"&. If there is more than one |
| 35896 | recipient to which the message has not yet been delivered, subsequent ones are |
| 35897 | listed on additional lines, up to a maximum configured number, following which |
| 35898 | an ellipsis is displayed. Recipients that have already received the message are |
| 35899 | not shown. |
| 35900 | |
| 35901 | .cindex "frozen messages" "display" |
| 35902 | If a message is frozen, an asterisk is displayed at the left-hand side. |
| 35903 | |
| 35904 | The queue display has a vertical scroll bar, and can also be scrolled by means |
| 35905 | of the arrow keys. Text can be cut from it using the mouse in the normal way. |
| 35906 | The text searching facilities, as described above for the log window, are also |
| 35907 | available, but the caret is always moved to the end of the text when the queue |
| 35908 | display is updated. |
| 35909 | |
| 35910 | |
| 35911 | |
| 35912 | .section "The queue menu" "SECID269" |
| 35913 | .cindex "queue" "menu in monitor" |
| 35914 | If the &%shift%& key is held down and the left button is clicked when the mouse |
| 35915 | pointer is over the text for any message, an action menu pops up, and the first |
| 35916 | line of the queue display for the message is highlighted. This does not affect |
| 35917 | any selected text. |
| 35918 | |
| 35919 | If you want to use some other event for popping up the menu, you can set the |
| 35920 | MENU_EVENT parameter in &_Local/eximon.conf_& to change the default, or |
| 35921 | set EXIMON_MENU_EVENT in the environment before starting the monitor. The |
| 35922 | value set in this parameter is a standard X event description. For example, to |
| 35923 | run eximon using &%ctrl%& rather than &%shift%& you could use |
| 35924 | .code |
| 35925 | EXIMON_MENU_EVENT='Ctrl<Btn1Down>' eximon |
| 35926 | .endd |
| 35927 | The title of the menu is the message id, and it contains entries which act as |
| 35928 | follows: |
| 35929 | |
| 35930 | .ilist |
| 35931 | &'message log'&: The contents of the message log for the message are displayed |
| 35932 | in a new text window. |
| 35933 | .next |
| 35934 | &'headers'&: Information from the spool file that contains the envelope |
| 35935 | information and headers is displayed in a new text window. See chapter |
| 35936 | &<<CHAPspool>>& for a description of the format of spool files. |
| 35937 | .next |
| 35938 | &'body'&: The contents of the spool file containing the body of the message are |
| 35939 | displayed in a new text window. There is a default limit of 20,000 bytes to the |
| 35940 | amount of data displayed. This can be changed by setting the BODY_MAX |
| 35941 | option at compile time, or the EXIMON_BODY_MAX option at run time. |
| 35942 | .next |
| 35943 | &'deliver message'&: A call to Exim is made using the &%-M%& option to request |
| 35944 | delivery of the message. This causes an automatic thaw if the message is |
| 35945 | frozen. The &%-v%& option is also set, and the output from Exim is displayed in |
| 35946 | a new text window. The delivery is run in a separate process, to avoid holding |
| 35947 | up the monitor while the delivery proceeds. |
| 35948 | .next |
| 35949 | &'freeze message'&: A call to Exim is made using the &%-Mf%& option to request |
| 35950 | that the message be frozen. |
| 35951 | .next |
| 35952 | .cindex "thawing messages" |
| 35953 | .cindex "unfreezing messages" |
| 35954 | .cindex "frozen messages" "thawing" |
| 35955 | &'thaw message'&: A call to Exim is made using the &%-Mt%& option to request |
| 35956 | that the message be thawed. |
| 35957 | .next |
| 35958 | .cindex "delivery" "forcing failure" |
| 35959 | &'give up on msg'&: A call to Exim is made using the &%-Mg%& option to request |
| 35960 | that Exim gives up trying to deliver the message. A bounce message is generated |
| 35961 | for any remaining undelivered addresses. |
| 35962 | .next |
| 35963 | &'remove message'&: A call to Exim is made using the &%-Mrm%& option to request |
| 35964 | that the message be deleted from the system without generating a bounce |
| 35965 | message. |
| 35966 | .next |
| 35967 | &'add recipient'&: A dialog box is displayed into which a recipient address can |
| 35968 | be typed. If the address is not qualified and the QUALIFY_DOMAIN parameter |
| 35969 | is set in &_Local/eximon.conf_&, the address is qualified with that domain. |
| 35970 | Otherwise it must be entered as a fully qualified address. Pressing RETURN |
| 35971 | causes a call to Exim to be made using the &%-Mar%& option to request that an |
| 35972 | additional recipient be added to the message, unless the entry box is empty, in |
| 35973 | which case no action is taken. |
| 35974 | .next |
| 35975 | &'mark delivered'&: A dialog box is displayed into which a recipient address |
| 35976 | can be typed. If the address is not qualified and the QUALIFY_DOMAIN parameter |
| 35977 | is set in &_Local/eximon.conf_&, the address is qualified with that domain. |
| 35978 | Otherwise it must be entered as a fully qualified address. Pressing RETURN |
| 35979 | causes a call to Exim to be made using the &%-Mmd%& option to mark the given |
| 35980 | recipient address as already delivered, unless the entry box is empty, in which |
| 35981 | case no action is taken. |
| 35982 | .next |
| 35983 | &'mark all delivered'&: A call to Exim is made using the &%-Mmad%& option to |
| 35984 | mark all recipient addresses as already delivered. |
| 35985 | .next |
| 35986 | &'edit sender'&: A dialog box is displayed initialized with the current |
| 35987 | sender's address. Pressing RETURN causes a call to Exim to be made using the |
| 35988 | &%-Mes%& option to replace the sender address, unless the entry box is empty, |
| 35989 | in which case no action is taken. If you want to set an empty sender (as in |
| 35990 | bounce messages), you must specify it as &"<>"&. Otherwise, if the address is |
| 35991 | not qualified and the QUALIFY_DOMAIN parameter is set in &_Local/eximon.conf_&, |
| 35992 | the address is qualified with that domain. |
| 35993 | .endlist |
| 35994 | |
| 35995 | When a delivery is forced, a window showing the &%-v%& output is displayed. In |
| 35996 | other cases when a call to Exim is made, if there is any output from Exim (in |
| 35997 | particular, if the command fails) a window containing the command and the |
| 35998 | output is displayed. Otherwise, the results of the action are normally apparent |
| 35999 | from the log and queue displays. However, if you set ACTION_OUTPUT=yes in |
| 36000 | &_Local/eximon.conf_&, a window showing the Exim command is always opened, even |
| 36001 | if no output is generated. |
| 36002 | |
| 36003 | The queue display is automatically updated for actions such as freezing and |
| 36004 | thawing, unless ACTION_QUEUE_UPDATE=no has been set in |
| 36005 | &_Local/eximon.conf_&. In this case the &"Update"& button has to be used to |
| 36006 | force an update of the display after one of these actions. |
| 36007 | |
| 36008 | In any text window that is displayed as result of a menu action, the normal |
| 36009 | cut-and-paste facility is available, and searching can be carried out using ^R |
| 36010 | and ^S, as described above for the log tail window. |
| 36011 | .ecindex IIDeximon |
| 36012 | |
| 36013 | |
| 36014 | |
| 36015 | |
| 36016 | |
| 36017 | . //////////////////////////////////////////////////////////////////////////// |
| 36018 | . //////////////////////////////////////////////////////////////////////////// |
| 36019 | |
| 36020 | .chapter "Security considerations" "CHAPsecurity" |
| 36021 | .scindex IIDsecurcon "security" "discussion of" |
| 36022 | This chapter discusses a number of issues concerned with security, some of |
| 36023 | which are also covered in other parts of this manual. |
| 36024 | |
| 36025 | For reasons that this author does not understand, some people have promoted |
| 36026 | Exim as a &"particularly secure"& mailer. Perhaps it is because of the |
| 36027 | existence of this chapter in the documentation. However, the intent of the |
| 36028 | chapter is simply to describe the way Exim works in relation to certain |
| 36029 | security concerns, not to make any specific claims about the effectiveness of |
| 36030 | its security as compared with other MTAs. |
| 36031 | |
| 36032 | What follows is a description of the way Exim is supposed to be. Best efforts |
| 36033 | have been made to try to ensure that the code agrees with the theory, but an |
| 36034 | absence of bugs can never be guaranteed. Any that are reported will get fixed |
| 36035 | as soon as possible. |
| 36036 | |
| 36037 | |
| 36038 | .section "Building a more &""hardened""& Exim" "SECID286" |
| 36039 | .cindex "security" "build-time features" |
| 36040 | There are a number of build-time options that can be set in &_Local/Makefile_& |
| 36041 | to create Exim binaries that are &"harder"& to attack, in particular by a rogue |
| 36042 | Exim administrator who does not have the root password, or by someone who has |
| 36043 | penetrated the Exim (but not the root) account. These options are as follows: |
| 36044 | |
| 36045 | .ilist |
| 36046 | ALT_CONFIG_PREFIX can be set to a string that is required to match the |
| 36047 | start of any file names used with the &%-C%& option. When it is set, these file |
| 36048 | names are also not allowed to contain the sequence &"/../"&. (However, if the |
| 36049 | value of the &%-C%& option is identical to the value of CONFIGURE_FILE in |
| 36050 | &_Local/Makefile_&, Exim ignores &%-C%& and proceeds as usual.) There is no |
| 36051 | default setting for &%ALT_CONFIG_PREFIX%&. |
| 36052 | |
| 36053 | If the permitted configuration files are confined to a directory to |
| 36054 | which only root has access, this guards against someone who has broken |
| 36055 | into the Exim account from running a privileged Exim with an arbitrary |
| 36056 | configuration file, and using it to break into other accounts. |
| 36057 | .next |
| 36058 | |
| 36059 | If a non-trusted configuration file (i.e. not the default configuration file |
| 36060 | or one which is trusted by virtue of being listed in the TRUSTED_CONFIG_LIST |
| 36061 | file) is specified with &%-C%&, or if macros are given with &%-D%& (but see |
| 36062 | the next item), then root privilege is retained only if the caller of Exim is |
| 36063 | root. This locks out the possibility of testing a configuration using &%-C%& |
| 36064 | right through message reception and delivery, even if the caller is root. The |
| 36065 | reception works, but by that time, Exim is running as the Exim user, so when |
| 36066 | it re-execs to regain privilege for the delivery, the use of &%-C%& causes |
| 36067 | privilege to be lost. However, root can test reception and delivery using two |
| 36068 | separate commands. |
| 36069 | |
| 36070 | .next |
| 36071 | The WHITELIST_D_MACROS build option declares some macros to be safe to override |
| 36072 | with &%-D%& if the real uid is one of root, the Exim run-time user or the |
| 36073 | CONFIGURE_OWNER, if defined. The potential impact of this option is limited by |
| 36074 | requiring the run-time value supplied to &%-D%& to match a regex that errs on |
| 36075 | the restrictive side. Requiring build-time selection of safe macros is onerous |
| 36076 | but this option is intended solely as a transition mechanism to permit |
| 36077 | previously-working configurations to continue to work after release 4.73. |
| 36078 | .next |
| 36079 | If DISABLE_D_OPTION is defined, the use of the &%-D%& command line option |
| 36080 | is disabled. |
| 36081 | .next |
| 36082 | FIXED_NEVER_USERS can be set to a colon-separated list of users that are |
| 36083 | never to be used for any deliveries. This is like the &%never_users%& runtime |
| 36084 | option, but it cannot be overridden; the runtime option adds additional users |
| 36085 | to the list. The default setting is &"root"&; this prevents a non-root user who |
| 36086 | is permitted to modify the runtime file from using Exim as a way to get root. |
| 36087 | .endlist |
| 36088 | |
| 36089 | |
| 36090 | |
| 36091 | .section "Root privilege" "SECID270" |
| 36092 | .cindex "setuid" |
| 36093 | .cindex "root privilege" |
| 36094 | The Exim binary is normally setuid to root, which means that it gains root |
| 36095 | privilege (runs as root) when it starts execution. In some special cases (for |
| 36096 | example, when the daemon is not in use and there are no local deliveries), it |
| 36097 | may be possible to run Exim setuid to some user other than root. This is |
| 36098 | discussed in the next section. However, in most installations, root privilege |
| 36099 | is required for two things: |
| 36100 | |
| 36101 | .ilist |
| 36102 | To set up a socket connected to the standard SMTP port (25) when initialising |
| 36103 | the listening daemon. If Exim is run from &'inetd'&, this privileged action is |
| 36104 | not required. |
| 36105 | .next |
| 36106 | To be able to change uid and gid in order to read users' &_.forward_& files and |
| 36107 | perform local deliveries as the receiving user or as specified in the |
| 36108 | configuration. |
| 36109 | .endlist |
| 36110 | |
| 36111 | It is not necessary to be root to do any of the other things Exim does, such as |
| 36112 | receiving messages and delivering them externally over SMTP, and it is |
| 36113 | obviously more secure if Exim does not run as root except when necessary. |
| 36114 | For this reason, a user and group for Exim to use must be defined in |
| 36115 | &_Local/Makefile_&. These are known as &"the Exim user"& and &"the Exim |
| 36116 | group"&. Their values can be changed by the run time configuration, though this |
| 36117 | is not recommended. Often a user called &'exim'& is used, but some sites use |
| 36118 | &'mail'& or another user name altogether. |
| 36119 | |
| 36120 | Exim uses &[setuid()]& whenever it gives up root privilege. This is a permanent |
| 36121 | abdication; the process cannot regain root afterwards. Prior to release 4.00, |
| 36122 | &[seteuid()]& was used in some circumstances, but this is no longer the case. |
| 36123 | |
| 36124 | After a new Exim process has interpreted its command line options, it changes |
| 36125 | uid and gid in the following cases: |
| 36126 | |
| 36127 | .ilist |
| 36128 | .oindex "&%-C%&" |
| 36129 | .oindex "&%-D%&" |
| 36130 | If the &%-C%& option is used to specify an alternate configuration file, or if |
| 36131 | the &%-D%& option is used to define macro values for the configuration, and the |
| 36132 | calling process is not running as root, the uid and gid are changed to those of |
| 36133 | the calling process. |
| 36134 | However, if DISABLE_D_OPTION is defined in &_Local/Makefile_&, the &%-D%& |
| 36135 | option may not be used at all. |
| 36136 | If WHITELIST_D_MACROS is defined in &_Local/Makefile_&, then some macro values |
| 36137 | can be supplied if the calling process is running as root, the Exim run-time |
| 36138 | user or CONFIGURE_OWNER, if defined. |
| 36139 | .next |
| 36140 | .oindex "&%-be%&" |
| 36141 | .oindex "&%-bf%&" |
| 36142 | .oindex "&%-bF%&" |
| 36143 | If the expansion test option (&%-be%&) or one of the filter testing options |
| 36144 | (&%-bf%& or &%-bF%&) are used, the uid and gid are changed to those of the |
| 36145 | calling process. |
| 36146 | .next |
| 36147 | If the process is not a daemon process or a queue runner process or a delivery |
| 36148 | process or a process for testing address routing (started with &%-bt%&), the |
| 36149 | uid and gid are changed to the Exim user and group. This means that Exim always |
| 36150 | runs under its own uid and gid when receiving messages. This also applies when |
| 36151 | testing address verification |
| 36152 | .oindex "&%-bv%&" |
| 36153 | .oindex "&%-bh%&" |
| 36154 | (the &%-bv%& option) and testing incoming message policy controls (the &%-bh%& |
| 36155 | option). |
| 36156 | .next |
| 36157 | For a daemon, queue runner, delivery, or address testing process, the uid |
| 36158 | remains as root at this stage, but the gid is changed to the Exim group. |
| 36159 | .endlist |
| 36160 | |
| 36161 | The processes that initially retain root privilege behave as follows: |
| 36162 | |
| 36163 | .ilist |
| 36164 | A daemon process changes the gid to the Exim group and the uid to the Exim |
| 36165 | user after setting up one or more listening sockets. The &[initgroups()]& |
| 36166 | function is called, so that if the Exim user is in any additional groups, they |
| 36167 | will be used during message reception. |
| 36168 | .next |
| 36169 | A queue runner process retains root privilege throughout its execution. Its |
| 36170 | job is to fork a controlled sequence of delivery processes. |
| 36171 | .next |
| 36172 | A delivery process retains root privilege throughout most of its execution, |
| 36173 | but any actual deliveries (that is, the transports themselves) are run in |
| 36174 | subprocesses which always change to a non-root uid and gid. For local |
| 36175 | deliveries this is typically the uid and gid of the owner of the mailbox; for |
| 36176 | remote deliveries, the Exim uid and gid are used. Once all the delivery |
| 36177 | subprocesses have been run, a delivery process changes to the Exim uid and gid |
| 36178 | while doing post-delivery tidying up such as updating the retry database and |
| 36179 | generating bounce and warning messages. |
| 36180 | |
| 36181 | While the recipient addresses in a message are being routed, the delivery |
| 36182 | process runs as root. However, if a user's filter file has to be processed, |
| 36183 | this is done in a subprocess that runs under the individual user's uid and |
| 36184 | gid. A system filter is run as root unless &%system_filter_user%& is set. |
| 36185 | .next |
| 36186 | A process that is testing addresses (the &%-bt%& option) runs as root so that |
| 36187 | the routing is done in the same environment as a message delivery. |
| 36188 | .endlist |
| 36189 | |
| 36190 | |
| 36191 | |
| 36192 | |
| 36193 | .section "Running Exim without privilege" "SECTrunexiwitpri" |
| 36194 | .cindex "privilege, running without" |
| 36195 | .cindex "unprivileged running" |
| 36196 | .cindex "root privilege" "running without" |
| 36197 | Some installations like to run Exim in an unprivileged state for more of its |
| 36198 | operation, for added security. Support for this mode of operation is provided |
| 36199 | by the global option &%deliver_drop_privilege%&. When this is set, the uid and |
| 36200 | gid are changed to the Exim user and group at the start of a delivery process |
| 36201 | (and also queue runner and address testing processes). This means that address |
| 36202 | routing is no longer run as root, and the deliveries themselves cannot change |
| 36203 | to any other uid. |
| 36204 | |
| 36205 | .cindex SIGHUP |
| 36206 | .cindex "daemon" "restarting" |
| 36207 | Leaving the binary setuid to root, but setting &%deliver_drop_privilege%& means |
| 36208 | that the daemon can still be started in the usual way, and it can respond |
| 36209 | correctly to SIGHUP because the re-invocation regains root privilege. |
| 36210 | |
| 36211 | An alternative approach is to make Exim setuid to the Exim user and also setgid |
| 36212 | to the Exim group. If you do this, the daemon must be started from a root |
| 36213 | process. (Calling Exim from a root process makes it behave in the way it does |
| 36214 | when it is setuid root.) However, the daemon cannot restart itself after a |
| 36215 | SIGHUP signal because it cannot regain privilege. |
| 36216 | |
| 36217 | It is still useful to set &%deliver_drop_privilege%& in this case, because it |
| 36218 | stops Exim from trying to re-invoke itself to do a delivery after a message has |
| 36219 | been received. Such a re-invocation is a waste of resources because it has no |
| 36220 | effect. |
| 36221 | |
| 36222 | If restarting the daemon is not an issue (for example, if &%mua_wrapper%& is |
| 36223 | set, or &'inetd'& is being used instead of a daemon), having the binary setuid |
| 36224 | to the Exim user seems a clean approach, but there is one complication: |
| 36225 | |
| 36226 | In this style of operation, Exim is running with the real uid and gid set to |
| 36227 | those of the calling process, and the effective uid/gid set to Exim's values. |
| 36228 | Ideally, any association with the calling process' uid/gid should be dropped, |
| 36229 | that is, the real uid/gid should be reset to the effective values so as to |
| 36230 | discard any privileges that the caller may have. While some operating systems |
| 36231 | have a function that permits this action for a non-root effective uid, quite a |
| 36232 | number of them do not. Because of this lack of standardization, Exim does not |
| 36233 | address this problem at this time. |
| 36234 | |
| 36235 | For this reason, the recommended approach for &"mostly unprivileged"& running |
| 36236 | is to keep the Exim binary setuid to root, and to set |
| 36237 | &%deliver_drop_privilege%&. This also has the advantage of allowing a daemon to |
| 36238 | be used in the most straightforward way. |
| 36239 | |
| 36240 | If you configure Exim not to run delivery processes as root, there are a |
| 36241 | number of restrictions on what you can do: |
| 36242 | |
| 36243 | .ilist |
| 36244 | You can deliver only as the Exim user/group. You should explicitly use the |
| 36245 | &%user%& and &%group%& options to override routers or local transports that |
| 36246 | normally deliver as the recipient. This makes sure that configurations that |
| 36247 | work in this mode function the same way in normal mode. Any implicit or |
| 36248 | explicit specification of another user causes an error. |
| 36249 | .next |
| 36250 | Use of &_.forward_& files is severely restricted, such that it is usually |
| 36251 | not worthwhile to include them in the configuration. |
| 36252 | .next |
| 36253 | Users who wish to use &_.forward_& would have to make their home directory and |
| 36254 | the file itself accessible to the Exim user. Pipe and append-to-file entries, |
| 36255 | and their equivalents in Exim filters, cannot be used. While they could be |
| 36256 | enabled in the Exim user's name, that would be insecure and not very useful. |
| 36257 | .next |
| 36258 | Unless the local user mailboxes are all owned by the Exim user (possible in |
| 36259 | some POP3 or IMAP-only environments): |
| 36260 | |
| 36261 | .olist |
| 36262 | They must be owned by the Exim group and be writeable by that group. This |
| 36263 | implies you must set &%mode%& in the appendfile configuration, as well as the |
| 36264 | mode of the mailbox files themselves. |
| 36265 | .next |
| 36266 | You must set &%no_check_owner%&, since most or all of the files will not be |
| 36267 | owned by the Exim user. |
| 36268 | .next |
| 36269 | You must set &%file_must_exist%&, because Exim cannot set the owner correctly |
| 36270 | on a newly created mailbox when unprivileged. This also implies that new |
| 36271 | mailboxes need to be created manually. |
| 36272 | .endlist olist |
| 36273 | .endlist ilist |
| 36274 | |
| 36275 | |
| 36276 | These restrictions severely restrict what can be done in local deliveries. |
| 36277 | However, there are no restrictions on remote deliveries. If you are running a |
| 36278 | gateway host that does no local deliveries, setting &%deliver_drop_privilege%& |
| 36279 | gives more security at essentially no cost. |
| 36280 | |
| 36281 | If you are using the &%mua_wrapper%& facility (see chapter |
| 36282 | &<<CHAPnonqueueing>>&), &%deliver_drop_privilege%& is forced to be true. |
| 36283 | |
| 36284 | |
| 36285 | |
| 36286 | |
| 36287 | .section "Delivering to local files" "SECID271" |
| 36288 | Full details of the checks applied by &(appendfile)& before it writes to a file |
| 36289 | are given in chapter &<<CHAPappendfile>>&. |
| 36290 | |
| 36291 | |
| 36292 | |
| 36293 | .section "Running local commands" "SECTsecconslocalcmds" |
| 36294 | .cindex "security" "local commands" |
| 36295 | .cindex "security" "command injection attacks" |
| 36296 | There are a number of ways in which an administrator can configure Exim to run |
| 36297 | commands based upon received, untrustworthy, data. Further, in some |
| 36298 | configurations a user who can control a &_.forward_& file can also arrange to |
| 36299 | run commands. Configuration to check includes, but is not limited to: |
| 36300 | |
| 36301 | .ilist |
| 36302 | Use of &%use_shell%& in the pipe transport: various forms of shell command |
| 36303 | injection may be possible with this option present. It is dangerous and should |
| 36304 | be used only with considerable caution. Consider constraints which whitelist |
| 36305 | allowed characters in a variable which is to be used in a pipe transport that |
| 36306 | has &%use_shell%& enabled. |
| 36307 | .next |
| 36308 | A number of options such as &%forbid_filter_run%&, &%forbid_filter_perl%&, |
| 36309 | &%forbid_filter_dlfunc%& and so forth which restrict facilities available to |
| 36310 | &_.forward_& files in a redirect router. If Exim is running on a central mail |
| 36311 | hub to which ordinary users do not have shell access, but home directories are |
| 36312 | NFS mounted (for instance) then administrators should review the list of these |
| 36313 | forbid options available, and should bear in mind that the options that may |
| 36314 | need forbidding can change as new features are added between releases. |
| 36315 | .next |
| 36316 | The &%${run...}%& expansion item does not use a shell by default, but |
| 36317 | administrators can configure use of &_/bin/sh_& as part of the command. |
| 36318 | Such invocations should be viewed with prejudicial suspicion. |
| 36319 | .next |
| 36320 | Administrators who use embedded Perl are advised to explore how Perl's |
| 36321 | taint checking might apply to their usage. |
| 36322 | .next |
| 36323 | Use of &%${expand...}%& is somewhat analagous to shell's eval builtin and |
| 36324 | administrators are well advised to view its use with suspicion, in case (for |
| 36325 | instance) it allows a local-part to contain embedded Exim directives. |
| 36326 | .next |
| 36327 | Use of &%${match_local_part...}%& and friends becomes more dangerous if |
| 36328 | Exim was built with EXPAND_LISTMATCH_RHS defined: the second string in |
| 36329 | each can reference arbitrary lists and files, rather than just being a list |
| 36330 | of opaque strings. |
| 36331 | The EXPAND_LISTMATCH_RHS option was added and set false by default because of |
| 36332 | real-world security vulnerabilities caused by its use with untrustworthy data |
| 36333 | injected in, for SQL injection attacks. |
| 36334 | Consider the use of the &%inlisti%& expansion condition instead. |
| 36335 | .endlist |
| 36336 | |
| 36337 | |
| 36338 | |
| 36339 | |
| 36340 | .section "Trust in configuration data" "SECTsecconfdata" |
| 36341 | .cindex "security" "data sources" |
| 36342 | .cindex "security" "regular expressions" |
| 36343 | .cindex "regular expressions" "security" |
| 36344 | .cindex "PCRE" "security" |
| 36345 | If configuration data for Exim can come from untrustworthy sources, there |
| 36346 | are some issues to be aware of: |
| 36347 | |
| 36348 | .ilist |
| 36349 | Use of &%${expand...}%& may provide a path for shell injection attacks. |
| 36350 | .next |
| 36351 | Letting untrusted data provide a regular expression is unwise. |
| 36352 | .next |
| 36353 | Using &%${match...}%& to apply a fixed regular expression against untrusted |
| 36354 | data may result in pathological behaviour within PCRE. Be aware of what |
| 36355 | "backtracking" means and consider options for being more strict with a regular |
| 36356 | expression. Avenues to explore include limiting what can match (avoiding &`.`& |
| 36357 | when &`[a-z0-9]`& or other character class will do), use of atomic grouping and |
| 36358 | possessive quantifiers or just not using regular expressions against untrusted |
| 36359 | data. |
| 36360 | .next |
| 36361 | It can be important to correctly use &%${quote:...}%&, |
| 36362 | &%${quote_local_part:...}%& and &%${quote_%&<&'lookup-type'&>&%:...}%& expansion |
| 36363 | items to ensure that data is correctly constructed. |
| 36364 | .next |
| 36365 | Some lookups might return multiple results, even though normal usage is only |
| 36366 | expected to yield one result. |
| 36367 | .endlist |
| 36368 | |
| 36369 | |
| 36370 | |
| 36371 | |
| 36372 | .section "IPv4 source routing" "SECID272" |
| 36373 | .cindex "source routing" "in IP packets" |
| 36374 | .cindex "IP source routing" |
| 36375 | Many operating systems suppress IP source-routed packets in the kernel, but |
| 36376 | some cannot be made to do this, so Exim does its own check. It logs incoming |
| 36377 | IPv4 source-routed TCP calls, and then drops them. Things are all different in |
| 36378 | IPv6. No special checking is currently done. |
| 36379 | |
| 36380 | |
| 36381 | |
| 36382 | .section "The VRFY, EXPN, and ETRN commands in SMTP" "SECID273" |
| 36383 | Support for these SMTP commands is disabled by default. If required, they can |
| 36384 | be enabled by defining suitable ACLs. |
| 36385 | |
| 36386 | |
| 36387 | |
| 36388 | |
| 36389 | .section "Privileged users" "SECID274" |
| 36390 | .cindex "trusted users" |
| 36391 | .cindex "admin user" |
| 36392 | .cindex "privileged user" |
| 36393 | .cindex "user" "trusted" |
| 36394 | .cindex "user" "admin" |
| 36395 | Exim recognizes two sets of users with special privileges. Trusted users are |
| 36396 | able to submit new messages to Exim locally, but supply their own sender |
| 36397 | addresses and information about a sending host. For other users submitting |
| 36398 | local messages, Exim sets up the sender address from the uid, and doesn't |
| 36399 | permit a remote host to be specified. |
| 36400 | |
| 36401 | .oindex "&%-f%&" |
| 36402 | However, an untrusted user is permitted to use the &%-f%& command line option |
| 36403 | in the special form &%-f <>%& to indicate that a delivery failure for the |
| 36404 | message should not cause an error report. This affects the message's envelope, |
| 36405 | but it does not affect the &'Sender:'& header. Untrusted users may also be |
| 36406 | permitted to use specific forms of address with the &%-f%& option by setting |
| 36407 | the &%untrusted_set_sender%& option. |
| 36408 | |
| 36409 | Trusted users are used to run processes that receive mail messages from some |
| 36410 | other mail domain and pass them on to Exim for delivery either locally, or over |
| 36411 | the Internet. Exim trusts a caller that is running as root, as the Exim user, |
| 36412 | as any user listed in the &%trusted_users%& configuration option, or under any |
| 36413 | group listed in the &%trusted_groups%& option. |
| 36414 | |
| 36415 | Admin users are permitted to do things to the messages on Exim's queue. They |
| 36416 | can freeze or thaw messages, cause them to be returned to their senders, remove |
| 36417 | them entirely, or modify them in various ways. In addition, admin users can run |
| 36418 | the Exim monitor and see all the information it is capable of providing, which |
| 36419 | includes the contents of files on the spool. |
| 36420 | |
| 36421 | .oindex "&%-M%&" |
| 36422 | .oindex "&%-q%&" |
| 36423 | By default, the use of the &%-M%& and &%-q%& options to cause Exim to attempt |
| 36424 | delivery of messages on its queue is restricted to admin users. This |
| 36425 | restriction can be relaxed by setting the &%no_prod_requires_admin%& option. |
| 36426 | Similarly, the use of &%-bp%& (and its variants) to list the contents of the |
| 36427 | queue is also restricted to admin users. This restriction can be relaxed by |
| 36428 | setting &%no_queue_list_requires_admin%&. |
| 36429 | |
| 36430 | Exim recognizes an admin user if the calling process is running as root or as |
| 36431 | the Exim user or if any of the groups associated with the calling process is |
| 36432 | the Exim group. It is not necessary actually to be running under the Exim |
| 36433 | group. However, if admin users who are not root or the Exim user are to access |
| 36434 | the contents of files on the spool via the Exim monitor (which runs |
| 36435 | unprivileged), Exim must be built to allow group read access to its spool |
| 36436 | files. |
| 36437 | |
| 36438 | |
| 36439 | |
| 36440 | .section "Spool files" "SECID275" |
| 36441 | .cindex "spool directory" "files" |
| 36442 | Exim's spool directory and everything it contains is owned by the Exim user and |
| 36443 | set to the Exim group. The mode for spool files is defined in the |
| 36444 | &_Local/Makefile_& configuration file, and defaults to 0640. This means that |
| 36445 | any user who is a member of the Exim group can access these files. |
| 36446 | |
| 36447 | |
| 36448 | |
| 36449 | .section "Use of argv[0]" "SECID276" |
| 36450 | Exim examines the last component of &%argv[0]%&, and if it matches one of a set |
| 36451 | of specific strings, Exim assumes certain options. For example, calling Exim |
| 36452 | with the last component of &%argv[0]%& set to &"rsmtp"& is exactly equivalent |
| 36453 | to calling it with the option &%-bS%&. There are no security implications in |
| 36454 | this. |
| 36455 | |
| 36456 | |
| 36457 | |
| 36458 | .section "Use of %f formatting" "SECID277" |
| 36459 | The only use made of &"%f"& by Exim is in formatting load average values. These |
| 36460 | are actually stored in integer variables as 1000 times the load average. |
| 36461 | Consequently, their range is limited and so therefore is the length of the |
| 36462 | converted output. |
| 36463 | |
| 36464 | |
| 36465 | |
| 36466 | .section "Embedded Exim path" "SECID278" |
| 36467 | Exim uses its own path name, which is embedded in the code, only when it needs |
| 36468 | to re-exec in order to regain root privilege. Therefore, it is not root when it |
| 36469 | does so. If some bug allowed the path to get overwritten, it would lead to an |
| 36470 | arbitrary program's being run as exim, not as root. |
| 36471 | |
| 36472 | |
| 36473 | |
| 36474 | .section "Dynamic module directory" "SECTdynmoddir" |
| 36475 | Any dynamically loadable modules must be installed into the directory |
| 36476 | defined in &`LOOKUP_MODULE_DIR`& in &_Local/Makefile_& for Exim to permit |
| 36477 | loading it. |
| 36478 | |
| 36479 | |
| 36480 | .section "Use of sprintf()" "SECID279" |
| 36481 | .cindex "&[sprintf()]&" |
| 36482 | A large number of occurrences of &"sprintf"& in the code are actually calls to |
| 36483 | &'string_sprintf()'&, a function that returns the result in malloc'd store. |
| 36484 | The intermediate formatting is done into a large fixed buffer by a function |
| 36485 | that runs through the format string itself, and checks the length of each |
| 36486 | conversion before performing it, thus preventing buffer overruns. |
| 36487 | |
| 36488 | The remaining uses of &[sprintf()]& happen in controlled circumstances where |
| 36489 | the output buffer is known to be sufficiently long to contain the converted |
| 36490 | string. |
| 36491 | |
| 36492 | |
| 36493 | |
| 36494 | .section "Use of debug_printf() and log_write()" "SECID280" |
| 36495 | Arbitrary strings are passed to both these functions, but they do their |
| 36496 | formatting by calling the function &'string_vformat()'&, which runs through |
| 36497 | the format string itself, and checks the length of each conversion. |
| 36498 | |
| 36499 | |
| 36500 | |
| 36501 | .section "Use of strcat() and strcpy()" "SECID281" |
| 36502 | These are used only in cases where the output buffer is known to be large |
| 36503 | enough to hold the result. |
| 36504 | .ecindex IIDsecurcon |
| 36505 | |
| 36506 | |
| 36507 | |
| 36508 | |
| 36509 | . //////////////////////////////////////////////////////////////////////////// |
| 36510 | . //////////////////////////////////////////////////////////////////////////// |
| 36511 | |
| 36512 | .chapter "Format of spool files" "CHAPspool" |
| 36513 | .scindex IIDforspo1 "format" "spool files" |
| 36514 | .scindex IIDforspo2 "spool directory" "format of files" |
| 36515 | .scindex IIDforspo3 "spool files" "format of" |
| 36516 | .cindex "spool files" "editing" |
| 36517 | A message on Exim's queue consists of two files, whose names are the message id |
| 36518 | followed by -D and -H, respectively. The data portion of the message is kept in |
| 36519 | the -D file on its own. The message's envelope, status, and headers are all |
| 36520 | kept in the -H file, whose format is described in this chapter. Each of these |
| 36521 | two files contains the final component of its own name as its first line. This |
| 36522 | is insurance against disk crashes where the directory is lost but the files |
| 36523 | themselves are recoverable. |
| 36524 | |
| 36525 | Some people are tempted into editing -D files in order to modify messages. You |
| 36526 | need to be extremely careful if you do this; it is not recommended and you are |
| 36527 | on your own if you do it. Here are some of the pitfalls: |
| 36528 | |
| 36529 | .ilist |
| 36530 | You must ensure that Exim does not try to deliver the message while you are |
| 36531 | fiddling with it. The safest way is to take out a write lock on the -D file, |
| 36532 | which is what Exim itself does, using &[fcntl()]&. If you update the file in |
| 36533 | place, the lock will be retained. If you write a new file and rename it, the |
| 36534 | lock will be lost at the instant of rename. |
| 36535 | .next |
| 36536 | .vindex "&$body_linecount$&" |
| 36537 | If you change the number of lines in the file, the value of |
| 36538 | &$body_linecount$&, which is stored in the -H file, will be incorrect. At |
| 36539 | present, this value is not used by Exim, but there is no guarantee that this |
| 36540 | will always be the case. |
| 36541 | .next |
| 36542 | If the message is in MIME format, you must take care not to break it. |
| 36543 | .next |
| 36544 | If the message is cryptographically signed, any change will invalidate the |
| 36545 | signature. |
| 36546 | .endlist |
| 36547 | All in all, modifying -D files is fraught with danger. |
| 36548 | |
| 36549 | Files whose names end with -J may also be seen in the &_input_& directory (or |
| 36550 | its subdirectories when &%split_spool_directory%& is set). These are journal |
| 36551 | files, used to record addresses to which the message has been delivered during |
| 36552 | the course of a delivery attempt. If there are still undelivered recipients at |
| 36553 | the end, the -H file is updated, and the -J file is deleted. If, however, there |
| 36554 | is some kind of crash (for example, a power outage) before this happens, the -J |
| 36555 | file remains in existence. When Exim next processes the message, it notices the |
| 36556 | -J file and uses it to update the -H file before starting the next delivery |
| 36557 | attempt. |
| 36558 | |
| 36559 | .section "Format of the -H file" "SECID282" |
| 36560 | .cindex "uid (user id)" "in spool file" |
| 36561 | .cindex "gid (group id)" "in spool file" |
| 36562 | The second line of the -H file contains the login name for the uid of the |
| 36563 | process that called Exim to read the message, followed by the numerical uid and |
| 36564 | gid. For a locally generated message, this is normally the user who sent the |
| 36565 | message. For a message received over TCP/IP via the daemon, it is |
| 36566 | normally the Exim user. |
| 36567 | |
| 36568 | The third line of the file contains the address of the message's sender as |
| 36569 | transmitted in the envelope, contained in angle brackets. The sender address is |
| 36570 | empty for bounce messages. For incoming SMTP mail, the sender address is given |
| 36571 | in the MAIL command. For locally generated mail, the sender address is |
| 36572 | created by Exim from the login name of the current user and the configured |
| 36573 | &%qualify_domain%&. However, this can be overridden by the &%-f%& option or a |
| 36574 | leading &"From&~"& line if the caller is trusted, or if the supplied address is |
| 36575 | &"<>"& or an address that matches &%untrusted_set_senders%&. |
| 36576 | |
| 36577 | The fourth line contains two numbers. The first is the time that the message |
| 36578 | was received, in the conventional Unix form &-- the number of seconds since the |
| 36579 | start of the epoch. The second number is a count of the number of messages |
| 36580 | warning of delayed delivery that have been sent to the sender. |
| 36581 | |
| 36582 | There follow a number of lines starting with a hyphen. These can appear in any |
| 36583 | order, and are omitted when not relevant: |
| 36584 | |
| 36585 | .vlist |
| 36586 | .vitem "&%-acl%&&~<&'number'&>&~<&'length'&>" |
| 36587 | This item is obsolete, and is not generated from Exim release 4.61 onwards; |
| 36588 | &%-aclc%& and &%-aclm%& are used instead. However, &%-acl%& is still |
| 36589 | recognized, to provide backward compatibility. In the old format, a line of |
| 36590 | this form is present for every ACL variable that is not empty. The number |
| 36591 | identifies the variable; the &%acl_c%&&*x*& variables are numbered 0&--9 and |
| 36592 | the &%acl_m%&&*x*& variables are numbered 10&--19. The length is the length of |
| 36593 | the data string for the variable. The string itself starts at the beginning of |
| 36594 | the next line, and is followed by a newline character. It may contain internal |
| 36595 | newlines. |
| 36596 | |
| 36597 | .vitem "&%-aclc%&&~<&'rest-of-name'&>&~<&'length'&>" |
| 36598 | A line of this form is present for every ACL connection variable that is |
| 36599 | defined. Note that there is a space between &%-aclc%& and the rest of the name. |
| 36600 | The length is the length of the data string for the variable. The string itself |
| 36601 | starts at the beginning of the next line, and is followed by a newline |
| 36602 | character. It may contain internal newlines. |
| 36603 | |
| 36604 | .vitem "&%-aclm%&&~<&'rest-of-name'&>&~<&'length'&>" |
| 36605 | A line of this form is present for every ACL message variable that is defined. |
| 36606 | Note that there is a space between &%-aclm%& and the rest of the name. The |
| 36607 | length is the length of the data string for the variable. The string itself |
| 36608 | starts at the beginning of the next line, and is followed by a newline |
| 36609 | character. It may contain internal newlines. |
| 36610 | |
| 36611 | .vitem "&%-active_hostname%&&~<&'hostname'&>" |
| 36612 | This is present if, when the message was received over SMTP, the value of |
| 36613 | &$smtp_active_hostname$& was different to the value of &$primary_hostname$&. |
| 36614 | |
| 36615 | .vitem &%-allow_unqualified_recipient%& |
| 36616 | This is present if unqualified recipient addresses are permitted in header |
| 36617 | lines (to stop such addresses from being qualified if rewriting occurs at |
| 36618 | transport time). Local messages that were input using &%-bnq%& and remote |
| 36619 | messages from hosts that match &%recipient_unqualified_hosts%& set this flag. |
| 36620 | |
| 36621 | .vitem &%-allow_unqualified_sender%& |
| 36622 | This is present if unqualified sender addresses are permitted in header lines |
| 36623 | (to stop such addresses from being qualified if rewriting occurs at transport |
| 36624 | time). Local messages that were input using &%-bnq%& and remote messages from |
| 36625 | hosts that match &%sender_unqualified_hosts%& set this flag. |
| 36626 | |
| 36627 | .vitem "&%-auth_id%&&~<&'text'&>" |
| 36628 | The id information for a message received on an authenticated SMTP connection |
| 36629 | &-- the value of the &$authenticated_id$& variable. |
| 36630 | |
| 36631 | .vitem "&%-auth_sender%&&~<&'address'&>" |
| 36632 | The address of an authenticated sender &-- the value of the |
| 36633 | &$authenticated_sender$& variable. |
| 36634 | |
| 36635 | .vitem "&%-body_linecount%&&~<&'number'&>" |
| 36636 | This records the number of lines in the body of the message, and is always |
| 36637 | present. |
| 36638 | |
| 36639 | .vitem "&%-body_zerocount%&&~<&'number'&>" |
| 36640 | This records the number of binary zero bytes in the body of the message, and is |
| 36641 | present if the number is greater than zero. |
| 36642 | |
| 36643 | .vitem &%-deliver_firsttime%& |
| 36644 | This is written when a new message is first added to the spool. When the spool |
| 36645 | file is updated after a deferral, it is omitted. |
| 36646 | |
| 36647 | .vitem "&%-frozen%&&~<&'time'&>" |
| 36648 | .cindex "frozen messages" "spool data" |
| 36649 | The message is frozen, and the freezing happened at <&'time'&>. |
| 36650 | |
| 36651 | .vitem "&%-helo_name%&&~<&'text'&>" |
| 36652 | This records the host name as specified by a remote host in a HELO or EHLO |
| 36653 | command. |
| 36654 | |
| 36655 | .vitem "&%-host_address%&&~<&'address'&>.<&'port'&>" |
| 36656 | This records the IP address of the host from which the message was received and |
| 36657 | the remote port number that was used. It is omitted for locally generated |
| 36658 | messages. |
| 36659 | |
| 36660 | .vitem "&%-host_auth%&&~<&'text'&>" |
| 36661 | If the message was received on an authenticated SMTP connection, this records |
| 36662 | the name of the authenticator &-- the value of the |
| 36663 | &$sender_host_authenticated$& variable. |
| 36664 | |
| 36665 | .vitem &%-host_lookup_failed%& |
| 36666 | This is present if an attempt to look up the sending host's name from its IP |
| 36667 | address failed. It corresponds to the &$host_lookup_failed$& variable. |
| 36668 | |
| 36669 | .vitem "&%-host_name%&&~<&'text'&>" |
| 36670 | .cindex "reverse DNS lookup" |
| 36671 | .cindex "DNS" "reverse lookup" |
| 36672 | This records the name of the remote host from which the message was received, |
| 36673 | if the host name was looked up from the IP address when the message was being |
| 36674 | received. It is not present if no reverse lookup was done. |
| 36675 | |
| 36676 | .vitem "&%-ident%&&~<&'text'&>" |
| 36677 | For locally submitted messages, this records the login of the originating user, |
| 36678 | unless it was a trusted user and the &%-oMt%& option was used to specify an |
| 36679 | ident value. For messages received over TCP/IP, this records the ident string |
| 36680 | supplied by the remote host, if any. |
| 36681 | |
| 36682 | .vitem "&%-interface_address%&&~<&'address'&>.<&'port'&>" |
| 36683 | This records the IP address of the local interface and the port number through |
| 36684 | which a message was received from a remote host. It is omitted for locally |
| 36685 | generated messages. |
| 36686 | |
| 36687 | .vitem &%-local%& |
| 36688 | The message is from a local sender. |
| 36689 | |
| 36690 | .vitem &%-localerror%& |
| 36691 | The message is a locally-generated bounce message. |
| 36692 | |
| 36693 | .vitem "&%-local_scan%&&~<&'string'&>" |
| 36694 | This records the data string that was returned by the &[local_scan()]& function |
| 36695 | when the message was received &-- the value of the &$local_scan_data$& |
| 36696 | variable. It is omitted if no data was returned. |
| 36697 | |
| 36698 | .vitem &%-manual_thaw%& |
| 36699 | The message was frozen but has been thawed manually, that is, by an explicit |
| 36700 | Exim command rather than via the auto-thaw process. |
| 36701 | |
| 36702 | .vitem &%-N%& |
| 36703 | A testing delivery process was started using the &%-N%& option to suppress any |
| 36704 | actual deliveries, but delivery was deferred. At any further delivery attempts, |
| 36705 | &%-N%& is assumed. |
| 36706 | |
| 36707 | .vitem &%-received_protocol%& |
| 36708 | This records the value of the &$received_protocol$& variable, which contains |
| 36709 | the name of the protocol by which the message was received. |
| 36710 | |
| 36711 | .vitem &%-sender_set_untrusted%& |
| 36712 | The envelope sender of this message was set by an untrusted local caller (used |
| 36713 | to ensure that the caller is displayed in queue listings). |
| 36714 | |
| 36715 | .vitem "&%-spam_score_int%&&~<&'number'&>" |
| 36716 | If a message was scanned by SpamAssassin, this is present. It records the value |
| 36717 | of &$spam_score_int$&. |
| 36718 | |
| 36719 | .vitem &%-tls_certificate_verified%& |
| 36720 | A TLS certificate was received from the client that sent this message, and the |
| 36721 | certificate was verified by the server. |
| 36722 | |
| 36723 | .vitem "&%-tls_cipher%&&~<&'cipher name'&>" |
| 36724 | When the message was received over an encrypted connection, this records the |
| 36725 | name of the cipher suite that was used. |
| 36726 | |
| 36727 | .vitem "&%-tls_peerdn%&&~<&'peer DN'&>" |
| 36728 | When the message was received over an encrypted connection, and a certificate |
| 36729 | was received from the client, this records the Distinguished Name from that |
| 36730 | certificate. |
| 36731 | .endlist |
| 36732 | |
| 36733 | Following the options there is a list of those addresses to which the message |
| 36734 | is not to be delivered. This set of addresses is initialized from the command |
| 36735 | line when the &%-t%& option is used and &%extract_addresses_remove_arguments%& |
| 36736 | is set; otherwise it starts out empty. Whenever a successful delivery is made, |
| 36737 | the address is added to this set. The addresses are kept internally as a |
| 36738 | balanced binary tree, and it is a representation of that tree which is written |
| 36739 | to the spool file. If an address is expanded via an alias or forward file, the |
| 36740 | original address is added to the tree when deliveries to all its child |
| 36741 | addresses are complete. |
| 36742 | |
| 36743 | If the tree is empty, there is a single line in the spool file containing just |
| 36744 | the text &"XX"&. Otherwise, each line consists of two letters, which are either |
| 36745 | Y or N, followed by an address. The address is the value for the node of the |
| 36746 | tree, and the letters indicate whether the node has a left branch and/or a |
| 36747 | right branch attached to it, respectively. If branches exist, they immediately |
| 36748 | follow. Here is an example of a three-node tree: |
| 36749 | .code |
| 36750 | YY darcy@austen.fict.example |
| 36751 | NN alice@wonderland.fict.example |
| 36752 | NN editor@thesaurus.ref.example |
| 36753 | .endd |
| 36754 | After the non-recipients tree, there is a list of the message's recipients. |
| 36755 | This is a simple list, preceded by a count. It includes all the original |
| 36756 | recipients of the message, including those to whom the message has already been |
| 36757 | delivered. In the simplest case, the list contains one address per line. For |
| 36758 | example: |
| 36759 | .code |
| 36760 | 4 |
| 36761 | editor@thesaurus.ref.example |
| 36762 | darcy@austen.fict.example |
| 36763 | rdo@foundation |
| 36764 | alice@wonderland.fict.example |
| 36765 | .endd |
| 36766 | However, when a child address has been added to the top-level addresses as a |
| 36767 | result of the use of the &%one_time%& option on a &(redirect)& router, each |
| 36768 | line is of the following form: |
| 36769 | .display |
| 36770 | <&'top-level address'&> <&'errors_to address'&> &&& |
| 36771 | <&'length'&>,<&'parent number'&>#<&'flag bits'&> |
| 36772 | .endd |
| 36773 | The 01 flag bit indicates the presence of the three other fields that follow |
| 36774 | the top-level address. Other bits may be used in future to support additional |
| 36775 | fields. The <&'parent number'&> is the offset in the recipients list of the |
| 36776 | original parent of the &"one time"& address. The first two fields are the |
| 36777 | envelope sender that is associated with this address and its length. If the |
| 36778 | length is zero, there is no special envelope sender (there are then two space |
| 36779 | characters in the line). A non-empty field can arise from a &(redirect)& router |
| 36780 | that has an &%errors_to%& setting. |
| 36781 | |
| 36782 | |
| 36783 | A blank line separates the envelope and status information from the headers |
| 36784 | which follow. A header may occupy several lines of the file, and to save effort |
| 36785 | when reading it in, each header is preceded by a number and an identifying |
| 36786 | character. The number is the number of characters in the header, including any |
| 36787 | embedded newlines and the terminating newline. The character is one of the |
| 36788 | following: |
| 36789 | |
| 36790 | .table2 50pt |
| 36791 | .row <&'blank'&> "header in which Exim has no special interest" |
| 36792 | .row &`B`& "&'Bcc:'& header" |
| 36793 | .row &`C`& "&'Cc:'& header" |
| 36794 | .row &`F`& "&'From:'& header" |
| 36795 | .row &`I`& "&'Message-id:'& header" |
| 36796 | .row &`P`& "&'Received:'& header &-- P for &""postmark""&" |
| 36797 | .row &`R`& "&'Reply-To:'& header" |
| 36798 | .row &`S`& "&'Sender:'& header" |
| 36799 | .row &`T`& "&'To:'& header" |
| 36800 | .row &`*`& "replaced or deleted header" |
| 36801 | .endtable |
| 36802 | |
| 36803 | Deleted or replaced (rewritten) headers remain in the spool file for debugging |
| 36804 | purposes. They are not transmitted when the message is delivered. Here is a |
| 36805 | typical set of headers: |
| 36806 | .code |
| 36807 | 111P Received: by hobbit.fict.example with local (Exim 4.00) |
| 36808 | id 14y9EI-00026G-00; Fri, 11 May 2001 10:28:59 +0100 |
| 36809 | 049 Message-Id: <E14y9EI-00026G-00@hobbit.fict.example> |
| 36810 | 038* X-rewrote-sender: bb@hobbit.fict.example |
| 36811 | 042* From: Bilbo Baggins <bb@hobbit.fict.example> |
| 36812 | 049F From: Bilbo Baggins <B.Baggins@hobbit.fict.example> |
| 36813 | 099* To: alice@wonderland.fict.example, rdo@foundation, |
| 36814 | darcy@austen.fict.example, editor@thesaurus.ref.example |
| 36815 | 104T To: alice@wonderland.fict.example, rdo@foundation.example, |
| 36816 | darcy@austen.fict.example, editor@thesaurus.ref.example |
| 36817 | 038 Date: Fri, 11 May 2001 10:28:59 +0100 |
| 36818 | .endd |
| 36819 | The asterisked headers indicate that the envelope sender, &'From:'& header, and |
| 36820 | &'To:'& header have been rewritten, the last one because routing expanded the |
| 36821 | unqualified domain &'foundation'&. |
| 36822 | .ecindex IIDforspo1 |
| 36823 | .ecindex IIDforspo2 |
| 36824 | .ecindex IIDforspo3 |
| 36825 | |
| 36826 | . //////////////////////////////////////////////////////////////////////////// |
| 36827 | . //////////////////////////////////////////////////////////////////////////// |
| 36828 | |
| 36829 | .chapter "Support for DKIM (DomainKeys Identified Mail)" "CHAPdkim" &&& |
| 36830 | "DKIM Support" |
| 36831 | .cindex "DKIM" |
| 36832 | |
| 36833 | DKIM is a mechanism by which messages sent by some entity can be provably |
| 36834 | linked to a domain which that entity controls. It permits reputation to |
| 36835 | be tracked on a per-domain basis, rather than merely upon source IP address. |
| 36836 | DKIM is documented in RFC 4871. |
| 36837 | |
| 36838 | Since version 4.70, DKIM support is compiled into Exim by default. It can be |
| 36839 | disabled by setting DISABLE_DKIM=yes in Local/Makefile. |
| 36840 | |
| 36841 | Exim's DKIM implementation allows to |
| 36842 | .olist |
| 36843 | Sign outgoing messages: This function is implemented in the SMTP transport. |
| 36844 | It can co-exist with all other Exim features |
| 36845 | (including transport filters) |
| 36846 | except cutthrough delivery. |
| 36847 | .next |
| 36848 | Verify signatures in incoming messages: This is implemented by an additional |
| 36849 | ACL (acl_smtp_dkim), which can be called several times per message, with |
| 36850 | different signature contexts. |
| 36851 | .endlist |
| 36852 | |
| 36853 | In typical Exim style, the verification implementation does not include any |
| 36854 | default "policy". Instead it enables you to build your own policy using |
| 36855 | Exim's standard controls. |
| 36856 | |
| 36857 | Please note that verification of DKIM signatures in incoming mail is turned |
| 36858 | on by default for logging purposes. For each signature in incoming email, |
| 36859 | exim will log a line displaying the most important signature details, and the |
| 36860 | signature status. Here is an example (with line-breaks added for clarity): |
| 36861 | .code |
| 36862 | 2009-09-09 10:22:28 1MlIRf-0003LU-U3 DKIM: |
| 36863 | d=facebookmail.com s=q1-2009b |
| 36864 | c=relaxed/relaxed a=rsa-sha1 |
| 36865 | i=@facebookmail.com t=1252484542 [verification succeeded] |
| 36866 | .endd |
| 36867 | You might want to turn off DKIM verification processing entirely for internal |
| 36868 | or relay mail sources. To do that, set the &%dkim_disable_verify%& ACL |
| 36869 | control modifier. This should typically be done in the RCPT ACL, at points |
| 36870 | where you accept mail from relay sources (internal hosts or authenticated |
| 36871 | senders). |
| 36872 | |
| 36873 | |
| 36874 | .section "Signing outgoing messages" "SECID513" |
| 36875 | .cindex "DKIM" "signing" |
| 36876 | |
| 36877 | Signing is implemented by setting private options on the SMTP transport. |
| 36878 | These options take (expandable) strings as arguments. |
| 36879 | |
| 36880 | .option dkim_domain smtp string&!! unset |
| 36881 | MANDATORY: |
| 36882 | The domain you want to sign with. The result of this expanded |
| 36883 | option is put into the &%$dkim_domain%& expansion variable. |
| 36884 | |
| 36885 | .option dkim_selector smtp string&!! unset |
| 36886 | MANDATORY: |
| 36887 | This sets the key selector string. You can use the &%$dkim_domain%& expansion |
| 36888 | variable to look up a matching selector. The result is put in the expansion |
| 36889 | variable &%$dkim_selector%& which should be used in the &%dkim_private_key%& |
| 36890 | option along with &%$dkim_domain%&. |
| 36891 | |
| 36892 | .option dkim_private_key smtp string&!! unset |
| 36893 | MANDATORY: |
| 36894 | This sets the private key to use. You can use the &%$dkim_domain%& and |
| 36895 | &%$dkim_selector%& expansion variables to determine the private key to use. |
| 36896 | The result can either |
| 36897 | .ilist |
| 36898 | be a valid RSA private key in ASCII armor, including line breaks. |
| 36899 | .next |
| 36900 | start with a slash, in which case it is treated as a file that contains |
| 36901 | the private key. |
| 36902 | .next |
| 36903 | be "0", "false" or the empty string, in which case the message will not |
| 36904 | be signed. This case will not result in an error, even if &%dkim_strict%& |
| 36905 | is set. |
| 36906 | .endlist |
| 36907 | |
| 36908 | .option dkim_canon smtp string&!! unset |
| 36909 | OPTIONAL: |
| 36910 | This option sets the canonicalization method used when signing a message. |
| 36911 | The DKIM RFC currently supports two methods: "simple" and "relaxed". |
| 36912 | The option defaults to "relaxed" when unset. Note: the current implementation |
| 36913 | only supports using the same canonicalization method for both headers and body. |
| 36914 | |
| 36915 | .option dkim_strict smtp string&!! unset |
| 36916 | OPTIONAL: |
| 36917 | This option defines how Exim behaves when signing a message that |
| 36918 | should be signed fails for some reason. When the expansion evaluates to |
| 36919 | either "1" or "true", Exim will defer. Otherwise Exim will send the message |
| 36920 | unsigned. You can use the &%$dkim_domain%& and &%$dkim_selector%& expansion |
| 36921 | variables here. |
| 36922 | |
| 36923 | .option dkim_sign_headers smtp string&!! unset |
| 36924 | OPTIONAL: |
| 36925 | When set, this option must expand to (or be specified as) a colon-separated |
| 36926 | list of header names. Headers with these names will be included in the message |
| 36927 | signature. When unspecified, the header names recommended in RFC4871 will be |
| 36928 | used. |
| 36929 | |
| 36930 | |
| 36931 | .section "Verifying DKIM signatures in incoming mail" "SECID514" |
| 36932 | .cindex "DKIM" "verification" |
| 36933 | |
| 36934 | Verification of DKIM signatures in incoming email is implemented via the |
| 36935 | &%acl_smtp_dkim%& ACL. By default, this ACL is called once for each |
| 36936 | syntactically(!) correct signature in the incoming message. |
| 36937 | A missing ACL definition defaults to accept. |
| 36938 | If any ACL call does not acccept, the message is not accepted. |
| 36939 | If a cutthrough delivery was in progress for the message it is |
| 36940 | summarily dropped (having wasted the transmission effort). |
| 36941 | |
| 36942 | To evaluate the signature in the ACL a large number of expansion variables |
| 36943 | containing the signature status and its details are set up during the |
| 36944 | runtime of the ACL. |
| 36945 | |
| 36946 | Calling the ACL only for existing signatures is not sufficient to build |
| 36947 | more advanced policies. For that reason, the global option |
| 36948 | &%dkim_verify_signers%&, and a global expansion variable |
| 36949 | &%$dkim_signers%& exist. |
| 36950 | |
| 36951 | The global option &%dkim_verify_signers%& can be set to a colon-separated |
| 36952 | list of DKIM domains or identities for which the ACL &%acl_smtp_dkim%& is |
| 36953 | called. It is expanded when the message has been received. At this point, |
| 36954 | the expansion variable &%$dkim_signers%& already contains a colon-separated |
| 36955 | list of signer domains and identities for the message. When |
| 36956 | &%dkim_verify_signers%& is not specified in the main configuration, |
| 36957 | it defaults as: |
| 36958 | .code |
| 36959 | dkim_verify_signers = $dkim_signers |
| 36960 | .endd |
| 36961 | This leads to the default behaviour of calling &%acl_smtp_dkim%& for each |
| 36962 | DKIM signature in the message. Current DKIM verifiers may want to explicitly |
| 36963 | call the ACL for known domains or identities. This would be achieved as follows: |
| 36964 | .code |
| 36965 | dkim_verify_signers = paypal.com:ebay.com:$dkim_signers |
| 36966 | .endd |
| 36967 | This would result in &%acl_smtp_dkim%& always being called for "paypal.com" |
| 36968 | and "ebay.com", plus all domains and identities that have signatures in the message. |
| 36969 | You can also be more creative in constructing your policy. For example: |
| 36970 | .code |
| 36971 | dkim_verify_signers = $sender_address_domain:$dkim_signers |
| 36972 | .endd |
| 36973 | |
| 36974 | If a domain or identity is listed several times in the (expanded) value of |
| 36975 | &%dkim_verify_signers%&, the ACL is only called once for that domain or identity. |
| 36976 | |
| 36977 | |
| 36978 | Inside the &%acl_smtp_dkim%&, the following expansion variables are |
| 36979 | available (from most to least important): |
| 36980 | |
| 36981 | |
| 36982 | .vlist |
| 36983 | .vitem &%$dkim_cur_signer%& |
| 36984 | The signer that is being evaluated in this ACL run. This can be a domain or |
| 36985 | an identity. This is one of the list items from the expanded main option |
| 36986 | &%dkim_verify_signers%& (see above). |
| 36987 | .vitem &%$dkim_verify_status%& |
| 36988 | A string describing the general status of the signature. One of |
| 36989 | .ilist |
| 36990 | &%none%&: There is no signature in the message for the current domain or |
| 36991 | identity (as reflected by &%$dkim_cur_signer%&). |
| 36992 | .next |
| 36993 | &%invalid%&: The signature could not be verified due to a processing error. |
| 36994 | More detail is available in &%$dkim_verify_reason%&. |
| 36995 | .next |
| 36996 | &%fail%&: Verification of the signature failed. More detail is |
| 36997 | available in &%$dkim_verify_reason%&. |
| 36998 | .next |
| 36999 | &%pass%&: The signature passed verification. It is valid. |
| 37000 | .endlist |
| 37001 | .vitem &%$dkim_verify_reason%& |
| 37002 | A string giving a litte bit more detail when &%$dkim_verify_status%& is either |
| 37003 | "fail" or "invalid". One of |
| 37004 | .ilist |
| 37005 | &%pubkey_unavailable%& (when &%$dkim_verify_status%&="invalid"): The public |
| 37006 | key for the domain could not be retrieved. This may be a temporary problem. |
| 37007 | .next |
| 37008 | &%pubkey_syntax%& (when &%$dkim_verify_status%&="invalid"): The public key |
| 37009 | record for the domain is syntactically invalid. |
| 37010 | .next |
| 37011 | &%bodyhash_mismatch%& (when &%$dkim_verify_status%&="fail"): The calculated |
| 37012 | body hash does not match the one specified in the signature header. This |
| 37013 | means that the message body was modified in transit. |
| 37014 | .next |
| 37015 | &%signature_incorrect%& (when &%$dkim_verify_status%&="fail"): The signature |
| 37016 | could not be verified. This may mean that headers were modified, |
| 37017 | re-written or otherwise changed in a way which is incompatible with |
| 37018 | DKIM verification. It may of course also mean that the signature is forged. |
| 37019 | .endlist |
| 37020 | .vitem &%$dkim_domain%& |
| 37021 | The signing domain. IMPORTANT: This variable is only populated if there is |
| 37022 | an actual signature in the message for the current domain or identity (as |
| 37023 | reflected by &%$dkim_cur_signer%&). |
| 37024 | .vitem &%$dkim_identity%& |
| 37025 | The signing identity, if present. IMPORTANT: This variable is only populated |
| 37026 | if there is an actual signature in the message for the current domain or |
| 37027 | identity (as reflected by &%$dkim_cur_signer%&). |
| 37028 | .vitem &%$dkim_selector%& |
| 37029 | The key record selector string. |
| 37030 | .vitem &%$dkim_algo%& |
| 37031 | The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'. |
| 37032 | .vitem &%$dkim_canon_body%& |
| 37033 | The body canonicalization method. One of 'relaxed' or 'simple'. |
| 37034 | .vitem &%dkim_canon_headers%& |
| 37035 | The header canonicalization method. One of 'relaxed' or 'simple'. |
| 37036 | .vitem &%$dkim_copiedheaders%& |
| 37037 | A transcript of headers and their values which are included in the signature |
| 37038 | (copied from the 'z=' tag of the signature). |
| 37039 | .vitem &%$dkim_bodylength%& |
| 37040 | The number of signed body bytes. If zero ("0"), the body is unsigned. If no |
| 37041 | limit was set by the signer, "9999999999999" is returned. This makes sure |
| 37042 | that this variable always expands to an integer value. |
| 37043 | .vitem &%$dkim_created%& |
| 37044 | UNIX timestamp reflecting the date and time when the signature was created. |
| 37045 | When this was not specified by the signer, "0" is returned. |
| 37046 | .vitem &%$dkim_expires%& |
| 37047 | UNIX timestamp reflecting the date and time when the signer wants the |
| 37048 | signature to be treated as "expired". When this was not specified by the |
| 37049 | signer, "9999999999999" is returned. This makes it possible to do useful |
| 37050 | integer size comparisons against this value. |
| 37051 | .vitem &%$dkim_headernames%& |
| 37052 | A colon-separated list of names of headers included in the signature. |
| 37053 | .vitem &%$dkim_key_testing%& |
| 37054 | "1" if the key record has the "testing" flag set, "0" if not. |
| 37055 | .vitem &%$dkim_key_nosubdomains%& |
| 37056 | "1" if the key record forbids subdomaining, "0" otherwise. |
| 37057 | .vitem &%$dkim_key_srvtype%& |
| 37058 | Service type (tag s=) from the key record. Defaults to "*" if not specified |
| 37059 | in the key record. |
| 37060 | .vitem &%$dkim_key_granularity%& |
| 37061 | Key granularity (tag g=) from the key record. Defaults to "*" if not specified |
| 37062 | in the key record. |
| 37063 | .vitem &%$dkim_key_notes%& |
| 37064 | Notes from the key record (tag n=). |
| 37065 | .endlist |
| 37066 | |
| 37067 | In addition, two ACL conditions are provided: |
| 37068 | |
| 37069 | .vlist |
| 37070 | .vitem &%dkim_signers%& |
| 37071 | ACL condition that checks a colon-separated list of domains or identities |
| 37072 | for a match against the domain or identity that the ACL is currently verifying |
| 37073 | (reflected by &%$dkim_cur_signer%&). This is typically used to restrict an ACL |
| 37074 | verb to a group of domains or identities. For example: |
| 37075 | |
| 37076 | .code |
| 37077 | # Warn when Mail purportedly from GMail has no signature at all |
| 37078 | warn log_message = GMail sender without DKIM signature |
| 37079 | sender_domains = gmail.com |
| 37080 | dkim_signers = gmail.com |
| 37081 | dkim_status = none |
| 37082 | .endd |
| 37083 | |
| 37084 | .vitem &%dkim_status%& |
| 37085 | ACL condition that checks a colon-separated list of possible DKIM verification |
| 37086 | results against the actual result of verification. This is typically used |
| 37087 | to restrict an ACL verb to a list of verification outcomes, for example: |
| 37088 | |
| 37089 | .code |
| 37090 | deny message = Mail from Paypal with invalid/missing signature |
| 37091 | sender_domains = paypal.com:paypal.de |
| 37092 | dkim_signers = paypal.com:paypal.de |
| 37093 | dkim_status = none:invalid:fail |
| 37094 | .endd |
| 37095 | |
| 37096 | The possible status keywords are: 'none','invalid','fail' and 'pass'. Please |
| 37097 | see the documentation of the &%$dkim_verify_status%& expansion variable above |
| 37098 | for more information of what they mean. |
| 37099 | .endlist |
| 37100 | |
| 37101 | . //////////////////////////////////////////////////////////////////////////// |
| 37102 | . //////////////////////////////////////////////////////////////////////////// |
| 37103 | |
| 37104 | .chapter "Adding new drivers or lookup types" "CHID13" &&& |
| 37105 | "Adding drivers or lookups" |
| 37106 | .cindex "adding drivers" |
| 37107 | .cindex "new drivers, adding" |
| 37108 | .cindex "drivers" "adding new" |
| 37109 | The following actions have to be taken in order to add a new router, transport, |
| 37110 | authenticator, or lookup type to Exim: |
| 37111 | |
| 37112 | .olist |
| 37113 | Choose a name for the driver or lookup type that does not conflict with any |
| 37114 | existing name; I will use &"newdriver"& in what follows. |
| 37115 | .next |
| 37116 | Add to &_src/EDITME_& the line: |
| 37117 | .display |
| 37118 | <&'type'&>&`_NEWDRIVER=yes`& |
| 37119 | .endd |
| 37120 | where <&'type'&> is ROUTER, TRANSPORT, AUTH, or LOOKUP. If the |
| 37121 | code is not to be included in the binary by default, comment this line out. You |
| 37122 | should also add any relevant comments about the driver or lookup type. |
| 37123 | .next |
| 37124 | Add to &_src/config.h.defaults_& the line: |
| 37125 | .code |
| 37126 | #define <type>_NEWDRIVER |
| 37127 | .endd |
| 37128 | .next |
| 37129 | Edit &_src/drtables.c_&, adding conditional code to pull in the private header |
| 37130 | and create a table entry as is done for all the other drivers and lookup types. |
| 37131 | .next |
| 37132 | Edit &_scripts/lookups-Makefile_& if this is a new lookup; there is a for-loop |
| 37133 | near the bottom, ranging the &`name_mod`& variable over a list of all lookups. |
| 37134 | Add your &`NEWDRIVER`& to that list. |
| 37135 | As long as the dynamic module would be named &_newdriver.so_&, you can use the |
| 37136 | simple form that most lookups have. |
| 37137 | .next |
| 37138 | Edit &_Makefile_& in the appropriate sub-directory (&_src/routers_&, |
| 37139 | &_src/transports_&, &_src/auths_&, or &_src/lookups_&); add a line for the new |
| 37140 | driver or lookup type and add it to the definition of OBJ. |
| 37141 | .next |
| 37142 | Create &_newdriver.h_& and &_newdriver.c_& in the appropriate sub-directory of |
| 37143 | &_src_&. |
| 37144 | .next |
| 37145 | Edit &_scripts/MakeLinks_& and add commands to link the &_.h_& and &_.c_& files |
| 37146 | as for other drivers and lookups. |
| 37147 | .endlist |
| 37148 | |
| 37149 | Then all you need to do is write the code! A good way to start is to make a |
| 37150 | proforma by copying an existing module of the same type, globally changing all |
| 37151 | occurrences of the name, and cutting out most of the code. Note that any |
| 37152 | options you create must be listed in alphabetical order, because the tables are |
| 37153 | searched using a binary chop procedure. |
| 37154 | |
| 37155 | There is a &_README_& file in each of the sub-directories of &_src_& describing |
| 37156 | the interface that is expected. |
| 37157 | |
| 37158 | |
| 37159 | |
| 37160 | |
| 37161 | . //////////////////////////////////////////////////////////////////////////// |
| 37162 | . //////////////////////////////////////////////////////////////////////////// |
| 37163 | |
| 37164 | . ///////////////////////////////////////////////////////////////////////////// |
| 37165 | . These lines are processing instructions for the Simple DocBook Processor that |
| 37166 | . Philip Hazel has developed as a less cumbersome way of making PostScript and |
| 37167 | . PDFs than using xmlto and fop. They will be ignored by all other XML |
| 37168 | . processors. |
| 37169 | . ///////////////////////////////////////////////////////////////////////////// |
| 37170 | |
| 37171 | .literal xml |
| 37172 | <?sdop |
| 37173 | format="newpage" |
| 37174 | foot_right_recto="&chaptertitle;" |
| 37175 | foot_right_verso="&chaptertitle;" |
| 37176 | ?> |
| 37177 | .literal off |
| 37178 | |
| 37179 | .makeindex "Options index" "option" |
| 37180 | .makeindex "Variables index" "variable" |
| 37181 | .makeindex "Concept index" "concept" |
| 37182 | |
| 37183 | |
| 37184 | . ///////////////////////////////////////////////////////////////////////////// |
| 37185 | . ///////////////////////////////////////////////////////////////////////////// |