Imported Upstream version 4.84
[hcoop/debian/exim4.git] / doc / spec.txt
1 Specification of the Exim Mail Transfer Agent
2
3 Exim Maintainers
4
5 Copyright (c) 2014 University of Cambridge
6
7 +-----------------------------------------------------------------------------+
8 +-------------------------------------+--------------------------------+------+
9 |Revision 4.84 |11 Aug 2014 |EM |
10 +-------------------------------------+--------------------------------+------+
11 -------------------------------------------------------------------------------
12
13 TABLE OF CONTENTS
14
15 1. Introduction
16
17 1.1. Exim documentation
18 1.2. FTP and web sites
19 1.3. Mailing lists
20 1.4. Exim training
21 1.5. Bug reports
22 1.6. Where to find the Exim distribution
23 1.7. Limitations
24 1.8. Run time configuration
25 1.9. Calling interface
26 1.10. Terminology
27
28 2. Incorporated code
29 3. How Exim receives and delivers mail
30
31 3.1. Overall philosophy
32 3.2. Policy control
33 3.3. User filters
34 3.4. Message identification
35 3.5. Receiving mail
36 3.6. Handling an incoming message
37 3.7. Life of a message
38 3.8. Processing an address for delivery
39 3.9. Processing an address for verification
40 3.10. Running an individual router
41 3.11. Duplicate addresses
42 3.12. Router preconditions
43 3.13. Delivery in detail
44 3.14. Retry mechanism
45 3.15. Temporary delivery failure
46 3.16. Permanent delivery failure
47 3.17. Failures to deliver bounce messages
48
49 4. Building and installing Exim
50
51 4.1. Unpacking
52 4.2. Multiple machine architectures and operating systems
53 4.3. PCRE library
54 4.4. DBM libraries
55 4.5. Pre-building configuration
56 4.6. Support for iconv()
57 4.7. Including TLS/SSL encryption support
58 4.8. Use of tcpwrappers
59 4.9. Including support for IPv6
60 4.10. Dynamically loaded lookup module support
61 4.11. The building process
62 4.12. Output from "make"
63 4.13. Overriding build-time options for Exim
64 4.14. OS-specific header files
65 4.15. Overriding build-time options for the monitor
66 4.16. Installing Exim binaries and scripts
67 4.17. Installing info documentation
68 4.18. Setting up the spool directory
69 4.19. Testing
70 4.20. Replacing another MTA with Exim
71 4.21. Upgrading Exim
72 4.22. Stopping the Exim daemon on Solaris
73
74 5. The Exim command line
75
76 5.1. Setting options by program name
77 5.2. Trusted and admin users
78 5.3. Command line options
79
80 6. The Exim run time configuration file
81
82 6.1. Using a different configuration file
83 6.2. Configuration file format
84 6.3. File inclusions in the configuration file
85 6.4. Macros in the configuration file
86 6.5. Macro substitution
87 6.6. Redefining macros
88 6.7. Overriding macro values
89 6.8. Example of macro usage
90 6.9. Conditional skips in the configuration file
91 6.10. Common option syntax
92 6.11. Boolean options
93 6.12. Integer values
94 6.13. Octal integer values
95 6.14. Fixed point numbers
96 6.15. Time intervals
97 6.16. String values
98 6.17. Expanded strings
99 6.18. User and group names
100 6.19. List construction
101 6.20. Changing list separators
102 6.21. Empty items in lists
103 6.22. Format of driver configurations
104
105 7. The default configuration file
106
107 7.1. Main configuration settings
108 7.2. ACL configuration
109 7.3. Router configuration
110 7.4. Transport configuration
111 7.5. Default retry rule
112 7.6. Rewriting configuration
113 7.7. Authenticators configuration
114
115 8. Regular expressions
116 9. File and database lookups
117
118 9.1. Examples of different lookup syntax
119 9.2. Lookup types
120 9.3. Single-key lookup types
121 9.4. Query-style lookup types
122 9.5. Temporary errors in lookups
123 9.6. Default values in single-key lookups
124 9.7. Partial matching in single-key lookups
125 9.8. Lookup caching
126 9.9. Quoting lookup data
127 9.10. More about dnsdb
128 9.11. Pseudo dnsdb record types
129 9.12. Multiple dnsdb lookups
130 9.13. More about LDAP
131 9.14. Format of LDAP queries
132 9.15. LDAP quoting
133 9.16. LDAP connections
134 9.17. LDAP authentication and control information
135 9.18. Format of data returned by LDAP
136 9.19. More about NIS+
137 9.20. SQL lookups
138 9.21. More about MySQL, PostgreSQL, Oracle, and InterBase
139 9.22. Specifying the server in the query
140 9.23. Special MySQL features
141 9.24. Special PostgreSQL features
142 9.25. More about SQLite
143
144 10. Domain, host, address, and local part lists
145
146 10.1. Expansion of lists
147 10.2. Negated items in lists
148 10.3. File names in lists
149 10.4. An lsearch file is not an out-of-line list
150 10.5. Named lists
151 10.6. Named lists compared with macros
152 10.7. Named list caching
153 10.8. Domain lists
154 10.9. Host lists
155 10.10. Special host list patterns
156 10.11. Host list patterns that match by IP address
157 10.12. Host list patterns for single-key lookups by host address
158 10.13. Host list patterns that match by host name
159 10.14. Behaviour when an IP address or name cannot be found
160 10.15. Mixing wildcarded host names and addresses in host lists
161 10.16. Temporary DNS errors when looking up host information
162 10.17. Host list patterns for single-key lookups by host name
163 10.18. Host list patterns for query-style lookups
164 10.19. Address lists
165 10.20. Case of letters in address lists
166 10.21. Local part lists
167
168 11. String expansions
169
170 11.1. Literal text in expanded strings
171 11.2. Character escape sequences in expanded strings
172 11.3. Testing string expansions
173 11.4. Forced expansion failure
174 11.5. Expansion items
175 11.6. Expansion operators
176 11.7. Expansion conditions
177 11.8. Combining expansion conditions
178 11.9. Expansion variables
179
180 12. Embedded Perl
181
182 12.1. Setting up so Perl can be used
183 12.2. Calling Perl subroutines
184 12.3. Calling Exim functions from Perl
185 12.4. Use of standard output and error by Perl
186
187 13. Starting the daemon and the use of network interfaces
188
189 13.1. Starting a listening daemon
190 13.2. Special IP listening addresses
191 13.3. Overriding local_interfaces and daemon_smtp_ports
192 13.4. Support for the obsolete SSMTP (or SMTPS) protocol
193 13.5. IPv6 address scopes
194 13.6. Disabling IPv6
195 13.7. Examples of starting a listening daemon
196 13.8. Recognizing the local host
197 13.9. Delivering to a remote host
198
199 14. Main configuration
200
201 14.1. Miscellaneous
202 14.2. Exim parameters
203 14.3. Privilege controls
204 14.4. Logging
205 14.5. Frozen messages
206 14.6. Data lookups
207 14.7. Message ids
208 14.8. Embedded Perl Startup
209 14.9. Daemon
210 14.10. Resource control
211 14.11. Policy controls
212 14.12. Callout cache
213 14.13. TLS
214 14.14. Local user handling
215 14.15. All incoming messages (SMTP and non-SMTP)
216 14.16. Non-SMTP incoming messages
217 14.17. Incoming SMTP messages
218 14.18. SMTP extensions
219 14.19. Processing messages
220 14.20. System filter
221 14.21. Routing and delivery
222 14.22. Bounce and warning messages
223 14.23. Alphabetical list of main options
224
225 15. Generic options for routers
226 16. The accept router
227 17. The dnslookup router
228
229 17.1. Problems with DNS lookups
230 17.2. Declining addresses by dnslookup
231 17.3. Private options for dnslookup
232 17.4. Effect of qualify_single and search_parents
233
234 18. The ipliteral router
235 19. The iplookup router
236 20. The manualroute router
237
238 20.1. Private options for manualroute
239 20.2. Routing rules in route_list
240 20.3. Routing rules in route_data
241 20.4. Format of the list of hosts
242 20.5. Format of one host item
243 20.6. How the list of hosts is used
244 20.7. How the options are used
245 20.8. Manualroute examples
246
247 21. The queryprogram router
248 22. The redirect router
249
250 22.1. Redirection data
251 22.2. Forward files and address verification
252 22.3. Interpreting redirection data
253 22.4. Items in a non-filter redirection list
254 22.5. Redirecting to a local mailbox
255 22.6. Special items in redirection lists
256 22.7. Duplicate addresses
257 22.8. Repeated redirection expansion
258 22.9. Errors in redirection lists
259 22.10. Private options for the redirect router
260
261 23. Environment for running local transports
262
263 23.1. Concurrent deliveries
264 23.2. Uids and gids
265 23.3. Current and home directories
266 23.4. Expansion variables derived from the address
267
268 24. Generic options for transports
269 25. Address batching in local transports
270 26. The appendfile transport
271
272 26.1. The file and directory options
273 26.2. Private options for appendfile
274 26.3. Operational details for appending
275 26.4. Operational details for delivery to a new file
276 26.5. Maildir delivery
277 26.6. Using tags to record message sizes
278 26.7. Using a maildirsize file
279 26.8. Mailstore delivery
280 26.9. Non-special new file delivery
281
282 27. The autoreply transport
283
284 27.1. Private options for autoreply
285
286 28. The lmtp transport
287 29. The pipe transport
288
289 29.1. Concurrent delivery
290 29.2. Returned status and data
291 29.3. How the command is run
292 29.4. Environment variables
293 29.5. Private options for pipe
294 29.6. Using an external local delivery agent
295
296 30. The smtp transport
297
298 30.1. Multiple messages on a single connection
299 30.2. Use of the $host and $host_address variables
300 30.3. Use of $tls_cipher and $tls_peerdn
301 30.4. Private options for smtp
302 30.5. How the limits for the number of hosts to try are used
303
304 31. Address rewriting
305
306 31.1. Explicitly configured address rewriting
307 31.2. When does rewriting happen?
308 31.3. Testing the rewriting rules that apply on input
309 31.4. Rewriting rules
310 31.5. Rewriting patterns
311 31.6. Rewriting replacements
312 31.7. Rewriting flags
313 31.8. Flags specifying which headers and envelope addresses to rewrite
314 31.9. The SMTP-time rewriting flag
315 31.10. Flags controlling the rewriting process
316 31.11. Rewriting examples
317
318 32. Retry configuration
319
320 32.1. Changing retry rules
321 32.2. Format of retry rules
322 32.3. Choosing which retry rule to use for address errors
323 32.4. Choosing which retry rule to use for host and message errors
324 32.5. Retry rules for specific errors
325 32.6. Retry rules for specified senders
326 32.7. Retry parameters
327 32.8. Retry rule examples
328 32.9. Timeout of retry data
329 32.10. Long-term failures
330 32.11. Deliveries that work intermittently
331
332 33. SMTP authentication
333
334 33.1. Generic options for authenticators
335 33.2. The AUTH parameter on MAIL commands
336 33.3. Authentication on an Exim server
337 33.4. Testing server authentication
338 33.5. Authentication by an Exim client
339
340 34. The plaintext authenticator
341
342 34.1. Plaintext options
343 34.2. Using plaintext in a server
344 34.3. The PLAIN authentication mechanism
345 34.4. The LOGIN authentication mechanism
346 34.5. Support for different kinds of authentication
347 34.6. Using plaintext in a client
348
349 35. The cram_md5 authenticator
350
351 35.1. Using cram_md5 as a server
352 35.2. Using cram_md5 as a client
353
354 36. The cyrus_sasl authenticator
355
356 36.1. Using cyrus_sasl as a server
357
358 37. The dovecot authenticator
359 38. The gsasl authenticator
360
361 38.1. gsasl auth variables
362
363 39. The heimdal_gssapi authenticator
364
365 39.1. heimdal_gssapi auth variables
366
367 40. The spa authenticator
368
369 40.1. Using spa as a server
370 40.2. Using spa as a client
371
372 41. Encrypted SMTP connections using TLS/SSL
373
374 41.1. Support for the legacy "ssmtp" (aka "smtps") protocol
375 41.2. OpenSSL vs GnuTLS
376 41.3. GnuTLS parameter computation
377 41.4. Requiring specific ciphers in OpenSSL
378 41.5. Requiring specific ciphers or other parameters in GnuTLS
379 41.6. Configuring an Exim server to use TLS
380 41.7. Requesting and verifying client certificates
381 41.8. Revoked certificates
382 41.9. Configuring an Exim client to use TLS
383 41.10. Use of TLS Server Name Indication
384 41.11. Multiple messages on the same encrypted TCP/IP connection
385 41.12. Certificates and all that
386 41.13. Certificate chains
387 41.14. Self-signed certificates
388
389 42. Access control lists
390
391 42.1. Testing ACLs
392 42.2. Specifying when ACLs are used
393 42.3. The non-SMTP ACLs
394 42.4. The SMTP connect ACL
395 42.5. The EHLO/HELO ACL
396 42.6. The DATA ACLs
397 42.7. The SMTP DKIM ACL
398 42.8. The SMTP MIME ACL
399 42.9. The SMTP PRDR ACL
400 42.10. The QUIT ACL
401 42.11. The not-QUIT ACL
402 42.12. Finding an ACL to use
403 42.13. ACL return codes
404 42.14. Unset ACL options
405 42.15. Data for message ACLs
406 42.16. Data for non-message ACLs
407 42.17. Format of an ACL
408 42.18. ACL verbs
409 42.19. ACL variables
410 42.20. Condition and modifier processing
411 42.21. ACL modifiers
412 42.22. Use of the control modifier
413 42.23. Summary of message fixup control
414 42.24. Adding header lines in ACLs
415 42.25. Removing header lines in ACLs
416 42.26. ACL conditions
417 42.27. Using DNS lists
418 42.28. Specifying the IP address for a DNS list lookup
419 42.29. DNS lists keyed on domain names
420 42.30. Multiple explicit keys for a DNS list
421 42.31. Data returned by DNS lists
422 42.32. Variables set from DNS lists
423 42.33. Additional matching conditions for DNS lists
424 42.34. Negated DNS matching conditions
425 42.35. Handling multiple DNS records from a DNS list
426 42.36. Detailed information from merged DNS lists
427 42.37. DNS lists and IPv6
428 42.38. Rate limiting incoming messages
429 42.39. Ratelimit options for what is being measured
430 42.40. Ratelimit update modes
431 42.41. Ratelimit options for handling fast clients
432 42.42. Limiting the rate of different events
433 42.43. Using rate limiting
434 42.44. Address verification
435 42.45. Callout verification
436 42.46. Additional parameters for callouts
437 42.47. Callout caching
438 42.48. Sender address verification reporting
439 42.49. Redirection while verifying
440 42.50. Client SMTP authorization (CSA)
441 42.51. Bounce address tag validation
442 42.52. Using an ACL to control relaying
443 42.53. Checking a relay configuration
444
445 43. Content scanning at ACL time
446
447 43.1. Scanning for viruses
448 43.2. Scanning with SpamAssassin
449 43.3. Calling SpamAssassin from an Exim ACL
450 43.4. Scanning MIME parts
451 43.5. Scanning with regular expressions
452 43.6. The demime condition
453
454 44. Adding a local scan function to Exim
455
456 44.1. Building Exim to use a local scan function
457 44.2. API for local_scan()
458 44.3. Configuration options for local_scan()
459 44.4. Available Exim variables
460 44.5. Structure of header lines
461 44.6. Structure of recipient items
462 44.7. Available Exim functions
463 44.8. More about Exim's memory handling
464
465 45. System-wide message filtering
466
467 45.1. Specifying a system filter
468 45.2. Testing a system filter
469 45.3. Contents of a system filter
470 45.4. Additional variable for system filters
471 45.5. Defer, freeze, and fail commands for system filters
472 45.6. Adding and removing headers in a system filter
473 45.7. Setting an errors address in a system filter
474 45.8. Per-address filtering
475
476 46. Message processing
477
478 46.1. Submission mode for non-local messages
479 46.2. Line endings
480 46.3. Unqualified addresses
481 46.4. The UUCP From line
482 46.5. Resent- header lines
483 46.6. The Auto-Submitted: header line
484 46.7. The Bcc: header line
485 46.8. The Date: header line
486 46.9. The Delivery-date: header line
487 46.10. The Envelope-to: header line
488 46.11. The From: header line
489 46.12. The Message-ID: header line
490 46.13. The Received: header line
491 46.14. The References: header line
492 46.15. The Return-path: header line
493 46.16. The Sender: header line
494 46.17. Adding and removing header lines in routers and transports
495 46.18. Constructed addresses
496 46.19. Case of local parts
497 46.20. Dots in local parts
498 46.21. Rewriting addresses
499
500 47. SMTP processing
501
502 47.1. Outgoing SMTP and LMTP over TCP/IP
503 47.2. Errors in outgoing SMTP
504 47.3. Incoming SMTP messages over TCP/IP
505 47.4. Unrecognized SMTP commands
506 47.5. Syntax and protocol errors in SMTP commands
507 47.6. Use of non-mail SMTP commands
508 47.7. The VRFY and EXPN commands
509 47.8. The ETRN command
510 47.9. Incoming local SMTP
511 47.10. Outgoing batched SMTP
512 47.11. Incoming batched SMTP
513
514 48. Customizing bounce and warning messages
515
516 48.1. Customizing bounce messages
517 48.2. Customizing warning messages
518
519 49. Some common configuration settings
520
521 49.1. Sending mail to a smart host
522 49.2. Using Exim to handle mailing lists
523 49.3. Syntax errors in mailing lists
524 49.4. Re-expansion of mailing lists
525 49.5. Closed mailing lists
526 49.6. Variable Envelope Return Paths (VERP)
527 49.7. Virtual domains
528 49.8. Multiple user mailboxes
529 49.9. Simplified vacation processing
530 49.10. Taking copies of mail
531 49.11. Intermittently connected hosts
532 49.12. Exim on the upstream server host
533 49.13. Exim on the intermittently connected client host
534
535 50. Using Exim as a non-queueing client
536 51. Log files
537
538 51.1. Where the logs are written
539 51.2. Logging to local files that are periodically "cycled"
540 51.3. Datestamped log files
541 51.4. Logging to syslog
542 51.5. Log line flags
543 51.6. Logging message reception
544 51.7. Logging deliveries
545 51.8. Discarded deliveries
546 51.9. Deferred deliveries
547 51.10. Delivery failures
548 51.11. Fake deliveries
549 51.12. Completion
550 51.13. Summary of Fields in Log Lines
551 51.14. Other log entries
552 51.15. Reducing or increasing what is logged
553 51.16. Message log
554
555 52. Exim utilities
556
557 52.1. Finding out what Exim processes are doing (exiwhat)
558 52.2. Selective queue listing (exiqgrep)
559 52.3. Summarizing the queue (exiqsumm)
560 52.4. Extracting specific information from the log (exigrep)
561 52.5. Selecting messages by various criteria (exipick)
562 52.6. Cycling log files (exicyclog)
563 52.7. Mail statistics (eximstats)
564 52.8. Checking access policy (exim_checkaccess)
565 52.9. Making DBM files (exim_dbmbuild)
566 52.10. Finding individual retry times (exinext)
567 52.11. Hints database maintenance
568 52.12. exim_dumpdb
569 52.13. exim_tidydb
570 52.14. exim_fixdb
571 52.15. Mailbox maintenance (exim_lock)
572
573 53. The Exim monitor
574
575 53.1. Running the monitor
576 53.2. The stripcharts
577 53.3. Main action buttons
578 53.4. The log display
579 53.5. The queue display
580 53.6. The queue menu
581
582 54. Security considerations
583
584 54.1. Building a more "hardened" Exim
585 54.2. Root privilege
586 54.3. Running Exim without privilege
587 54.4. Delivering to local files
588 54.5. Running local commands
589 54.6. Trust in configuration data
590 54.7. IPv4 source routing
591 54.8. The VRFY, EXPN, and ETRN commands in SMTP
592 54.9. Privileged users
593 54.10. Spool files
594 54.11. Use of argv[0]
595 54.12. Use of %f formatting
596 54.13. Embedded Exim path
597 54.14. Dynamic module directory
598 54.15. Use of sprintf()
599 54.16. Use of debug_printf() and log_write()
600 54.17. Use of strcat() and strcpy()
601
602 55. Format of spool files
603
604 55.1. Format of the -H file
605
606 56. Support for DKIM (DomainKeys Identified Mail)
607
608 56.1. Signing outgoing messages
609 56.2. Verifying DKIM signatures in incoming mail
610
611 57. Adding new drivers or lookup types
612
613
614
615 ===============================================================================
616 1. INTRODUCTION
617
618 Exim is a mail transfer agent (MTA) for hosts that are running Unix or
619 Unix-like operating systems. It was designed on the assumption that it would be
620 run on hosts that are permanently connected to the Internet. However, it can be
621 used on intermittently connected hosts with suitable configuration adjustments.
622
623 Configuration files currently exist for the following operating systems: AIX,
624 BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, Dragonfly, FreeBSD, GNU/Hurd, GNU/
625 Linux, HI-OSF (Hitachi), HI-UX, HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD,
626 OpenUNIX, QNX, SCO, SCO SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4,
627 Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware.
628 Some of these operating systems are no longer current and cannot easily be
629 tested, so the configuration files may no longer work in practice.
630
631 There are also configuration files for compiling Exim in the Cygwin environment
632 that can be installed on systems running Windows. However, this document does
633 not contain any information about running Exim in the Cygwin environment.
634
635 The terms and conditions for the use and distribution of Exim are contained in
636 the file NOTICE. Exim is distributed under the terms of the GNU General Public
637 Licence, a copy of which may be found in the file LICENCE.
638
639 The use, supply or promotion of Exim for the purpose of sending bulk,
640 unsolicited electronic mail is incompatible with the basic aims of the program,
641 which revolve around the free provision of a service that enhances the quality
642 of personal communications. The author of Exim regards indiscriminate
643 mass-mailing as an antisocial, irresponsible abuse of the Internet.
644
645 Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the
646 experience of running and working on the Smail 3 code, I could never have
647 contemplated starting to write a new MTA. Many of the ideas and user interfaces
648 were originally taken from Smail 3, though the actual code of Exim is entirely
649 new, and has developed far beyond the initial concept.
650
651 Many people, both in Cambridge and around the world, have contributed to the
652 development and the testing of Exim, and to porting it to various operating
653 systems. I am grateful to them all. The distribution now contains a file called
654 ACKNOWLEDGMENTS, in which I have started recording the names of contributors.
655
656
657 1.1 Exim documentation
658 ----------------------
659
660 This edition of the Exim specification applies to version 4.84 of Exim.
661 Substantive changes from the 4.83 edition are marked in some renditions of the
662 document; this paragraph is so marked if the rendition is capable of showing a
663 change indicator.
664
665 This document is very much a reference manual; it is not a tutorial. The reader
666 is expected to have some familiarity with the SMTP mail transfer protocol and
667 with general Unix system administration. Although there are some discussions
668 and examples in places, the information is mostly organized in a way that makes
669 it easy to look up, rather than in a natural order for sequential reading.
670 Furthermore, the manual aims to cover every aspect of Exim in detail, including
671 a number of rarely-used, special-purpose features that are unlikely to be of
672 very wide interest.
673
674 An "easier" discussion of Exim which provides more in-depth explanatory,
675 introductory, and tutorial material can be found in a book entitled The Exim
676 SMTP Mail Server (second edition, 2007), published by UIT Cambridge (http://
677 www.uit.co.uk/exim-book/).
678
679 This book also contains a chapter that gives a general introduction to SMTP and
680 Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date
681 with the latest release of Exim. (Note that the earlier book about Exim,
682 published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.)
683
684 If you are using a Debian distribution of Exim, you will find information about
685 Debian-specific features in the file /usr/share/doc/exim4-base/README.Debian.
686 The command man update-exim.conf is another source of Debian-specific
687 information.
688
689 As the program develops, there may be features in newer versions that have not
690 yet made it into this document, which is updated only when the most significant
691 digit of the fractional part of the version number changes. Specifications of
692 new features that are not yet in this manual are placed in the file doc/
693 NewStuff in the Exim distribution.
694
695 Some features may be classified as "experimental". These may change
696 incompatibly while they are developing, or even be withdrawn. For this reason,
697 they are not documented in this manual. Information about experimental features
698 can be found in the file doc/experimental.txt.
699
700 All changes to the program (whether new features, bug fixes, or other kinds of
701 change) are noted briefly in the file called doc/ChangeLog.
702
703 This specification itself is available as an ASCII file in doc/spec.txt so that
704 it can easily be searched with a text editor. Other files in the doc directory
705 are:
706
707 OptionLists.txt list of all options in alphabetical order
708 dbm.discuss.txt discussion about DBM libraries
709 exim.8 a man page of Exim's command line options
710 experimental.txt documentation of experimental features
711 filter.txt specification of the filter language
712 Exim3.upgrade upgrade notes from release 2 to release 3
713 Exim4.upgrade upgrade notes from release 3 to release 4
714
715 The main specification and the specification of the filtering language are also
716 available in other formats (HTML, PostScript, PDF, and Texinfo). Section 1.6
717 below tells you how to get hold of these.
718
719
720 1.2 FTP and web sites
721 ---------------------
722
723 The primary site for Exim source distributions is currently the University of
724 Cambridge's FTP site, whose contents are described in Where to find the Exim
725 distribution below. In addition, there is a web site and an FTP site at
726 exim.org. These are now also hosted at the University of Cambridge. The
727 exim.org site was previously hosted for a number of years by Energis Squared,
728 formerly Planet Online Ltd, whose support I gratefully acknowledge.
729
730 As well as Exim distribution tar files, the Exim web site contains a number of
731 differently formatted versions of the documentation. A recent addition to the
732 online information is the Exim wiki (http://wiki.exim.org), which contains what
733 used to be a separate FAQ, as well as various other examples, tips, and
734 know-how that have been contributed by Exim users.
735
736 An Exim Bugzilla exists at http://bugs.exim.org. You can use this to report
737 bugs, and also to add items to the wish list. Please search first to check that
738 you are not duplicating a previous entry.
739
740
741 1.3 Mailing lists
742 -----------------
743
744 The following Exim mailing lists exist:
745
746 exim-announce@exim.org Moderated, low volume announcements list
747 exim-users@exim.org General discussion list
748 exim-dev@exim.org Discussion of bugs, enhancements, etc.
749 exim-cvs@exim.org Automated commit messages from the VCS
750
751 You can subscribe to these lists, change your existing subscriptions, and view
752 or search the archives via the mailing lists link on the Exim home page. If you
753 are using a Debian distribution of Exim, you may wish to subscribe to the
754 Debian-specific mailing list pkg-exim4-users@lists.alioth.debian.org via this
755 web page:
756
757 http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-users
758
759 Please ask Debian-specific questions on this list and not on the general Exim
760 lists.
761
762
763 1.4 Exim training
764 -----------------
765
766 Training courses in Cambridge (UK) used to be run annually by the author of
767 Exim, before he retired. At the time of writing, there are no plans to run
768 further Exim courses in Cambridge. However, if that changes, relevant
769 information will be posted at http://www-tus.csx.cam.ac.uk/courses/exim/.
770
771
772 1.5 Bug reports
773 ---------------
774
775 Reports of obvious bugs can be emailed to bugs@exim.org or reported via the
776 Bugzilla (http://bugs.exim.org). However, if you are unsure whether some
777 behaviour is a bug or not, the best thing to do is to post a message to the
778 exim-dev mailing list and have it discussed.
779
780
781 1.6 Where to find the Exim distribution
782 ---------------------------------------
783
784 The master ftp site for the Exim distribution is
785
786 ftp://ftp.csx.cam.ac.uk/pub/software/email/exim
787
788 This is mirrored by
789
790 ftp://ftp.exim.org/pub/exim
791
792 The file references that follow are relative to the exim directories at these
793 sites. There are now quite a number of independent mirror sites around the
794 world. Those that I know about are listed in the file called Mirrors.
795
796 Within the exim directory there are subdirectories called exim3 (for previous
797 Exim 3 distributions), exim4 (for the latest Exim 4 distributions), and Testing
798 for testing versions. In the exim4 subdirectory, the current release can always
799 be found in files called
800
801 exim-n.nn.tar.gz
802 exim-n.nn.tar.bz2
803
804 where n.nn is the highest such version number in the directory. The two files
805 contain identical data; the only difference is the type of compression. The
806 .bz2 file is usually a lot smaller than the .gz file.
807
808 The distributions will be PGP signed by an individual key of the Release
809 Coordinator. This key will have a uid containing an email address in the
810 exim.org domain and will have signatures from other people, including other
811 Exim maintainers. We expect that the key will be in the "strong set" of PGP
812 keys. There should be a trust path to that key from Nigel Metheringham's PGP
813 key, a version of which can be found in the release directory in the file
814 nigel-pubkey.asc. All keys used will be available in public keyserver pools,
815 such as pool.sks-keyservers.net.
816
817 At time of last update, releases were being made by Phil Pennock and signed
818 with key 0x403043153903637F, although that key is expected to be replaced in
819 2013. A trust path from Nigel's key to Phil's can be observed at https://
820 www.security.spodhuis.org/exim-trustpath.
821
822 Releases have also been authorized to be performed by Todd Lyons who signs with
823 key 0xC4F4F94804D29EBA. A direct trust path exists between previous RE Phil
824 Pennock and Todd Lyons through a common associate.
825
826 The signatures for the tar bundles are in:
827
828 exim-n.nn.tar.gz.asc
829 exim-n.nn.tar.bz2.asc
830
831 For each released version, the log of changes is made separately available in a
832 separate file in the directory ChangeLogs so that it is possible to find out
833 what has changed without having to download the entire distribution.
834
835 The main distribution contains ASCII versions of this specification and other
836 documentation; other formats of the documents are available in separate files
837 inside the exim4 directory of the FTP site:
838
839 exim-html-n.nn.tar.gz
840 exim-pdf-n.nn.tar.gz
841 exim-postscript-n.nn.tar.gz
842 exim-texinfo-n.nn.tar.gz
843
844 These tar files contain only the doc directory, not the complete distribution,
845 and are also available in .bz2 as well as .gz forms.
846
847
848 1.7 Limitations
849 ---------------
850
851 * Exim is designed for use as an Internet MTA, and therefore handles
852 addresses in RFC 2822 domain format only. It cannot handle UUCP "bang
853 paths", though simple two-component bang paths can be converted by a
854 straightforward rewriting configuration. This restriction does not prevent
855 Exim from being interfaced to UUCP as a transport mechanism, provided that
856 domain addresses are used.
857
858 * Exim insists that every address it handles has a domain attached. For
859 incoming local messages, domainless addresses are automatically qualified
860 with a configured domain value. Configuration options specify from which
861 remote systems unqualified addresses are acceptable. These are then
862 qualified on arrival.
863
864 * The only external transport mechanisms that are currently implemented are
865 SMTP and LMTP over a TCP/IP network (including support for IPv6). However,
866 a pipe transport is available, and there are facilities for writing
867 messages to files and pipes, optionally in batched SMTP format; these
868 facilities can be used to send messages to other transport mechanisms such
869 as UUCP, provided they can handle domain-style addresses. Batched SMTP
870 input is also catered for.
871
872 * Exim is not designed for storing mail for dial-in hosts. When the volumes
873 of such mail are large, it is better to get the messages "delivered" into
874 files (that is, off Exim's queue) and subsequently passed on to the dial-in
875 hosts by other means.
876
877 * Although Exim does have basic facilities for scanning incoming messages,
878 these are not comprehensive enough to do full virus or spam scanning. Such
879 operations are best carried out using additional specialized software
880 packages. If you compile Exim with the content-scanning extension,
881 straightforward interfaces to a number of common scanners are provided.
882
883
884 1.8 Run time configuration
885 --------------------------
886
887 Exim's run time configuration is held in a single text file that is divided
888 into a number of sections. The entries in this file consist of keywords and
889 values, in the style of Smail 3 configuration files. A default configuration
890 file which is suitable for simple online installations is provided in the
891 distribution, and is described in chapter 7 below.
892
893
894 1.9 Calling interface
895 ---------------------
896
897 Like many MTAs, Exim has adopted the Sendmail command line interface so that it
898 can be a straight replacement for /usr/lib/sendmail or /usr/sbin/sendmail when
899 sending mail, but you do not need to know anything about Sendmail in order to
900 run Exim. For actions other than sending messages, Sendmail-compatible options
901 also exist, but those that produce output (for example, -bp, which lists the
902 messages on the queue) do so in Exim's own format. There are also some
903 additional options that are compatible with Smail 3, and some further options
904 that are new to Exim. Chapter 5 documents all Exim's command line options. This
905 information is automatically made into the man page that forms part of the Exim
906 distribution.
907
908 Control of messages on the queue can be done via certain privileged command
909 line options. There is also an optional monitor program called eximon, which
910 displays current information in an X window, and which contains a menu
911 interface to Exim's command line administration options.
912
913
914 1.10 Terminology
915 ----------------
916
917 The body of a message is the actual data that the sender wants to transmit. It
918 is the last part of a message, and is separated from the header (see below) by
919 a blank line.
920
921 When a message cannot be delivered, it is normally returned to the sender in a
922 delivery failure message or a "non-delivery report" (NDR). The term bounce is
923 commonly used for this action, and the error reports are often called bounce
924 messages. This is a convenient shorthand for "delivery failure error report".
925 Such messages have an empty sender address in the message's envelope (see
926 below) to ensure that they cannot themselves give rise to further bounce
927 messages.
928
929 The term default appears frequently in this manual. It is used to qualify a
930 value which is used in the absence of any setting in the configuration. It may
931 also qualify an action which is taken unless a configuration setting specifies
932 otherwise.
933
934 The term defer is used when the delivery of a message to a specific destination
935 cannot immediately take place for some reason (a remote host may be down, or a
936 user's local mailbox may be full). Such deliveries are deferred until a later
937 time.
938
939 The word domain is sometimes used to mean all but the first component of a
940 host's name. It is not used in that sense here, where it normally refers to the
941 part of an email address following the @ sign.
942
943 A message in transit has an associated envelope, as well as a header and a
944 body. The envelope contains a sender address (to which bounce messages should
945 be delivered), and any number of recipient addresses. References to the sender
946 or the recipients of a message usually mean the addresses in the envelope. An
947 MTA uses these addresses for delivery, and for returning bounce messages, not
948 the addresses that appear in the header lines.
949
950 The header of a message is the first part of a message's text, consisting of a
951 number of lines, each of which has a name such as From:, To:, Subject:, etc.
952 Long header lines can be split over several text lines by indenting the
953 continuations. The header is separated from the body by a blank line.
954
955 The term local part, which is taken from RFC 2822, is used to refer to that
956 part of an email address that precedes the @ sign. The part that follows the @
957 sign is called the domain or mail domain.
958
959 The terms local delivery and remote delivery are used to distinguish delivery
960 to a file or a pipe on the local host from delivery by SMTP over TCP/IP to
961 another host. As far as Exim is concerned, all hosts other than the host it is
962 running on are remote.
963
964 Return path is another name that is used for the sender address in a message's
965 envelope.
966
967 The term queue is used to refer to the set of messages awaiting delivery,
968 because this term is in widespread use in the context of MTAs. However, in
969 Exim's case the reality is more like a pool than a queue, because there is
970 normally no ordering of waiting messages.
971
972 The term queue runner is used to describe a process that scans the queue and
973 attempts to deliver those messages whose retry times have come. This term is
974 used by other MTAs, and also relates to the command runq, but in Exim the
975 waiting messages are normally processed in an unpredictable order.
976
977 The term spool directory is used for a directory in which Exim keeps the
978 messages on its queue - that is, those that it is in the process of delivering.
979 This should not be confused with the directory in which local mailboxes are
980 stored, which is called a "spool directory" by some people. In the Exim
981 documentation, "spool" is always used in the first sense.
982
983
984
985 ===============================================================================
986 2. INCORPORATED CODE
987
988 A number of pieces of external code are included in the Exim distribution.
989
990 * Regular expressions are supported in the main Exim program and in the Exim
991 monitor using the freely-distributable PCRE library, copyright (c)
992 University of Cambridge. The source to PCRE is no longer shipped with Exim,
993 so you will need to use the version of PCRE shipped with your system, or
994 obtain and install the full version of the library from ftp://
995 ftp.csx.cam.ac.uk/pub/software/programming/pcre.
996
997 * Support for the cdb (Constant DataBase) lookup method is provided by code
998 contributed by Nigel Metheringham of (at the time he contributed it) Planet
999 Online Ltd. The implementation is completely contained within the code of
1000 Exim. It does not link against an external cdb library. The code contains
1001 the following statements:
1002
1003 Copyright (c) 1998 Nigel Metheringham, Planet Online Ltd
1004
1005 This program is free software; you can redistribute it and/or modify it
1006 under the terms of the GNU General Public License as published by the
1007 Free Software Foundation; either version 2 of the License, or (at your
1008 option) any later version. This code implements Dan Bernstein's
1009 Constant DataBase (cdb) spec. Information, the spec and sample code for
1010 cdb can be obtained from http://www.pobox.com/~djb/cdb.html. This
1011 implementation borrows some code from Dan Bernstein's implementation
1012 (which has no license restrictions applied to it).
1013
1014 * Client support for Microsoft's Secure Password Authentication is provided
1015 by code contributed by Marc Prud'hommeaux. Server support was contributed
1016 by Tom Kistner. This includes code taken from the Samba project, which is
1017 released under the Gnu GPL.
1018
1019 * Support for calling the Cyrus pwcheck and saslauthd daemons is provided by
1020 code taken from the Cyrus-SASL library and adapted by Alexander S.
1021 Sabourenkov. The permission notice appears below, in accordance with the
1022 conditions expressed therein.
1023
1024 Copyright (c) 2001 Carnegie Mellon University. All rights reserved.
1025
1026 Redistribution and use in source and binary forms, with or without
1027 modification, are permitted provided that the following conditions are
1028 met:
1029
1030 1. Redistributions of source code must retain the above copyright
1031 notice, this list of conditions and the following disclaimer.
1032
1033 2. Redistributions in binary form must reproduce the above copyright
1034 notice, this list of conditions and the following disclaimer in the
1035 documentation and/or other materials provided with the
1036 distribution.
1037
1038 3. The name "Carnegie Mellon University" must not be used to endorse
1039 or promote products derived from this software without prior
1040 written permission. For permission or any other legal details,
1041 please contact
1042
1043 Office of Technology Transfer
1044 Carnegie Mellon University
1045 5000 Forbes Avenue
1046 Pittsburgh, PA 15213-3890
1047 (412) 268-4387, fax: (412) 268-7395
1048 tech-transfer@andrew.cmu.edu
1049
1050 4. Redistributions of any form whatsoever must retain the following
1051 acknowledgment:
1052
1053 "This product includes software developed by Computing Services at
1054 Carnegie Mellon University (http://www.cmu.edu/computing/."
1055
1056 CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO
1057 THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
1058 AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE
1059 FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
1060 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
1061 AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
1062 OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
1063 SOFTWARE.
1064
1065 * The Exim Monitor program, which is an X-Window application, includes
1066 modified versions of the Athena StripChart and TextPop widgets. This code
1067 is copyright by DEC and MIT, and their permission notice appears below, in
1068 accordance with the conditions expressed therein.
1069
1070 Copyright 1987, 1988 by Digital Equipment Corporation, Maynard,
1071 Massachusetts, and the Massachusetts Institute of Technology,
1072 Cambridge, Massachusetts.
1073
1074 All Rights Reserved
1075
1076 Permission to use, copy, modify, and distribute this software and its
1077 documentation for any purpose and without fee is hereby granted,
1078 provided that the above copyright notice appear in all copies and that
1079 both that copyright notice and this permission notice appear in
1080 supporting documentation, and that the names of Digital or MIT not be
1081 used in advertising or publicity pertaining to distribution of the
1082 software without specific, written prior permission.
1083
1084 DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
1085 INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
1086 EVENT SHALL DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR
1087 CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
1088 USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
1089 OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
1090 PERFORMANCE OF THIS SOFTWARE.
1091
1092 * The DMARC implementation uses the OpenDMARC library which is Copyrighted by
1093 The Trusted Domain Project. Portions of Exim source which use OpenDMARC
1094 derived code are indicated in the respective source files. The full
1095 OpenDMARC license is provided in the LICENSE.opendmarc file contained in
1096 the distributed source code.
1097
1098 * Many people have contributed code fragments, some large, some small, that
1099 were not covered by any specific licence requirements. It is assumed that
1100 the contributors are happy to see their code incorporated into Exim under
1101 the GPL.
1102
1103
1104
1105 ===============================================================================
1106 3. HOW EXIM RECEIVES AND DELIVERS MAIL
1107
1108
1109 3.1 Overall philosophy
1110 ----------------------
1111
1112 Exim is designed to work efficiently on systems that are permanently connected
1113 to the Internet and are handling a general mix of mail. In such circumstances,
1114 most messages can be delivered immediately. Consequently, Exim does not
1115 maintain independent queues of messages for specific domains or hosts, though
1116 it does try to send several messages in a single SMTP connection after a host
1117 has been down, and it also maintains per-host retry information.
1118
1119
1120 3.2 Policy control
1121 ------------------
1122
1123 Policy controls are now an important feature of MTAs that are connected to the
1124 Internet. Perhaps their most important job is to stop MTAs being abused as
1125 "open relays" by misguided individuals who send out vast amounts of unsolicited
1126 junk, and want to disguise its source. Exim provides flexible facilities for
1127 specifying policy controls on incoming mail:
1128
1129 * Exim 4 (unlike previous versions of Exim) implements policy controls on
1130 incoming mail by means of Access Control Lists (ACLs). Each list is a
1131 series of statements that may either grant or deny access. ACLs can be used
1132 at several places in the SMTP dialogue while receiving a message from a
1133 remote host. However, the most common places are after each RCPT command,
1134 and at the very end of the message. The sysadmin can specify conditions for
1135 accepting or rejecting individual recipients or the entire message,
1136 respectively, at these two points (see chapter 42). Denial of access
1137 results in an SMTP error code.
1138
1139 * An ACL is also available for locally generated, non-SMTP messages. In this
1140 case, the only available actions are to accept or deny the entire message.
1141
1142 * When Exim is compiled with the content-scanning extension, facilities are
1143 provided in the ACL mechanism for passing the message to external virus and
1144 /or spam scanning software. The result of such a scan is passed back to the
1145 ACL, which can then use it to decide what to do with the message.
1146
1147 * When a message has been received, either from a remote host or from the
1148 local host, but before the final acknowledgment has been sent, a locally
1149 supplied C function called local_scan() can be run to inspect the message
1150 and decide whether to accept it or not (see chapter 44). If the message is
1151 accepted, the list of recipients can be modified by the function.
1152
1153 * Using the local_scan() mechanism is another way of calling external scanner
1154 software. The SA-Exim add-on package works this way. It does not require
1155 Exim to be compiled with the content-scanning extension.
1156
1157 * After a message has been accepted, a further checking mechanism is
1158 available in the form of the system filter (see chapter 45). This runs at
1159 the start of every delivery process.
1160
1161
1162 3.3 User filters
1163 ----------------
1164
1165 In a conventional Exim configuration, users are able to run private filters by
1166 setting up appropriate .forward files in their home directories. See chapter 22
1167 (about the redirect router) for the configuration needed to support this, and
1168 the separate document entitled Exim's interfaces to mail filtering for user
1169 details. Two different kinds of filtering are available:
1170
1171 * Sieve filters are written in the standard filtering language that is
1172 defined by RFC 3028.
1173
1174 * Exim filters are written in a syntax that is unique to Exim, but which is
1175 more powerful than Sieve, which it pre-dates.
1176
1177 User filters are run as part of the routing process, described below.
1178
1179
1180 3.4 Message identification
1181 --------------------------
1182
1183 Every message handled by Exim is given a message id which is sixteen characters
1184 long. It is divided into three parts, separated by hyphens, for example
1185 "16VDhn-0001bo-D3". Each part is a sequence of letters and digits, normally
1186 encoding numbers in base 62. However, in the Darwin operating system (Mac OS X)
1187 and when Exim is compiled to run under Cygwin, base 36 (avoiding the use of
1188 lower case letters) is used instead, because the message id is used to
1189 construct file names, and the names of files in those systems are not always
1190 case-sensitive.
1191
1192 The detail of the contents of the message id have changed as Exim has evolved.
1193 Earlier versions relied on the operating system not re-using a process id (pid)
1194 within one second. On modern operating systems, this assumption can no longer
1195 be made, so the algorithm had to be changed. To retain backward compatibility,
1196 the format of the message id was retained, which is why the following rules are
1197 somewhat eccentric:
1198
1199 * The first six characters of the message id are the time at which the
1200 message started to be received, to a granularity of one second. That is,
1201 this field contains the number of seconds since the start of the epoch (the
1202 normal Unix way of representing the date and time of day).
1203
1204 * After the first hyphen, the next six characters are the id of the process
1205 that received the message.
1206
1207 * There are two different possibilities for the final two characters:
1208
1209 1. If localhost_number is not set, this value is the fractional part of
1210 the time of reception, normally in units of 1/2000 of a second, but for
1211 systems that must use base 36 instead of base 62 (because of
1212 case-insensitive file systems), the units are 1/1000 of a second.
1213
1214 2. If localhost_number is set, it is multiplied by 200 (100) and added to
1215 the fractional part of the time, which in this case is in units of 1/
1216 200 (1/100) of a second.
1217
1218 After a message has been received, Exim waits for the clock to tick at the
1219 appropriate resolution before proceeding, so that if another message is
1220 received by the same process, or by another process with the same (re-used)
1221 pid, it is guaranteed that the time will be different. In most cases, the clock
1222 will already have ticked while the message was being received.
1223
1224
1225 3.5 Receiving mail
1226 ------------------
1227
1228 The only way Exim can receive mail from another host is using SMTP over TCP/IP,
1229 in which case the sender and recipient addresses are transferred using SMTP
1230 commands. However, from a locally running process (such as a user's MUA), there
1231 are several possibilities:
1232
1233 * If the process runs Exim with the -bm option, the message is read
1234 non-interactively (usually via a pipe), with the recipients taken from the
1235 command line, or from the body of the message if -t is also used.
1236
1237 * If the process runs Exim with the -bS option, the message is also read
1238 non-interactively, but in this case the recipients are listed at the start
1239 of the message in a series of SMTP RCPT commands, terminated by a DATA
1240 command. This is so-called "batch SMTP" format, but it isn't really SMTP.
1241 The SMTP commands are just another way of passing envelope addresses in a
1242 non-interactive submission.
1243
1244 * If the process runs Exim with the -bs option, the message is read
1245 interactively, using the SMTP protocol. A two-way pipe is normally used for
1246 passing data between the local process and the Exim process. This is "real"
1247 SMTP and is handled in the same way as SMTP over TCP/IP. For example, the
1248 ACLs for SMTP commands are used for this form of submission.
1249
1250 * A local process may also make a TCP/IP call to the host's loopback address
1251 (127.0.0.1) or any other of its IP addresses. When receiving messages, Exim
1252 does not treat the loopback address specially. It treats all such
1253 connections in the same way as connections from other hosts.
1254
1255 In the three cases that do not involve TCP/IP, the sender address is
1256 constructed from the login name of the user that called Exim and a default
1257 qualification domain (which can be set by the qualify_domain configuration
1258 option). For local or batch SMTP, a sender address that is passed using the
1259 SMTP MAIL command is ignored. However, the system administrator may allow
1260 certain users ("trusted users") to specify a different sender address
1261 unconditionally, or all users to specify certain forms of different sender
1262 address. The -f option or the SMTP MAIL command is used to specify these
1263 different addresses. See section 5.2 for details of trusted users, and the
1264 untrusted_set_sender option for a way of allowing untrusted users to change
1265 sender addresses.
1266
1267 Messages received by either of the non-interactive mechanisms are subject to
1268 checking by the non-SMTP ACL, if one is defined. Messages received using SMTP
1269 (either over TCP/IP, or interacting with a local process) can be checked by a
1270 number of ACLs that operate at different times during the SMTP session. Either
1271 individual recipients, or the entire message, can be rejected if local policy
1272 requirements are not met. The local_scan() function (see chapter 44) is run for
1273 all incoming messages.
1274
1275 Exim can be configured not to start a delivery process when a message is
1276 received; this can be unconditional, or depend on the number of incoming SMTP
1277 connections or the system load. In these situations, new messages wait on the
1278 queue until a queue runner process picks them up. However, in standard
1279 configurations under normal conditions, delivery is started as soon as a
1280 message is received.
1281
1282
1283 3.6 Handling an incoming message
1284 --------------------------------
1285
1286 When Exim accepts a message, it writes two files in its spool directory. The
1287 first contains the envelope information, the current status of the message, and
1288 the header lines, and the second contains the body of the message. The names of
1289 the two spool files consist of the message id, followed by "-H" for the file
1290 containing the envelope and header, and "-D" for the data file.
1291
1292 By default all these message files are held in a single directory called input
1293 inside the general Exim spool directory. Some operating systems do not perform
1294 very well if the number of files in a directory gets large; to improve
1295 performance in such cases, the split_spool_directory option can be used. This
1296 causes Exim to split up the input files into 62 sub-directories whose names are
1297 single letters or digits. When this is done, the queue is processed one
1298 sub-directory at a time instead of all at once, which can improve overall
1299 performance even when there are not enough files in each directory to affect
1300 file system performance.
1301
1302 The envelope information consists of the address of the message's sender and
1303 the addresses of the recipients. This information is entirely separate from any
1304 addresses contained in the header lines. The status of the message includes a
1305 list of recipients who have already received the message. The format of the
1306 first spool file is described in chapter 55.
1307
1308 Address rewriting that is specified in the rewrite section of the configuration
1309 (see chapter 31) is done once and for all on incoming addresses, both in the
1310 header lines and the envelope, at the time the message is accepted. If during
1311 the course of delivery additional addresses are generated (for example, via
1312 aliasing), these new addresses are rewritten as soon as they are generated. At
1313 the time a message is actually delivered (transported) further rewriting can
1314 take place; because this is a transport option, it can be different for
1315 different forms of delivery. It is also possible to specify the addition or
1316 removal of certain header lines at the time the message is delivered (see
1317 chapters 15 and 24).
1318
1319
1320 3.7 Life of a message
1321 ---------------------
1322
1323 A message remains in the spool directory until it is completely delivered to
1324 its recipients or to an error address, or until it is deleted by an
1325 administrator or by the user who originally created it. In cases when delivery
1326 cannot proceed - for example, when a message can neither be delivered to its
1327 recipients nor returned to its sender, the message is marked "frozen" on the
1328 spool, and no more deliveries are attempted.
1329
1330 An administrator can "thaw" such messages when the problem has been corrected,
1331 and can also freeze individual messages by hand if necessary. In addition, an
1332 administrator can force a delivery error, causing a bounce message to be sent.
1333
1334 There are options called ignore_bounce_errors_after and timeout_frozen_after,
1335 which discard frozen messages after a certain time. The first applies only to
1336 frozen bounces, the second to any frozen messages.
1337
1338 While Exim is working on a message, it writes information about each delivery
1339 attempt to its main log file. This includes successful, unsuccessful, and
1340 delayed deliveries for each recipient (see chapter 51). The log lines are also
1341 written to a separate message log file for each message. These logs are solely
1342 for the benefit of the administrator, and are normally deleted along with the
1343 spool files when processing of a message is complete. The use of individual
1344 message logs can be disabled by setting no_message_logs; this might give an
1345 improvement in performance on very busy systems.
1346
1347 All the information Exim itself needs to set up a delivery is kept in the first
1348 spool file, along with the header lines. When a successful delivery occurs, the
1349 address is immediately written at the end of a journal file, whose name is the
1350 message id followed by "-J". At the end of a delivery run, if there are some
1351 addresses left to be tried again later, the first spool file (the "-H" file) is
1352 updated to indicate which these are, and the journal file is then deleted.
1353 Updating the spool file is done by writing a new file and renaming it, to
1354 minimize the possibility of data loss.
1355
1356 Should the system or the program crash after a successful delivery but before
1357 the spool file has been updated, the journal is left lying around. The next
1358 time Exim attempts to deliver the message, it reads the journal file and
1359 updates the spool file before proceeding. This minimizes the chances of double
1360 deliveries caused by crashes.
1361
1362
1363 3.8 Processing an address for delivery
1364 --------------------------------------
1365
1366 The main delivery processing elements of Exim are called routers and transports
1367 , and collectively these are known as drivers. Code for a number of them is
1368 provided in the source distribution, and compile-time options specify which
1369 ones are included in the binary. Run time options specify which ones are
1370 actually used for delivering messages.
1371
1372 Each driver that is specified in the run time configuration is an instance of
1373 that particular driver type. Multiple instances are allowed; for example, you
1374 can set up several different smtp transports, each with different option values
1375 that might specify different ports or different timeouts. Each instance has its
1376 own identifying name. In what follows we will normally use the instance name
1377 when discussing one particular instance (that is, one specific configuration of
1378 the driver), and the generic driver name when discussing the driver's features
1379 in general.
1380
1381 A router is a driver that operates on an address, either determining how its
1382 delivery should happen, by assigning it to a specific transport, or converting
1383 the address into one or more new addresses (for example, via an alias file). A
1384 router may also explicitly choose to fail an address, causing it to be bounced.
1385
1386 A transport is a driver that transmits a copy of the message from Exim's spool
1387 to some destination. There are two kinds of transport: for a local transport,
1388 the destination is a file or a pipe on the local host, whereas for a remote
1389 transport the destination is some other host. A message is passed to a specific
1390 transport as a result of successful routing. If a message has several
1391 recipients, it may be passed to a number of different transports.
1392
1393 An address is processed by passing it to each configured router instance in
1394 turn, subject to certain preconditions, until a router accepts the address or
1395 specifies that it should be bounced. We will describe this process in more
1396 detail shortly. First, as a simple example, we consider how each recipient
1397 address in a message is processed in a small configuration of three routers.
1398
1399 To make this a more concrete example, it is described in terms of some actual
1400 routers, but remember, this is only an example. You can configure Exim's
1401 routers in many different ways, and there may be any number of routers in a
1402 configuration.
1403
1404 The first router that is specified in a configuration is often one that handles
1405 addresses in domains that are not recognized specially by the local host. These
1406 are typically addresses for arbitrary domains on the Internet. A precondition
1407 is set up which looks for the special domains known to the host (for example,
1408 its own domain name), and the router is run for addresses that do not match.
1409 Typically, this is a router that looks up domains in the DNS in order to find
1410 the hosts to which this address routes. If it succeeds, the address is assigned
1411 to a suitable SMTP transport; if it does not succeed, the router is configured
1412 to fail the address.
1413
1414 The second router is reached only when the domain is recognized as one that
1415 "belongs" to the local host. This router does redirection - also known as
1416 aliasing and forwarding. When it generates one or more new addresses from the
1417 original, each of them is routed independently from the start. Otherwise, the
1418 router may cause an address to fail, or it may simply decline to handle the
1419 address, in which case the address is passed to the next router.
1420
1421 The final router in many configurations is one that checks to see if the
1422 address belongs to a local mailbox. The precondition may involve a check to see
1423 if the local part is the name of a login account, or it may look up the local
1424 part in a file or a database. If its preconditions are not met, or if the
1425 router declines, we have reached the end of the routers. When this happens, the
1426 address is bounced.
1427
1428
1429 3.9 Processing an address for verification
1430 ------------------------------------------
1431
1432 As well as being used to decide how to deliver to an address, Exim's routers
1433 are also used for address verification. Verification can be requested as one of
1434 the checks to be performed in an ACL for incoming messages, on both sender and
1435 recipient addresses, and it can be tested using the -bv and -bvs command line
1436 options.
1437
1438 When an address is being verified, the routers are run in "verify mode". This
1439 does not affect the way the routers work, but it is a state that can be
1440 detected. By this means, a router can be skipped or made to behave differently
1441 when verifying. A common example is a configuration in which the first router
1442 sends all messages to a message-scanning program, unless they have been
1443 previously scanned. Thus, the first router accepts all addresses without any
1444 checking, making it useless for verifying. Normally, the no_verify option would
1445 be set for such a router, causing it to be skipped in verify mode.
1446
1447
1448 3.10 Running an individual router
1449 ---------------------------------
1450
1451 As explained in the example above, a number of preconditions are checked before
1452 running a router. If any are not met, the router is skipped, and the address is
1453 passed to the next router. When all the preconditions on a router are met, the
1454 router is run. What happens next depends on the outcome, which is one of the
1455 following:
1456
1457 * accept: The router accepts the address, and either assigns it to a
1458 transport, or generates one or more "child" addresses. Processing the
1459 original address ceases, unless the unseen option is set on the router.
1460 This option can be used to set up multiple deliveries with different
1461 routing (for example, for keeping archive copies of messages). When unseen
1462 is set, the address is passed to the next router. Normally, however, an
1463 accept return marks the end of routing.
1464
1465 Any child addresses generated by the router are processed independently,
1466 starting with the first router by default. It is possible to change this by
1467 setting the redirect_router option to specify which router to start at for
1468 child addresses. Unlike pass_router (see below) the router specified by
1469 redirect_router may be anywhere in the router configuration.
1470
1471 * pass: The router recognizes the address, but cannot handle it itself. It
1472 requests that the address be passed to another router. By default the
1473 address is passed to the next router, but this can be changed by setting
1474 the pass_router option. However, (unlike redirect_router) the named router
1475 must be below the current router (to avoid loops).
1476
1477 * decline: The router declines to accept the address because it does not
1478 recognize it at all. By default, the address is passed to the next router,
1479 but this can be prevented by setting the no_more option. When no_more is
1480 set, all the remaining routers are skipped. In effect, no_more converts
1481 decline into fail.
1482
1483 * fail: The router determines that the address should fail, and queues it for
1484 the generation of a bounce message. There is no further processing of the
1485 original address unless unseen is set on the router.
1486
1487 * defer: The router cannot handle the address at the present time. (A
1488 database may be offline, or a DNS lookup may have timed out.) No further
1489 processing of the address happens in this delivery attempt. It is tried
1490 again next time the message is considered for delivery.
1491
1492 * error: There is some error in the router (for example, a syntax error in
1493 its configuration). The action is as for defer.
1494
1495 If an address reaches the end of the routers without having been accepted by
1496 any of them, it is bounced as unrouteable. The default error message in this
1497 situation is "unrouteable address", but you can set your own message by making
1498 use of the cannot_route_message option. This can be set for any router; the
1499 value from the last router that "saw" the address is used.
1500
1501 Sometimes while routing you want to fail a delivery when some conditions are
1502 met but others are not, instead of passing the address on for further routing.
1503 You can do this by having a second router that explicitly fails the delivery
1504 when the relevant conditions are met. The redirect router has a "fail" facility
1505 for this purpose.
1506
1507
1508 3.11 Duplicate addresses
1509 ------------------------
1510
1511 Once routing is complete, Exim scans the addresses that are assigned to local
1512 and remote transports, and discards any duplicates that it finds. During this
1513 check, local parts are treated as case-sensitive. This happens only when
1514 actually delivering a message; when testing routers with -bt, all the routed
1515 addresses are shown.
1516
1517
1518 3.12 Router preconditions
1519 -------------------------
1520
1521 The preconditions that are tested for each router are listed below, in the
1522 order in which they are tested. The individual configuration options are
1523 described in more detail in chapter 15.
1524
1525 * The local_part_prefix and local_part_suffix options can specify that the
1526 local parts handled by the router may or must have certain prefixes and/or
1527 suffixes. If a mandatory affix (prefix or suffix) is not present, the
1528 router is skipped. These conditions are tested first. When an affix is
1529 present, it is removed from the local part before further processing,
1530 including the evaluation of any other conditions.
1531
1532 * Routers can be designated for use only when not verifying an address, that
1533 is, only when routing it for delivery (or testing its delivery routing). If
1534 the verify option is set false, the router is skipped when Exim is
1535 verifying an address. Setting the verify option actually sets two options,
1536 verify_sender and verify_recipient, which independently control the use of
1537 the router for sender and recipient verification. You can set these options
1538 directly if you want a router to be used for only one type of verification.
1539 Note that cutthrough delivery is classed as a recipient verification for
1540 this purpose.
1541
1542 * If the address_test option is set false, the router is skipped when Exim is
1543 run with the -bt option to test an address routing. This can be helpful
1544 when the first router sends all new messages to a scanner of some sort; it
1545 makes it possible to use -bt to test subsequent delivery routing without
1546 having to simulate the effect of the scanner.
1547
1548 * Routers can be designated for use only when verifying an address, as
1549 opposed to routing it for delivery. The verify_only option controls this.
1550 Again, cutthrough delivery counts as a verification.
1551
1552 * Individual routers can be explicitly skipped when running the routers to
1553 check an address given in the SMTP EXPN command (see the expn option).
1554
1555 * If the domains option is set, the domain of the address must be in the set
1556 of domains that it defines.
1557
1558 * If the local_parts option is set, the local part of the address must be in
1559 the set of local parts that it defines. If local_part_prefix or
1560 local_part_suffix is in use, the prefix or suffix is removed from the local
1561 part before this check. If you want to do precondition tests on local parts
1562 that include affixes, you can do so by using a condition option (see below)
1563 that uses the variables $local_part, $local_part_prefix, and
1564 $local_part_suffix as necessary.
1565
1566 * If the check_local_user option is set, the local part must be the name of
1567 an account on the local host. If this check succeeds, the uid and gid of
1568 the local user are placed in $local_user_uid and $local_user_gid and the
1569 user's home directory is placed in $home; these values can be used in the
1570 remaining preconditions.
1571
1572 * If the router_home_directory option is set, it is expanded at this point,
1573 because it overrides the value of $home. If this expansion were left till
1574 later, the value of $home as set by check_local_user would be used in
1575 subsequent tests. Having two different values of $home in the same router
1576 could lead to confusion.
1577
1578 * If the senders option is set, the envelope sender address must be in the
1579 set of addresses that it defines.
1580
1581 * If the require_files option is set, the existence or non-existence of
1582 specified files is tested.
1583
1584 * If the condition option is set, it is evaluated and tested. This option
1585 uses an expanded string to allow you to set up your own custom
1586 preconditions. Expanded strings are described in chapter 11.
1587
1588 Note that require_files comes near the end of the list, so you cannot use it to
1589 check for the existence of a file in which to lookup up a domain, local part,
1590 or sender. However, as these options are all expanded, you can use the exists
1591 expansion condition to make such tests within each condition. The require_files
1592 option is intended for checking files that the router may be going to use
1593 internally, or which are needed by a specific transport (for example,
1594 .procmailrc).
1595
1596
1597 3.13 Delivery in detail
1598 -----------------------
1599
1600 When a message is to be delivered, the sequence of events is as follows:
1601
1602 * If a system-wide filter file is specified, the message is passed to it. The
1603 filter may add recipients to the message, replace the recipients, discard
1604 the message, cause a new message to be generated, or cause the message
1605 delivery to fail. The format of the system filter file is the same as for
1606 Exim user filter files, described in the separate document entitled Exim's
1607 interfaces to mail filtering. (Note: Sieve cannot be used for system filter
1608 files.)
1609
1610 Some additional features are available in system filters - see chapter 45
1611 for details. Note that a message is passed to the system filter only once
1612 per delivery attempt, however many recipients it has. However, if there are
1613 several delivery attempts because one or more addresses could not be
1614 immediately delivered, the system filter is run each time. The filter
1615 condition first_delivery can be used to detect the first run of the system
1616 filter.
1617
1618 * Each recipient address is offered to each configured router in turn,
1619 subject to its preconditions, until one is able to handle it. If no router
1620 can handle the address, that is, if they all decline, the address is
1621 failed. Because routers can be targeted at particular domains, several
1622 locally handled domains can be processed entirely independently of each
1623 other.
1624
1625 * A router that accepts an address may assign it to a local or a remote
1626 transport. However, the transport is not run at this time. Instead, the
1627 address is placed on a list for the particular transport, which will be run
1628 later. Alternatively, the router may generate one or more new addresses
1629 (typically from alias, forward, or filter files). New addresses are fed
1630 back into this process from the top, but in order to avoid loops, a router
1631 ignores any address which has an identically-named ancestor that was
1632 processed by itself.
1633
1634 * When all the routing has been done, addresses that have been successfully
1635 handled are passed to their assigned transports. When local transports are
1636 doing real local deliveries, they handle only one address at a time, but if
1637 a local transport is being used as a pseudo-remote transport (for example,
1638 to collect batched SMTP messages for transmission by some other means)
1639 multiple addresses can be handled. Remote transports can always handle more
1640 than one address at a time, but can be configured not to do so, or to
1641 restrict multiple addresses to the same domain.
1642
1643 * Each local delivery to a file or a pipe runs in a separate process under a
1644 non-privileged uid, and these deliveries are run one at a time. Remote
1645 deliveries also run in separate processes, normally under a uid that is
1646 private to Exim ("the Exim user"), but in this case, several remote
1647 deliveries can be run in parallel. The maximum number of simultaneous
1648 remote deliveries for any one message is set by the remote_max_parallel
1649 option. The order in which deliveries are done is not defined, except that
1650 all local deliveries happen before any remote deliveries.
1651
1652 * When it encounters a local delivery during a queue run, Exim checks its
1653 retry database to see if there has been a previous temporary delivery
1654 failure for the address before running the local transport. If there was a
1655 previous failure, Exim does not attempt a new delivery until the retry time
1656 for the address is reached. However, this happens only for delivery
1657 attempts that are part of a queue run. Local deliveries are always
1658 attempted when delivery immediately follows message reception, even if
1659 retry times are set for them. This makes for better behaviour if one
1660 particular message is causing problems (for example, causing quota
1661 overflow, or provoking an error in a filter file).
1662
1663 * Remote transports do their own retry handling, since an address may be
1664 deliverable to one of a number of hosts, each of which may have a different
1665 retry time. If there have been previous temporary failures and no host has
1666 reached its retry time, no delivery is attempted, whether in a queue run or
1667 not. See chapter 32 for details of retry strategies.
1668
1669 * If there were any permanent errors, a bounce message is returned to an
1670 appropriate address (the sender in the common case), with details of the
1671 error for each failing address. Exim can be configured to send copies of
1672 bounce messages to other addresses.
1673
1674 * If one or more addresses suffered a temporary failure, the message is left
1675 on the queue, to be tried again later. Delivery of these addresses is said
1676 to be deferred.
1677
1678 * When all the recipient addresses have either been delivered or bounced,
1679 handling of the message is complete. The spool files and message log are
1680 deleted, though the message log can optionally be preserved if required.
1681
1682
1683 3.14 Retry mechanism
1684 --------------------
1685
1686 Exim's mechanism for retrying messages that fail to get delivered at the first
1687 attempt is the queue runner process. You must either run an Exim daemon that
1688 uses the -q option with a time interval to start queue runners at regular
1689 intervals, or use some other means (such as cron) to start them. If you do not
1690 arrange for queue runners to be run, messages that fail temporarily at the
1691 first attempt will remain on your queue for ever. A queue runner process works
1692 its way through the queue, one message at a time, trying each delivery that has
1693 passed its retry time. You can run several queue runners at once.
1694
1695 Exim uses a set of configured rules to determine when next to retry the failing
1696 address (see chapter 32). These rules also specify when Exim should give up
1697 trying to deliver to the address, at which point it generates a bounce message.
1698 If no retry rules are set for a particular host, address, and error
1699 combination, no retries are attempted, and temporary errors are treated as
1700 permanent.
1701
1702
1703 3.15 Temporary delivery failure
1704 -------------------------------
1705
1706 There are many reasons why a message may not be immediately deliverable to a
1707 particular address. Failure to connect to a remote machine (because it, or the
1708 connection to it, is down) is one of the most common. Temporary failures may be
1709 detected during routing as well as during the transport stage of delivery.
1710 Local deliveries may be delayed if NFS files are unavailable, or if a mailbox
1711 is on a file system where the user is over quota. Exim can be configured to
1712 impose its own quotas on local mailboxes; where system quotas are set they will
1713 also apply.
1714
1715 If a host is unreachable for a period of time, a number of messages may be
1716 waiting for it by the time it recovers, and sending them in a single SMTP
1717 connection is clearly beneficial. Whenever a delivery to a remote host is
1718 deferred, Exim makes a note in its hints database, and whenever a successful
1719 SMTP delivery has happened, it looks to see if any other messages are waiting
1720 for the same host. If any are found, they are sent over the same SMTP
1721 connection, subject to a configuration limit as to the maximum number in any
1722 one connection.
1723
1724
1725 3.16 Permanent delivery failure
1726 -------------------------------
1727
1728 When a message cannot be delivered to some or all of its intended recipients, a
1729 bounce message is generated. Temporary delivery failures turn into permanent
1730 errors when their timeout expires. All the addresses that fail in a given
1731 delivery attempt are listed in a single message. If the original message has
1732 many recipients, it is possible for some addresses to fail in one delivery
1733 attempt and others to fail subsequently, giving rise to more than one bounce
1734 message. The wording of bounce messages can be customized by the administrator.
1735 See chapter 48 for details.
1736
1737 Bounce messages contain an X-Failed-Recipients: header line that lists the
1738 failed addresses, for the benefit of programs that try to analyse such messages
1739 automatically.
1740
1741 A bounce message is normally sent to the sender of the original message, as
1742 obtained from the message's envelope. For incoming SMTP messages, this is the
1743 address given in the MAIL command. However, when an address is expanded via a
1744 forward or alias file, an alternative address can be specified for delivery
1745 failures of the generated addresses. For a mailing list expansion (see section
1746 49.2) it is common to direct bounce messages to the manager of the list.
1747
1748
1749 3.17 Failures to deliver bounce messages
1750 ----------------------------------------
1751
1752 If a bounce message (either locally generated or received from a remote host)
1753 itself suffers a permanent delivery failure, the message is left on the queue,
1754 but it is frozen, awaiting the attention of an administrator. There are options
1755 that can be used to make Exim discard such failed messages, or to keep them for
1756 only a short time (see timeout_frozen_after and ignore_bounce_errors_after).
1757
1758
1759
1760 ===============================================================================
1761 4. BUILDING AND INSTALLING EXIM
1762
1763
1764 4.1 Unpacking
1765 -------------
1766
1767 Exim is distributed as a gzipped or bzipped tar file which, when unpacked,
1768 creates a directory with the name of the current release (for example,
1769 exim-4.84) into which the following files are placed:
1770
1771 ACKNOWLEDGMENTS contains some acknowledgments
1772 CHANGES contains a reference to where changes are documented
1773 LICENCE the GNU General Public Licence
1774 Makefile top-level make file
1775 NOTICE conditions for the use of Exim
1776 README list of files, directories and simple build instructions
1777
1778 Other files whose names begin with README may also be present. The following
1779 subdirectories are created:
1780
1781 Local an empty directory for local configuration files
1782 OS OS-specific files
1783 doc documentation files
1784 exim_monitor source files for the Exim monitor
1785 scripts scripts used in the build process
1786 src remaining source files
1787 util independent utilities
1788
1789 The main utility programs are contained in the src directory, and are built
1790 with the Exim binary. The util directory contains a few optional scripts that
1791 may be useful to some sites.
1792
1793
1794 4.2 Multiple machine architectures and operating systems
1795 --------------------------------------------------------
1796
1797 The building process for Exim is arranged to make it easy to build binaries for
1798 a number of different architectures and operating systems from the same set of
1799 source files. Compilation does not take place in the src directory. Instead, a
1800 build directory is created for each architecture and operating system. Symbolic
1801 links to the sources are installed in this directory, which is where the actual
1802 building takes place. In most cases, Exim can discover the machine architecture
1803 and operating system for itself, but the defaults can be overridden if
1804 necessary.
1805
1806
1807 4.3 PCRE library
1808 ----------------
1809
1810 Exim no longer has an embedded PCRE library as the vast majority of modern
1811 systems include PCRE as a system library, although you may need to install the
1812 PCRE or PCRE development package for your operating system. If your system has
1813 a normal PCRE installation the Exim build process will need no further
1814 configuration. If the library or the headers are in an unusual location you
1815 will need to either set the PCRE_LIBS and INCLUDE directives appropriately, or
1816 set PCRE_CONFIG=yes to use the installed pcre-config command. If your operating
1817 system has no PCRE support then you will need to obtain and build the current
1818 PCRE from ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/. More
1819 information on PCRE is available at http://www.pcre.org/.
1820
1821
1822 4.4 DBM libraries
1823 -----------------
1824
1825 Even if you do not use any DBM files in your configuration, Exim still needs a
1826 DBM library in order to operate, because it uses indexed files for its hints
1827 databases. Unfortunately, there are a number of DBM libraries in existence, and
1828 different operating systems often have different ones installed.
1829
1830 If you are using Solaris, IRIX, one of the modern BSD systems, or a modern
1831 Linux distribution, the DBM configuration should happen automatically, and you
1832 may be able to ignore this section. Otherwise, you may have to learn more than
1833 you would like about DBM libraries from what follows.
1834
1835 Licensed versions of Unix normally contain a library of DBM functions operating
1836 via the ndbm interface, and this is what Exim expects by default. Free versions
1837 of Unix seem to vary in what they contain as standard. In particular, some
1838 early versions of Linux have no default DBM library, and different distributors
1839 have chosen to bundle different libraries with their packaged versions.
1840 However, the more recent releases seem to have standardized on the Berkeley DB
1841 library.
1842
1843 Different DBM libraries have different conventions for naming the files they
1844 use. When a program opens a file called dbmfile, there are several
1845 possibilities:
1846
1847 1. A traditional ndbm implementation, such as that supplied as part of
1848 Solaris, operates on two files called dbmfile.dir and dbmfile.pag.
1849
1850 2. The GNU library, gdbm, operates on a single file. If used via its ndbm
1851 compatibility interface it makes two different hard links to it with names
1852 dbmfile.dir and dbmfile.pag, but if used via its native interface, the file
1853 name is used unmodified.
1854
1855 3. The Berkeley DB package, if called via its ndbm compatibility interface,
1856 operates on a single file called dbmfile.db, but otherwise looks to the
1857 programmer exactly the same as the traditional ndbm implementation.
1858
1859 4. If the Berkeley package is used in its native mode, it operates on a single
1860 file called dbmfile; the programmer's interface is somewhat different to
1861 the traditional ndbm interface.
1862
1863 5. To complicate things further, there are several very different versions of
1864 the Berkeley DB package. Version 1.85 was stable for a very long time,
1865 releases 2.x and 3.x were current for a while, but the latest versions are
1866 now numbered 4.x. Maintenance of some of the earlier releases has ceased.
1867 All versions of Berkeley DB can be obtained from http://www.sleepycat.com/.
1868
1869 6. Yet another DBM library, called tdb, is available from http://
1870 download.sourceforge.net/tdb. It has its own interface, and also operates
1871 on a single file.
1872
1873 Exim and its utilities can be compiled to use any of these interfaces. In order
1874 to use any version of the Berkeley DB package in native mode, you must set
1875 USE_DB in an appropriate configuration file (typically Local/Makefile). For
1876 example:
1877
1878 USE_DB=yes
1879
1880 Similarly, for gdbm you set USE_GDBM, and for tdb you set USE_TDB. An error is
1881 diagnosed if you set more than one of these.
1882
1883 At the lowest level, the build-time configuration sets none of these options,
1884 thereby assuming an interface of type (1). However, some operating system
1885 configuration files (for example, those for the BSD operating systems and
1886 Linux) assume type (4) by setting USE_DB as their default, and the
1887 configuration files for Cygwin set USE_GDBM. Anything you set in Local/Makefile
1888 , however, overrides these system defaults.
1889
1890 As well as setting USE_DB, USE_GDBM, or USE_TDB, it may also be necessary to
1891 set DBMLIB, to cause inclusion of the appropriate library, as in one of these
1892 lines:
1893
1894 DBMLIB = -ldb
1895 DBMLIB = -ltdb
1896
1897 Settings like that will work if the DBM library is installed in the standard
1898 place. Sometimes it is not, and the library's header file may also not be in
1899 the default path. You may need to set INCLUDE to specify where the header file
1900 is, and to specify the path to the library more fully in DBMLIB, as in this
1901 example:
1902
1903 INCLUDE=-I/usr/local/include/db-4.1
1904 DBMLIB=/usr/local/lib/db-4.1/libdb.a
1905
1906 There is further detailed discussion about the various DBM libraries in the
1907 file doc/dbm.discuss.txt in the Exim distribution.
1908
1909
1910 4.5 Pre-building configuration
1911 ------------------------------
1912
1913 Before building Exim, a local configuration file that specifies options
1914 independent of any operating system has to be created with the name Local/
1915 Makefile. A template for this file is supplied as the file src/EDITME, and it
1916 contains full descriptions of all the option settings therein. These
1917 descriptions are therefore not repeated here. If you are building Exim for the
1918 first time, the simplest thing to do is to copy src/EDITME to Local/Makefile,
1919 then read it and edit it appropriately.
1920
1921 There are three settings that you must supply, because Exim will not build
1922 without them. They are the location of the run time configuration file
1923 (CONFIGURE_FILE), the directory in which Exim binaries will be installed
1924 (BIN_DIRECTORY), and the identity of the Exim user (EXIM_USER and maybe
1925 EXIM_GROUP as well). The value of CONFIGURE_FILE can in fact be a
1926 colon-separated list of file names; Exim uses the first of them that exists.
1927
1928 There are a few other parameters that can be specified either at build time or
1929 at run time, to enable the same binary to be used on a number of different
1930 machines. However, if the locations of Exim's spool directory and log file
1931 directory (if not within the spool directory) are fixed, it is recommended that
1932 you specify them in Local/Makefile instead of at run time, so that errors
1933 detected early in Exim's execution (such as a malformed configuration file) can
1934 be logged.
1935
1936 Exim's interfaces for calling virus and spam scanning software directly from
1937 access control lists are not compiled by default. If you want to include these
1938 facilities, you need to set
1939
1940 WITH_CONTENT_SCAN=yes
1941
1942 in your Local/Makefile. For details of the facilities themselves, see chapter
1943 43.
1944
1945 If you are going to build the Exim monitor, a similar configuration process is
1946 required. The file exim_monitor/EDITME must be edited appropriately for your
1947 installation and saved under the name Local/eximon.conf. If you are happy with
1948 the default settings described in exim_monitor/EDITME, Local/eximon.conf can be
1949 empty, but it must exist.
1950
1951 This is all the configuration that is needed in straightforward cases for known
1952 operating systems. However, the building process is set up so that it is easy
1953 to override options that are set by default or by operating-system-specific
1954 configuration files, for example to change the name of the C compiler, which
1955 defaults to gcc. See section 4.13 below for details of how to do this.
1956
1957
1958 4.6 Support for iconv()
1959 -----------------------
1960
1961 The contents of header lines in messages may be encoded according to the rules
1962 described RFC 2047. This makes it possible to transmit characters that are not
1963 in the ASCII character set, and to label them as being in a particular
1964 character set. When Exim is inspecting header lines by means of the $h_
1965 mechanism, it decodes them, and translates them into a specified character set
1966 (default ISO-8859-1). The translation is possible only if the operating system
1967 supports the iconv() function.
1968
1969 However, some of the operating systems that supply iconv() do not support very
1970 many conversions. The GNU libiconv library (available from http://www.gnu.org/
1971 software/libiconv/) can be installed on such systems to remedy this deficiency,
1972 as well as on systems that do not supply iconv() at all. After installing
1973 libiconv, you should add
1974
1975 HAVE_ICONV=yes
1976
1977 to your Local/Makefile and rebuild Exim.
1978
1979
1980 4.7 Including TLS/SSL encryption support
1981 ----------------------------------------
1982
1983 Exim can be built to support encrypted SMTP connections, using the STARTTLS
1984 command as per RFC 2487. It can also support legacy clients that expect to
1985 start a TLS session immediately on connection to a non-standard port (see the
1986 tls_on_connect_ports runtime option and the -tls-on-connect command line
1987 option).
1988
1989 If you want to build Exim with TLS support, you must first install either the
1990 OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for
1991 implementing SSL.
1992
1993 If OpenSSL is installed, you should set
1994
1995 SUPPORT_TLS=yes
1996 TLS_LIBS=-lssl -lcrypto
1997
1998 in Local/Makefile. You may also need to specify the locations of the OpenSSL
1999 library and include files. For example:
2000
2001 SUPPORT_TLS=yes
2002 TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto
2003 TLS_INCLUDE=-I/usr/local/openssl/include/
2004
2005 If you have pkg-config available, then instead you can just use:
2006
2007 SUPPORT_TLS=yes
2008 USE_OPENSSL_PC=openssl
2009
2010 If GnuTLS is installed, you should set
2011
2012 SUPPORT_TLS=yes
2013 USE_GNUTLS=yes
2014 TLS_LIBS=-lgnutls -ltasn1 -lgcrypt
2015
2016 in Local/Makefile, and again you may need to specify the locations of the
2017 library and include files. For example:
2018
2019 SUPPORT_TLS=yes
2020 USE_GNUTLS=yes
2021 TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt
2022 TLS_INCLUDE=-I/usr/gnu/include
2023
2024 If you have pkg-config available, then instead you can just use:
2025
2026 SUPPORT_TLS=yes
2027 USE_GNUTLS=yes
2028 USE_GNUTLS_PC=gnutls
2029
2030 You do not need to set TLS_INCLUDE if the relevant directory is already
2031 specified in INCLUDE. Details of how to configure Exim to make use of TLS are
2032 given in chapter 41.
2033
2034
2035 4.8 Use of tcpwrappers
2036 ----------------------
2037
2038 Exim can be linked with the tcpwrappers library in order to check incoming SMTP
2039 calls using the tcpwrappers control files. This may be a convenient alternative
2040 to Exim's own checking facilities for installations that are already making use
2041 of tcpwrappers for other purposes. To do this, you should set USE_TCP_WRAPPERS
2042 in Local/Makefile, arrange for the file tcpd.h to be available at compile time,
2043 and also ensure that the library libwrap.a is available at link time, typically
2044 by including -lwrap in EXTRALIBS_EXIM. For example, if tcpwrappers is installed
2045 in /usr/local, you might have
2046
2047 USE_TCP_WRAPPERS=yes
2048 CFLAGS=-O -I/usr/local/include
2049 EXTRALIBS_EXIM=-L/usr/local/lib -lwrap
2050
2051 in Local/Makefile. The daemon name to use in the tcpwrappers control files is
2052 "exim". For example, the line
2053
2054 exim : LOCAL 192.168.1. .friendly.domain.example
2055
2056 in your /etc/hosts.allow file allows connections from the local host, from the
2057 subnet 192.168.1.0/24, and from all hosts in friendly.domain.example. All other
2058 connections are denied. The daemon name used by tcpwrappers can be changed at
2059 build time by setting TCP_WRAPPERS_DAEMON_NAME in Local/Makefile, or by setting
2060 tcp_wrappers_daemon_name in the configure file. Consult the tcpwrappers
2061 documentation for further details.
2062
2063
2064 4.9 Including support for IPv6
2065 ------------------------------
2066
2067 Exim contains code for use on systems that have IPv6 support. Setting
2068 "HAVE_IPV6=YES" in Local/Makefile causes the IPv6 code to be included; it may
2069 also be necessary to set IPV6_INCLUDE and IPV6_LIBS on systems where the IPv6
2070 support is not fully integrated into the normal include and library files.
2071
2072 Two different types of DNS record for handling IPv6 addresses have been
2073 defined. AAAA records (analogous to A records for IPv4) are in use, and are
2074 currently seen as the mainstream. Another record type called A6 was proposed as
2075 better than AAAA because it had more flexibility. However, it was felt to be
2076 over-complex, and its status was reduced to "experimental". It is not known if
2077 anyone is actually using A6 records. Exim has support for A6 records, but this
2078 is included only if you set "SUPPORT_A6=YES" in Local/Makefile. The support has
2079 not been tested for some time.
2080
2081
2082 4.10 Dynamically loaded lookup module support
2083 ---------------------------------------------
2084
2085 On some platforms, Exim supports not compiling all lookup types directly into
2086 the main binary, instead putting some into external modules which can be loaded
2087 on demand. This permits packagers to build Exim with support for lookups with
2088 extensive library dependencies without requiring all users to install all of
2089 those dependencies. Most, but not all, lookup types can be built this way.
2090
2091 Set "LOOKUP_MODULE_DIR" to the directory into which the modules will be
2092 installed; Exim will only load modules from that directory, as a security
2093 measure. You will need to set "CFLAGS_DYNAMIC" if not already defined for your
2094 OS; see OS/Makefile-Linux for an example. Some other requirements for adjusting
2095 "EXTRALIBS" may also be necessary, see src/EDITME for details.
2096
2097 Then, for each module to be loaded dynamically, define the relevant "LOOKUP_"<
2098 lookup_type> flags to have the value "2" instead of "yes". For example, this
2099 will build in lsearch but load sqlite and mysql support on demand:
2100
2101 LOOKUP_LSEARCH=yes
2102 LOOKUP_SQLITE=2
2103 LOOKUP_MYSQL=2
2104
2105
2106 4.11 The building process
2107 -------------------------
2108
2109 Once Local/Makefile (and Local/eximon.conf, if required) have been created, run
2110 make at the top level. It determines the architecture and operating system
2111 types, and creates a build directory if one does not exist. For example, on a
2112 Sun system running Solaris 8, the directory build-SunOS5-5.8-sparc is created.
2113 Symbolic links to relevant source files are installed in the build directory.
2114
2115 Warning: The -j (parallel) flag must not be used with make; the building
2116 process fails if it is set.
2117
2118 If this is the first time make has been run, it calls a script that builds a
2119 make file inside the build directory, using the configuration files from the
2120 Local directory. The new make file is then passed to another instance of make.
2121 This does the real work, building a number of utility scripts, and then
2122 compiling and linking the binaries for the Exim monitor (if configured), a
2123 number of utility programs, and finally Exim itself. The command "make
2124 makefile" can be used to force a rebuild of the make file in the build
2125 directory, should this ever be necessary.
2126
2127 If you have problems building Exim, check for any comments there may be in the
2128 README file concerning your operating system, and also take a look at the FAQ,
2129 where some common problems are covered.
2130
2131
2132 4.12 Output from "make"
2133 -----------------------
2134
2135 The output produced by the make process for compile lines is often very
2136 unreadable, because these lines can be very long. For this reason, the normal
2137 output is suppressed by default, and instead output similar to that which
2138 appears when compiling the 2.6 Linux kernel is generated: just a short line for
2139 each module that is being compiled or linked. However, it is still possible to
2140 get the full output, by calling make like this:
2141
2142 FULLECHO='' make -e
2143
2144 The value of FULLECHO defaults to "@", the flag character that suppresses
2145 command reflection in make. When you ask for the full output, it is given in
2146 addition to the short output.
2147
2148
2149 4.13 Overriding build-time options for Exim
2150 -------------------------------------------
2151
2152 The main make file that is created at the beginning of the building process
2153 consists of the concatenation of a number of files which set configuration
2154 values, followed by a fixed set of make instructions. If a value is set more
2155 than once, the last setting overrides any previous ones. This provides a
2156 convenient way of overriding defaults. The files that are concatenated are, in
2157 order:
2158
2159 OS/Makefile-Default
2160 OS/Makefile-<ostype>
2161 Local/Makefile
2162 Local/Makefile-<ostype>
2163 Local/Makefile-<archtype>
2164 Local/Makefile-<ostype>-<archtype>
2165 OS/Makefile-Base
2166
2167 where <ostype> is the operating system type and <archtype> is the architecture
2168 type. Local/Makefile is required to exist, and the building process fails if it
2169 is absent. The other three Local files are optional, and are often not needed.
2170
2171 The values used for <ostype> and <archtype> are obtained from scripts called
2172 scripts/os-type and scripts/arch-type respectively. If either of the
2173 environment variables EXIM_OSTYPE or EXIM_ARCHTYPE is set, their values are
2174 used, thereby providing a means of forcing particular settings. Otherwise, the
2175 scripts try to get values from the uname command. If this fails, the shell
2176 variables OSTYPE and ARCHTYPE are inspected. A number of ad hoc transformations
2177 are then applied, to produce the standard names that Exim expects. You can run
2178 these scripts directly from the shell in order to find out what values are
2179 being used on your system.
2180
2181 OS/Makefile-Default contains comments about the variables that are set therein.
2182 Some (but not all) are mentioned below. If there is something that needs
2183 changing, review the contents of this file and the contents of the make file
2184 for your operating system (OS/Makefile-<ostype>) to see what the default values
2185 are.
2186
2187 If you need to change any of the values that are set in OS/Makefile-Default or
2188 in OS/Makefile-<ostype>, or to add any new definitions, you do not need to
2189 change the original files. Instead, you should make the changes by putting the
2190 new values in an appropriate Local file. For example, when building Exim in
2191 many releases of the Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1)
2192 operating system, it is necessary to specify that the C compiler is called cc
2193 rather than gcc. Also, the compiler must be called with the option -std1, to
2194 make it recognize some of the features of Standard C that Exim uses. (Most
2195 other compilers recognize Standard C by default.) To do this, you should create
2196 a file called Local/Makefile-OSF1 containing the lines
2197
2198 CC=cc
2199 CFLAGS=-std1
2200
2201 If you are compiling for just one operating system, it may be easier to put
2202 these lines directly into Local/Makefile.
2203
2204 Keeping all your local configuration settings separate from the distributed
2205 files makes it easy to transfer them to new versions of Exim simply by copying
2206 the contents of the Local directory.
2207
2208 Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file
2209 lookup, but not all systems have these components installed, so the default is
2210 not to include the relevant code in the binary. All the different kinds of file
2211 and database lookup that Exim supports are implemented as separate code modules
2212 which are included only if the relevant compile-time options are set. In the
2213 case of LDAP, NIS, and NIS+, the settings for Local/Makefile are:
2214
2215 LOOKUP_LDAP=yes
2216 LOOKUP_NIS=yes
2217 LOOKUP_NISPLUS=yes
2218
2219 and similar settings apply to the other lookup types. They are all listed in
2220 src/EDITME. In many cases the relevant include files and interface libraries
2221 need to be installed before compiling Exim. However, there are some optional
2222 lookup types (such as cdb) for which the code is entirely contained within
2223 Exim, and no external include files or libraries are required. When a lookup
2224 type is not included in the binary, attempts to configure Exim to use it cause
2225 run time configuration errors.
2226
2227 Many systems now use a tool called pkg-config to encapsulate information about
2228 how to compile against a library; Exim has some initial support for being able
2229 to use pkg-config for lookups and authenticators. For any given makefile
2230 variable which starts "LOOKUP_" or "AUTH_", you can add a new variable with the
2231 "_PC" suffix in the name and assign as the value the name of the package to be
2232 queried. The results of querying via the pkg-config command will be added to
2233 the appropriate Makefile variables with "+=" directives, so your version of
2234 make will need to support that syntax. For instance:
2235
2236 LOOKUP_SQLITE=yes
2237 LOOKUP_SQLITE_PC=sqlite3
2238 AUTH_GSASL=yes
2239 AUTH_GSASL_PC=libgsasl
2240 AUTH_HEIMDAL_GSSAPI=yes
2241 AUTH_HEIMDAL_GSSAPI_PC=heimdal-gssapi
2242
2243 Exim can be linked with an embedded Perl interpreter, allowing Perl subroutines
2244 to be called during string expansion. To enable this facility,
2245
2246 EXIM_PERL=perl.o
2247
2248 must be defined in Local/Makefile. Details of this facility are given in
2249 chapter 12.
2250
2251 The location of the X11 libraries is something that varies a lot between
2252 operating systems, and there may be different versions of X11 to cope with.
2253 Exim itself makes no use of X11, but if you are compiling the Exim monitor, the
2254 X11 libraries must be available. The following three variables are set in OS/
2255 Makefile-Default:
2256
2257 X11=/usr/X11R6
2258 XINCLUDE=-I$(X11)/include
2259 XLFLAGS=-L$(X11)/lib
2260
2261 These are overridden in some of the operating-system configuration files. For
2262 example, in OS/Makefile-SunOS5 there is
2263
2264 X11=/usr/openwin
2265 XINCLUDE=-I$(X11)/include
2266 XLFLAGS=-L$(X11)/lib -R$(X11)/lib
2267
2268 If you need to override the default setting for your operating system, place a
2269 definition of all three of these variables into your Local/Makefile-<ostype>
2270 file.
2271
2272 If you need to add any extra libraries to the link steps, these can be put in a
2273 variable called EXTRALIBS, which appears in all the link commands, but by
2274 default is not defined. In contrast, EXTRALIBS_EXIM is used only on the command
2275 for linking the main Exim binary, and not for any associated utilities.
2276
2277 There is also DBMLIB, which appears in the link commands for binaries that use
2278 DBM functions (see also section 4.4). Finally, there is EXTRALIBS_EXIMON, which
2279 appears only in the link step for the Exim monitor binary, and which can be
2280 used, for example, to include additional X11 libraries.
2281
2282 The make file copes with rebuilding Exim correctly if any of the configuration
2283 files are edited. However, if an optional configuration file is deleted, it is
2284 necessary to touch the associated non-optional file (that is, Local/Makefile or
2285 Local/eximon.conf) before rebuilding.
2286
2287
2288 4.14 OS-specific header files
2289 -----------------------------
2290
2291 The OS directory contains a number of files with names of the form os.h-
2292 <ostype>. These are system-specific C header files that should not normally
2293 need to be changed. There is a list of macro settings that are recognized in
2294 the file OS/os.configuring, which should be consulted if you are porting Exim
2295 to a new operating system.
2296
2297
2298 4.15 Overriding build-time options for the monitor
2299 --------------------------------------------------
2300
2301 A similar process is used for overriding things when building the Exim monitor,
2302 where the files that are involved are
2303
2304 OS/eximon.conf-Default
2305 OS/eximon.conf-<ostype>
2306 Local/eximon.conf
2307 Local/eximon.conf-<ostype>
2308 Local/eximon.conf-<archtype>
2309 Local/eximon.conf-<ostype>-<archtype>
2310
2311 As with Exim itself, the final three files need not exist, and in this case the
2312 OS/eximon.conf-<ostype> file is also optional. The default values in OS/
2313 eximon.conf-Default can be overridden dynamically by setting environment
2314 variables of the same name, preceded by EXIMON_. For example, setting
2315 EXIMON_LOG_DEPTH in the environment overrides the value of LOG_DEPTH at run
2316 time.
2317
2318
2319 4.16 Installing Exim binaries and scripts
2320 -----------------------------------------
2321
2322 The command "make install" runs the exim_install script with no arguments. The
2323 script copies binaries and utility scripts into the directory whose name is
2324 specified by the BIN_DIRECTORY setting in Local/Makefile. The install script
2325 copies files only if they are newer than the files they are going to replace.
2326 The Exim binary is required to be owned by root and have the setuid bit set,
2327 for normal configurations. Therefore, you must run "make install" as root so
2328 that it can set up the Exim binary in this way. However, in some special
2329 situations (for example, if a host is doing no local deliveries) it may be
2330 possible to run Exim without making the binary setuid root (see chapter 54 for
2331 details).
2332
2333 Exim's run time configuration file is named by the CONFIGURE_FILE setting in
2334 Local/Makefile. If this names a single file, and the file does not exist, the
2335 default configuration file src/configure.default is copied there by the
2336 installation script. If a run time configuration file already exists, it is
2337 left alone. If CONFIGURE_FILE is a colon-separated list, naming several
2338 alternative files, no default is installed.
2339
2340 One change is made to the default configuration file when it is installed: the
2341 default configuration contains a router that references a system aliases file.
2342 The path to this file is set to the value specified by SYSTEM_ALIASES_FILE in
2343 Local/Makefile (/etc/aliases by default). If the system aliases file does not
2344 exist, the installation script creates it, and outputs a comment to the user.
2345
2346 The created file contains no aliases, but it does contain comments about the
2347 aliases a site should normally have. Mail aliases have traditionally been kept
2348 in /etc/aliases. However, some operating systems are now using /etc/mail/
2349 aliases. You should check if yours is one of these, and change Exim's
2350 configuration if necessary.
2351
2352 The default configuration uses the local host's name as the only local domain,
2353 and is set up to do local deliveries into the shared directory /var/mail,
2354 running as the local user. System aliases and .forward files in users' home
2355 directories are supported, but no NIS or NIS+ support is configured. Domains
2356 other than the name of the local host are routed using the DNS, with delivery
2357 over SMTP.
2358
2359 It is possible to install Exim for special purposes (such as building a binary
2360 distribution) in a private part of the file system. You can do this by a
2361 command such as
2362
2363 make DESTDIR=/some/directory/ install
2364
2365 This has the effect of pre-pending the specified directory to all the file
2366 paths, except the name of the system aliases file that appears in the default
2367 configuration. (If a default alias file is created, its name is modified.) For
2368 backwards compatibility, ROOT is used if DESTDIR is not set, but this usage is
2369 deprecated.
2370
2371 Running make install does not copy the Exim 4 conversion script convert4r4. You
2372 will probably run this only once if you are upgrading from Exim 3. None of the
2373 documentation files in the doc directory are copied, except for the info files
2374 when you have set INFO_DIRECTORY, as described in section 4.17 below.
2375
2376 For the utility programs, old versions are renamed by adding the suffix .O to
2377 their names. The Exim binary itself, however, is handled differently. It is
2378 installed under a name that includes the version number and the compile number,
2379 for example exim-4.84-1. The script then arranges for a symbolic link called
2380 exim to point to the binary. If you are updating a previous version of Exim,
2381 the script takes care to ensure that the name exim is never absent from the
2382 directory (as seen by other processes).
2383
2384 If you want to see what the make install will do before running it for real,
2385 you can pass the -n option to the installation script by this command:
2386
2387 make INSTALL_ARG=-n install
2388
2389 The contents of the variable INSTALL_ARG are passed to the installation script.
2390 You do not need to be root to run this test. Alternatively, you can run the
2391 installation script directly, but this must be from within the build directory.
2392 For example, from the top-level Exim directory you could use this command:
2393
2394 (cd build-SunOS5-5.5.1-sparc; ../scripts/exim_install -n)
2395
2396 There are two other options that can be supplied to the installation script.
2397
2398 * -no_chown bypasses the call to change the owner of the installed binary to
2399 root, and the call to make it a setuid binary.
2400
2401 * -no_symlink bypasses the setting up of the symbolic link exim to the
2402 installed binary.
2403
2404 INSTALL_ARG can be used to pass these options to the script. For example:
2405
2406 make INSTALL_ARG=-no_symlink install
2407
2408 The installation script can also be given arguments specifying which files are
2409 to be copied. For example, to install just the Exim binary, and nothing else,
2410 without creating the symbolic link, you could use:
2411
2412 make INSTALL_ARG='-no_symlink exim' install
2413
2414
2415 4.17 Installing info documentation
2416 ----------------------------------
2417
2418 Not all systems use the GNU info system for documentation, and for this reason,
2419 the Texinfo source of Exim's documentation is not included in the main
2420 distribution. Instead it is available separately from the ftp site (see section
2421 1.6).
2422
2423 If you have defined INFO_DIRECTORY in Local/Makefile and the Texinfo source of
2424 the documentation is found in the source tree, running "make install"
2425 automatically builds the info files and installs them.
2426
2427
2428 4.18 Setting up the spool directory
2429 -----------------------------------
2430
2431 When it starts up, Exim tries to create its spool directory if it does not
2432 exist. The Exim uid and gid are used for the owner and group of the spool
2433 directory. Sub-directories are automatically created in the spool directory as
2434 necessary.
2435
2436
2437 4.19 Testing
2438 ------------
2439
2440 Having installed Exim, you can check that the run time configuration file is
2441 syntactically valid by running the following command, which assumes that the
2442 Exim binary directory is within your PATH environment variable:
2443
2444 exim -bV
2445
2446 If there are any errors in the configuration file, Exim outputs error messages.
2447 Otherwise it outputs the version number and build date, the DBM library that is
2448 being used, and information about which drivers and other optional code modules
2449 are included in the binary. Some simple routing tests can be done by using the
2450 address testing option. For example,
2451
2452 exim -bt <local username>
2453
2454 should verify that it recognizes a local mailbox, and
2455
2456 exim -bt <remote address>
2457
2458 a remote one. Then try getting it to deliver mail, both locally and remotely.
2459 This can be done by passing messages directly to Exim, without going through a
2460 user agent. For example:
2461
2462 exim -v postmaster@your.domain.example
2463 From: user@your.domain.example
2464 To: postmaster@your.domain.example
2465 Subject: Testing Exim
2466
2467 This is a test message.
2468 ^D
2469
2470 The -v option causes Exim to output some verification of what it is doing. In
2471 this case you should see copies of three log lines, one for the message's
2472 arrival, one for its delivery, and one containing "Completed".
2473
2474 If you encounter problems, look at Exim's log files (mainlog and paniclog) to
2475 see if there is any relevant information there. Another source of information
2476 is running Exim with debugging turned on, by specifying the -d option. If a
2477 message is stuck on Exim's spool, you can force a delivery with debugging
2478 turned on by a command of the form
2479
2480 exim -d -M <exim-message-id>
2481
2482 You must be root or an "admin user" in order to do this. The -d option produces
2483 rather a lot of output, but you can cut this down to specific areas. For
2484 example, if you use -d-all+route only the debugging information relevant to
2485 routing is included. (See the -d option in chapter 5 for more details.)
2486
2487 One specific problem that has shown up on some sites is the inability to do
2488 local deliveries into a shared mailbox directory, because it does not have the
2489 "sticky bit" set on it. By default, Exim tries to create a lock file before
2490 writing to a mailbox file, and if it cannot create the lock file, the delivery
2491 is deferred. You can get round this either by setting the "sticky bit" on the
2492 directory, or by setting a specific group for local deliveries and allowing
2493 that group to create files in the directory (see the comments above the
2494 local_delivery transport in the default configuration file). Another approach
2495 is to configure Exim not to use lock files, but just to rely on fcntl() locking
2496 instead. However, you should do this only if all user agents also use fcntl()
2497 locking. For further discussion of locking issues, see chapter 26.
2498
2499 One thing that cannot be tested on a system that is already running an MTA is
2500 the receipt of incoming SMTP mail on the standard SMTP port. However, the -oX
2501 option can be used to run an Exim daemon that listens on some other port, or
2502 inetd can be used to do this. The -bh option and the exim_checkaccess utility
2503 can be used to check out policy controls on incoming SMTP mail.
2504
2505 Testing a new version on a system that is already running Exim can most easily
2506 be done by building a binary with a different CONFIGURE_FILE setting. From
2507 within the run time configuration, all other file and directory names that Exim
2508 uses can be altered, in order to keep it entirely clear of the production
2509 version.
2510
2511
2512 4.20 Replacing another MTA with Exim
2513 ------------------------------------
2514
2515 Building and installing Exim for the first time does not of itself put it in
2516 general use. The name by which the system's MTA is called by mail user agents
2517 is either /usr/sbin/sendmail, or /usr/lib/sendmail (depending on the operating
2518 system), and it is necessary to make this name point to the exim binary in
2519 order to get the user agents to pass messages to Exim. This is normally done by
2520 renaming any existing file and making /usr/sbin/sendmail or /usr/lib/sendmail a
2521 symbolic link to the exim binary. It is a good idea to remove any setuid
2522 privilege and executable status from the old MTA. It is then necessary to stop
2523 and restart the mailer daemon, if one is running.
2524
2525 Some operating systems have introduced alternative ways of switching MTAs. For
2526 example, if you are running FreeBSD, you need to edit the file /etc/mail/
2527 mailer.conf instead of setting up a symbolic link as just described. A typical
2528 example of the contents of this file for running Exim is as follows:
2529
2530 sendmail /usr/exim/bin/exim
2531 send-mail /usr/exim/bin/exim
2532 mailq /usr/exim/bin/exim -bp
2533 newaliases /usr/bin/true
2534
2535 Once you have set up the symbolic link, or edited /etc/mail/mailer.conf, your
2536 Exim installation is "live". Check it by sending a message from your favourite
2537 user agent.
2538
2539 You should consider what to tell your users about the change of MTA. Exim may
2540 have different capabilities to what was previously running, and there are
2541 various operational differences such as the text of messages produced by
2542 command line options and in bounce messages. If you allow your users to make
2543 use of Exim's filtering capabilities, you should make the document entitled
2544 Exim's interface to mail filtering available to them.
2545
2546
2547 4.21 Upgrading Exim
2548 -------------------
2549
2550 If you are already running Exim on your host, building and installing a new
2551 version automatically makes it available to MUAs, or any other programs that
2552 call the MTA directly. However, if you are running an Exim daemon, you do need
2553 to send it a HUP signal, to make it re-execute itself, and thereby pick up the
2554 new binary. You do not need to stop processing mail in order to install a new
2555 version of Exim. The install script does not modify an existing runtime
2556 configuration file.
2557
2558
2559 4.22 Stopping the Exim daemon on Solaris
2560 ----------------------------------------
2561
2562 The standard command for stopping the mailer daemon on Solaris is
2563
2564 /etc/init.d/sendmail stop
2565
2566 If /usr/lib/sendmail has been turned into a symbolic link, this script fails to
2567 stop Exim because it uses the command ps -e and greps the output for the text
2568 "sendmail"; this is not present because the actual program name (that is,
2569 "exim") is given by the ps command with these options. A solution is to replace
2570 the line that finds the process id with something like
2571
2572 pid=`cat /var/spool/exim/exim-daemon.pid`
2573
2574 to obtain the daemon's pid directly from the file that Exim saves it in.
2575
2576 Note, however, that stopping the daemon does not "stop Exim". Messages can
2577 still be received from local processes, and if automatic delivery is configured
2578 (the normal case), deliveries will still occur.
2579
2580
2581
2582 ===============================================================================
2583 5. THE EXIM COMMAND LINE
2584
2585 Exim's command line takes the standard Unix form of a sequence of options, each
2586 starting with a hyphen character, followed by a number of arguments. The
2587 options are compatible with the main options of Sendmail, and there are also
2588 some additional options, some of which are compatible with Smail 3. Certain
2589 combinations of options do not make sense, and provoke an error if used. The
2590 form of the arguments depends on which options are set.
2591
2592
2593 5.1 Setting options by program name
2594 -----------------------------------
2595
2596 If Exim is called under the name mailq, it behaves as if the option -bp were
2597 present before any other options. The -bp option requests a listing of the
2598 contents of the mail queue on the standard output. This feature is for
2599 compatibility with some systems that contain a command of that name in one of
2600 the standard libraries, symbolically linked to /usr/sbin/sendmail or /usr/lib/
2601 sendmail.
2602
2603 If Exim is called under the name rsmtp it behaves as if the option -bS were
2604 present before any other options, for compatibility with Smail. The -bS option
2605 is used for reading in a number of messages in batched SMTP format.
2606
2607 If Exim is called under the name rmail it behaves as if the -i and -oee options
2608 were present before any other options, for compatibility with Smail. The name
2609 rmail is used as an interface by some UUCP systems.
2610
2611 If Exim is called under the name runq it behaves as if the option -q were
2612 present before any other options, for compatibility with Smail. The -q option
2613 causes a single queue runner process to be started.
2614
2615 If Exim is called under the name newaliases it behaves as if the option -bi
2616 were present before any other options, for compatibility with Sendmail. This
2617 option is used for rebuilding Sendmail's alias file. Exim does not have the
2618 concept of a single alias file, but can be configured to run a given command if
2619 called with the -bi option.
2620
2621
2622 5.2 Trusted and admin users
2623 ---------------------------
2624
2625 Some Exim options are available only to trusted users and others are available
2626 only to admin users. In the description below, the phrases "Exim user" and
2627 "Exim group" mean the user and group defined by EXIM_USER and EXIM_GROUP in
2628 Local/Makefile or set by the exim_user and exim_group options. These do not
2629 necessarily have to use the name "exim".
2630
2631 * The trusted users are root, the Exim user, any user listed in the
2632 trusted_users configuration option, and any user whose current group or any
2633 supplementary group is one of those listed in the trusted_groups
2634 configuration option. Note that the Exim group is not automatically
2635 trusted.
2636
2637 Trusted users are always permitted to use the -f option or a leading
2638 "From " line to specify the envelope sender of a message that is passed to
2639 Exim through the local interface (see the -bm and -f options below). See
2640 the untrusted_set_sender option for a way of permitting non-trusted users
2641 to set envelope senders.
2642
2643 For a trusted user, there is never any check on the contents of the From:
2644 header line, and a Sender: line is never added. Furthermore, any existing
2645 Sender: line in incoming local (non-TCP/IP) messages is not removed.
2646
2647 Trusted users may also specify a host name, host address, interface
2648 address, protocol name, ident value, and authentication data when
2649 submitting a message locally. Thus, they are able to insert messages into
2650 Exim's queue locally that have the characteristics of messages received
2651 from a remote host. Untrusted users may in some circumstances use -f, but
2652 can never set the other values that are available to trusted users.
2653
2654 * The admin users are root, the Exim user, and any user that is a member of
2655 the Exim group or of any group listed in the admin_groups configuration
2656 option. The current group does not have to be one of these groups.
2657
2658 Admin users are permitted to list the queue, and to carry out certain
2659 operations on messages, for example, to force delivery failures. It is also
2660 necessary to be an admin user in order to see the full information provided
2661 by the Exim monitor, and full debugging output.
2662
2663 By default, the use of the -M, -q, -R, and -S options to cause Exim to
2664 attempt delivery of messages on its queue is restricted to admin users.
2665 However, this restriction can be relaxed by setting the prod_requires_admin
2666 option false (that is, specifying no_prod_requires_admin).
2667
2668 Similarly, the use of the -bp option to list all the messages in the queue
2669 is restricted to admin users unless queue_list_requires_admin is set false.
2670
2671 Warning: If you configure your system so that admin users are able to edit
2672 Exim's configuration file, you are giving those users an easy way of getting
2673 root. There is further discussion of this issue at the start of chapter 6.
2674
2675
2676 5.3 Command line options
2677 ------------------------
2678
2679 Exim's command line options are described in alphabetical order below. If none
2680 of the options that specifies a specific action (such as starting the daemon or
2681 a queue runner, or testing an address, or receiving a message in a specific
2682 format, or listing the queue) are present, and there is at least one argument
2683 on the command line, -bm (accept a local message on the standard input, with
2684 the arguments specifying the recipients) is assumed. Otherwise, Exim outputs a
2685 brief message about itself and exits.
2686
2687 --
2688
2689 This is a pseudo-option whose only purpose is to terminate the options and
2690 therefore to cause subsequent command line items to be treated as arguments
2691 rather than options, even if they begin with hyphens.
2692
2693 --help
2694
2695 This option causes Exim to output a few sentences stating what it is. The
2696 same output is generated if the Exim binary is called with no options and
2697 no arguments.
2698
2699 --version
2700
2701 This option is an alias for -bV and causes version information to be
2702 displayed.
2703
2704 -Ac, -Am
2705
2706 These options are used by Sendmail for selecting configuration files and
2707 are ignored by Exim.
2708
2709 -B<type>
2710
2711 This is a Sendmail option for selecting 7 or 8 bit processing. Exim is
2712 8-bit clean; it ignores this option.
2713
2714 -bd
2715
2716 This option runs Exim as a daemon, awaiting incoming SMTP connections.
2717 Usually the -bd option is combined with the -q<time> option, to specify
2718 that the daemon should also initiate periodic queue runs.
2719
2720 The -bd option can be used only by an admin user. If either of the -d
2721 (debugging) or -v (verifying) options are set, the daemon does not
2722 disconnect from the controlling terminal. When running this way, it can be
2723 stopped by pressing ctrl-C.
2724
2725 By default, Exim listens for incoming connections to the standard SMTP port
2726 on all the host's running interfaces. However, it is possible to listen on
2727 other ports, on multiple ports, and only on specific interfaces. Chapter 13
2728 contains a description of the options that control this.
2729
2730 When a listening daemon is started without the use of -oX (that is, without
2731 overriding the normal configuration), it writes its process id to a file
2732 called exim-daemon.pid in Exim's spool directory. This location can be
2733 overridden by setting PID_FILE_PATH in Local/Makefile. The file is written
2734 while Exim is still running as root.
2735
2736 When -oX is used on the command line to start a listening daemon, the
2737 process id is not written to the normal pid file path. However, -oP can be
2738 used to specify a path on the command line if a pid file is required.
2739
2740 The SIGHUP signal can be used to cause the daemon to re-execute itself.
2741 This should be done whenever Exim's configuration file, or any file that is
2742 incorporated into it by means of the .include facility, is changed, and
2743 also whenever a new version of Exim is installed. It is not necessary to do
2744 this when other files that are referenced from the configuration (for
2745 example, alias files) are changed, because these are reread each time they
2746 are used.
2747
2748 -bdf
2749
2750 This option has the same effect as -bd except that it never disconnects
2751 from the controlling terminal, even when no debugging is specified.
2752
2753 -be
2754
2755 Run Exim in expansion testing mode. Exim discards its root privilege, to
2756 prevent ordinary users from using this mode to read otherwise inaccessible
2757 files. If no arguments are given, Exim runs interactively, prompting for
2758 lines of data. Otherwise, it processes each argument in turn.
2759
2760 If Exim was built with USE_READLINE=yes in Local/Makefile, it tries to load
2761 the libreadline library dynamically whenever the -be option is used without
2762 command line arguments. If successful, it uses the readline() function,
2763 which provides extensive line-editing facilities, for reading the test
2764 data. A line history is supported.
2765
2766 Long expansion expressions can be split over several lines by using
2767 backslash continuations. As in Exim's run time configuration, white space
2768 at the start of continuation lines is ignored. Each argument or data line
2769 is passed through the string expansion mechanism, and the result is output.
2770 Variable values from the configuration file (for example, $qualify_domain)
2771 are available, but no message-specific values (such as $sender_domain) are
2772 set, because no message is being processed (but see -bem and -Mset).
2773
2774 Note: If you use this mechanism to test lookups, and you change the data
2775 files or databases you are using, you must exit and restart Exim before
2776 trying the same lookup again. Otherwise, because each Exim process caches
2777 the results of lookups, you will just get the same result as before.
2778
2779 -bem <filename>
2780
2781 This option operates like -be except that it must be followed by the name
2782 of a file. For example:
2783
2784 exim -bem /tmp/testmessage
2785
2786 The file is read as a message (as if receiving a locally-submitted non-SMTP
2787 message) before any of the test expansions are done. Thus, message-specific
2788 variables such as $message_size and $header_from: are available. However,
2789 no Received: header is added to the message. If the -t option is set,
2790 recipients are read from the headers in the normal way, and are shown in
2791 the $recipients variable. Note that recipients cannot be given on the
2792 command line, because further arguments are taken as strings to expand
2793 (just like -be).
2794
2795 -bF <filename>
2796
2797 This option is the same as -bf except that it assumes that the filter being
2798 tested is a system filter. The additional commands that are available only
2799 in system filters are recognized.
2800
2801 -bf <filename>
2802
2803 This option runs Exim in user filter testing mode; the file is the filter
2804 file to be tested, and a test message must be supplied on the standard
2805 input. If there are no message-dependent tests in the filter, an empty file
2806 can be supplied.
2807
2808 If you want to test a system filter file, use -bF instead of -bf. You can
2809 use both -bF and -bf on the same command, in order to test a system filter
2810 and a user filter in the same run. For example:
2811
2812 exim -bF /system/filter -bf /user/filter </test/message
2813
2814 This is helpful when the system filter adds header lines or sets filter
2815 variables that are used by the user filter.
2816
2817 If the test filter file does not begin with one of the special lines
2818
2819 # Exim filter
2820 # Sieve filter
2821
2822 it is taken to be a normal .forward file, and is tested for validity under
2823 that interpretation. See sections 22.4 to 22.6 for a description of the
2824 possible contents of non-filter redirection lists.
2825
2826 The result of an Exim command that uses -bf, provided no errors are
2827 detected, is a list of the actions that Exim would try to take if presented
2828 with the message for real. More details of filter testing are given in the
2829 separate document entitled Exim's interfaces to mail filtering.
2830
2831 When testing a filter file, the envelope sender can be set by the -f
2832 option, or by a "From " line at the start of the test message. Various
2833 parameters that would normally be taken from the envelope recipient address
2834 of the message can be set by means of additional command line options (see
2835 the next four options).
2836
2837 -bfd <domain>
2838
2839 This sets the domain of the recipient address when a filter file is being
2840 tested by means of the -bf option. The default is the value of
2841 $qualify_domain.
2842
2843 -bfl <local part>
2844
2845 This sets the local part of the recipient address when a filter file is
2846 being tested by means of the -bf option. The default is the username of the
2847 process that calls Exim. A local part should be specified with any prefix
2848 or suffix stripped, because that is how it appears to the filter when a
2849 message is actually being delivered.
2850
2851 -bfp <prefix>
2852
2853 This sets the prefix of the local part of the recipient address when a
2854 filter file is being tested by means of the -bf option. The default is an
2855 empty prefix.
2856
2857 -bfs <suffix>
2858
2859 This sets the suffix of the local part of the recipient address when a
2860 filter file is being tested by means of the -bf option. The default is an
2861 empty suffix.
2862
2863 -bh <IP address>
2864
2865 This option runs a fake SMTP session as if from the given IP address, using
2866 the standard input and output. The IP address may include a port number at
2867 the end, after a full stop. For example:
2868
2869 exim -bh 10.9.8.7.1234
2870 exim -bh fe80::a00:20ff:fe86:a061.5678
2871
2872 When an IPv6 address is given, it is converted into canonical form. In the
2873 case of the second example above, the value of $sender_host_address after
2874 conversion to the canonical form is
2875 "fe80:0000:0000:0a00:20ff:fe86:a061.5678".
2876
2877 Comments as to what is going on are written to the standard error file.
2878 These include lines beginning with "LOG" for anything that would have been
2879 logged. This facility is provided for testing configuration options for
2880 incoming messages, to make sure they implement the required policy. For
2881 example, you can test your relay controls using -bh.
2882
2883 Warning 1: You can test features of the configuration that rely on ident
2884 (RFC 1413) information by using the -oMt option. However, Exim cannot
2885 actually perform an ident callout when testing using -bh because there is
2886 no incoming SMTP connection.
2887
2888 Warning 2: Address verification callouts (see section 42.45) are also
2889 skipped when testing using -bh. If you want these callouts to occur, use
2890 -bhc instead.
2891
2892 Messages supplied during the testing session are discarded, and nothing is
2893 written to any of the real log files. There may be pauses when DNS (and
2894 other) lookups are taking place, and of course these may time out. The -oMi
2895 option can be used to specify a specific IP interface and port if this is
2896 important, and -oMaa and -oMai can be used to set parameters as if the SMTP
2897 session were authenticated.
2898
2899 The exim_checkaccess utility is a "packaged" version of -bh whose output
2900 just states whether a given recipient address from a given host is
2901 acceptable or not. See section 52.8.
2902
2903 Features such as authentication and encryption, where the client input is
2904 not plain text, cannot easily be tested with -bh. Instead, you should use a
2905 specialized SMTP test program such as swaks.
2906
2907 -bhc <IP address>
2908
2909 This option operates in the same way as -bh, except that address
2910 verification callouts are performed if required. This includes consulting
2911 and updating the callout cache database.
2912
2913 -bi
2914
2915 Sendmail interprets the -bi option as a request to rebuild its alias file.
2916 Exim does not have the concept of a single alias file, and so it cannot
2917 mimic this behaviour. However, calls to /usr/lib/sendmail with the -bi
2918 option tend to appear in various scripts such as NIS make files, so the
2919 option must be recognized.
2920
2921 If -bi is encountered, the command specified by the bi_command
2922 configuration option is run, under the uid and gid of the caller of Exim.
2923 If the -oA option is used, its value is passed to the command as an
2924 argument. The command set by bi_command may not contain arguments. The
2925 command can use the exim_dbmbuild utility, or some other means, to rebuild
2926 alias files if this is required. If the bi_command option is not set,
2927 calling Exim with -bi is a no-op.
2928
2929 -bI:help
2930
2931 We shall provide various options starting "-bI:" for querying Exim for
2932 information. The output of many of these will be intended for machine
2933 consumption. This one is not. The -bI:help option asks Exim for a synopsis
2934 of supported options beginning "-bI:". Use of any of these options shall
2935 cause Exim to exit after producing the requested output.
2936
2937 -bI:dscp
2938
2939 This option causes Exim to emit an alphabetically sorted list of all
2940 recognised DSCP names.
2941
2942 -bI:sieve
2943
2944 This option causes Exim to emit an alphabetically sorted list of all
2945 supported Sieve protocol extensions on stdout, one per line. This is
2946 anticipated to be useful for ManageSieve (RFC 5804) implementations, in
2947 providing that protocol's "SIEVE" capability response line. As the precise
2948 list may depend upon compile-time build options, which this option will
2949 adapt to, this is the only way to guarantee a correct response.
2950
2951 -bm
2952
2953 This option runs an Exim receiving process that accepts an incoming,
2954 locally-generated message on the standard input. The recipients are given
2955 as the command arguments (except when -t is also present - see below). Each
2956 argument can be a comma-separated list of RFC 2822 addresses. This is the
2957 default option for selecting the overall action of an Exim call; it is
2958 assumed if no other conflicting option is present.
2959
2960 If any addresses in the message are unqualified (have no domain), they are
2961 qualified by the values of the qualify_domain or qualify_recipient options,
2962 as appropriate. The -bnq option (see below) provides a way of suppressing
2963 this for special cases.
2964
2965 Policy checks on the contents of local messages can be enforced by means of
2966 the non-SMTP ACL. See chapter 42 for details.
2967
2968 The return code is zero if the message is successfully accepted. Otherwise,
2969 the action is controlled by the -oex option setting - see below.
2970
2971 The format of the message must be as defined in RFC 2822, except that, for
2972 compatibility with Sendmail and Smail, a line in one of the forms
2973
2974 From sender Fri Jan 5 12:55 GMT 1997
2975 From sender Fri, 5 Jan 97 12:55:01
2976
2977 (with the weekday optional, and possibly with additional text after the
2978 date) is permitted to appear at the start of the message. There appears to
2979 be no authoritative specification of the format of this line. Exim
2980 recognizes it by matching against the regular expression defined by the
2981 uucp_from_pattern option, which can be changed if necessary.
2982
2983 The specified sender is treated as if it were given as the argument to the
2984 -f option, but if a -f option is also present, its argument is used in
2985 preference to the address taken from the message. The caller of Exim must
2986 be a trusted user for the sender of a message to be set in this way.
2987
2988 -bmalware <filename>
2989
2990 This debugging option causes Exim to scan the given file, using the malware
2991 scanning framework. The option of av_scanner influences this option, so if
2992 av_scanner's value is dependent upon an expansion then the expansion should
2993 have defaults which apply to this invocation. ACLs are not invoked, so if
2994 av_scanner references an ACL variable then that variable will never be
2995 populated and -bmalware will fail.
2996
2997 Exim will have changed working directory before resolving the filename, so
2998 using fully qualified pathnames is advisable. Exim will be running as the
2999 Exim user when it tries to open the file, rather than as the invoking user.
3000 This option requires admin privileges.
3001
3002 The -bmalware option will not be extended to be more generally useful,
3003 there are better tools for file-scanning. This option exists to help
3004 administrators verify their Exim and AV scanner configuration.
3005
3006 -bnq
3007
3008 By default, Exim automatically qualifies unqualified addresses (those
3009 without domains) that appear in messages that are submitted locally (that
3010 is, not over TCP/IP). This qualification applies both to addresses in
3011 envelopes, and addresses in header lines. Sender addresses are qualified
3012 using qualify_domain, and recipient addresses using qualify_recipient
3013 (which defaults to the value of qualify_domain).
3014
3015 Sometimes, qualification is not wanted. For example, if -bS (batch SMTP) is
3016 being used to re-submit messages that originally came from remote hosts
3017 after content scanning, you probably do not want to qualify unqualified
3018 addresses in header lines. (Such lines will be present only if you have not
3019 enabled a header syntax check in the appropriate ACL.)
3020
3021 The -bnq option suppresses all qualification of unqualified addresses in
3022 messages that originate on the local host. When this is used, unqualified
3023 addresses in the envelope provoke errors (causing message rejection) and
3024 unqualified addresses in header lines are left alone.
3025
3026 -bP
3027
3028 If this option is given with no arguments, it causes the values of all
3029 Exim's main configuration options to be written to the standard output. The
3030 values of one or more specific options can be requested by giving their
3031 names as arguments, for example:
3032
3033 exim -bP qualify_domain hold_domains
3034
3035 However, any option setting that is preceded by the word "hide" in the
3036 configuration file is not shown in full, except to an admin user. For other
3037 users, the output is as in this example:
3038
3039 mysql_servers = <value not displayable>
3040
3041 If configure_file is given as an argument, the name of the run time
3042 configuration file is output. If a list of configuration files was
3043 supplied, the value that is output here is the name of the file that was
3044 actually used.
3045
3046 If the -n flag is given, then for most modes of -bP operation the name will
3047 not be output.
3048
3049 If log_file_path or pid_file_path are given, the names of the directories
3050 where log files and daemon pid files are written are output, respectively.
3051 If these values are unset, log files are written in a sub-directory of the
3052 spool directory called log, and the pid file is written directly into the
3053 spool directory.
3054
3055 If -bP is followed by a name preceded by "+", for example,
3056
3057 exim -bP +local_domains
3058
3059 it searches for a matching named list of any type (domain, host, address,
3060 or local part) and outputs what it finds.
3061
3062 If one of the words router, transport, or authenticator is given, followed
3063 by the name of an appropriate driver instance, the option settings for that
3064 driver are output. For example:
3065
3066 exim -bP transport local_delivery
3067
3068 The generic driver options are output first, followed by the driver's
3069 private options. A list of the names of drivers of a particular type can be
3070 obtained by using one of the words router_list, transport_list, or
3071 authenticator_list, and a complete list of all drivers with their option
3072 settings can be obtained by using routers, transports, or authenticators.
3073
3074 If invoked by an admin user, then macro, macro_list and macros are
3075 available, similarly to the drivers. Because macros are sometimes used for
3076 storing passwords, this option is restricted. The output format is one item
3077 per line.
3078
3079 -bp
3080
3081 This option requests a listing of the contents of the mail queue on the
3082 standard output. If the -bp option is followed by a list of message ids,
3083 just those messages are listed. By default, this option can be used only by
3084 an admin user. However, the queue_list_requires_admin option can be set
3085 false to allow any user to see the queue.
3086
3087 Each message on the queue is displayed as in the following example:
3088
3089 25m 2.9K 0t5C6f-0000c8-00 <alice@wonderland.fict.example>
3090 red.king@looking-glass.fict.example
3091 <other addresses>
3092
3093 The first line contains the length of time the message has been on the
3094 queue (in this case 25 minutes), the size of the message (2.9K), the unique
3095 local identifier for the message, and the message sender, as contained in
3096 the envelope. For bounce messages, the sender address is empty, and appears
3097 as "<>". If the message was submitted locally by an untrusted user who
3098 overrode the default sender address, the user's login name is shown in
3099 parentheses before the sender address.
3100
3101 If the message is frozen (attempts to deliver it are suspended) then the
3102 text "*** frozen ***" is displayed at the end of this line.
3103
3104 The recipients of the message (taken from the envelope, not the headers)
3105 are displayed on subsequent lines. Those addresses to which the message has
3106 already been delivered are marked with the letter D. If an original address
3107 gets expanded into several addresses via an alias or forward file, the
3108 original is displayed with a D only when deliveries for all of its child
3109 addresses are complete.
3110
3111 -bpa
3112
3113 This option operates like -bp, but in addition it shows delivered addresses
3114 that were generated from the original top level address(es) in each message
3115 by alias or forwarding operations. These addresses are flagged with "+D"
3116 instead of just "D".
3117
3118 -bpc
3119
3120 This option counts the number of messages on the queue, and writes the
3121 total to the standard output. It is restricted to admin users, unless
3122 queue_list_requires_admin is set false.
3123
3124 -bpr
3125
3126 This option operates like -bp, but the output is not sorted into
3127 chronological order of message arrival. This can speed it up when there are
3128 lots of messages on the queue, and is particularly useful if the output is
3129 going to be post-processed in a way that doesn't need the sorting.
3130
3131 -bpra
3132
3133 This option is a combination of -bpr and -bpa.
3134
3135 -bpru
3136
3137 This option is a combination of -bpr and -bpu.
3138
3139 -bpu
3140
3141 This option operates like -bp but shows only undelivered top-level
3142 addresses for each message displayed. Addresses generated by aliasing or
3143 forwarding are not shown, unless the message was deferred after processing
3144 by a router with the one_time option set.
3145
3146 -brt
3147
3148 This option is for testing retry rules, and it must be followed by up to
3149 three arguments. It causes Exim to look for a retry rule that matches the
3150 values and to write it to the standard output. For example:
3151
3152 exim -brt bach.comp.mus.example
3153 Retry rule: *.comp.mus.example F,2h,15m; F,4d,30m;
3154
3155 See chapter 32 for a description of Exim's retry rules. The first argument,
3156 which is required, can be a complete address in the form local_part@domain,
3157 or it can be just a domain name. If the second argument contains a dot, it
3158 is interpreted as an optional second domain name; if no retry rule is found
3159 for the first argument, the second is tried. This ties in with Exim's
3160 behaviour when looking for retry rules for remote hosts - if no rule is
3161 found that matches the host, one that matches the mail domain is sought.
3162 Finally, an argument that is the name of a specific delivery error, as used
3163 in setting up retry rules, can be given. For example:
3164
3165 exim -brt haydn.comp.mus.example quota_3d
3166 Retry rule: *@haydn.comp.mus.example quota_3d F,1h,15m
3167
3168 -brw
3169
3170 This option is for testing address rewriting rules, and it must be followed
3171 by a single argument, consisting of either a local part without a domain,
3172 or a complete address with a fully qualified domain. Exim outputs how this
3173 address would be rewritten for each possible place it might appear. See
3174 chapter 31 for further details.
3175
3176 -bS
3177
3178 This option is used for batched SMTP input, which is an alternative
3179 interface for non-interactive local message submission. A number of
3180 messages can be submitted in a single run. However, despite its name, this
3181 is not really SMTP input. Exim reads each message's envelope from SMTP
3182 commands on the standard input, but generates no responses. If the caller
3183 is trusted, or untrusted_set_sender is set, the senders in the SMTP MAIL
3184 commands are believed; otherwise the sender is always the caller of Exim.
3185
3186 The message itself is read from the standard input, in SMTP format (leading
3187 dots doubled), terminated by a line containing just a single dot. An error
3188 is provoked if the terminating dot is missing. A further message may then
3189 follow.
3190
3191 As for other local message submissions, the contents of incoming batch SMTP
3192 messages can be checked using the non-SMTP ACL (see chapter 42).
3193 Unqualified addresses are automatically qualified using qualify_domain and
3194 qualify_recipient, as appropriate, unless the -bnq option is used.
3195
3196 Some other SMTP commands are recognized in the input. HELO and EHLO act as
3197 RSET; VRFY, EXPN, ETRN, and HELP act as NOOP; QUIT quits, ignoring the rest
3198 of the standard input.
3199
3200 If any error is encountered, reports are written to the standard output and
3201 error streams, and Exim gives up immediately. The return code is 0 if no
3202 error was detected; it is 1 if one or more messages were accepted before
3203 the error was detected; otherwise it is 2.
3204
3205 More details of input using batched SMTP are given in section 47.11.
3206
3207 -bs
3208
3209 This option causes Exim to accept one or more messages by reading SMTP
3210 commands on the standard input, and producing SMTP replies on the standard
3211 output. SMTP policy controls, as defined in ACLs (see chapter 42) are
3212 applied. Some user agents use this interface as a way of passing
3213 locally-generated messages to the MTA.
3214
3215 In this usage, if the caller of Exim is trusted, or untrusted_set_sender is
3216 set, the senders of messages are taken from the SMTP MAIL commands.
3217 Otherwise the content of these commands is ignored and the sender is set up
3218 as the calling user. Unqualified addresses are automatically qualified
3219 using qualify_domain and qualify_recipient, as appropriate, unless the -bnq
3220 option is used.
3221
3222 The -bs option is also used to run Exim from inetd, as an alternative to
3223 using a listening daemon. Exim can distinguish the two cases by checking
3224 whether the standard input is a TCP/IP socket. When Exim is called from
3225 inetd, the source of the mail is assumed to be remote, and the comments
3226 above concerning senders and qualification do not apply. In this situation,
3227 Exim behaves in exactly the same way as it does when receiving a message
3228 via the listening daemon.
3229
3230 -bt
3231
3232 This option runs Exim in address testing mode, in which each argument is
3233 taken as a recipient address to be tested for deliverability. The results
3234 are written to the standard output. If a test fails, and the caller is not
3235 an admin user, no details of the failure are output, because these might
3236 contain sensitive information such as usernames and passwords for database
3237 lookups.
3238
3239 If no arguments are given, Exim runs in an interactive manner, prompting
3240 with a right angle bracket for addresses to be tested.
3241
3242 Unlike the -be test option, you cannot arrange for Exim to use the readline
3243 () function, because it is running as root and there are security issues.
3244
3245 Each address is handled as if it were the recipient address of a message
3246 (compare the -bv option). It is passed to the routers and the result is
3247 written to the standard output. However, any router that has
3248 no_address_test set is bypassed. This can make -bt easier to use for
3249 genuine routing tests if your first router passes everything to a scanner
3250 program.
3251
3252 The return code is 2 if any address failed outright; it is 1 if no address
3253 failed outright but at least one could not be resolved for some reason.
3254 Return code 0 is given only when all addresses succeed.
3255
3256 Note: When actually delivering a message, Exim removes duplicate recipient
3257 addresses after routing is complete, so that only one delivery takes place.
3258 This does not happen when testing with -bt; the full results of routing are
3259 always shown.
3260
3261 Warning: -bt can only do relatively simple testing. If any of the routers
3262 in the configuration makes any tests on the sender address of a message,
3263 you can use the -f option to set an appropriate sender when running -bt
3264 tests. Without it, the sender is assumed to be the calling user at the
3265 default qualifying domain. However, if you have set up (for example)
3266 routers whose behaviour depends on the contents of an incoming message, you
3267 cannot test those conditions using -bt. The -N option provides a possible
3268 way of doing such tests.
3269
3270 -bV
3271
3272 This option causes Exim to write the current version number, compilation
3273 number, and compilation date of the exim binary to the standard output. It
3274 also lists the DBM library that is being used, the optional modules (such
3275 as specific lookup types), the drivers that are included in the binary, and
3276 the name of the run time configuration file that is in use.
3277
3278 As part of its operation, -bV causes Exim to read and syntax check its
3279 configuration file. However, this is a static check only. It cannot check
3280 values that are to be expanded. For example, although a misspelt ACL verb
3281 is detected, an error in the verb's arguments is not. You cannot rely on
3282 -bV alone to discover (for example) all the typos in the configuration;
3283 some realistic testing is needed. The -bh and -N options provide more
3284 dynamic testing facilities.
3285
3286 -bv
3287
3288 This option runs Exim in address verification mode, in which each argument
3289 is taken as a recipient address to be verified by the routers. (This does
3290 not involve any verification callouts). During normal operation,
3291 verification happens mostly as a consequence processing a verify condition
3292 in an ACL (see chapter 42). If you want to test an entire ACL, possibly
3293 including callouts, see the -bh and -bhc options.
3294
3295 If verification fails, and the caller is not an admin user, no details of
3296 the failure are output, because these might contain sensitive information
3297 such as usernames and passwords for database lookups.
3298
3299 If no arguments are given, Exim runs in an interactive manner, prompting
3300 with a right angle bracket for addresses to be verified.
3301
3302 Unlike the -be test option, you cannot arrange for Exim to use the readline
3303 () function, because it is running as exim and there are security issues.
3304
3305 Verification differs from address testing (the -bt option) in that routers
3306 that have no_verify set are skipped, and if the address is accepted by a
3307 router that has fail_verify set, verification fails. The address is
3308 verified as a recipient if -bv is used; to test verification for a sender
3309 address, -bvs should be used.
3310
3311 If the -v option is not set, the output consists of a single line for each
3312 address, stating whether it was verified or not, and giving a reason in the
3313 latter case. Without -v, generating more than one address by redirection
3314 causes verification to end successfully, without considering the generated
3315 addresses. However, if just one address is generated, processing continues,
3316 and the generated address must verify successfully for the overall
3317 verification to succeed.
3318
3319 When -v is set, more details are given of how the address has been handled,
3320 and in the case of address redirection, all the generated addresses are
3321 also considered. Verification may succeed for some and fail for others.
3322
3323 The return code is 2 if any address failed outright; it is 1 if no address
3324 failed outright but at least one could not be resolved for some reason.
3325 Return code 0 is given only when all addresses succeed.
3326
3327 If any of the routers in the configuration makes any tests on the sender
3328 address of a message, you should use the -f option to set an appropriate
3329 sender when running -bv tests. Without it, the sender is assumed to be the
3330 calling user at the default qualifying domain.
3331
3332 -bvs
3333
3334 This option acts like -bv, but verifies the address as a sender rather than
3335 a recipient address. This affects any rewriting and qualification that
3336 might happen.
3337
3338 -bw
3339
3340 This option runs Exim as a daemon, awaiting incoming SMTP connections,
3341 similarly to the -bd option. All port specifications on the command-line
3342 and in the configuration file are ignored. Queue-running may not be
3343 specified.
3344
3345 In this mode, Exim expects to be passed a socket as fd 0 (stdin) which is
3346 listening for connections. This permits the system to start up and have
3347 inetd (or equivalent) listen on the SMTP ports, starting an Exim daemon for
3348 each port only when the first connection is received.
3349
3350 If the option is given as -bw<time> then the time is a timeout, after which
3351 the daemon will exit, which should cause inetd to listen once more.
3352
3353 -C <filelist>
3354
3355 This option causes Exim to find the run time configuration file from the
3356 given list instead of from the list specified by the CONFIGURE_FILE
3357 compile-time setting. Usually, the list will consist of just a single file
3358 name, but it can be a colon-separated list of names. In this case, the
3359 first file that exists is used. Failure to open an existing file stops Exim
3360 from proceeding any further along the list, and an error is generated.
3361
3362 When this option is used by a caller other than root, and the list is
3363 different from the compiled-in list, Exim gives up its root privilege
3364 immediately, and runs with the real and effective uid and gid set to those
3365 of the caller. However, if a TRUSTED_CONFIG_LIST file is defined in Local/
3366 Makefile, that file contains a list of full pathnames, one per line, for
3367 configuration files which are trusted. Root privilege is retained for any
3368 configuration file so listed, as long as the caller is the Exim user (or
3369 the user specified in the CONFIGURE_OWNER option, if any), and as long as
3370 the configuration file is not writeable by inappropriate users or groups.
3371
3372 Leaving TRUSTED_CONFIG_LIST unset precludes the possibility of testing a
3373 configuration using -C right through message reception and delivery, even
3374 if the caller is root. The reception works, but by that time, Exim is
3375 running as the Exim user, so when it re-executes to regain privilege for
3376 the delivery, the use of -C causes privilege to be lost. However, root can
3377 test reception and delivery using two separate commands (one to put a
3378 message on the queue, using -odq, and another to do the delivery, using -M
3379 ).
3380
3381 If ALT_CONFIG_PREFIX is defined in Local/Makefile, it specifies a prefix
3382 string with which any file named in a -C command line option must start. In
3383 addition, the file name must not contain the sequence "/../". However, if
3384 the value of the -C option is identical to the value of CONFIGURE_FILE in
3385 Local/Makefile, Exim ignores -C and proceeds as usual. There is no default
3386 setting for ALT_CONFIG_PREFIX; when it is unset, any file name can be used
3387 with -C.
3388
3389 ALT_CONFIG_PREFIX can be used to confine alternative configuration files to
3390 a directory to which only root has access. This prevents someone who has
3391 broken into the Exim account from running a privileged Exim with an
3392 arbitrary configuration file.
3393
3394 The -C facility is useful for ensuring that configuration files are
3395 syntactically correct, but cannot be used for test deliveries, unless the
3396 caller is privileged, or unless it is an exotic configuration that does not
3397 require privilege. No check is made on the owner or group of the files
3398 specified by this option.
3399
3400 -D<macro>=<value>
3401
3402 This option can be used to override macro definitions in the configuration
3403 file (see section 6.4). However, like -C, if it is used by an unprivileged
3404 caller, it causes Exim to give up its root privilege. If DISABLE_D_OPTION
3405 is defined in Local/Makefile, the use of -D is completely disabled, and its
3406 use causes an immediate error exit.
3407
3408 If WHITELIST_D_MACROS is defined in Local/Makefile then it should be a
3409 colon-separated list of macros which are considered safe and, if -D only
3410 supplies macros from this list, and the values are acceptable, then Exim
3411 will not give up root privilege if the caller is root, the Exim run-time
3412 user, or the CONFIGURE_OWNER, if set. This is a transition mechanism and is
3413 expected to be removed in the future. Acceptable values for the macros
3414 satisfy the regexp: "^[A-Za-z0-9_/.-]*$"
3415
3416 The entire option (including equals sign if present) must all be within one
3417 command line item. -D can be used to set the value of a macro to the empty
3418 string, in which case the equals sign is optional. These two commands are
3419 synonymous:
3420
3421 exim -DABC ...
3422 exim -DABC= ...
3423
3424 To include spaces in a macro definition item, quotes must be used. If you
3425 use quotes, spaces are permitted around the macro name and the equals sign.
3426 For example:
3427
3428 exim '-D ABC = something' ...
3429
3430 -D may be repeated up to 10 times on a command line.
3431
3432 -d<debug options>
3433
3434 This option causes debugging information to be written to the standard
3435 error stream. It is restricted to admin users because debugging output may
3436 show database queries that contain password information. Also, the details
3437 of users' filter files should be protected. If a non-admin user uses -d,
3438 Exim writes an error message to the standard error stream and exits with a
3439 non-zero return code.
3440
3441 When -d is used, -v is assumed. If -d is given on its own, a lot of
3442 standard debugging data is output. This can be reduced, or increased to
3443 include some more rarely needed information, by directly following -d with
3444 a string made up of names preceded by plus or minus characters. These add
3445 or remove sets of debugging data, respectively. For example, -d+filter adds
3446 filter debugging, whereas -d-all+filter selects only filter debugging. Note
3447 that no spaces are allowed in the debug setting. The available debugging
3448 categories are:
3449
3450 acl ACL interpretation
3451 auth authenticators
3452 deliver general delivery logic
3453 dns DNS lookups (see also resolver)
3454 dnsbl DNS black list (aka RBL) code
3455 exec arguments for execv() calls
3456 expand detailed debugging for string expansions
3457 filter filter handling
3458 hints_lookup hints data lookups
3459 host_lookup all types of name-to-IP address handling
3460 ident ident lookup
3461 interface lists of local interfaces
3462 lists matching things in lists
3463 load system load checks
3464 local_scan can be used by local_scan() (see chapter 44)
3465 lookup general lookup code and all lookups
3466 memory memory handling
3467 pid add pid to debug output lines
3468 process_info setting info for the process log
3469 queue_run queue runs
3470 receive general message reception logic
3471 resolver turn on the DNS resolver's debugging output
3472 retry retry handling
3473 rewrite address rewriting
3474 route address routing
3475 timestamp add timestamp to debug output lines
3476 tls TLS logic
3477 transport transports
3478 uid changes of uid/gid and looking up uid/gid
3479 verify address verification logic
3480 all almost all of the above (see below), and also -v
3481
3482 The "all" option excludes "memory" when used as "+all", but includes it for
3483 "-all". The reason for this is that "+all" is something that people tend to
3484 use when generating debug output for Exim maintainers. If "+memory" is
3485 included, an awful lot of output that is very rarely of interest is
3486 generated, so it now has to be explicitly requested. However, "-all" does
3487 turn everything off.
3488
3489 The "resolver" option produces output only if the DNS resolver was compiled
3490 with DEBUG enabled. This is not the case in some operating systems. Also,
3491 unfortunately, debugging output from the DNS resolver is written to stdout
3492 rather than stderr.
3493
3494 The default (-d with no argument) omits "expand", "filter", "interface",
3495 "load", "memory", "pid", "resolver", and "timestamp". However, the "pid"
3496 selector is forced when debugging is turned on for a daemon, which then
3497 passes it on to any re-executed Exims. Exim also automatically adds the pid
3498 to debug lines when several remote deliveries are run in parallel.
3499
3500 The "timestamp" selector causes the current time to be inserted at the
3501 start of all debug output lines. This can be useful when trying to track
3502 down delays in processing.
3503
3504 If the debug_print option is set in any driver, it produces output whenever
3505 any debugging is selected, or if -v is used.
3506
3507 -dd<debug options>
3508
3509 This option behaves exactly like -d except when used on a command that
3510 starts a daemon process. In that case, debugging is turned off for the
3511 subprocesses that the daemon creates. Thus, it is useful for monitoring the
3512 behaviour of the daemon without creating as much output as full debugging
3513 does.
3514
3515 -dropcr
3516
3517 This is an obsolete option that is now a no-op. It used to affect the way
3518 Exim handled CR and LF characters in incoming messages. What happens now is
3519 described in section 46.2.
3520
3521 -E
3522
3523 This option specifies that an incoming message is a locally-generated
3524 delivery failure report. It is used internally by Exim when handling
3525 delivery failures and is not intended for external use. Its only effect is
3526 to stop Exim generating certain messages to the postmaster, as otherwise
3527 message cascades could occur in some situations. As part of the same
3528 option, a message id may follow the characters -E. If it does, the log
3529 entry for the receipt of the new message contains the id, following "R=",
3530 as a cross-reference.
3531
3532 -ex
3533
3534 There are a number of Sendmail options starting with -oe which seem to be
3535 called by various programs without the leading o in the option. For
3536 example, the vacation program uses -eq. Exim treats all options of the form
3537 -ex as synonymous with the corresponding -oex options.
3538
3539 -F <string>
3540
3541 This option sets the sender's full name for use when a locally-generated
3542 message is being accepted. In the absence of this option, the user's gecos
3543 entry from the password data is used. As users are generally permitted to
3544 alter their gecos entries, no security considerations are involved. White
3545 space between -F and the <string> is optional.
3546
3547 -f <address>
3548
3549 This option sets the address of the envelope sender of a locally-generated
3550 message (also known as the return path). The option can normally be used
3551 only by a trusted user, but untrusted_set_sender can be set to allow
3552 untrusted users to use it.
3553
3554 Processes running as root or the Exim user are always trusted. Other
3555 trusted users are defined by the trusted_users or trusted_groups options.
3556 In the absence of -f, or if the caller is not trusted, the sender of a
3557 local message is set to the caller's login name at the default qualify
3558 domain.
3559
3560 There is one exception to the restriction on the use of -f: an empty sender
3561 can be specified by any user, trusted or not, to create a message that can
3562 never provoke a bounce. An empty sender can be specified either as an empty
3563 string, or as a pair of angle brackets with nothing between them, as in
3564 these examples of shell commands:
3565
3566 exim -f '<>' user@domain
3567 exim -f "" user@domain
3568
3569 In addition, the use of -f is not restricted when testing a filter file
3570 with -bf or when testing or verifying addresses using the -bt or -bv
3571 options.
3572
3573 Allowing untrusted users to change the sender address does not of itself
3574 make it possible to send anonymous mail. Exim still checks that the From:
3575 header refers to the local user, and if it does not, it adds a Sender:
3576 header, though this can be overridden by setting no_local_from_check.
3577
3578 White space between -f and the <address> is optional (that is, they can be
3579 given as two arguments or one combined argument). The sender of a
3580 locally-generated message can also be set (when permitted) by an initial
3581 "From " line in the message - see the description of -bm above - but if -f
3582 is also present, it overrides "From ".
3583
3584 -G
3585
3586 This option is equivalent to an ACL applying:
3587
3588 control = suppress_local_fixups
3589
3590 for every message received. Note that Sendmail will complain about such bad
3591 formatting, where Exim silently just does not fix it up. This may change in
3592 future.
3593
3594 As this affects audit information, the caller must be a trusted user to use
3595 this option.
3596
3597 -h <number>
3598
3599 This option is accepted for compatibility with Sendmail, but has no effect.
3600 (In Sendmail it overrides the "hop count" obtained by counting Received:
3601 headers.)
3602
3603 -i
3604
3605 This option, which has the same effect as -oi, specifies that a dot on a
3606 line by itself should not terminate an incoming, non-SMTP message. I can
3607 find no documentation for this option in Solaris 2.4 Sendmail, but the
3608 mailx command in Solaris 2.4 uses it. See also -ti.
3609
3610 -L <tag>
3611
3612 This option is equivalent to setting syslog_processname in the config file
3613 and setting log_file_path to "syslog". Its use is restricted to
3614 administrators. The configuration file has to be read and parsed, to
3615 determine access rights, before this is set and takes effect, so early
3616 configuration file errors will not honour this flag.
3617
3618 The tag should not be longer than 32 characters.
3619
3620 -M <message id> <message id> ...
3621
3622 This option requests Exim to run a delivery attempt on each message in
3623 turn. If any of the messages are frozen, they are automatically thawed
3624 before the delivery attempt. The settings of queue_domains,
3625 queue_smtp_domains, and hold_domains are ignored.
3626
3627 Retry hints for any of the addresses are overridden - Exim tries to deliver
3628 even if the normal retry time has not yet been reached. This option
3629 requires the caller to be an admin user. However, there is an option called
3630 prod_requires_admin which can be set false to relax this restriction (and
3631 also the same requirement for the -q, -R, and -S options).
3632
3633 The deliveries happen synchronously, that is, the original Exim process
3634 does not terminate until all the delivery attempts have finished. No output
3635 is produced unless there is a serious error. If you want to see what is
3636 happening, use the -v option as well, or inspect Exim's main log.
3637
3638 -Mar <message id> <address> <address> ...
3639
3640 This option requests Exim to add the addresses to the list of recipients of
3641 the message ("ar" for "add recipients"). The first argument must be a
3642 message id, and the remaining ones must be email addresses. However, if the
3643 message is active (in the middle of a delivery attempt), it is not altered.
3644 This option can be used only by an admin user.
3645
3646 -MC <transport> <hostname> <sequence number> <message id>
3647
3648 This option is not intended for use by external callers. It is used
3649 internally by Exim to invoke another instance of itself to deliver a
3650 waiting message using an existing SMTP connection, which is passed as the
3651 standard input. Details are given in chapter 47. This must be the final
3652 option, and the caller must be root or the Exim user in order to use it.
3653
3654 -MCA
3655
3656 This option is not intended for use by external callers. It is used
3657 internally by Exim in conjunction with the -MC option. It signifies that
3658 the connection to the remote host has been authenticated.
3659
3660 -MCP
3661
3662 This option is not intended for use by external callers. It is used
3663 internally by Exim in conjunction with the -MC option. It signifies that
3664 the server to which Exim is connected supports pipelining.
3665
3666 -MCQ <process id> <pipe fd>
3667
3668 This option is not intended for use by external callers. It is used
3669 internally by Exim in conjunction with the -MC option when the original
3670 delivery was started by a queue runner. It passes on the process id of the
3671 queue runner, together with the file descriptor number of an open pipe.
3672 Closure of the pipe signals the final completion of the sequence of
3673 processes that are passing messages through the same SMTP connection.
3674
3675 -MCS
3676
3677 This option is not intended for use by external callers. It is used
3678 internally by Exim in conjunction with the -MC option, and passes on the
3679 fact that the SMTP SIZE option should be used on messages delivered down
3680 the existing connection.
3681
3682 -MCT
3683
3684 This option is not intended for use by external callers. It is used
3685 internally by Exim in conjunction with the -MC option, and passes on the
3686 fact that the host to which Exim is connected supports TLS encryption.
3687
3688 -Mc <message id> <message id> ...
3689
3690 This option requests Exim to run a delivery attempt on each message in
3691 turn, but unlike the -M option, it does check for retry hints, and respects
3692 any that are found. This option is not very useful to external callers. It
3693 is provided mainly for internal use by Exim when it needs to re-invoke
3694 itself in order to regain root privilege for a delivery (see chapter 54).
3695 However, -Mc can be useful when testing, in order to run a delivery that
3696 respects retry times and other options such as hold_domains that are
3697 overridden when -M is used. Such a delivery does not count as a queue run.
3698 If you want to run a specific delivery as if in a queue run, you should use
3699 -q with a message id argument. A distinction between queue run deliveries
3700 and other deliveries is made in one or two places.
3701
3702 -Mes <message id> <address>
3703
3704 This option requests Exim to change the sender address in the message to
3705 the given address, which must be a fully qualified address or "<>" ("es"
3706 for "edit sender"). There must be exactly two arguments. The first argument
3707 must be a message id, and the second one an email address. However, if the
3708 message is active (in the middle of a delivery attempt), its status is not
3709 altered. This option can be used only by an admin user.
3710
3711 -Mf <message id> <message id> ...
3712
3713 This option requests Exim to mark each listed message as "frozen". This
3714 prevents any delivery attempts taking place until the message is "thawed",
3715 either manually or as a result of the auto_thaw configuration option.
3716 However, if any of the messages are active (in the middle of a delivery
3717 attempt), their status is not altered. This option can be used only by an
3718 admin user.
3719
3720 -Mg <message id> <message id> ...
3721
3722 This option requests Exim to give up trying to deliver the listed messages,
3723 including any that are frozen. However, if any of the messages are active,
3724 their status is not altered. For non-bounce messages, a delivery error
3725 message is sent to the sender, containing the text "cancelled by
3726 administrator". Bounce messages are just discarded. This option can be used
3727 only by an admin user.
3728
3729 -Mmad <message id> <message id> ...
3730
3731 This option requests Exim to mark all the recipient addresses in the
3732 messages as already delivered ("mad" for "mark all delivered"). However, if
3733 any message is active (in the middle of a delivery attempt), its status is
3734 not altered. This option can be used only by an admin user.
3735
3736 -Mmd <message id> <address> <address> ...
3737
3738 This option requests Exim to mark the given addresses as already delivered
3739 ("md" for "mark delivered"). The first argument must be a message id, and
3740 the remaining ones must be email addresses. These are matched to recipient
3741 addresses in the message in a case-sensitive manner. If the message is
3742 active (in the middle of a delivery attempt), its status is not altered.
3743 This option can be used only by an admin user.
3744
3745 -Mrm <message id> <message id> ...
3746
3747 This option requests Exim to remove the given messages from the queue. No
3748 bounce messages are sent; each message is simply forgotten. However, if any
3749 of the messages are active, their status is not altered. This option can be
3750 used only by an admin user or by the user who originally caused the message
3751 to be placed on the queue.
3752
3753 -Mset <message id>
3754
3755 This option is useful only in conjunction with -be (that is, when testing
3756 string expansions). Exim loads the given message from its spool before
3757 doing the test expansions, thus setting message-specific variables such as
3758 $message_size and the header variables. The $recipients variable is made
3759 available. This feature is provided to make it easier to test expansions
3760 that make use of these variables. However, this option can be used only by
3761 an admin user. See also -bem.
3762
3763 -Mt <message id> <message id> ...
3764
3765 This option requests Exim to "thaw" any of the listed messages that are
3766 "frozen", so that delivery attempts can resume. However, if any of the
3767 messages are active, their status is not altered. This option can be used
3768 only by an admin user.
3769
3770 -Mvb <message id>
3771
3772 This option causes the contents of the message body (-D) spool file to be
3773 written to the standard output. This option can be used only by an admin
3774 user.
3775
3776 -Mvc <message id>
3777
3778 This option causes a copy of the complete message (header lines plus body)
3779 to be written to the standard output in RFC 2822 format. This option can be
3780 used only by an admin user.
3781
3782 -Mvh <message id>
3783
3784 This option causes the contents of the message headers (-H) spool file to
3785 be written to the standard output. This option can be used only by an admin
3786 user.
3787
3788 -Mvl <message id>
3789
3790 This option causes the contents of the message log spool file to be written
3791 to the standard output. This option can be used only by an admin user.
3792
3793 -m
3794
3795 This is apparently a synonym for -om that is accepted by Sendmail, so Exim
3796 treats it that way too.
3797
3798 -N
3799
3800 This is a debugging option that inhibits delivery of a message at the
3801 transport level. It implies -v. Exim goes through many of the motions of
3802 delivery - it just doesn't actually transport the message, but instead
3803 behaves as if it had successfully done so. However, it does not make any
3804 updates to the retry database, and the log entries for deliveries are
3805 flagged with "*>" rather than "=>".
3806
3807 Because -N discards any message to which it applies, only root or the Exim
3808 user are allowed to use it with -bd, -q, -R or -M. In other words, an
3809 ordinary user can use it only when supplying an incoming message to which
3810 it will apply. Although transportation never fails when -N is set, an
3811 address may be deferred because of a configuration problem on a transport,
3812 or a routing problem. Once -N has been used for a delivery attempt, it
3813 sticks to the message, and applies to any subsequent delivery attempts that
3814 may happen for that message.
3815
3816 -n
3817
3818 This option is interpreted by Sendmail to mean "no aliasing". For normal
3819 modes of operation, it is ignored by Exim. When combined with -bP it
3820 suppresses the name of an option from being output.
3821
3822 -O <data>
3823
3824 This option is interpreted by Sendmail to mean "set option". It is ignored
3825 by Exim.
3826
3827 -oA <file name>
3828
3829 This option is used by Sendmail in conjunction with -bi to specify an
3830 alternative alias file name. Exim handles -bi differently; see the
3831 description above.
3832
3833 -oB <n>
3834
3835 This is a debugging option which limits the maximum number of messages that
3836 can be delivered down one SMTP connection, overriding the value set in any
3837 smtp transport. If <n> is omitted, the limit is set to 1.
3838
3839 -odb
3840
3841 This option applies to all modes in which Exim accepts incoming messages,
3842 including the listening daemon. It requests "background" delivery of such
3843 messages, which means that the accepting process automatically starts a
3844 delivery process for each message received, but does not wait for the
3845 delivery processes to finish.
3846
3847 When all the messages have been received, the reception process exits,
3848 leaving the delivery processes to finish in their own time. The standard
3849 output and error streams are closed at the start of each delivery process.
3850 This is the default action if none of the -od options are present.
3851
3852 If one of the queueing options in the configuration file (queue_only or
3853 queue_only_file, for example) is in effect, -odb overrides it if
3854 queue_only_override is set true, which is the default setting. If
3855 queue_only_override is set false, -odb has no effect.
3856
3857 -odf
3858
3859 This option requests "foreground" (synchronous) delivery when Exim has
3860 accepted a locally-generated message. (For the daemon it is exactly the
3861 same as -odb.) A delivery process is automatically started to deliver the
3862 message, and Exim waits for it to complete before proceeding.
3863
3864 The original Exim reception process does not finish until the delivery
3865 process for the final message has ended. The standard error stream is left
3866 open during deliveries.
3867
3868 However, like -odb, this option has no effect if queue_only_override is
3869 false and one of the queueing options in the configuration file is in
3870 effect.
3871
3872 If there is a temporary delivery error during foreground delivery, the
3873 message is left on the queue for later delivery, and the original reception
3874 process exits. See chapter 50 for a way of setting up a restricted
3875 configuration that never queues messages.
3876
3877 -odi
3878
3879 This option is synonymous with -odf. It is provided for compatibility with
3880 Sendmail.
3881
3882 -odq
3883
3884 This option applies to all modes in which Exim accepts incoming messages,
3885 including the listening daemon. It specifies that the accepting process
3886 should not automatically start a delivery process for each message
3887 received. Messages are placed on the queue, and remain there until a
3888 subsequent queue runner process encounters them. There are several
3889 configuration options (such as queue_only) that can be used to queue
3890 incoming messages under certain conditions. This option overrides all of
3891 them and also -odqs. It always forces queueing.
3892
3893 -odqs
3894
3895 This option is a hybrid between -odb/-odi and -odq. However, like -odb and
3896 -odi, this option has no effect if queue_only_override is false and one of
3897 the queueing options in the configuration file is in effect.
3898
3899 When -odqs does operate, a delivery process is started for each incoming
3900 message, in the background by default, but in the foreground if -odi is
3901 also present. The recipient addresses are routed, and local deliveries are
3902 done in the normal way. However, if any SMTP deliveries are required, they
3903 are not done at this time, so the message remains on the queue until a
3904 subsequent queue runner process encounters it. Because routing was done,
3905 Exim knows which messages are waiting for which hosts, and so a number of
3906 messages for the same host can be sent in a single SMTP connection. The
3907 queue_smtp_domains configuration option has the same effect for specific
3908 domains. See also the -qq option.
3909
3910 -oee
3911
3912 If an error is detected while a non-SMTP message is being received (for
3913 example, a malformed address), the error is reported to the sender in a
3914 mail message.
3915
3916 Provided this error message is successfully sent, the Exim receiving
3917 process exits with a return code of zero. If not, the return code is 2 if
3918 the problem is that the original message has no recipients, or 1 for any
3919 other error. This is the default -oex option if Exim is called as rmail.
3920
3921 -oem
3922
3923 This is the same as -oee, except that Exim always exits with a non-zero
3924 return code, whether or not the error message was successfully sent. This
3925 is the default -oex option, unless Exim is called as rmail.
3926
3927 -oep
3928
3929 If an error is detected while a non-SMTP message is being received, the
3930 error is reported by writing a message to the standard error file (stderr).
3931 The return code is 1 for all errors.
3932
3933 -oeq
3934
3935 This option is supported for compatibility with Sendmail, but has the same
3936 effect as -oep.
3937
3938 -oew
3939
3940 This option is supported for compatibility with Sendmail, but has the same
3941 effect as -oem.
3942
3943 -oi
3944
3945 This option, which has the same effect as -i, specifies that a dot on a
3946 line by itself should not terminate an incoming, non-SMTP message.
3947 Otherwise, a single dot does terminate, though Exim does no special
3948 processing for other lines that start with a dot. This option is set by
3949 default if Exim is called as rmail. See also -ti.
3950
3951 -oitrue
3952
3953 This option is treated as synonymous with -oi.
3954
3955 -oMa <host address>
3956
3957 A number of options starting with -oM can be used to set values associated
3958 with remote hosts on locally-submitted messages (that is, messages not
3959 received over TCP/IP). These options can be used by any caller in
3960 conjunction with the -bh, -be, -bf, -bF, -bt, or -bv testing options. In
3961 other circumstances, they are ignored unless the caller is trusted.
3962
3963 The -oMa option sets the sender host address. This may include a port
3964 number at the end, after a full stop (period). For example:
3965
3966 exim -bs -oMa 10.9.8.7.1234
3967
3968 An alternative syntax is to enclose the IP address in square brackets,
3969 followed by a colon and the port number:
3970
3971 exim -bs -oMa [10.9.8.7]:1234
3972
3973 The IP address is placed in the $sender_host_address variable, and the
3974 port, if present, in $sender_host_port. If both -oMa and -bh are present on
3975 the command line, the sender host IP address is taken from whichever one is
3976 last.
3977
3978 -oMaa <name>
3979
3980 See -oMa above for general remarks about the -oM options. The -oMaa option
3981 sets the value of $sender_host_authenticated (the authenticator name). See
3982 chapter 33 for a discussion of SMTP authentication. This option can be used
3983 with -bh and -bs to set up an authenticated SMTP session without actually
3984 using the SMTP AUTH command.
3985
3986 -oMai <string>
3987
3988 See -oMa above for general remarks about the -oM options. The -oMai option
3989 sets the value of $authenticated_id (the id that was authenticated). This
3990 overrides the default value (the caller's login id, except with -bh, where
3991 there is no default) for messages from local sources. See chapter 33 for a
3992 discussion of authenticated ids.
3993
3994 -oMas <address>
3995
3996 See -oMa above for general remarks about the -oM options. The -oMas option
3997 sets the authenticated sender value in $authenticated_sender. It overrides
3998 the sender address that is created from the caller's login id for messages
3999 from local sources, except when -bh is used, when there is no default. For
4000 both -bh and -bs, an authenticated sender that is specified on a MAIL
4001 command overrides this value. See chapter 33 for a discussion of
4002 authenticated senders.
4003
4004 -oMi <interface address>
4005
4006 See -oMa above for general remarks about the -oM options. The -oMi option
4007 sets the IP interface address value. A port number may be included, using
4008 the same syntax as for -oMa. The interface address is placed in
4009 $received_ip_address and the port number, if present, in $received_port.
4010
4011 -oMm <message reference>
4012
4013 See -oMa above for general remarks about the -oM options. The -oMm option
4014 sets the message reference, e.g. message-id, and is logged during delivery.
4015 This is useful when some kind of audit trail is required to tie messages
4016 together. The format of the message reference is checked and will abort if
4017 the format is invalid. The option will only be accepted if exim is running
4018 in trusted mode, not as any regular user.
4019
4020 The best example of a message reference is when Exim sends a bounce
4021 message. The message reference is the message-id of the original message
4022 for which Exim is sending the bounce.
4023
4024 -oMr <protocol name>
4025
4026 See -oMa above for general remarks about the -oM options. The -oMr option
4027 sets the received protocol value that is stored in $received_protocol.
4028 However, it does not apply (and is ignored) when -bh or -bs is used. For
4029 -bh, the protocol is forced to one of the standard SMTP protocol names (see
4030 the description of $received_protocol in section 11.9). For -bs, the
4031 protocol is always "local-" followed by one of those same names. For -bS
4032 (batched SMTP) however, the protocol can be set by -oMr.
4033
4034 -oMs <host name>
4035
4036 See -oMa above for general remarks about the -oM options. The -oMs option
4037 sets the sender host name in $sender_host_name. When this option is
4038 present, Exim does not attempt to look up a host name from an IP address;
4039 it uses the name it is given.
4040
4041 -oMt <ident string>
4042
4043 See -oMa above for general remarks about the -oM options. The -oMt option
4044 sets the sender ident value in $sender_ident. The default setting for local
4045 callers is the login id of the calling process, except when -bh is used,
4046 when there is no default.
4047
4048 -om
4049
4050 In Sendmail, this option means "me too", indicating that the sender of a
4051 message should receive a copy of the message if the sender appears in an
4052 alias expansion. Exim always does this, so the option does nothing.
4053
4054 -oo
4055
4056 This option is ignored. In Sendmail it specifies "old style headers",
4057 whatever that means.
4058
4059 -oP <path>
4060
4061 This option is useful only in conjunction with -bd or -q with a time value.
4062 The option specifies the file to which the process id of the daemon is
4063 written. When -oX is used with -bd, or when -q with a time is used without
4064 -bd, this is the only way of causing Exim to write a pid file, because in
4065 those cases, the normal pid file is not used.
4066
4067 -or <time>
4068
4069 This option sets a timeout value for incoming non-SMTP messages. If it is
4070 not set, Exim will wait forever for the standard input. The value can also
4071 be set by the receive_timeout option. The format used for specifying times
4072 is described in section 6.15.
4073
4074 -os <time>
4075
4076 This option sets a timeout value for incoming SMTP messages. The timeout
4077 applies to each SMTP command and block of data. The value can also be set
4078 by the smtp_receive_timeout option; it defaults to 5 minutes. The format
4079 used for specifying times is described in section 6.15.
4080
4081 -ov
4082
4083 This option has exactly the same effect as -v.
4084
4085 -oX <number or string>
4086
4087 This option is relevant only when the -bd (start listening daemon) option
4088 is also given. It controls which ports and interfaces the daemon uses.
4089 Details of the syntax, and how it interacts with configuration file
4090 options, are given in chapter 13. When -oX is used to start a daemon, no
4091 pid file is written unless -oP is also present to specify a pid file name.
4092
4093 -pd
4094
4095 This option applies when an embedded Perl interpreter is linked with Exim
4096 (see chapter 12). It overrides the setting of the perl_at_start option,
4097 forcing the starting of the interpreter to be delayed until it is needed.
4098
4099 -ps
4100
4101 This option applies when an embedded Perl interpreter is linked with Exim
4102 (see chapter 12). It overrides the setting of the perl_at_start option,
4103 forcing the starting of the interpreter to occur as soon as Exim is
4104 started.
4105
4106 -p<rval>:<sval>
4107
4108 For compatibility with Sendmail, this option is equivalent to
4109
4110 -oMr <rval> -oMs <sval>
4111
4112 It sets the incoming protocol and host name (for trusted callers). The host
4113 name and its colon can be omitted when only the protocol is to be set. Note
4114 the Exim already has two private options, -pd and -ps, that refer to
4115 embedded Perl. It is therefore impossible to set a protocol value of "d" or
4116 "s" using this option (but that does not seem a real limitation).
4117
4118 -q
4119
4120 This option is normally restricted to admin users. However, there is a
4121 configuration option called prod_requires_admin which can be set false to
4122 relax this restriction (and also the same requirement for the -M, -R, and
4123 -S options).
4124
4125 The -q option starts one queue runner process. This scans the queue of
4126 waiting messages, and runs a delivery process for each one in turn. It
4127 waits for each delivery process to finish before starting the next one. A
4128 delivery process may not actually do any deliveries if the retry times for
4129 the addresses have not been reached. Use -qf (see below) if you want to
4130 override this.
4131
4132 If the delivery process spawns other processes to deliver other messages
4133 down passed SMTP connections, the queue runner waits for these to finish
4134 before proceeding.
4135
4136 When all the queued messages have been considered, the original queue
4137 runner process terminates. In other words, a single pass is made over the
4138 waiting mail, one message at a time. Use -q with a time (see below) if you
4139 want this to be repeated periodically.
4140
4141 Exim processes the waiting messages in an unpredictable order. It isn't
4142 very random, but it is likely to be different each time, which is all that
4143 matters. If one particular message screws up a remote MTA, other messages
4144 to the same MTA have a chance of getting through if they get tried first.
4145
4146 It is possible to cause the messages to be processed in lexical message id
4147 order, which is essentially the order in which they arrived, by setting the
4148 queue_run_in_order option, but this is not recommended for normal use.
4149
4150 -q<qflags>
4151
4152 The -q option may be followed by one or more flag letters that change its
4153 behaviour. They are all optional, but if more than one is present, they
4154 must appear in the correct order. Each flag is described in a separate item
4155 below.
4156
4157 -qq...
4158
4159 An option starting with -qq requests a two-stage queue run. In the first
4160 stage, the queue is scanned as if the queue_smtp_domains option matched
4161 every domain. Addresses are routed, local deliveries happen, but no remote
4162 transports are run.
4163
4164 The hints database that remembers which messages are waiting for specific
4165 hosts is updated, as if delivery to those hosts had been deferred. After
4166 this is complete, a second, normal queue scan happens, with routing and
4167 delivery taking place as normal. Messages that are routed to the same host
4168 should mostly be delivered down a single SMTP connection because of the
4169 hints that were set up during the first queue scan. This option may be
4170 useful for hosts that are connected to the Internet intermittently.
4171
4172 -q[q]i...
4173
4174 If the i flag is present, the queue runner runs delivery processes only for
4175 those messages that haven't previously been tried. (i stands for "initial
4176 delivery".) This can be helpful if you are putting messages on the queue
4177 using -odq and want a queue runner just to process the new messages.
4178
4179 -q[q][i]f...
4180
4181 If one f flag is present, a delivery attempt is forced for each non-frozen
4182 message, whereas without f only those non-frozen addresses that have passed
4183 their retry times are tried.
4184
4185 -q[q][i]ff...
4186
4187 If ff is present, a delivery attempt is forced for every message, whether
4188 frozen or not.
4189
4190 -q[q][i][f[f]]l
4191
4192 The l (the letter "ell") flag specifies that only local deliveries are to
4193 be done. If a message requires any remote deliveries, it remains on the
4194 queue for later delivery.
4195
4196 -q<qflags> <start id> <end id>
4197
4198 When scanning the queue, Exim can be made to skip over messages whose ids
4199 are lexically less than a given value by following the -q option with a
4200 starting message id. For example:
4201
4202 exim -q 0t5C6f-0000c8-00
4203
4204 Messages that arrived earlier than "0t5C6f-0000c8-00" are not inspected. If
4205 a second message id is given, messages whose ids are lexically greater than
4206 it are also skipped. If the same id is given twice, for example,
4207
4208 exim -q 0t5C6f-0000c8-00 0t5C6f-0000c8-00
4209
4210 just one delivery process is started, for that message. This differs from
4211 -M in that retry data is respected, and it also differs from -Mc in that it
4212 counts as a delivery from a queue run. Note that the selection mechanism
4213 does not affect the order in which the messages are scanned. There are also
4214 other ways of selecting specific sets of messages for delivery in a queue
4215 run - see -R and -S.
4216
4217 -q<qflags><time>
4218
4219 When a time value is present, the -q option causes Exim to run as a daemon,
4220 starting a queue runner process at intervals specified by the given time
4221 value (whose format is described in section 6.15). This form of the -q
4222 option is commonly combined with the -bd option, in which case a single
4223 daemon process handles both functions. A common way of starting up a
4224 combined daemon at system boot time is to use a command such as
4225
4226 /usr/exim/bin/exim -bd -q30m
4227
4228 Such a daemon listens for incoming SMTP calls, and also starts a queue
4229 runner process every 30 minutes.
4230
4231 When a daemon is started by -q with a time value, but without -bd, no pid
4232 file is written unless one is explicitly requested by the -oP option.
4233
4234 -qR<rsflags> <string>
4235
4236 This option is synonymous with -R. It is provided for Sendmail
4237 compatibility.
4238
4239 -qS<rsflags> <string>
4240
4241 This option is synonymous with -S.
4242
4243 -R<rsflags> <string>
4244
4245 The <rsflags> may be empty, in which case the white space before the string
4246 is optional, unless the string is f, ff, r, rf, or rff, which are the
4247 possible values for <rsflags>. White space is required if <rsflags> is not
4248 empty.
4249
4250 This option is similar to -q with no time value, that is, it causes Exim to
4251 perform a single queue run, except that, when scanning the messages on the
4252 queue, Exim processes only those that have at least one undelivered
4253 recipient address containing the given string, which is checked in a
4254 case-independent way. If the <rsflags> start with r, <string> is
4255 interpreted as a regular expression; otherwise it is a literal string.
4256
4257 If you want to do periodic queue runs for messages with specific
4258 recipients, you can combine -R with -q and a time value. For example:
4259
4260 exim -q25m -R @special.domain.example
4261
4262 This example does a queue run for messages with recipients in the given
4263 domain every 25 minutes. Any additional flags that are specified with -q
4264 are applied to each queue run.
4265
4266 Once a message is selected for delivery by this mechanism, all its
4267 addresses are processed. For the first selected message, Exim overrides any
4268 retry information and forces a delivery attempt for each undelivered
4269 address. This means that if delivery of any address in the first message is
4270 successful, any existing retry information is deleted, and so delivery
4271 attempts for that address in subsequently selected messages (which are
4272 processed without forcing) will run. However, if delivery of any address
4273 does not succeed, the retry information is updated, and in subsequently
4274 selected messages, the failing address will be skipped.
4275
4276 If the <rsflags> contain f or ff, the delivery forcing applies to all
4277 selected messages, not just the first; frozen messages are included when ff
4278 is present.
4279
4280 The -R option makes it straightforward to initiate delivery of all messages
4281 to a given domain after a host has been down for some time. When the SMTP
4282 command ETRN is accepted by its ACL (see chapter 42), its default effect is
4283 to run Exim with the -R option, but it can be configured to run an
4284 arbitrary command instead.
4285
4286 -r
4287
4288 This is a documented (for Sendmail) obsolete alternative name for -f.
4289
4290 -S<rsflags> <string>
4291
4292 This option acts like -R except that it checks the string against each
4293 message's sender instead of against the recipients. If -R is also set, both
4294 conditions must be met for a message to be selected. If either of the
4295 options has f or ff in its flags, the associated action is taken.
4296
4297 -Tqt <times>
4298
4299 This is an option that is exclusively for use by the Exim testing suite. It
4300 is not recognized when Exim is run normally. It allows for the setting up
4301 of explicit "queue times" so that various warning/retry features can be
4302 tested.
4303
4304 -t
4305
4306 When Exim is receiving a locally-generated, non-SMTP message on its
4307 standard input, the -t option causes the recipients of the message to be
4308 obtained from the To:, Cc:, and Bcc: header lines in the message instead of
4309 from the command arguments. The addresses are extracted before any
4310 rewriting takes place and the Bcc: header line, if present, is then
4311 removed.
4312
4313 If the command has any arguments, they specify addresses to which the
4314 message is not to be delivered. That is, the argument addresses are removed
4315 from the recipients list obtained from the headers. This is compatible with
4316 Smail 3 and in accordance with the documented behaviour of several versions
4317 of Sendmail, as described in man pages on a number of operating systems
4318 (e.g. Solaris 8, IRIX 6.5, HP-UX 11). However, some versions of Sendmail
4319 add argument addresses to those obtained from the headers, and the O'Reilly
4320 Sendmail book documents it that way. Exim can be made to add argument
4321 addresses instead of subtracting them by setting the option
4322 extract_addresses_remove_arguments false.
4323
4324 If there are any Resent- header lines in the message, Exim extracts
4325 recipients from all Resent-To:, Resent-Cc:, and Resent-Bcc: header lines
4326 instead of from To:, Cc:, and Bcc:. This is for compatibility with Sendmail
4327 and other MTAs. (Prior to release 4.20, Exim gave an error if -t was used
4328 in conjunction with Resent- header lines.)
4329
4330 RFC 2822 talks about different sets of Resent- header lines (for when a
4331 message is resent several times). The RFC also specifies that they should
4332 be added at the front of the message, and separated by Received: lines. It
4333 is not at all clear how -t should operate in the present of multiple sets,
4334 nor indeed exactly what constitutes a "set". In practice, it seems that
4335 MUAs do not follow the RFC. The Resent- lines are often added at the end of
4336 the header, and if a message is resent more than once, it is common for the
4337 original set of Resent- headers to be renamed as X-Resent- when a new set
4338 is added. This removes any possible ambiguity.
4339
4340 -ti
4341
4342 This option is exactly equivalent to -t -i. It is provided for
4343 compatibility with Sendmail.
4344
4345 -tls-on-connect
4346
4347 This option is available when Exim is compiled with TLS support. It forces
4348 all incoming SMTP connections to behave as if the incoming port is listed
4349 in the tls_on_connect_ports option. See section 13.4 and chapter 41 for
4350 further details.
4351
4352 -U
4353
4354 Sendmail uses this option for "initial message submission", and its
4355 documentation states that in future releases, it may complain about
4356 syntactically invalid messages rather than fixing them when this flag is
4357 not set. Exim ignores this option.
4358
4359 -v
4360
4361 This option causes Exim to write information to the standard error stream,
4362 describing what it is doing. In particular, it shows the log lines for
4363 receiving and delivering a message, and if an SMTP connection is made, the
4364 SMTP dialogue is shown. Some of the log lines shown may not actually be
4365 written to the log if the setting of log_selector discards them. Any
4366 relevant selectors are shown with each log line. If none are shown, the
4367 logging is unconditional.
4368
4369 -x
4370
4371 AIX uses -x for a private purpose ("mail from a local mail program has
4372 National Language Support extended characters in the body of the mail
4373 item"). It sets -x when calling the MTA from its mail command. Exim ignores
4374 this option.
4375
4376 -X <logfile>
4377
4378 This option is interpreted by Sendmail to cause debug information to be
4379 sent to the named file. It is ignored by Exim.
4380
4381
4382
4383 ===============================================================================
4384 6. THE EXIM RUN TIME CONFIGURATION FILE
4385
4386 Exim uses a single run time configuration file that is read whenever an Exim
4387 binary is executed. Note that in normal operation, this happens frequently,
4388 because Exim is designed to operate in a distributed manner, without central
4389 control.
4390
4391 If a syntax error is detected while reading the configuration file, Exim writes
4392 a message on the standard error, and exits with a non-zero return code. The
4393 message is also written to the panic log. Note: Only simple syntax errors can
4394 be detected at this time. The values of any expanded options are not checked
4395 until the expansion happens, even when the expansion does not actually alter
4396 the string.
4397
4398 The name of the configuration file is compiled into the binary for security
4399 reasons, and is specified by the CONFIGURE_FILE compilation option. In most
4400 configurations, this specifies a single file. However, it is permitted to give
4401 a colon-separated list of file names, in which case Exim uses the first
4402 existing file in the list.
4403
4404 The run time configuration file must be owned by root or by the user that is
4405 specified at compile time by the CONFIGURE_OWNER option (if set). The
4406 configuration file must not be world-writeable, or group-writeable unless its
4407 group is the root group or the one specified at compile time by the
4408 CONFIGURE_GROUP option.
4409
4410 Warning: In a conventional configuration, where the Exim binary is setuid to
4411 root, anybody who is able to edit the run time configuration file has an easy
4412 way to run commands as root. If you specify a user or group in the
4413 CONFIGURE_OWNER or CONFIGURE_GROUP options, then that user and/or any users who
4414 are members of that group will trivially be able to obtain root privileges.
4415
4416 Up to Exim version 4.72, the run time configuration file was also permitted to
4417 be writeable by the Exim user and/or group. That has been changed in Exim 4.73
4418 since it offered a simple privilege escalation for any attacker who managed to
4419 compromise the Exim user account.
4420
4421 A default configuration file, which will work correctly in simple situations,
4422 is provided in the file src/configure.default. If CONFIGURE_FILE defines just
4423 one file name, the installation process copies the default configuration to a
4424 new file of that name if it did not previously exist. If CONFIGURE_FILE is a
4425 list, no default is automatically installed. Chapter 7 is a "walk-through"
4426 discussion of the default configuration.
4427
4428
4429 6.1 Using a different configuration file
4430 ----------------------------------------
4431
4432 A one-off alternate configuration can be specified by the -C command line
4433 option, which may specify a single file or a list of files. However, when -C is
4434 used, Exim gives up its root privilege, unless called by root (or unless the
4435 argument for -C is identical to the built-in value from CONFIGURE_FILE), or is
4436 listed in the TRUSTED_CONFIG_LIST file and the caller is the Exim user or the
4437 user specified in the CONFIGURE_OWNER setting. -C is useful mainly for checking
4438 the syntax of configuration files before installing them. No owner or group
4439 checks are done on a configuration file specified by -C, if root privilege has
4440 been dropped.
4441
4442 Even the Exim user is not trusted to specify an arbitrary configuration file
4443 with the -C option to be used with root privileges, unless that file is listed
4444 in the TRUSTED_CONFIG_LIST file. This locks out the possibility of testing a
4445 configuration using -C right through message reception and delivery, even if
4446 the caller is root. The reception works, but by that time, Exim is running as
4447 the Exim user, so when it re-execs to regain privilege for the delivery, the
4448 use of -C causes privilege to be lost. However, root can test reception and
4449 delivery using two separate commands (one to put a message on the queue, using
4450 -odq, and another to do the delivery, using -M).
4451
4452 If ALT_CONFIG_PREFIX is defined in Local/Makefile, it specifies a prefix string
4453 with which any file named in a -C command line option must start. In addition,
4454 the file name must not contain the sequence "/../". There is no default setting
4455 for ALT_CONFIG_PREFIX; when it is unset, any file name can be used with -C.
4456
4457 One-off changes to a configuration can be specified by the -D command line
4458 option, which defines and overrides values for macros used inside the
4459 configuration file. However, like -C, the use of this option by a
4460 non-privileged user causes Exim to discard its root privilege. If
4461 DISABLE_D_OPTION is defined in Local/Makefile, the use of -D is completely
4462 disabled, and its use causes an immediate error exit.
4463
4464 The WHITELIST_D_MACROS option in Local/Makefile permits the binary builder to
4465 declare certain macro names trusted, such that root privilege will not
4466 necessarily be discarded. WHITELIST_D_MACROS defines a colon-separated list of
4467 macros which are considered safe and, if -D only supplies macros from this
4468 list, and the values are acceptable, then Exim will not give up root privilege
4469 if the caller is root, the Exim run-time user, or the CONFIGURE_OWNER, if set.
4470 This is a transition mechanism and is expected to be removed in the future.
4471 Acceptable values for the macros satisfy the regexp: "^[A-Za-z0-9_/.-]*$"
4472
4473 Some sites may wish to use the same Exim binary on different machines that
4474 share a file system, but to use different configuration files on each machine.
4475 If CONFIGURE_FILE_USE_NODE is defined in Local/Makefile, Exim first looks for a
4476 file whose name is the configuration file name followed by a dot and the
4477 machine's node name, as obtained from the uname() function. If this file does
4478 not exist, the standard name is tried. This processing occurs for each file
4479 name in the list given by CONFIGURE_FILE or -C.
4480
4481 In some esoteric situations different versions of Exim may be run under
4482 different effective uids and the CONFIGURE_FILE_USE_EUID is defined to help
4483 with this. See the comments in src/EDITME for details.
4484
4485
4486 6.2 Configuration file format
4487 -----------------------------
4488
4489 Exim's configuration file is divided into a number of different parts. General
4490 option settings must always appear at the start of the file. The other parts
4491 are all optional, and may appear in any order. Each part other than the first
4492 is introduced by the word "begin" followed by the name of the part. The
4493 optional parts are:
4494
4495 * ACL: Access control lists for controlling incoming SMTP mail (see chapter
4496 42).
4497
4498 * authenticators: Configuration settings for the authenticator drivers. These
4499 are concerned with the SMTP AUTH command (see chapter 33).
4500
4501 * routers: Configuration settings for the router drivers. Routers process
4502 addresses and determine how the message is to be delivered (see chapters 15
4503 -22).
4504
4505 * transports: Configuration settings for the transport drivers. Transports
4506 define mechanisms for copying messages to destinations (see chapters 24-30
4507 ).
4508
4509 * retry: Retry rules, for use when a message cannot be delivered immediately.
4510 If there is no retry section, or if it is empty (that is, no retry rules
4511 are defined), Exim will not retry deliveries. In this situation, temporary
4512 errors are treated the same as permanent errors. Retry rules are discussed
4513 in chapter 32.
4514
4515 * rewrite: Global address rewriting rules, for use when a message arrives and
4516 when new addresses are generated during delivery. Rewriting is discussed in
4517 chapter 31.
4518
4519 * local_scan: Private options for the local_scan() function. If you want to
4520 use this feature, you must set
4521
4522 LOCAL_SCAN_HAS_OPTIONS=yes
4523
4524 in Local/Makefile before building Exim. Details of the local_scan()
4525 facility are given in chapter 44.
4526
4527 Leading and trailing white space in configuration lines is always ignored.
4528
4529 Blank lines in the file, and lines starting with a # character (ignoring
4530 leading white space) are treated as comments and are ignored. Note: A #
4531 character other than at the beginning of a line is not treated specially, and
4532 does not introduce a comment.
4533
4534 Any non-comment line can be continued by ending it with a backslash. Note that
4535 the general rule for white space means that trailing white space after the
4536 backslash and leading white space at the start of continuation lines is
4537 ignored. Comment lines beginning with # (but not empty lines) may appear in the
4538 middle of a sequence of continuation lines.
4539
4540 A convenient way to create a configuration file is to start from the default,
4541 which is supplied in src/configure.default, and add, delete, or change settings
4542 as required.
4543
4544 The ACLs, retry rules, and rewriting rules have their own syntax which is
4545 described in chapters 42, 32, and 31, respectively. The other parts of the
4546 configuration file have some syntactic items in common, and these are described
4547 below, from section 6.10 onwards. Before that, the inclusion, macro, and
4548 conditional facilities are described.
4549
4550
4551 6.3 File inclusions in the configuration file
4552 ---------------------------------------------
4553
4554 You can include other files inside Exim's run time configuration file by using
4555 this syntax:
4556
4557 .include <file name>
4558 .include_if_exists <file name>
4559
4560 on a line by itself. Double quotes round the file name are optional. If you use
4561 the first form, a configuration error occurs if the file does not exist; the
4562 second form does nothing for non-existent files. In all cases, an absolute file
4563 name is required.
4564
4565 Includes may be nested to any depth, but remember that Exim reads its
4566 configuration file often, so it is a good idea to keep them to a minimum. If
4567 you change the contents of an included file, you must HUP the daemon, because
4568 an included file is read only when the configuration itself is read.
4569
4570 The processing of inclusions happens early, at a physical line level, so, like
4571 comment lines, an inclusion can be used in the middle of an option setting, for
4572 example:
4573
4574 hosts_lookup = a.b.c \
4575 .include /some/file
4576
4577 Include processing happens after macro processing (see below). Its effect is to
4578 process the lines of the included file as if they occurred inline where the
4579 inclusion appears.
4580
4581
4582 6.4 Macros in the configuration file
4583 ------------------------------------
4584
4585 If a line in the main part of the configuration (that is, before the first
4586 "begin" line) begins with an upper case letter, it is taken as a macro
4587 definition, and must be of the form
4588
4589 <name> = <rest of line>
4590
4591 The name must consist of letters, digits, and underscores, and need not all be
4592 in upper case, though that is recommended. The rest of the line, including any
4593 continuations, is the replacement text, and has leading and trailing white
4594 space removed. Quotes are not removed. The replacement text can never end with
4595 a backslash character, but this doesn't seem to be a serious limitation.
4596
4597 Macros may also be defined between router, transport, authenticator, or ACL
4598 definitions. They may not, however, be defined within an individual driver or
4599 ACL, or in the local_scan, retry, or rewrite sections of the configuration.
4600
4601
4602 6.5 Macro substitution
4603 ----------------------
4604
4605 Once a macro is defined, all subsequent lines in the file (and any included
4606 files) are scanned for the macro name; if there are several macros, the line is
4607 scanned for each in turn, in the order in which the macros are defined. The
4608 replacement text is not re-scanned for the current macro, though it is scanned
4609 for subsequently defined macros. For this reason, a macro name may not contain
4610 the name of a previously defined macro as a substring. You could, for example,
4611 define
4612
4613 ABCD_XYZ = <something>
4614 ABCD = <something else>
4615
4616 but putting the definitions in the opposite order would provoke a configuration
4617 error. Macro expansion is applied to individual physical lines from the file,
4618 before checking for line continuation or file inclusion (see above). If a line
4619 consists solely of a macro name, and the expansion of the macro is empty, the
4620 line is ignored. A macro at the start of a line may turn the line into a
4621 comment line or a ".include" line.
4622
4623
4624 6.6 Redefining macros
4625 ---------------------
4626
4627 Once defined, the value of a macro can be redefined later in the configuration
4628 (or in an included file). Redefinition is specified by using == instead of =.
4629 For example:
4630
4631 MAC = initial value
4632 ...
4633 MAC == updated value
4634
4635 Redefinition does not alter the order in which the macros are applied to the
4636 subsequent lines of the configuration file. It is still the same order in which
4637 the macros were originally defined. All that changes is the macro's value.
4638 Redefinition makes it possible to accumulate values. For example:
4639
4640 MAC = initial value
4641 ...
4642 MAC == MAC and something added
4643
4644 This can be helpful in situations where the configuration file is built from a
4645 number of other files.
4646
4647
4648 6.7 Overriding macro values
4649 ---------------------------
4650
4651 The values set for macros in the configuration file can be overridden by the -D
4652 command line option, but Exim gives up its root privilege when -D is used,
4653 unless called by root or the Exim user. A definition on the command line using
4654 the -D option causes all definitions and redefinitions within the file to be
4655 ignored.
4656
4657
4658 6.8 Example of macro usage
4659 --------------------------
4660
4661 As an example of macro usage, consider a configuration where aliases are looked
4662 up in a MySQL database. It helps to keep the file less cluttered if long
4663 strings such as SQL statements are defined separately as macros, for example:
4664
4665 ALIAS_QUERY = select mailbox from user where \
4666 login='${quote_mysql:$local_part}';
4667
4668 This can then be used in a redirect router setting like this:
4669
4670 data = ${lookup mysql{ALIAS_QUERY}}
4671
4672 In earlier versions of Exim macros were sometimes used for domain, host, or
4673 address lists. In Exim 4 these are handled better by named lists - see section
4674 10.5.
4675
4676
4677 6.9 Conditional skips in the configuration file
4678 -----------------------------------------------
4679
4680 You can use the directives ".ifdef", ".ifndef", ".elifdef", ".elifndef",
4681 ".else", and ".endif" to dynamically include or exclude portions of the
4682 configuration file. The processing happens whenever the file is read (that is,
4683 when an Exim binary starts to run).
4684
4685 The implementation is very simple. Instances of the first four directives must
4686 be followed by text that includes the names of one or macros. The condition
4687 that is tested is whether or not any macro substitution has taken place in the
4688 line. Thus:
4689
4690 .ifdef AAA
4691 message_size_limit = 50M
4692 .else
4693 message_size_limit = 100M
4694 .endif
4695
4696 sets a message size limit of 50M if the macro "AAA" is defined, and 100M
4697 otherwise. If there is more than one macro named on the line, the condition is
4698 true if any of them are defined. That is, it is an "or" condition. To obtain an
4699 "and" condition, you need to use nested ".ifdef"s.
4700
4701 Although you can use a macro expansion to generate one of these directives, it
4702 is not very useful, because the condition "there was a macro substitution in
4703 this line" will always be true.
4704
4705 Text following ".else" and ".endif" is ignored, and can be used as comment to
4706 clarify complicated nestings.
4707
4708
4709 6.10 Common option syntax
4710 -------------------------
4711
4712 For the main set of options, driver options, and local_scan() options, each
4713 setting is on a line by itself, and starts with a name consisting of lower-case
4714 letters and underscores. Many options require a data value, and in these cases
4715 the name must be followed by an equals sign (with optional white space) and
4716 then the value. For example:
4717
4718 qualify_domain = mydomain.example.com
4719
4720 Some option settings may contain sensitive data, for example, passwords for
4721 accessing databases. To stop non-admin users from using the -bP command line
4722 option to read these values, you can precede the option settings with the word
4723 "hide". For example:
4724
4725 hide mysql_servers = localhost/users/admin/secret-password
4726
4727 For non-admin users, such options are displayed like this:
4728
4729 mysql_servers = <value not displayable>
4730
4731 If "hide" is used on a driver option, it hides the value of that option on all
4732 instances of the same driver.
4733
4734 The following sections describe the syntax used for the different data types
4735 that are found in option settings.
4736
4737
4738 6.11 Boolean options
4739 --------------------
4740
4741 Options whose type is given as boolean are on/off switches. There are two
4742 different ways of specifying such options: with and without a data value. If
4743 the option name is specified on its own without data, the switch is turned on;
4744 if it is preceded by "no_" or "not_" the switch is turned off. However, boolean
4745 options may be followed by an equals sign and one of the words "true", "false",
4746 "yes", or "no", as an alternative syntax. For example, the following two
4747 settings have exactly the same effect:
4748
4749 queue_only
4750 queue_only = true
4751
4752 The following two lines also have the same (opposite) effect:
4753
4754 no_queue_only
4755 queue_only = false
4756
4757 You can use whichever syntax you prefer.
4758
4759
4760 6.12 Integer values
4761 -------------------
4762
4763 If an option's type is given as "integer", the value can be given in decimal,
4764 hexadecimal, or octal. If it starts with a digit greater than zero, a decimal
4765 number is assumed. Otherwise, it is treated as an octal number unless it starts
4766 with the characters "0x", in which case the remainder is interpreted as a
4767 hexadecimal number.
4768
4769 If an integer value is followed by the letter K, it is multiplied by 1024; if
4770 it is followed by the letter M, it is multiplied by 1024x1024. When the values
4771 of integer option settings are output, values which are an exact multiple of
4772 1024 or 1024x1024 are sometimes, but not always, printed using the letters K
4773 and M. The printing style is independent of the actual input format that was
4774 used.
4775
4776
4777 6.13 Octal integer values
4778 -------------------------
4779
4780 If an option's type is given as "octal integer", its value is always
4781 interpreted as an octal number, whether or not it starts with the digit zero.
4782 Such options are always output in octal.
4783
4784
4785 6.14 Fixed point numbers
4786 ------------------------
4787
4788 If an option's type is given as "fixed-point", its value must be a decimal
4789 integer, optionally followed by a decimal point and up to three further digits.
4790
4791
4792 6.15 Time intervals
4793 -------------------
4794
4795 A time interval is specified as a sequence of numbers, each followed by one of
4796 the following letters, with no intervening white space:
4797
4798 s seconds
4799 m minutes
4800 h hours
4801 d days
4802 w weeks
4803
4804 For example, "3h50m" specifies 3 hours and 50 minutes. The values of time
4805 intervals are output in the same format. Exim does not restrict the values; it
4806 is perfectly acceptable, for example, to specify "90m" instead of "1h30m".
4807
4808
4809 6.16 String values
4810 ------------------
4811
4812 If an option's type is specified as "string", the value can be specified with
4813 or without double-quotes. If it does not start with a double-quote, the value
4814 consists of the remainder of the line plus any continuation lines, starting at
4815 the first character after any leading white space, with trailing white space
4816 removed, and with no interpretation of the characters in the string. Because
4817 Exim removes comment lines (those beginning with #) at an early stage, they can
4818 appear in the middle of a multi-line string. The following two settings are
4819 therefore equivalent:
4820
4821 trusted_users = uucp:mail
4822 trusted_users = uucp:\
4823 # This comment line is ignored
4824 mail
4825
4826 If a string does start with a double-quote, it must end with a closing
4827 double-quote, and any backslash characters other than those used for line
4828 continuation are interpreted as escape characters, as follows:
4829
4830 "\\" single backslash
4831 "\n" newline
4832 "\r" carriage return
4833 "\t" tab
4834 "\"<octal digits> up to 3 octal digits specify one character
4835 "\x"<hex digits> up to 2 hexadecimal digits specify one character
4836
4837 If a backslash is followed by some other character, including a double-quote
4838 character, that character replaces the pair.
4839
4840 Quoting is necessary only if you want to make use of the backslash escapes to
4841 insert special characters, or if you need to specify a value with leading or
4842 trailing spaces. These cases are rare, so quoting is almost never needed in
4843 current versions of Exim. In versions of Exim before 3.14, quoting was required
4844 in order to continue lines, so you may come across older configuration files
4845 and examples that apparently quote unnecessarily.
4846
4847
4848 6.17 Expanded strings
4849 ---------------------
4850
4851 Some strings in the configuration file are subjected to string expansion, by
4852 which means various parts of the string may be changed according to the
4853 circumstances (see chapter 11). The input syntax for such strings is as just
4854 described; in particular, the handling of backslashes in quoted strings is done
4855 as part of the input process, before expansion takes place. However, backslash
4856 is also an escape character for the expander, so any backslashes that are
4857 required for that reason must be doubled if they are within a quoted
4858 configuration string.
4859
4860
4861 6.18 User and group names
4862 -------------------------
4863
4864 User and group names are specified as strings, using the syntax described
4865 above, but the strings are interpreted specially. A user or group name must
4866 either consist entirely of digits, or be a name that can be looked up using the
4867 getpwnam() or getgrnam() function, as appropriate.
4868
4869
4870 6.19 List construction
4871 ----------------------
4872
4873 The data for some configuration options is a list of items, with colon as the
4874 default separator. Many of these options are shown with type "string list" in
4875 the descriptions later in this document. Others are listed as "domain list",
4876 "host list", "address list", or "local part list". Syntactically, they are all
4877 the same; however, those other than "string list" are subject to particular
4878 kinds of interpretation, as described in chapter 10.
4879
4880 In all these cases, the entire list is treated as a single string as far as the
4881 input syntax is concerned. The trusted_users setting in section 6.16 above is
4882 an example. If a colon is actually needed in an item in a list, it must be
4883 entered as two colons. Leading and trailing white space on each item in a list
4884 is ignored. This makes it possible to include items that start with a colon,
4885 and in particular, certain forms of IPv6 address. For example, the list
4886
4887 local_interfaces = 127.0.0.1 : ::::1
4888
4889 contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address ::1.
4890
4891 Note: Although leading and trailing white space is ignored in individual list
4892 items, it is not ignored when parsing the list. The space after the first colon
4893 in the example above is necessary. If it were not there, the list would be
4894 interpreted as the two items 127.0.0.1:: and 1.
4895
4896
4897 6.20 Changing list separators
4898 -----------------------------
4899
4900 Doubling colons in IPv6 addresses is an unwelcome chore, so a mechanism was
4901 introduced to allow the separator character to be changed. If a list begins
4902 with a left angle bracket, followed by any punctuation character, that
4903 character is used instead of colon as the list separator. For example, the list
4904 above can be rewritten to use a semicolon separator like this:
4905
4906 local_interfaces = <; 127.0.0.1 ; ::1
4907
4908 This facility applies to all lists, with the exception of the list in
4909 log_file_path. It is recommended that the use of non-colon separators be
4910 confined to circumstances where they really are needed.
4911
4912 It is also possible to use newline and other control characters (those with
4913 code values less than 32, plus DEL) as separators in lists. Such separators
4914 must be provided literally at the time the list is processed. For options that
4915 are string-expanded, you can write the separator using a normal escape
4916 sequence. This will be processed by the expander before the string is
4917 interpreted as a list. For example, if a newline-separated list of domains is
4918 generated by a lookup, you can process it directly by a line such as this:
4919
4920 domains = <\n ${lookup mysql{.....}}
4921
4922 This avoids having to change the list separator in such data. You are unlikely
4923 to want to use a control character as a separator in an option that is not
4924 expanded, because the value is literal text. However, it can be done by giving
4925 the value in quotes. For example:
4926
4927 local_interfaces = "<\n 127.0.0.1 \n ::1"
4928
4929 Unlike printing character separators, which can be included in list items by
4930 doubling, it is not possible to include a control character as data when it is
4931 set as the separator. Two such characters in succession are interpreted as
4932 enclosing an empty list item.
4933
4934
4935 6.21 Empty items in lists
4936 -------------------------
4937
4938 An empty item at the end of a list is always ignored. In other words, trailing
4939 separator characters are ignored. Thus, the list in
4940
4941 senders = user@domain :
4942
4943 contains only a single item. If you want to include an empty string as one item
4944 in a list, it must not be the last item. For example, this list contains three
4945 items, the second of which is empty:
4946
4947 senders = user1@domain : : user2@domain
4948
4949 Note: There must be white space between the two colons, as otherwise they are
4950 interpreted as representing a single colon data character (and the list would
4951 then contain just one item). If you want to specify a list that contains just
4952 one, empty item, you can do it as in this example:
4953
4954 senders = :
4955
4956 In this case, the first item is empty, and the second is discarded because it
4957 is at the end of the list.
4958
4959
4960 6.22 Format of driver configurations
4961 ------------------------------------
4962
4963 There are separate parts in the configuration for defining routers, transports,
4964 and authenticators. In each part, you are defining a number of driver
4965 instances, each with its own set of options. Each driver instance is defined by
4966 a sequence of lines like this:
4967
4968 <instance name>:
4969 <option>
4970 ...
4971 <option>
4972
4973 In the following example, the instance name is localuser, and it is followed by
4974 three options settings:
4975
4976 localuser:
4977 driver = accept
4978 check_local_user
4979 transport = local_delivery
4980
4981 For each driver instance, you specify which Exim code module it uses - by the
4982 setting of the driver option - and (optionally) some configuration settings.
4983 For example, in the case of transports, if you want a transport to deliver with
4984 SMTP you would use the smtp driver; if you want to deliver to a local file you
4985 would use the appendfile driver. Each of the drivers is described in detail in
4986 its own separate chapter later in this manual.
4987
4988 You can have several routers, transports, or authenticators that are based on
4989 the same underlying driver (each must have a different instance name).
4990
4991 The order in which routers are defined is important, because addresses are
4992 passed to individual routers one by one, in order. The order in which
4993 transports are defined does not matter at all. The order in which
4994 authenticators are defined is used only when Exim, as a client, is searching
4995 them to find one that matches an authentication mechanism offered by the
4996 server.
4997
4998 Within a driver instance definition, there are two kinds of option: generic and
4999 private. The generic options are those that apply to all drivers of the same
5000 type (that is, all routers, all transports or all authenticators). The driver
5001 option is a generic option that must appear in every definition. The private
5002 options are special for each driver, and none need appear, because they all
5003 have default values.
5004
5005 The options may appear in any order, except that the driver option must precede
5006 any private options, since these depend on the particular driver. For this
5007 reason, it is recommended that driver always be the first option.
5008
5009 Driver instance names, which are used for reference in log entries and
5010 elsewhere, can be any sequence of letters, digits, and underscores (starting
5011 with a letter) and must be unique among drivers of the same type. A router and
5012 a transport (for example) can each have the same name, but no two router
5013 instances can have the same name. The name of a driver instance should not be
5014 confused with the name of the underlying driver module. For example, the
5015 configuration lines:
5016
5017 remote_smtp:
5018 driver = smtp
5019
5020 create an instance of the smtp transport driver whose name is remote_smtp. The
5021 same driver code can be used more than once, with different instance names and
5022 different option settings each time. A second instance of the smtp transport,
5023 with different options, might be defined thus:
5024
5025 special_smtp:
5026 driver = smtp
5027 port = 1234
5028 command_timeout = 10s
5029
5030 The names remote_smtp and special_smtp would be used to reference these
5031 transport instances from routers, and these names would appear in log lines.
5032
5033 Comment lines may be present in the middle of driver specifications. The full
5034 list of option settings for any particular driver instance, including all the
5035 defaulted values, can be extracted by making use of the -bP command line
5036 option.
5037
5038
5039
5040 ===============================================================================
5041 7. THE DEFAULT CONFIGURATION FILE
5042
5043 The default configuration file supplied with Exim as src/configure.default is
5044 sufficient for a host with simple mail requirements. As an introduction to the
5045 way Exim is configured, this chapter "walks through" the default configuration,
5046 giving brief explanations of the settings. Detailed descriptions of the options
5047 are given in subsequent chapters. The default configuration file itself
5048 contains extensive comments about ways you might want to modify the initial
5049 settings. However, note that there are many options that are not mentioned at
5050 all in the default configuration.
5051
5052
5053 7.1 Main configuration settings
5054 -------------------------------
5055
5056 The main (global) configuration option settings must always come first in the
5057 file. The first thing you'll see in the file, after some initial comments, is
5058 the line
5059
5060 # primary_hostname =
5061
5062 This is a commented-out setting of the primary_hostname option. Exim needs to
5063 know the official, fully qualified name of your host, and this is where you can
5064 specify it. However, in most cases you do not need to set this option. When it
5065 is unset, Exim uses the uname() system function to obtain the host name.
5066
5067 The first three non-comment configuration lines are as follows:
5068
5069 domainlist local_domains = @
5070 domainlist relay_to_domains =
5071 hostlist relay_from_hosts = 127.0.0.1
5072
5073 These are not, in fact, option settings. They are definitions of two named
5074 domain lists and one named host list. Exim allows you to give names to lists of
5075 domains, hosts, and email addresses, in order to make it easier to manage the
5076 configuration file (see section 10.5).
5077
5078 The first line defines a domain list called local_domains; this is used later
5079 in the configuration to identify domains that are to be delivered on the local
5080 host.
5081
5082 There is just one item in this list, the string "@". This is a special form of
5083 entry which means "the name of the local host". Thus, if the local host is
5084 called a.host.example, mail to any.user@a.host.example is expected to be
5085 delivered locally. Because the local host's name is referenced indirectly, the
5086 same configuration file can be used on different hosts.
5087
5088 The second line defines a domain list called relay_to_domains, but the list
5089 itself is empty. Later in the configuration we will come to the part that
5090 controls mail relaying through the local host; it allows relaying to any
5091 domains in this list. By default, therefore, no relaying on the basis of a mail
5092 domain is permitted.
5093
5094 The third line defines a host list called relay_from_hosts. This list is used
5095 later in the configuration to permit relaying from any host or IP address that
5096 matches the list. The default contains just the IP address of the IPv4 loopback
5097 interface, which means that processes on the local host are able to submit mail
5098 for relaying by sending it over TCP/IP to that interface. No other hosts are
5099 permitted to submit messages for relaying.
5100
5101 Just to be sure there's no misunderstanding: at this point in the configuration
5102 we aren't actually setting up any controls. We are just defining some domains
5103 and hosts that will be used in the controls that are specified later.
5104
5105 The next two configuration lines are genuine option settings:
5106
5107 acl_smtp_rcpt = acl_check_rcpt
5108 acl_smtp_data = acl_check_data
5109
5110 These options specify Access Control Lists (ACLs) that are to be used during an
5111 incoming SMTP session for every recipient of a message (every RCPT command),
5112 and after the contents of the message have been received, respectively. The
5113 names of the lists are acl_check_rcpt and acl_check_data, and we will come to
5114 their definitions below, in the ACL section of the configuration. The RCPT ACL
5115 controls which recipients are accepted for an incoming message - if a
5116 configuration does not provide an ACL to check recipients, no SMTP mail can be
5117 accepted. The DATA ACL allows the contents of a message to be checked.
5118
5119 Two commented-out option settings are next:
5120
5121 # av_scanner = clamd:/tmp/clamd
5122 # spamd_address = 127.0.0.1 783
5123
5124 These are example settings that can be used when Exim is compiled with the
5125 content-scanning extension. The first specifies the interface to the virus
5126 scanner, and the second specifies the interface to SpamAssassin. Further
5127 details are given in chapter 43.
5128
5129 Three more commented-out option settings follow:
5130
5131 # tls_advertise_hosts = *
5132 # tls_certificate = /etc/ssl/exim.crt
5133 # tls_privatekey = /etc/ssl/exim.pem
5134
5135 These are example settings that can be used when Exim is compiled with support
5136 for TLS (aka SSL) as described in section 4.7. The first one specifies the list
5137 of clients that are allowed to use TLS when connecting to this server; in this
5138 case the wildcard means all clients. The other options specify where Exim
5139 should find its TLS certificate and private key, which together prove the
5140 server's identity to any clients that connect. More details are given in
5141 chapter 41.
5142
5143 Another two commented-out option settings follow:
5144
5145 # daemon_smtp_ports = 25 : 465 : 587
5146 # tls_on_connect_ports = 465
5147
5148 These options provide better support for roaming users who wish to use this
5149 server for message submission. They are not much use unless you have turned on
5150 TLS (as described in the previous paragraph) and authentication (about which
5151 more in section 7.7). The usual SMTP port 25 is often blocked on end-user
5152 networks, so RFC 4409 specifies that message submission should use port 587
5153 instead. However some software (notably Microsoft Outlook) cannot be configured
5154 to use port 587 correctly, so these settings also enable the non-standard
5155 "smtps" (aka "ssmtp") port 465 (see section 13.4).
5156
5157 Two more commented-out options settings follow:
5158
5159 # qualify_domain =
5160 # qualify_recipient =
5161
5162 The first of these specifies a domain that Exim uses when it constructs a
5163 complete email address from a local login name. This is often needed when Exim
5164 receives a message from a local process. If you do not set qualify_domain, the
5165 value of primary_hostname is used. If you set both of these options, you can
5166 have different qualification domains for sender and recipient addresses. If you
5167 set only the first one, its value is used in both cases.
5168
5169 The following line must be uncommented if you want Exim to recognize addresses
5170 of the form user@[10.11.12.13] that is, with a "domain literal" (an IP address
5171 within square brackets) instead of a named domain.
5172
5173 # allow_domain_literals
5174
5175 The RFCs still require this form, but many people think that in the modern
5176 Internet it makes little sense to permit mail to be sent to specific hosts by
5177 quoting their IP addresses. This ancient format has been used by people who try
5178 to abuse hosts by using them for unwanted relaying. However, some people
5179 believe there are circumstances (for example, messages addressed to postmaster)
5180 where domain literals are still useful.
5181
5182 The next configuration line is a kind of trigger guard:
5183
5184 never_users = root
5185
5186 It specifies that no delivery must ever be run as the root user. The normal
5187 convention is to set up root as an alias for the system administrator. This
5188 setting is a guard against slips in the configuration. The list of users
5189 specified by never_users is not, however, the complete list; the build-time
5190 configuration in Local/Makefile has an option called FIXED_NEVER_USERS
5191 specifying a list that cannot be overridden. The contents of never_users are
5192 added to this list. By default FIXED_NEVER_USERS also specifies root.
5193
5194 When a remote host connects to Exim in order to send mail, the only information
5195 Exim has about the host's identity is its IP address. The next configuration
5196 line,
5197
5198 host_lookup = *
5199
5200 specifies that Exim should do a reverse DNS lookup on all incoming connections,
5201 in order to get a host name. This improves the quality of the logging
5202 information, but if you feel it is too expensive, you can remove it entirely,
5203 or restrict the lookup to hosts on "nearby" networks. Note that it is not
5204 always possible to find a host name from an IP address, because not all DNS
5205 reverse zones are maintained, and sometimes DNS servers are unreachable.
5206
5207 The next two lines are concerned with ident callbacks, as defined by RFC 1413
5208 (hence their names):
5209
5210 rfc1413_hosts = *
5211 rfc1413_query_timeout = 0s
5212
5213 These settings cause Exim to avoid ident callbacks for all incoming SMTP calls.
5214 Few hosts offer RFC1413 service these days; calls have to be terminated by a
5215 timeout and this needlessly delays the startup of an incoming SMTP connection.
5216 If you have hosts for which you trust RFC1413 and need this information, you
5217 can change this.
5218
5219 This line enables an efficiency SMTP option. It is negociated by clients and
5220 not expected to cause problems but can be disabled if needed.
5221
5222 prdr_enable = true
5223
5224 When Exim receives messages over SMTP connections, it expects all addresses to
5225 be fully qualified with a domain, as required by the SMTP definition. However,
5226 if you are running a server to which simple clients submit messages, you may
5227 find that they send unqualified addresses. The two commented-out options:
5228
5229 # sender_unqualified_hosts =
5230 # recipient_unqualified_hosts =
5231
5232 show how you can specify hosts that are permitted to send unqualified sender
5233 and recipient addresses, respectively.
5234
5235 The percent_hack_domains option is also commented out:
5236
5237 # percent_hack_domains =
5238
5239 It provides a list of domains for which the "percent hack" is to operate. This
5240 is an almost obsolete form of explicit email routing. If you do not know
5241 anything about it, you can safely ignore this topic.
5242
5243 The last two settings in the main part of the default configuration are
5244 concerned with messages that have been "frozen" on Exim's queue. When a message
5245 is frozen, Exim no longer continues to try to deliver it. Freezing occurs when
5246 a bounce message encounters a permanent failure because the sender address of
5247 the original message that caused the bounce is invalid, so the bounce cannot be
5248 delivered. This is probably the most common case, but there are also other
5249 conditions that cause freezing, and frozen messages are not always bounce
5250 messages.
5251
5252 ignore_bounce_errors_after = 2d
5253 timeout_frozen_after = 7d
5254
5255 The first of these options specifies that failing bounce messages are to be
5256 discarded after 2 days on the queue. The second specifies that any frozen
5257 message (whether a bounce message or not) is to be timed out (and discarded)
5258 after a week. In this configuration, the first setting ensures that no failing
5259 bounce message ever lasts a week.
5260
5261
5262 7.2 ACL configuration
5263 ---------------------
5264
5265 In the default configuration, the ACL section follows the main configuration.
5266 It starts with the line
5267
5268 begin acl
5269
5270 and it contains the definitions of two ACLs, called acl_check_rcpt and
5271 acl_check_data, that were referenced in the settings of acl_smtp_rcpt and
5272 acl_smtp_data above.
5273
5274 The first ACL is used for every RCPT command in an incoming SMTP message. Each
5275 RCPT command specifies one of the message's recipients. The ACL statements are
5276 considered in order, until the recipient address is either accepted or
5277 rejected. The RCPT command is then accepted or rejected, according to the
5278 result of the ACL processing.
5279
5280 acl_check_rcpt:
5281
5282 This line, consisting of a name terminated by a colon, marks the start of the
5283 ACL, and names it.
5284
5285 accept hosts = :
5286
5287 This ACL statement accepts the recipient if the sending host matches the list.
5288 But what does that strange list mean? It doesn't actually contain any host
5289 names or IP addresses. The presence of the colon puts an empty item in the
5290 list; Exim matches this only if the incoming message did not come from a remote
5291 host, because in that case, the remote hostname is empty. The colon is
5292 important. Without it, the list itself is empty, and can never match anything.
5293
5294 What this statement is doing is to accept unconditionally all recipients in
5295 messages that are submitted by SMTP from local processes using the standard
5296 input and output (that is, not using TCP/IP). A number of MUAs operate in this
5297 manner.
5298
5299 deny message = Restricted characters in address
5300 domains = +local_domains
5301 local_parts = ^[.] : ^.*[@%!/|]
5302
5303 deny message = Restricted characters in address
5304 domains = !+local_domains
5305 local_parts = ^[./|] : ^.*[@%!] : ^.*/\\.\\./
5306
5307 These statements are concerned with local parts that contain any of the
5308 characters "@", "%", "!", "/", "|", or dots in unusual places. Although these
5309 characters are entirely legal in local parts (in the case of "@" and leading
5310 dots, only if correctly quoted), they do not commonly occur in Internet mail
5311 addresses.
5312
5313 The first three have in the past been associated with explicitly routed
5314 addresses (percent is still sometimes used - see the percent_hack_domains
5315 option). Addresses containing these characters are regularly tried by spammers
5316 in an attempt to bypass relaying restrictions, and also by open relay testing
5317 programs. Unless you really need them it is safest to reject these characters
5318 at this early stage. This configuration is heavy-handed in rejecting these
5319 characters for all messages it accepts from remote hosts. This is a deliberate
5320 policy of being as safe as possible.
5321
5322 The first rule above is stricter, and is applied to messages that are addressed
5323 to one of the local domains handled by this host. This is implemented by the
5324 first condition, which restricts it to domains that are listed in the
5325 local_domains domain list. The "+" character is used to indicate a reference to
5326 a named list. In this configuration, there is just one domain in local_domains,
5327 but in general there may be many.
5328
5329 The second condition on the first statement uses two regular expressions to
5330 block local parts that begin with a dot or contain "@", "%", "!", "/", or "|".
5331 If you have local accounts that include these characters, you will have to
5332 modify this rule.
5333
5334 Empty components (two dots in a row) are not valid in RFC 2822, but Exim allows
5335 them because they have been encountered in practice. (Consider the common
5336 convention of local parts constructed as "
5337 first-initial.second-initial.family-name" when applied to someone like the
5338 author of Exim, who has no second initial.) However, a local part starting with
5339 a dot or containing "/../" can cause trouble if it is used as part of a file
5340 name (for example, for a mailing list). This is also true for local parts that
5341 contain slashes. A pipe symbol can also be troublesome if the local part is
5342 incorporated unthinkingly into a shell command line.
5343
5344 The second rule above applies to all other domains, and is less strict. This
5345 allows your own users to send outgoing messages to sites that use slashes and
5346 vertical bars in their local parts. It blocks local parts that begin with a
5347 dot, slash, or vertical bar, but allows these characters within the local part.
5348 However, the sequence "/../" is barred. The use of "@", "%", and "!" is
5349 blocked, as before. The motivation here is to prevent your users (or your
5350 users' viruses) from mounting certain kinds of attack on remote sites.
5351
5352 accept local_parts = postmaster
5353 domains = +local_domains
5354
5355 This statement, which has two conditions, accepts an incoming address if the
5356 local part is postmaster and the domain is one of those listed in the
5357 local_domains domain list. The "+" character is used to indicate a reference to
5358 a named list. In this configuration, there is just one domain in local_domains,
5359 but in general there may be many.
5360
5361 The presence of this statement means that mail to postmaster is never blocked
5362 by any of the subsequent tests. This can be helpful while sorting out problems
5363 in cases where the subsequent tests are incorrectly denying access.
5364
5365 require verify = sender
5366
5367 This statement requires the sender address to be verified before any subsequent
5368 ACL statement can be used. If verification fails, the incoming recipient
5369 address is refused. Verification consists of trying to route the address, to
5370 see if a bounce message could be delivered to it. In the case of remote
5371 addresses, basic verification checks only the domain, but callouts can be used
5372 for more verification if required. Section 42.44 discusses the details of
5373 address verification.
5374
5375 accept hosts = +relay_from_hosts
5376 control = submission
5377
5378 This statement accepts the address if the message is coming from one of the
5379 hosts that are defined as being allowed to relay through this host. Recipient
5380 verification is omitted here, because in many cases the clients are dumb MUAs
5381 that do not cope well with SMTP error responses. For the same reason, the
5382 second line specifies "submission mode" for messages that are accepted. This is
5383 described in detail in section 46.1; it causes Exim to fix messages that are
5384 deficient in some way, for example, because they lack a Date: header line. If
5385 you are actually relaying out from MTAs, you should probably add recipient
5386 verification here, and disable submission mode.
5387
5388 accept authenticated = *
5389 control = submission
5390
5391 This statement accepts the address if the client host has authenticated itself.
5392 Submission mode is again specified, on the grounds that such messages are most
5393 likely to come from MUAs. The default configuration does not define any
5394 authenticators, though it does include some nearly complete commented-out
5395 examples described in 7.7. This means that no client can in fact authenticate
5396 until you complete the authenticator definitions.
5397
5398 require message = relay not permitted
5399 domains = +local_domains : +relay_to_domains
5400
5401 This statement rejects the address if its domain is neither a local domain nor
5402 one of the domains for which this host is a relay.
5403
5404 require verify = recipient
5405
5406 This statement requires the recipient address to be verified; if verification
5407 fails, the address is rejected.
5408
5409 # deny message = rejected because $sender_host_address \
5410 # is in a black list at $dnslist_domain\n\
5411 # $dnslist_text
5412 # dnslists = black.list.example
5413 #
5414 # warn dnslists = black.list.example
5415 # add_header = X-Warning: $sender_host_address is in \
5416 # a black list at $dnslist_domain
5417 # log_message = found in $dnslist_domain
5418
5419 These commented-out lines are examples of how you could configure Exim to check
5420 sending hosts against a DNS black list. The first statement rejects messages
5421 from blacklisted hosts, whereas the second just inserts a warning header line.
5422
5423 # require verify = csa
5424
5425 This commented-out line is an example of how you could turn on client SMTP
5426 authorization (CSA) checking. Such checks do DNS lookups for special SRV
5427 records.
5428
5429 accept
5430
5431 The final statement in the first ACL unconditionally accepts any recipient
5432 address that has successfully passed all the previous tests.
5433
5434 acl_check_data:
5435
5436 This line marks the start of the second ACL, and names it. Most of the contents
5437 of this ACL are commented out:
5438
5439 # deny malware = *
5440 # message = This message contains a virus \
5441 # ($malware_name).
5442
5443 These lines are examples of how to arrange for messages to be scanned for
5444 viruses when Exim has been compiled with the content-scanning extension, and a
5445 suitable virus scanner is installed. If the message is found to contain a
5446 virus, it is rejected with the given custom error message.
5447
5448 # warn spam = nobody
5449 # message = X-Spam_score: $spam_score\n\
5450 # X-Spam_score_int: $spam_score_int\n\
5451 # X-Spam_bar: $spam_bar\n\
5452 # X-Spam_report: $spam_report
5453
5454 These lines are an example of how to arrange for messages to be scanned by
5455 SpamAssassin when Exim has been compiled with the content-scanning extension,
5456 and SpamAssassin has been installed. The SpamAssassin check is run with
5457 "nobody" as its user parameter, and the results are added to the message as a
5458 series of extra header line. In this case, the message is not rejected,
5459 whatever the spam score.
5460
5461 accept
5462
5463 This final line in the DATA ACL accepts the message unconditionally.
5464
5465
5466 7.3 Router configuration
5467 ------------------------
5468
5469 The router configuration comes next in the default configuration, introduced by
5470 the line
5471
5472 begin routers
5473
5474 Routers are the modules in Exim that make decisions about where to send
5475 messages. An address is passed to each router in turn, until it is either
5476 accepted, or failed. This means that the order in which you define the routers
5477 matters. Each router is fully described in its own chapter later in this
5478 manual. Here we give only brief overviews.
5479
5480 # domain_literal:
5481 # driver = ipliteral
5482 # domains = !+local_domains
5483 # transport = remote_smtp
5484
5485 This router is commented out because the majority of sites do not want to
5486 support domain literal addresses (those of the form user@[10.9.8.7]). If you
5487 uncomment this router, you also need to uncomment the setting of
5488 allow_domain_literals in the main part of the configuration.
5489
5490 dnslookup:
5491 driver = dnslookup
5492 domains = ! +local_domains
5493 transport = remote_smtp
5494 ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8
5495 no_more
5496
5497 The first uncommented router handles addresses that do not involve any local
5498 domains. This is specified by the line
5499
5500 domains = ! +local_domains
5501
5502 The domains option lists the domains to which this router applies, but the
5503 exclamation mark is a negation sign, so the router is used only for domains
5504 that are not in the domain list called local_domains (which was defined at the
5505 start of the configuration). The plus sign before local_domains indicates that
5506 it is referring to a named list. Addresses in other domains are passed on to
5507 the following routers.
5508
5509 The name of the router driver is dnslookup, and is specified by the driver
5510 option. Do not be confused by the fact that the name of this router instance is
5511 the same as the name of the driver. The instance name is arbitrary, but the
5512 name set in the driver option must be one of the driver modules that is in the
5513 Exim binary.
5514
5515 The dnslookup router routes addresses by looking up their domains in the DNS in
5516 order to obtain a list of hosts to which the address is routed. If the router
5517 succeeds, the address is queued for the remote_smtp transport, as specified by
5518 the transport option. If the router does not find the domain in the DNS, no
5519 further routers are tried because of the no_more setting, so the address fails
5520 and is bounced.
5521
5522 The ignore_target_hosts option specifies a list of IP addresses that are to be
5523 entirely ignored. This option is present because a number of cases have been
5524 encountered where MX records in the DNS point to host names whose IP addresses
5525 are 0.0.0.0 or are in the 127 subnet (typically 127.0.0.1). Completely ignoring
5526 these IP addresses causes Exim to fail to route the email address, so it
5527 bounces. Otherwise, Exim would log a routing problem, and continue to try to
5528 deliver the message periodically until the address timed out.
5529
5530 system_aliases:
5531 driver = redirect
5532 allow_fail
5533 allow_defer
5534 data = ${lookup{$local_part}lsearch{/etc/aliases}}
5535 # user = exim
5536 file_transport = address_file
5537 pipe_transport = address_pipe
5538
5539 Control reaches this and subsequent routers only for addresses in the local
5540 domains. This router checks to see whether the local part is defined as an
5541 alias in the /etc/aliases file, and if so, redirects it according to the data
5542 that it looks up from that file. If no data is found for the local part, the
5543 value of the data option is empty, causing the address to be passed to the next
5544 router.
5545
5546 /etc/aliases is a conventional name for the system aliases file that is often
5547 used. That is why it is referenced by from the default configuration file.
5548 However, you can change this by setting SYSTEM_ALIASES_FILE in Local/Makefile
5549 before building Exim.
5550
5551 userforward:
5552 driver = redirect
5553 check_local_user
5554 # local_part_suffix = +* : -*
5555 # local_part_suffix_optional
5556 file = $home/.forward
5557 # allow_filter
5558 no_verify
5559 no_expn
5560 check_ancestor
5561 file_transport = address_file
5562 pipe_transport = address_pipe
5563 reply_transport = address_reply
5564
5565 This is the most complicated router in the default configuration. It is another
5566 redirection router, but this time it is looking for forwarding data set up by
5567 individual users. The check_local_user setting specifies a check that the local
5568 part of the address is the login name of a local user. If it is not, the router
5569 is skipped. The two commented options that follow check_local_user, namely:
5570
5571 # local_part_suffix = +* : -*
5572 # local_part_suffix_optional
5573
5574 show how you can specify the recognition of local part suffixes. If the first
5575 is uncommented, a suffix beginning with either a plus or a minus sign, followed
5576 by any sequence of characters, is removed from the local part and placed in the
5577 variable $local_part_suffix. The second suffix option specifies that the
5578 presence of a suffix in the local part is optional. When a suffix is present,
5579 the check for a local login uses the local part with the suffix removed.
5580
5581 When a local user account is found, the file called .forward in the user's home
5582 directory is consulted. If it does not exist, or is empty, the router declines.
5583 Otherwise, the contents of .forward are interpreted as redirection data (see
5584 chapter 22 for more details).
5585
5586 Traditional .forward files contain just a list of addresses, pipes, or files.
5587 Exim supports this by default. However, if allow_filter is set (it is commented
5588 out by default), the contents of the file are interpreted as a set of Exim or
5589 Sieve filtering instructions, provided the file begins with "#Exim filter" or "
5590 #Sieve filter", respectively. User filtering is discussed in the separate
5591 document entitled Exim's interfaces to mail filtering.
5592
5593 The no_verify and no_expn options mean that this router is skipped when
5594 verifying addresses, or when running as a consequence of an SMTP EXPN command.
5595 There are two reasons for doing this:
5596
5597 1. Whether or not a local user has a .forward file is not really relevant when
5598 checking an address for validity; it makes sense not to waste resources
5599 doing unnecessary work.
5600
5601 2. More importantly, when Exim is verifying addresses or handling an EXPN
5602 command during an SMTP session, it is running as the Exim user, not as
5603 root. The group is the Exim group, and no additional groups are set up. It
5604 may therefore not be possible for Exim to read users' .forward files at
5605 this time.
5606
5607 The setting of check_ancestor prevents the router from generating a new address
5608 that is the same as any previous address that was redirected. (This works round
5609 a problem concerning a bad interaction between aliasing and forwarding - see
5610 section 22.5).
5611
5612 The final three option settings specify the transports that are to be used when
5613 forwarding generates a direct delivery to a file, or to a pipe, or sets up an
5614 auto-reply, respectively. For example, if a .forward file contains
5615
5616 a.nother@elsewhere.example, /home/spqr/archive
5617
5618 the delivery to /home/spqr/archive is done by running the address_file
5619 transport.
5620
5621 localuser:
5622 driver = accept
5623 check_local_user
5624 # local_part_suffix = +* : -*
5625 # local_part_suffix_optional
5626 transport = local_delivery
5627
5628 The final router sets up delivery into local mailboxes, provided that the local
5629 part is the name of a local login, by accepting the address and assigning it to
5630 the local_delivery transport. Otherwise, we have reached the end of the
5631 routers, so the address is bounced. The commented suffix settings fulfil the
5632 same purpose as they do for the userforward router.
5633
5634
5635 7.4 Transport configuration
5636 ---------------------------
5637
5638 Transports define mechanisms for actually delivering messages. They operate
5639 only when referenced from routers, so the order in which they are defined does
5640 not matter. The transports section of the configuration starts with
5641
5642 begin transports
5643
5644 One remote transport and four local transports are defined.
5645
5646 remote_smtp:
5647 driver = smtp
5648 hosts_try_prdr = *
5649
5650 This transport is used for delivering messages over SMTP connections. The list
5651 of remote hosts comes from the router. The hosts_try_prdr option enables an
5652 efficiency SMTP option. It is negotiated between client and server and not
5653 expected to cause problems but can be disabled if needed. All other options are
5654 defaulted.
5655
5656 local_delivery:
5657 driver = appendfile
5658 file = /var/mail/$local_part
5659 delivery_date_add
5660 envelope_to_add
5661 return_path_add
5662 # group = mail
5663 # mode = 0660
5664
5665 This appendfile transport is used for local delivery to user mailboxes in
5666 traditional BSD mailbox format. By default it runs under the uid and gid of the
5667 local user, which requires the sticky bit to be set on the /var/mail directory.
5668 Some systems use the alternative approach of running mail deliveries under a
5669 particular group instead of using the sticky bit. The commented options show
5670 how this can be done.
5671
5672 Exim adds three headers to the message as it delivers it: Delivery-date:,
5673 Envelope-to: and Return-path:. This action is requested by the three
5674 similarly-named options above.
5675
5676 address_pipe:
5677 driver = pipe
5678 return_output
5679
5680 This transport is used for handling deliveries to pipes that are generated by
5681 redirection (aliasing or users' .forward files). The return_output option
5682 specifies that any output generated by the pipe is to be returned to the
5683 sender.
5684
5685 address_file:
5686 driver = appendfile
5687 delivery_date_add
5688 envelope_to_add
5689 return_path_add
5690
5691 This transport is used for handling deliveries to files that are generated by
5692 redirection. The name of the file is not specified in this instance of
5693 appendfile, because it comes from the redirect router.
5694
5695 address_reply:
5696 driver = autoreply
5697
5698 This transport is used for handling automatic replies generated by users'
5699 filter files.
5700
5701
5702 7.5 Default retry rule
5703 ----------------------
5704
5705 The retry section of the configuration file contains rules which affect the way
5706 Exim retries deliveries that cannot be completed at the first attempt. It is
5707 introduced by the line
5708
5709 begin retry
5710
5711 In the default configuration, there is just one rule, which applies to all
5712 errors:
5713
5714 * * F,2h,15m; G,16h,1h,1.5; F,4d,6h
5715
5716 This causes any temporarily failing address to be retried every 15 minutes for
5717 2 hours, then at intervals starting at one hour and increasing by a factor of
5718 1.5 until 16 hours have passed, then every 6 hours up to 4 days. If an address
5719 is not delivered after 4 days of temporary failure, it is bounced.
5720
5721 If the retry section is removed from the configuration, or is empty (that is,
5722 if no retry rules are defined), Exim will not retry deliveries. This turns
5723 temporary errors into permanent errors.
5724
5725
5726 7.6 Rewriting configuration
5727 ---------------------------
5728
5729 The rewriting section of the configuration, introduced by
5730
5731 begin rewrite
5732
5733 contains rules for rewriting addresses in messages as they arrive. There are no
5734 rewriting rules in the default configuration file.
5735
5736
5737 7.7 Authenticators configuration
5738 --------------------------------
5739
5740 The authenticators section of the configuration, introduced by
5741
5742 begin authenticators
5743
5744 defines mechanisms for the use of the SMTP AUTH command. The default
5745 configuration file contains two commented-out example authenticators which
5746 support plaintext username/password authentication using the standard PLAIN
5747 mechanism and the traditional but non-standard LOGIN mechanism, with Exim
5748 acting as the server. PLAIN and LOGIN are enough to support most MUA software.
5749
5750 The example PLAIN authenticator looks like this:
5751
5752 #PLAIN:
5753 # driver = plaintext
5754 # server_set_id = $auth2
5755 # server_prompts = :
5756 # server_condition = Authentication is not yet configured
5757 # server_advertise_condition = ${if def:tls_in_cipher }
5758
5759 And the example LOGIN authenticator looks like this:
5760
5761 #LOGIN:
5762 # driver = plaintext
5763 # server_set_id = $auth1
5764 # server_prompts = <| Username: | Password:
5765 # server_condition = Authentication is not yet configured
5766 # server_advertise_condition = ${if def:tls_in_cipher }
5767
5768 The server_set_id option makes Exim remember the authenticated username in
5769 $authenticated_id, which can be used later in ACLs or routers. The
5770 server_prompts option configures the plaintext authenticator so that it
5771 implements the details of the specific authentication mechanism, i.e. PLAIN or
5772 LOGIN. The server_advertise_condition setting controls when Exim offers
5773 authentication to clients; in the examples, this is only when TLS or SSL has
5774 been started, so to enable the authenticators you also need to add support for
5775 TLS as described in section 7.1.
5776
5777 The server_condition setting defines how to verify that the username and
5778 password are correct. In the examples it just produces an error message. To
5779 make the authenticators work, you can use a string expansion expression like
5780 one of the examples in chapter 34.
5781
5782 Beware that the sequence of the parameters to PLAIN and LOGIN differ; the
5783 usercode and password are in different positions. Chapter 34 covers both.
5784
5785
5786
5787 ===============================================================================
5788 8. REGULAR EXPRESSIONS
5789
5790 Exim supports the use of regular expressions in many of its options. It uses
5791 the PCRE regular expression library; this provides regular expression matching
5792 that is compatible with Perl 5. The syntax and semantics of regular expressions
5793 is discussed in many Perl reference books, and also in Jeffrey Friedl's
5794 Mastering Regular Expressions, which is published by O'Reilly (see http://
5795 www.oreilly.com/catalog/regex2/).
5796
5797 The documentation for the syntax and semantics of the regular expressions that
5798 are supported by PCRE is included in the PCRE distribution, and no further
5799 description is included here. The PCRE functions are called from Exim using the
5800 default option settings (that is, with no PCRE options set), except that the
5801 PCRE_CASELESS option is set when the matching is required to be
5802 case-insensitive.
5803
5804 In most cases, when a regular expression is required in an Exim configuration,
5805 it has to start with a circumflex, in order to distinguish it from plain text
5806 or an "ends with" wildcard. In this example of a configuration setting, the
5807 second item in the colon-separated list is a regular expression.
5808
5809 domains = a.b.c : ^\\d{3} : *.y.z : ...
5810
5811 The doubling of the backslash is required because of string expansion that
5812 precedes interpretation - see section 11.1 for more discussion of this issue,
5813 and a way of avoiding the need for doubling backslashes. The regular expression
5814 that is eventually used in this example contains just one backslash. The
5815 circumflex is included in the regular expression, and has the normal effect of
5816 "anchoring" it to the start of the string that is being matched.
5817
5818 There are, however, two cases where a circumflex is not required for the
5819 recognition of a regular expression: these are the match condition in a string
5820 expansion, and the matches condition in an Exim filter file. In these cases,
5821 the relevant string is always treated as a regular expression; if it does not
5822 start with a circumflex, the expression is not anchored, and can match anywhere
5823 in the subject string.
5824
5825 In all cases, if you want a regular expression to match at the end of a string,
5826 you must code the $ metacharacter to indicate this. For example:
5827
5828 domains = ^\\d{3}\\.example
5829
5830 matches the domain 123.example, but it also matches 123.example.com. You need
5831 to use:
5832
5833 domains = ^\\d{3}\\.example\$
5834
5835 if you want example to be the top-level domain. The backslash before the $ is
5836 needed because string expansion also interprets dollar characters.
5837
5838
5839
5840 ===============================================================================
5841 9. FILE AND DATABASE LOOKUPS
5842
5843 Exim can be configured to look up data in files or databases as it processes
5844 messages. Two different kinds of syntax are used:
5845
5846 1. A string that is to be expanded may contain explicit lookup requests. These
5847 cause parts of the string to be replaced by data that is obtained from the
5848 lookup. Lookups of this type are conditional expansion items. Different
5849 results can be defined for the cases of lookup success and failure. See
5850 chapter 11, where string expansions are described in detail.
5851
5852 2. Lists of domains, hosts, and email addresses can contain lookup requests as
5853 a way of avoiding excessively long linear lists. In this case, the data
5854 that is returned by the lookup is often (but not always) discarded; whether
5855 the lookup succeeds or fails is what really counts. These kinds of list are
5856 described in chapter 10.
5857
5858 String expansions, lists, and lookups interact with each other in such a way
5859 that there is no order in which to describe any one of them that does not
5860 involve references to the others. Each of these three chapters makes more sense
5861 if you have read the other two first. If you are reading this for the first
5862 time, be aware that some of it will make a lot more sense after you have read
5863 chapters 10 and 11.
5864
5865
5866 9.1 Examples of different lookup syntax
5867 ---------------------------------------
5868
5869 It is easy to confuse the two different kinds of lookup, especially as the
5870 lists that may contain the second kind are always expanded before being
5871 processed as lists. Therefore, they may also contain lookups of the first kind.
5872 Be careful to distinguish between the following two examples:
5873
5874 domains = ${lookup{$sender_host_address}lsearch{/some/file}}
5875 domains = lsearch;/some/file
5876
5877 The first uses a string expansion, the result of which must be a domain list.
5878 No strings have been specified for a successful or a failing lookup; the
5879 defaults in this case are the looked-up data and an empty string, respectively.
5880 The expansion takes place before the string is processed as a list, and the
5881 file that is searched could contain lines like this:
5882
5883 192.168.3.4: domain1:domain2:...
5884 192.168.1.9: domain3:domain4:...
5885
5886 When the lookup succeeds, the result of the expansion is a list of domains (and
5887 possibly other types of item that are allowed in domain lists).
5888
5889 In the second example, the lookup is a single item in a domain list. It causes
5890 Exim to use a lookup to see if the domain that is being processed can be found
5891 in the file. The file could contains lines like this:
5892
5893 domain1:
5894 domain2:
5895
5896 Any data that follows the keys is not relevant when checking that the domain
5897 matches the list item.
5898
5899 It is possible, though no doubt confusing, to use both kinds of lookup at once.
5900 Consider a file containing lines like this:
5901
5902 192.168.5.6: lsearch;/another/file
5903
5904 If the value of $sender_host_address is 192.168.5.6, expansion of the first
5905 domains setting above generates the second setting, which therefore causes a
5906 second lookup to occur.
5907
5908 The rest of this chapter describes the different lookup types that are
5909 available. Any of them can be used in any part of the configuration where a
5910 lookup is permitted.
5911
5912
5913 9.2 Lookup types
5914 ----------------
5915
5916 Two different types of data lookup are implemented:
5917
5918 * The single-key type requires the specification of a file in which to look,
5919 and a single key to search for. The key must be a non-empty string for the
5920 lookup to succeed. The lookup type determines how the file is searched.
5921
5922 * The query-style type accepts a generalized database query. No particular
5923 key value is assumed by Exim for query-style lookups. You can use whichever
5924 Exim variables you need to construct the database query.
5925
5926 The code for each lookup type is in a separate source file that is included in
5927 the binary of Exim only if the corresponding compile-time option is set. The
5928 default settings in src/EDITME are:
5929
5930 LOOKUP_DBM=yes
5931 LOOKUP_LSEARCH=yes
5932
5933 which means that only linear searching and DBM lookups are included by default.
5934 For some types of lookup (e.g. SQL databases), you need to install appropriate
5935 libraries and header files before building Exim.
5936
5937
5938 9.3 Single-key lookup types
5939 ---------------------------
5940
5941 The following single-key lookup types are implemented:
5942
5943 * cdb: The given file is searched as a Constant DataBase file, using the key
5944 string without a terminating binary zero. The cdb format is designed for
5945 indexed files that are read frequently and never updated, except by total
5946 re-creation. As such, it is particularly suitable for large files
5947 containing aliases or other indexed data referenced by an MTA. Information
5948 about cdb can be found in several places:
5949
5950 http://www.pobox.com/~djb/cdb.html
5951 ftp://ftp.corpit.ru/pub/tinycdb/
5952 http://packages.debian.org/stable/utils/freecdb.html
5953
5954 A cdb distribution is not needed in order to build Exim with cdb support,
5955 because the code for reading cdb files is included directly in Exim itself.
5956 However, no means of building or testing cdb files is provided with Exim,
5957 so you need to obtain a cdb distribution in order to do this.
5958
5959 * dbm: Calls to DBM library functions are used to extract data from the given
5960 DBM file by looking up the record with the given key. A terminating binary
5961 zero is included in the key that is passed to the DBM library. See section
5962 4.4 for a discussion of DBM libraries.
5963
5964 For all versions of Berkeley DB, Exim uses the DB_HASH style of database
5965 when building DBM files using the exim_dbmbuild utility. However, when
5966 using Berkeley DB versions 3 or 4, it opens existing databases for reading
5967 with the DB_UNKNOWN option. This enables it to handle any of the types of
5968 database that the library supports, and can be useful for accessing DBM
5969 files created by other applications. (For earlier DB versions, DB_HASH is
5970 always used.)
5971
5972 * dbmjz: This is the same as dbm, except that the lookup key is interpreted
5973 as an Exim list; the elements of the list are joined together with ASCII
5974 NUL characters to form the lookup key. An example usage would be to
5975 authenticate incoming SMTP calls using the passwords from Cyrus SASL's /etc
5976 /sasldb2 file with the gsasl authenticator or Exim's own cram_md5
5977 authenticator.
5978
5979 * dbmnz: This is the same as dbm, except that a terminating binary zero is
5980 not included in the key that is passed to the DBM library. You may need
5981 this if you want to look up data in files that are created by or shared
5982 with some other application that does not use terminating zeros. For
5983 example, you need to use dbmnz rather than dbm if you want to authenticate
5984 incoming SMTP calls using the passwords from Courier's /etc/
5985 userdbshadow.dat file. Exim's utility program for creating DBM files (
5986 exim_dbmbuild) includes the zeros by default, but has an option to omit
5987 them (see section 52.9).
5988
5989 * dsearch: The given file must be a directory; this is searched for an entry
5990 whose name is the key by calling the lstat() function. The key may not
5991 contain any forward slash characters. If lstat() succeeds, the result of
5992 the lookup is the name of the entry, which may be a file, directory,
5993 symbolic link, or any other kind of directory entry. An example of how this
5994 lookup can be used to support virtual domains is given in section 49.7.
5995
5996 * iplsearch: The given file is a text file containing keys and data. A key is
5997 terminated by a colon or white space or the end of the line. The keys in
5998 the file must be IP addresses, or IP addresses with CIDR masks. Keys that
5999 involve IPv6 addresses must be enclosed in quotes to prevent the first
6000 internal colon being interpreted as a key terminator. For example:
6001
6002 1.2.3.4: data for 1.2.3.4
6003 192.168.0.0/16: data for 192.168.0.0/16
6004 "abcd::cdab": data for abcd::cdab
6005 "abcd:abcd::/32" data for abcd:abcd::/32
6006
6007 The key for an iplsearch lookup must be an IP address (without a mask). The
6008 file is searched linearly, using the CIDR masks where present, until a
6009 matching key is found. The first key that matches is used; there is no
6010 attempt to find a "best" match. Apart from the way the keys are matched,
6011 the processing for iplsearch is the same as for lsearch.
6012
6013 Warning 1: Unlike most other single-key lookup types, a file of data for
6014 iplsearch can not be turned into a DBM or cdb file, because those lookup
6015 types support only literal keys.
6016
6017 Warning 2: In a host list, you must always use net-iplsearch so that the
6018 implicit key is the host's IP address rather than its name (see section
6019 10.12).
6020
6021 * lsearch: The given file is a text file that is searched linearly for a line
6022 beginning with the search key, terminated by a colon or white space or the
6023 end of the line. The search is case-insensitive; that is, upper and lower
6024 case letters are treated as the same. The first occurrence of the key that
6025 is found in the file is used.
6026
6027 White space between the key and the colon is permitted. The remainder of
6028 the line, with leading and trailing white space removed, is the data. This
6029 can be continued onto subsequent lines by starting them with any amount of
6030 white space, but only a single space character is included in the data at
6031 such a junction. If the data begins with a colon, the key must be
6032 terminated by a colon, for example:
6033
6034 baduser: :fail:
6035
6036 Empty lines and lines beginning with # are ignored, even if they occur in
6037 the middle of an item. This is the traditional textual format of alias
6038 files. Note that the keys in an lsearch file are literal strings. There is
6039 no wildcarding of any kind.
6040
6041 In most lsearch files, keys are not required to contain colons or #
6042 characters, or white space. However, if you need this feature, it is
6043 available. If a key begins with a doublequote character, it is terminated
6044 only by a matching quote (or end of line), and the normal escaping rules
6045 apply to its contents (see section 6.16). An optional colon is permitted
6046 after quoted keys (exactly as for unquoted keys). There is no special
6047 handling of quotes for the data part of an lsearch line.
6048
6049 * nis: The given file is the name of a NIS map, and a NIS lookup is done with
6050 the given key, without a terminating binary zero. There is a variant called
6051 nis0 which does include the terminating binary zero in the key. This is
6052 reportedly needed for Sun-style alias files. Exim does not recognize NIS
6053 aliases; the full map names must be used.
6054
6055 * wildlsearch or nwildlsearch: These search a file linearly, like lsearch,
6056 but instead of being interpreted as a literal string, each key in the file
6057 may be wildcarded. The difference between these two lookup types is that
6058 for wildlsearch, each key in the file is string-expanded before being used,
6059 whereas for nwildlsearch, no expansion takes place.
6060
6061 Like lsearch, the testing is done case-insensitively. However, keys in the
6062 file that are regular expressions can be made case-sensitive by the use of
6063 "(-i)" within the pattern. The following forms of wildcard are recognized:
6064
6065 1. The string may begin with an asterisk to mean "ends with". For example:
6066
6067 *.a.b.c data for anything.a.b.c
6068 *fish data for anythingfish
6069
6070 2. The string may begin with a circumflex to indicate a regular
6071 expression. For example, for wildlsearch:
6072
6073 ^\N\d+\.a\.b\N data for <digits>.a.b
6074
6075 Note the use of "\N" to disable expansion of the contents of the
6076 regular expression. If you are using nwildlsearch, where the keys are
6077 not string-expanded, the equivalent entry is:
6078
6079 ^\d+\.a\.b data for <digits>.a.b
6080
6081 The case-insensitive flag is set at the start of compiling the regular
6082 expression, but it can be turned off by using "(-i)" at an appropriate
6083 point. For example, to make the entire pattern case-sensitive:
6084
6085 ^(?-i)\d+\.a\.b data for <digits>.a.b
6086
6087 If the regular expression contains white space or colon characters, you
6088 must either quote it (see lsearch above), or represent these characters
6089 in other ways. For example, "\s" can be used for white space and "\x3A"
6090 for a colon. This may be easier than quoting, because if you quote, you
6091 have to escape all the backslashes inside the quotes.
6092
6093 Note: It is not possible to capture substrings in a regular expression
6094 match for later use, because the results of all lookups are cached. If
6095 a lookup is repeated, the result is taken from the cache, and no actual
6096 pattern matching takes place. The values of all the numeric variables
6097 are unset after a (n)wildlsearch match.
6098
6099 3. Although I cannot see it being of much use, the general matching
6100 function that is used to implement (n)wildlsearch means that the string
6101 may begin with a lookup name terminated by a semicolon, and followed by
6102 lookup data. For example:
6103
6104 cdb;/some/file data for keys that match the file
6105
6106 The data that is obtained from the nested lookup is discarded.
6107
6108 Keys that do not match any of these patterns are interpreted literally. The
6109 continuation rules for the data are the same as for lsearch, and keys may
6110 be followed by optional colons.
6111
6112 Warning: Unlike most other single-key lookup types, a file of data for (n)
6113 wildlsearch can not be turned into a DBM or cdb file, because those lookup
6114 types support only literal keys.
6115
6116
6117 9.4 Query-style lookup types
6118 ----------------------------
6119
6120 The supported query-style lookup types are listed below. Further details about
6121 many of them are given in later sections.
6122
6123 * dnsdb: This does a DNS search for one or more records whose domain names
6124 are given in the supplied query. The resulting data is the contents of the
6125 records. See section 9.10.
6126
6127 * ibase: This does a lookup in an InterBase database.
6128
6129 * ldap: This does an LDAP lookup using a query in the form of a URL, and
6130 returns attributes from a single entry. There is a variant called ldapm
6131 that permits values from multiple entries to be returned. A third variant
6132 called ldapdn returns the Distinguished Name of a single entry instead of
6133 any attribute values. See section 9.13.
6134
6135 * mysql: The format of the query is an SQL statement that is passed to a
6136 MySQL database. See section 9.20.
6137
6138 * nisplus: This does a NIS+ lookup using a query that can specify the name of
6139 the field to be returned. See section 9.19.
6140
6141 * oracle: The format of the query is an SQL statement that is passed to an
6142 Oracle database. See section 9.20.
6143
6144 * passwd is a query-style lookup with queries that are just user names. The
6145 lookup calls getpwnam() to interrogate the system password data, and on
6146 success, the result string is the same as you would get from an lsearch
6147 lookup on a traditional /etc/passwd file, though with "*" for the password
6148 value. For example:
6149
6150 *:42:42:King Rat:/home/kr:/bin/bash
6151
6152 * pgsql: The format of the query is an SQL statement that is passed to a
6153 PostgreSQL database. See section 9.20.
6154
6155 * sqlite: The format of the query is a file name followed by an SQL statement
6156 that is passed to an SQLite database. See section 9.25.
6157
6158 * testdb: This is a lookup type that is used for testing Exim. It is not
6159 likely to be useful in normal operation.
6160
6161 * whoson: Whoson (http://whoson.sourceforge.net) is a protocol that allows a
6162 server to check whether a particular (dynamically allocated) IP address is
6163 currently allocated to a known (trusted) user and, optionally, to obtain
6164 the identity of the said user. For SMTP servers, Whoson was popular at one
6165 time for "POP before SMTP" authentication, but that approach has been
6166 superseded by SMTP authentication. In Exim, Whoson can be used to implement
6167 "POP before SMTP" checking using ACL statements such as
6168
6169 require condition = \
6170 ${lookup whoson {$sender_host_address}{yes}{no}}
6171
6172 The query consists of a single IP address. The value returned is the name
6173 of the authenticated user, which is stored in the variable $value. However,
6174 in this example, the data in $value is not used; the result of the lookup
6175 is one of the fixed strings "yes" or "no".
6176
6177
6178 9.5 Temporary errors in lookups
6179 -------------------------------
6180
6181 Lookup functions can return temporary error codes if the lookup cannot be
6182 completed. For example, an SQL or LDAP database might be unavailable. For this
6183 reason, it is not advisable to use a lookup that might do this for critical
6184 options such as a list of local domains.
6185
6186 When a lookup cannot be completed in a router or transport, delivery of the
6187 message (to the relevant address) is deferred, as for any other temporary
6188 error. In other circumstances Exim may assume the lookup has failed, or may
6189 give up altogether.
6190
6191
6192 9.6 Default values in single-key lookups
6193 ----------------------------------------
6194
6195 In this context, a "default value" is a value specified by the administrator
6196 that is to be used if a lookup fails.
6197
6198 Note: This section applies only to single-key lookups. For query-style lookups,
6199 the facilities of the query language must be used. An attempt to specify a
6200 default for a query-style lookup provokes an error.
6201
6202 If "*" is added to a single-key lookup type (for example, lsearch*) and the
6203 initial lookup fails, the key "*" is looked up in the file to provide a default
6204 value. See also the section on partial matching below.
6205
6206 Alternatively, if "*@" is added to a single-key lookup type (for example dbm*@)
6207 then, if the initial lookup fails and the key contains an @ character, a second
6208 lookup is done with everything before the last @ replaced by *. This makes it
6209 possible to provide per-domain defaults in alias files that include the domains
6210 in the keys. If the second lookup fails (or doesn't take place because there is
6211 no @ in the key), "*" is looked up. For example, a redirect router might
6212 contain:
6213
6214 data = ${lookup{$local_part@$domain}lsearch*@{/etc/mix-aliases}}
6215
6216 Suppose the address that is being processed is jane@eyre.example. Exim looks up
6217 these keys, in this order:
6218
6219 jane@eyre.example
6220 *@eyre.example
6221 *
6222
6223 The data is taken from whichever key it finds first. Note: In an lsearch file,
6224 this does not mean the first of these keys in the file. A complete scan is done
6225 for each key, and only if it is not found at all does Exim move on to try the
6226 next key.
6227
6228
6229 9.7 Partial matching in single-key lookups
6230 ------------------------------------------
6231
6232 The normal operation of a single-key lookup is to search the file for an exact
6233 match with the given key. However, in a number of situations where domains are
6234 being looked up, it is useful to be able to do partial matching. In this case,
6235 information in the file that has a key starting with "*." is matched by any
6236 domain that ends with the components that follow the full stop. For example, if
6237 a key in a DBM file is
6238
6239 *.dates.fict.example
6240
6241 then when partial matching is enabled this is matched by (amongst others)
6242 2001.dates.fict.example and 1984.dates.fict.example. It is also matched by
6243 dates.fict.example, if that does not appear as a separate key in the file.
6244
6245 Note: Partial matching is not available for query-style lookups. It is also not
6246 available for any lookup items in address lists (see section 10.19).
6247
6248 Partial matching is implemented by doing a series of separate lookups using
6249 keys constructed by modifying the original subject key. This means that it can
6250 be used with any of the single-key lookup types, provided that partial matching
6251 keys beginning with a special prefix (default "*.") are included in the data
6252 file. Keys in the file that do not begin with the prefix are matched only by
6253 unmodified subject keys when partial matching is in use.
6254
6255 Partial matching is requested by adding the string "partial-" to the front of
6256 the name of a single-key lookup type, for example, partial-dbm. When this is
6257 done, the subject key is first looked up unmodified; if that fails, "*." is
6258 added at the start of the subject key, and it is looked up again. If that
6259 fails, further lookups are tried with dot-separated components removed from the
6260 start of the subject key, one-by-one, and "*." added on the front of what
6261 remains.
6262
6263 A minimum number of two non-* components are required. This can be adjusted by
6264 including a number before the hyphen in the search type. For example,
6265 partial3-lsearch specifies a minimum of three non-* components in the modified
6266 keys. Omitting the number is equivalent to "partial2-". If the subject key is
6267 2250.dates.fict.example then the following keys are looked up when the minimum
6268 number of non-* components is two:
6269
6270 2250.dates.fict.example
6271 *.2250.dates.fict.example
6272 *.dates.fict.example
6273 *.fict.example
6274
6275 As soon as one key in the sequence is successfully looked up, the lookup
6276 finishes.
6277
6278 The use of "*." as the partial matching prefix is a default that can be
6279 changed. The motivation for this feature is to allow Exim to operate with file
6280 formats that are used by other MTAs. A different prefix can be supplied in
6281 parentheses instead of the hyphen after "partial". For example:
6282
6283 domains = partial(.)lsearch;/some/file
6284
6285 In this example, if the domain is a.b.c, the sequence of lookups is "a.b.c",
6286 ".a.b.c", and ".b.c" (the default minimum of 2 non-wild components is
6287 unchanged). The prefix may consist of any punctuation characters other than a
6288 closing parenthesis. It may be empty, for example:
6289
6290 domains = partial1()cdb;/some/file
6291
6292 For this example, if the domain is a.b.c, the sequence of lookups is "a.b.c",
6293 "b.c", and "c".
6294
6295 If "partial0" is specified, what happens at the end (when the lookup with just
6296 one non-wild component has failed, and the original key is shortened right down
6297 to the null string) depends on the prefix:
6298
6299 * If the prefix has zero length, the whole lookup fails.
6300
6301 * If the prefix has length 1, a lookup for just the prefix is done. For
6302 example, the final lookup for "partial0(.)" is for "." alone.
6303
6304 * Otherwise, if the prefix ends in a dot, the dot is removed, and the
6305 remainder is looked up. With the default prefix, therefore, the final
6306 lookup is for "*" on its own.
6307
6308 * Otherwise, the whole prefix is looked up.
6309
6310 If the search type ends in "*" or "*@" (see section 9.6 above), the search for
6311 an ultimate default that this implies happens after all partial lookups have
6312 failed. If "partial0" is specified, adding "*" to the search type has no effect
6313 with the default prefix, because the "*" key is already included in the
6314 sequence of partial lookups. However, there might be a use for lookup types
6315 such as "partial0(.)lsearch*".
6316
6317 The use of "*" in lookup partial matching differs from its use as a wildcard in
6318 domain lists and the like. Partial matching works only in terms of
6319 dot-separated components; a key such as "*fict.example" in a database file is
6320 useless, because the asterisk in a partial matching subject key is always
6321 followed by a dot.
6322
6323
6324 9.8 Lookup caching
6325 ------------------
6326
6327 Exim caches all lookup results in order to avoid needless repetition of
6328 lookups. However, because (apart from the daemon) Exim operates as a collection
6329 of independent, short-lived processes, this caching applies only within a
6330 single Exim process. There is no inter-process lookup caching facility.
6331
6332 For single-key lookups, Exim keeps the relevant files open in case there is
6333 another lookup that needs them. In some types of configuration this can lead to
6334 many files being kept open for messages with many recipients. To avoid hitting
6335 the operating system limit on the number of simultaneously open files, Exim
6336 closes the least recently used file when it needs to open more files than its
6337 own internal limit, which can be changed via the lookup_open_max option.
6338
6339 The single-key lookup files are closed and the lookup caches are flushed at
6340 strategic points during delivery - for example, after all routing is complete.
6341
6342
6343 9.9 Quoting lookup data
6344 -----------------------
6345
6346 When data from an incoming message is included in a query-style lookup, there
6347 is the possibility of special characters in the data messing up the syntax of
6348 the query. For example, a NIS+ query that contains
6349
6350 [name=$local_part]
6351
6352 will be broken if the local part happens to contain a closing square bracket.
6353 For NIS+, data can be enclosed in double quotes like this:
6354
6355 [name="$local_part"]
6356
6357 but this still leaves the problem of a double quote in the data. The rule for
6358 NIS+ is that double quotes must be doubled. Other lookup types have different
6359 rules, and to cope with the differing requirements, an expansion operator of
6360 the following form is provided:
6361
6362 ${quote_<lookup-type>:<string>}
6363
6364 For example, the safest way to write the NIS+ query is
6365
6366 [name="${quote_nisplus:$local_part}"]
6367
6368 See chapter 11 for full coverage of string expansions. The quote operator can
6369 be used for all lookup types, but has no effect for single-key lookups, since
6370 no quoting is ever needed in their key strings.
6371
6372
6373 9.10 More about dnsdb
6374 ---------------------
6375
6376 The dnsdb lookup type uses the DNS as its database. A simple query consists of
6377 a record type and a domain name, separated by an equals sign. For example, an
6378 expansion string could contain:
6379
6380 ${lookup dnsdb{mx=a.b.example}{$value}fail}
6381
6382 If the lookup succeeds, the result is placed in $value, which in this case is
6383 used on its own as the result. If the lookup does not succeed, the "fail"
6384 keyword causes a forced expansion failure - see section 11.4 for an explanation
6385 of what this means.
6386
6387 The supported DNS record types are A, CNAME, MX, NS, PTR, SPF, SRV, TLSA and
6388 TXT, and, when Exim is compiled with IPv6 support, AAAA (and A6 if that is also
6389 configured). If no type is given, TXT is assumed. When the type is PTR, the
6390 data can be an IP address, written as normal; inversion and the addition of
6391 in-addr.arpa or ip6.arpa happens automatically. For example:
6392
6393 ${lookup dnsdb{ptr=192.168.4.5}{$value}fail}
6394
6395 If the data for a PTR record is not a syntactically valid IP address, it is not
6396 altered and nothing is added.
6397
6398 For an MX lookup, both the preference value and the host name are returned for
6399 each record, separated by a space. For an SRV lookup, the priority, weight,
6400 port, and host name are returned for each record, separated by spaces.
6401
6402 For any record type, if multiple records are found (or, for A6 lookups, if a
6403 single record leads to multiple addresses), the data is returned as a
6404 concatenation, with newline as the default separator. The order, of course,
6405 depends on the DNS resolver. You can specify a different separator character
6406 between multiple records by putting a right angle-bracket followed immediately
6407 by the new separator at the start of the query. For example:
6408
6409 ${lookup dnsdb{>: a=host1.example}}
6410
6411 It is permitted to specify a space as the separator character. Further white
6412 space is ignored.
6413
6414 For TXT records with multiple items of data, only the first item is returned,
6415 unless a separator for them is specified using a comma after the separator
6416 character followed immediately by the TXT record item separator. To concatenate
6417 items without a separator, use a semicolon instead. For SPF records the default
6418 behaviour is to concatenate multiple items without using a separator.
6419
6420 ${lookup dnsdb{>\n,: txt=a.b.example}}
6421 ${lookup dnsdb{>\n; txt=a.b.example}}
6422 ${lookup dnsdb{spf=example.org}}
6423
6424 It is permitted to specify a space as the separator character. Further white
6425 space is ignored.
6426
6427
6428 9.11 Pseudo dnsdb record types
6429 ------------------------------
6430
6431 By default, both the preference value and the host name are returned for each
6432 MX record, separated by a space. If you want only host names, you can use the
6433 pseudo-type MXH:
6434
6435 ${lookup dnsdb{mxh=a.b.example}}
6436
6437 In this case, the preference values are omitted, and just the host names are
6438 returned.
6439
6440 Another pseudo-type is ZNS (for "zone NS"). It performs a lookup for NS records
6441 on the given domain, but if none are found, it removes the first component of
6442 the domain name, and tries again. This process continues until NS records are
6443 found or there are no more components left (or there is a DNS error). In other
6444 words, it may return the name servers for a top-level domain, but it never
6445 returns the root name servers. If there are no NS records for the top-level
6446 domain, the lookup fails. Consider these examples:
6447
6448 ${lookup dnsdb{zns=xxx.quercite.com}}
6449 ${lookup dnsdb{zns=xxx.edu}}
6450
6451 Assuming that in each case there are no NS records for the full domain name,
6452 the first returns the name servers for quercite.com, and the second returns the
6453 name servers for edu.
6454
6455 You should be careful about how you use this lookup because, unless the
6456 top-level domain does not exist, the lookup always returns some host names. The
6457 sort of use to which this might be put is for seeing if the name servers for a
6458 given domain are on a blacklist. You can probably assume that the name servers
6459 for the high-level domains such as com or co.uk are not going to be on such a
6460 list.
6461
6462 A third pseudo-type is CSA (Client SMTP Authorization). This looks up SRV
6463 records according to the CSA rules, which are described in section 42.50.
6464 Although dnsdb supports SRV lookups directly, this is not sufficient because of
6465 the extra parent domain search behaviour of CSA. The result of a successful
6466 lookup such as:
6467
6468 ${lookup dnsdb {csa=$sender_helo_name}}
6469
6470 has two space-separated fields: an authorization code and a target host name.
6471 The authorization code can be "Y" for yes, "N" for no, "X" for explicit
6472 authorization required but absent, or "?" for unknown.
6473
6474 The pseudo-type A+ performs an A6 lookup (if configured) followed by an AAAA
6475 and then an A lookup. All results are returned; defer processing (see below) is
6476 handled separately for each lookup. Example:
6477
6478 ${lookup dnsdb {>; a+=$sender_helo_name}}
6479
6480
6481 9.12 Multiple dnsdb lookups
6482 ---------------------------
6483
6484 In the previous sections, dnsdb lookups for a single domain are described.
6485 However, you can specify a list of domains or IP addresses in a single dnsdb
6486 lookup. The list is specified in the normal Exim way, with colon as the default
6487 separator, but with the ability to change this. For example:
6488
6489 ${lookup dnsdb{one.domain.com:two.domain.com}}
6490 ${lookup dnsdb{a=one.host.com:two.host.com}}
6491 ${lookup dnsdb{ptr = <; 1.2.3.4 ; 4.5.6.8}}
6492
6493 In order to retain backwards compatibility, there is one special case: if the
6494 lookup type is PTR and no change of separator is specified, Exim looks to see
6495 if the rest of the string is precisely one IPv6 address. In this case, it does
6496 not treat it as a list.
6497
6498 The data from each lookup is concatenated, with newline separators by default,
6499 in the same way that multiple DNS records for a single item are handled. A
6500 different separator can be specified, as described above.
6501
6502 Modifiers for dnsdb lookups are givien by optional keywords, each followed by a
6503 comma, that may appear before the record type.
6504
6505 The dnsdb lookup fails only if all the DNS lookups fail. If there is a
6506 temporary DNS error for any of them, the behaviour is controlled by a
6507 defer-option modifier. The possible keywords are "defer_strict", "defer_never",
6508 and "defer_lax". With "strict" behaviour, any temporary DNS error causes the
6509 whole lookup to defer. With "never" behaviour, a temporary DNS error is
6510 ignored, and the behaviour is as if the DNS lookup failed to find anything.
6511 With "lax" behaviour, all the queries are attempted, but a temporary DNS error
6512 causes the whole lookup to defer only if none of the other lookups succeed. The
6513 default is "lax", so the following lookups are equivalent:
6514
6515 ${lookup dnsdb{defer_lax,a=one.host.com:two.host.com}}
6516 ${lookup dnsdb{a=one.host.com:two.host.com}}
6517
6518 Thus, in the default case, as long as at least one of the DNS lookups yields
6519 some data, the lookup succeeds.
6520
6521 Use of DNSSEC is controlled by a dnssec modifier. The possible keywords are
6522 "dnssec_strict", "dnssec_lax", and "dnssec_never". With "strict" or "lax"
6523 DNSSEC information is requested with the lookup. With "strict" a response from
6524 the DNS resolver that is not labelled as authenticated data is treated as
6525 equivalent to a temporary DNS error. The default is "never".
6526
6527 See also the $lookup_dnssec_authenticated variable.
6528
6529
6530 9.13 More about LDAP
6531 --------------------
6532
6533 The original LDAP implementation came from the University of Michigan; this has
6534 become "Open LDAP", and there are now two different releases. Another
6535 implementation comes from Netscape, and Solaris 7 and subsequent releases
6536 contain inbuilt LDAP support. Unfortunately, though these are all compatible at
6537 the lookup function level, their error handling is different. For this reason
6538 it is necessary to set a compile-time variable when building Exim with LDAP, to
6539 indicate which LDAP library is in use. One of the following should appear in
6540 your Local/Makefile:
6541
6542 LDAP_LIB_TYPE=UMICHIGAN
6543 LDAP_LIB_TYPE=OPENLDAP1
6544 LDAP_LIB_TYPE=OPENLDAP2
6545 LDAP_LIB_TYPE=NETSCAPE
6546 LDAP_LIB_TYPE=SOLARIS
6547
6548 If LDAP_LIB_TYPE is not set, Exim assumes "OPENLDAP1", which has the same
6549 interface as the University of Michigan version.
6550
6551 There are three LDAP lookup types in Exim. These behave slightly differently in
6552 the way they handle the results of a query:
6553
6554 * ldap requires the result to contain just one entry; if there are more, it
6555 gives an error.
6556
6557 * ldapdn also requires the result to contain just one entry, but it is the
6558 Distinguished Name that is returned rather than any attribute values.
6559
6560 * ldapm permits the result to contain more than one entry; the attributes
6561 from all of them are returned.
6562
6563 For ldap and ldapm, if a query finds only entries with no attributes, Exim
6564 behaves as if the entry did not exist, and the lookup fails. The format of the
6565 data returned by a successful lookup is described in the next section. First we
6566 explain how LDAP queries are coded.
6567
6568
6569 9.14 Format of LDAP queries
6570 ---------------------------
6571
6572 An LDAP query takes the form of a URL as defined in RFC 2255. For example, in
6573 the configuration of a redirect router one might have this setting:
6574
6575 data = ${lookup ldap \
6576 {ldap:///cn=$local_part,o=University%20of%20Cambridge,\
6577 c=UK?mailbox?base?}}
6578
6579 The URL may begin with "ldap" or "ldaps" if your LDAP library supports secure
6580 (encrypted) LDAP connections. The second of these ensures that an encrypted TLS
6581 connection is used.
6582
6583 With sufficiently modern LDAP libraries, Exim supports forcing TLS over regular
6584 LDAP connections, rather than the SSL-on-connect "ldaps". See the
6585 ldap_start_tls option.
6586
6587 Starting with Exim 4.83, the initialization of LDAP with TLS is more tightly
6588 controlled. Every part of the TLS configuration can be configured by settings
6589 in exim.conf. Depending on the version of the client libraries installed on
6590 your system, some of the initialization may have required setting options in /
6591 etc/ldap.conf or ~/.ldaprc to get TLS working with self-signed certificates.
6592 This revealed a nuance where the current UID that exim was running as could
6593 affect which config files it read. With Exim 4.83, these methods become
6594 optional, only taking effect if not specifically set in exim.conf.
6595
6596
6597 9.15 LDAP quoting
6598 -----------------
6599
6600 Two levels of quoting are required in LDAP queries, the first for LDAP itself
6601 and the second because the LDAP query is represented as a URL. Furthermore,
6602 within an LDAP query, two different kinds of quoting are required. For this
6603 reason, there are two different LDAP-specific quoting operators.
6604
6605 The quote_ldap operator is designed for use on strings that are part of filter
6606 specifications. Conceptually, it first does the following conversions on the
6607 string:
6608
6609 * => \2A
6610 ( => \28
6611 ) => \29
6612 \ => \5C
6613
6614 in accordance with RFC 2254. The resulting string is then quoted according to
6615 the rules for URLs, that is, all non-alphanumeric characters except
6616
6617 ! $ ' - . _ ( ) * +
6618
6619 are converted to their hex values, preceded by a percent sign. For example:
6620
6621 ${quote_ldap: a(bc)*, a<yz>; }
6622
6623 yields
6624
6625 %20a%5C28bc%5C29%5C2A%2C%20a%3Cyz%3E%3B%20
6626
6627 Removing the URL quoting, this is (with a leading and a trailing space):
6628
6629 a\28bc\29\2A, a<yz>;
6630
6631 The quote_ldap_dn operator is designed for use on strings that are part of base
6632 DN specifications in queries. Conceptually, it first converts the string by
6633 inserting a backslash in front of any of the following characters:
6634
6635 , + " \ < > ;
6636
6637 It also inserts a backslash before any leading spaces or # characters, and
6638 before any trailing spaces. (These rules are in RFC 2253.) The resulting string
6639 is then quoted according to the rules for URLs. For example:
6640
6641 ${quote_ldap_dn: a(bc)*, a<yz>; }
6642
6643 yields
6644
6645 %5C%20a(bc)*%5C%2C%20a%5C%3Cyz%5C%3E%5C%3B%5C%20
6646
6647 Removing the URL quoting, this is (with a trailing space):
6648
6649 \ a(bc)*\, a\<yz\>\;\
6650
6651 There are some further comments about quoting in the section on LDAP
6652 authentication below.
6653
6654
6655 9.16 LDAP connections
6656 ---------------------
6657
6658 The connection to an LDAP server may either be over TCP/IP, or, when OpenLDAP
6659 is in use, via a Unix domain socket. The example given above does not specify
6660 an LDAP server. A server that is reached by TCP/IP can be specified in a query
6661 by starting it with
6662
6663 ldap://<hostname>:<port>/...
6664
6665 If the port (and preceding colon) are omitted, the standard LDAP port (389) is
6666 used. When no server is specified in a query, a list of default servers is
6667 taken from the ldap_default_servers configuration option. This supplies a
6668 colon-separated list of servers which are tried in turn until one successfully
6669 handles a query, or there is a serious error. Successful handling either
6670 returns the requested data, or indicates that it does not exist. Serious errors
6671 are syntactical, or multiple values when only a single value is expected.
6672 Errors which cause the next server to be tried are connection failures, bind
6673 failures, and timeouts.
6674
6675 For each server name in the list, a port number can be given. The standard way
6676 of specifying a host and port is to use a colon separator (RFC 1738). Because
6677 ldap_default_servers is a colon-separated list, such colons have to be doubled.
6678 For example
6679
6680 ldap_default_servers = ldap1.example.com::145:ldap2.example.com
6681
6682 If ldap_default_servers is unset, a URL with no server name is passed to the
6683 LDAP library with no server name, and the library's default (normally the local
6684 host) is used.
6685
6686 If you are using the OpenLDAP library, you can connect to an LDAP server using
6687 a Unix domain socket instead of a TCP/IP connection. This is specified by using
6688 "ldapi" instead of "ldap" in LDAP queries. What follows here applies only to
6689 OpenLDAP. If Exim is compiled with a different LDAP library, this feature is
6690 not available.
6691
6692 For this type of connection, instead of a host name for the server, a pathname
6693 for the socket is required, and the port number is not relevant. The pathname
6694 can be specified either as an item in ldap_default_servers, or inline in the
6695 query. In the former case, you can have settings such as
6696
6697 ldap_default_servers = /tmp/ldap.sock : backup.ldap.your.domain
6698
6699 When the pathname is given in the query, you have to escape the slashes as
6700 "%2F" to fit in with the LDAP URL syntax. For example:
6701
6702 ${lookup ldap {ldapi://%2Ftmp%2Fldap.sock/o=...
6703
6704 When Exim processes an LDAP lookup and finds that the "hostname" is really a
6705 pathname, it uses the Unix domain socket code, even if the query actually
6706 specifies "ldap" or "ldaps". In particular, no encryption is used for a socket
6707 connection. This behaviour means that you can use a setting of
6708 ldap_default_servers such as in the example above with traditional "ldap" or
6709 "ldaps" queries, and it will work. First, Exim tries a connection via the Unix
6710 domain socket; if that fails, it tries a TCP/IP connection to the backup host.
6711
6712 If an explicit "ldapi" type is given in a query when a host name is specified,
6713 an error is diagnosed. However, if there are more items in ldap_default_servers
6714 , they are tried. In other words:
6715
6716 * Using a pathname with "ldap" or "ldaps" forces the use of the Unix domain
6717 interface.
6718
6719 * Using "ldapi" with a host name causes an error.
6720
6721 Using "ldapi" with no host or path in the query, and no setting of
6722 ldap_default_servers, does whatever the library does by default.
6723
6724
6725 9.17 LDAP authentication and control information
6726 ------------------------------------------------
6727
6728 The LDAP URL syntax provides no way of passing authentication and other control
6729 information to the server. To make this possible, the URL in an LDAP query may
6730 be preceded by any number of <name>=<value> settings, separated by spaces. If a
6731 value contains spaces it must be enclosed in double quotes, and when double
6732 quotes are used, backslash is interpreted in the usual way inside them. The
6733 following names are recognized:
6734
6735 DEREFERENCE set the dereferencing parameter
6736 NETTIME set a timeout for a network operation
6737 USER set the DN, for authenticating the LDAP bind
6738 PASS set the password, likewise
6739 REFERRALS set the referrals parameter
6740 SERVERS set alternate server list for this query only
6741 SIZE set the limit for the number of entries returned
6742 TIME set the maximum waiting time for a query
6743
6744 The value of the DEREFERENCE parameter must be one of the words "never",
6745 "searching", "finding", or "always". The value of the REFERRALS parameter must
6746 be "follow" (the default) or "nofollow". The latter stops the LDAP library from
6747 trying to follow referrals issued by the LDAP server.
6748
6749 The name CONNECT is an obsolete name for NETTIME, retained for backwards
6750 compatibility. This timeout (specified as a number of seconds) is enforced from
6751 the client end for operations that can be carried out over a network.
6752 Specifically, it applies to network connections and calls to the ldap_result()
6753 function. If the value is greater than zero, it is used if
6754 LDAP_OPT_NETWORK_TIMEOUT is defined in the LDAP headers (OpenLDAP), or if
6755 LDAP_X_OPT_CONNECT_TIMEOUT is defined in the LDAP headers (Netscape SDK 4.1). A
6756 value of zero forces an explicit setting of "no timeout" for Netscape SDK; for
6757 OpenLDAP no action is taken.
6758
6759 The TIME parameter (also a number of seconds) is passed to the server to set a
6760 server-side limit on the time taken to complete a search.
6761
6762 The SERVERS parameter allows you to specify an alternate list of ldap servers
6763 to use for an individual lookup. The global ldap_servers option provides a
6764 default list of ldap servers, and a single lookup can specify a single ldap
6765 server to use. But when you need to do a lookup with a list of servers that is
6766 different than the default list (maybe different order, maybe a completely
6767 different set of servers), the SERVERS parameter allows you to specify this
6768 alternate list.
6769
6770 Here is an example of an LDAP query in an Exim lookup that uses some of these
6771 values. This is a single line, folded to fit on the page:
6772
6773 ${lookup ldap
6774 {user="cn=manager,o=University of Cambridge,c=UK" pass=secret
6775 ldap:///o=University%20of%20Cambridge,c=UK?sn?sub?(cn=foo)}
6776 {$value}fail}
6777
6778 The encoding of spaces as "%20" is a URL thing which should not be done for any
6779 of the auxiliary data. Exim configuration settings that include lookups which
6780 contain password information should be preceded by "hide" to prevent non-admin
6781 users from using the -bP option to see their values.
6782
6783 The auxiliary data items may be given in any order. The default is no
6784 connection timeout (the system timeout is used), no user or password, no limit
6785 on the number of entries returned, and no time limit on queries.
6786
6787 When a DN is quoted in the USER= setting for LDAP authentication, Exim removes
6788 any URL quoting that it may contain before passing it LDAP. Apparently some
6789 libraries do this for themselves, but some do not. Removing the URL quoting has
6790 two advantages:
6791
6792 * It makes it possible to use the same quote_ldap_dn expansion for USER= DNs
6793 as with DNs inside actual queries.
6794
6795 * It permits spaces inside USER= DNs.
6796
6797 For example, a setting such as
6798
6799 USER=cn=${quote_ldap_dn:$1}
6800
6801 should work even if $1 contains spaces.
6802
6803 Expanded data for the PASS= value should be quoted using the quote expansion
6804 operator, rather than the LDAP quote operators. The only reason this field
6805 needs quoting is to ensure that it conforms to the Exim syntax, which does not
6806 allow unquoted spaces. For example:
6807
6808 PASS=${quote:$3}
6809
6810 The LDAP authentication mechanism can be used to check passwords as part of
6811 SMTP authentication. See the ldapauth expansion string condition in chapter 11.
6812
6813
6814 9.18 Format of data returned by LDAP
6815 ------------------------------------
6816
6817 The ldapdn lookup type returns the Distinguished Name from a single entry as a
6818 sequence of values, for example
6819
6820 cn=manager, o=University of Cambridge, c=UK
6821
6822 The ldap lookup type generates an error if more than one entry matches the
6823 search filter, whereas ldapm permits this case, and inserts a newline in the
6824 result between the data from different entries. It is possible for multiple
6825 values to be returned for both ldap and ldapm, but in the former case you know
6826 that whatever values are returned all came from a single entry in the
6827 directory.
6828
6829 In the common case where you specify a single attribute in your LDAP query, the
6830 result is not quoted, and does not contain the attribute name. If the attribute
6831 has multiple values, they are separated by commas.
6832
6833 If you specify multiple attributes, the result contains space-separated, quoted
6834 strings, each preceded by the attribute name and an equals sign. Within the
6835 quotes, the quote character, backslash, and newline are escaped with
6836 backslashes, and commas are used to separate multiple values for the attribute.
6837 Apart from the escaping, the string within quotes takes the same form as the
6838 output when a single attribute is requested. Specifying no attributes is the
6839 same as specifying all of an entry's attributes.
6840
6841 Here are some examples of the output format. The first line of each pair is an
6842 LDAP query, and the second is the data that is returned. The attribute called
6843 attr1 has two values, whereas attr2 has only one value:
6844
6845 ldap:///o=base?attr1?sub?(uid=fred)
6846 value1.1, value1.2
6847
6848 ldap:///o=base?attr2?sub?(uid=fred)
6849 value two
6850
6851 ldap:///o=base?attr1,attr2?sub?(uid=fred)
6852 attr1="value1.1, value1.2" attr2="value two"
6853
6854 ldap:///o=base??sub?(uid=fred)
6855 objectClass="top" attr1="value1.1, value1.2" attr2="value two"
6856
6857 The extract operator in string expansions can be used to pick out individual
6858 fields from data that consists of key=value pairs. You can make use of Exim's
6859 -be option to run expansion tests and thereby check the results of LDAP
6860 lookups.
6861
6862
6863 9.19 More about NIS+
6864 --------------------
6865
6866 NIS+ queries consist of a NIS+ indexed name followed by an optional colon and
6867 field name. If this is given, the result of a successful query is the contents
6868 of the named field; otherwise the result consists of a concatenation of
6869 field-name=field-value pairs, separated by spaces. Empty values and values
6870 containing spaces are quoted. For example, the query
6871
6872 [name=mg1456],passwd.org_dir
6873
6874 might return the string
6875
6876 name=mg1456 passwd="" uid=999 gid=999 gcos="Martin Guerre"
6877 home=/home/mg1456 shell=/bin/bash shadow=""
6878
6879 (split over two lines here to fit on the page), whereas
6880
6881 [name=mg1456],passwd.org_dir:gcos
6882
6883 would just return
6884
6885 Martin Guerre
6886
6887 with no quotes. A NIS+ lookup fails if NIS+ returns more than one table entry
6888 for the given indexed key. The effect of the quote_nisplus expansion operator
6889 is to double any quote characters within the text.
6890
6891
6892 9.20 SQL lookups
6893 ----------------
6894
6895 Exim can support lookups in InterBase, MySQL, Oracle, PostgreSQL, and SQLite
6896 databases. Queries for these databases contain SQL statements, so an example
6897 might be
6898
6899 ${lookup mysql{select mailbox from users where id='userx'}\
6900 {$value}fail}
6901
6902 If the result of the query contains more than one field, the data for each
6903 field in the row is returned, preceded by its name, so the result of
6904
6905 ${lookup pgsql{select home,name from users where id='userx'}\
6906 {$value}}
6907
6908 might be
6909
6910 home=/home/userx name="Mister X"
6911
6912 Empty values and values containing spaces are double quoted, with embedded
6913 quotes escaped by a backslash. If the result of the query contains just one
6914 field, the value is passed back verbatim, without a field name, for example:
6915
6916 Mister X
6917
6918 If the result of the query yields more than one row, it is all concatenated,
6919 with a newline between the data for each row.
6920
6921
6922 9.21 More about MySQL, PostgreSQL, Oracle, and InterBase
6923 --------------------------------------------------------
6924
6925 If any MySQL, PostgreSQL, Oracle, or InterBase lookups are used, the
6926 mysql_servers, pgsql_servers, oracle_servers, or ibase_servers option (as
6927 appropriate) must be set to a colon-separated list of server information. (For
6928 MySQL and PostgreSQL only, the global option need not be set if all queries
6929 contain their own server information - see section 9.22.) Each item in the list
6930 is a slash-separated list of four items: host name, database name, user name,
6931 and password. In the case of Oracle, the host name field is used for the
6932 "service name", and the database name field is not used and should be empty.
6933 For example:
6934
6935 hide oracle_servers = oracle.plc.example//userx/abcdwxyz
6936
6937 Because password data is sensitive, you should always precede the setting with
6938 "hide", to prevent non-admin users from obtaining the setting via the -bP
6939 option. Here is an example where two MySQL servers are listed:
6940
6941 hide mysql_servers = localhost/users/root/secret:\
6942 otherhost/users/root/othersecret
6943
6944 For MySQL and PostgreSQL, a host may be specified as <name>:<port> but because
6945 this is a colon-separated list, the colon has to be doubled. For each query,
6946 these parameter groups are tried in order until a connection is made and a
6947 query is successfully processed. The result of a query may be that no data is
6948 found, but that is still a successful query. In other words, the list of
6949 servers provides a backup facility, not a list of different places to look.
6950
6951 The quote_mysql, quote_pgsql, and quote_oracle expansion operators convert
6952 newline, tab, carriage return, and backspace to \n, \t, \r, and \b
6953 respectively, and the characters single-quote, double-quote, and backslash
6954 itself are escaped with backslashes. The quote_pgsql expansion operator, in
6955 addition, escapes the percent and underscore characters. This cannot be done
6956 for MySQL because these escapes are not recognized in contexts where these
6957 characters are not special.
6958
6959
6960 9.22 Specifying the server in the query
6961 ---------------------------------------
6962
6963 For MySQL and PostgreSQL lookups (but not currently for Oracle and InterBase),
6964 it is possible to specify a list of servers with an individual query. This is
6965 done by starting the query with
6966
6967 servers=server1:server2:server3:...;
6968
6969 Each item in the list may take one of two forms:
6970
6971 1. If it contains no slashes it is assumed to be just a host name. The
6972 appropriate global option (mysql_servers or pgsql_servers) is searched for
6973 a host of the same name, and the remaining parameters (database, user,
6974 password) are taken from there.
6975
6976 2. If it contains any slashes, it is taken as a complete parameter set.
6977
6978 The list of servers is used in exactly the same way as the global list. Once a
6979 connection to a server has happened and a query has been successfully executed,
6980 processing of the lookup ceases.
6981
6982 This feature is intended for use in master/slave situations where updates are
6983 occurring and you want to update the master rather than a slave. If the master
6984 is in the list as a backup for reading, you might have a global setting like
6985 this:
6986
6987 mysql_servers = slave1/db/name/pw:\
6988 slave2/db/name/pw:\
6989 master/db/name/pw
6990
6991 In an updating lookup, you could then write:
6992
6993 ${lookup mysql{servers=master; UPDATE ...} }
6994
6995 That query would then be sent only to the master server. If, on the other hand,
6996 the master is not to be used for reading, and so is not present in the global
6997 option, you can still update it by a query of this form:
6998
6999 ${lookup pgsql{servers=master/db/name/pw; UPDATE ...} }
7000
7001
7002 9.23 Special MySQL features
7003 ---------------------------
7004
7005 For MySQL, an empty host name or the use of "localhost" in mysql_servers causes
7006 a connection to the server on the local host by means of a Unix domain socket.
7007 An alternate socket can be specified in parentheses. The full syntax of each
7008 item in mysql_servers is:
7009
7010 <hostname>::<port>(<socket name>)/<database>/<user>/<password>
7011
7012 Any of the three sub-parts of the first field can be omitted. For normal use on
7013 the local host it can be left blank or set to just "localhost".
7014
7015 No database need be supplied - but if it is absent here, it must be given in
7016 the queries.
7017
7018 If a MySQL query is issued that does not request any data (an insert, update,
7019 or delete command), the result of the lookup is the number of rows affected.
7020
7021 Warning: This can be misleading. If an update does not actually change anything
7022 (for example, setting a field to the value it already has), the result is zero
7023 because no rows are affected.
7024
7025
7026 9.24 Special PostgreSQL features
7027 --------------------------------
7028
7029 PostgreSQL lookups can also use Unix domain socket connections to the database.
7030 This is usually faster and costs less CPU time than a TCP/IP connection.
7031 However it can be used only if the mail server runs on the same machine as the
7032 database server. A configuration line for PostgreSQL via Unix domain sockets
7033 looks like this:
7034
7035 hide pgsql_servers = (/tmp/.s.PGSQL.5432)/db/user/password : ...
7036
7037 In other words, instead of supplying a host name, a path to the socket is
7038 given. The path name is enclosed in parentheses so that its slashes aren't
7039 visually confused with the delimiters for the other server parameters.
7040
7041 If a PostgreSQL query is issued that does not request any data (an insert,
7042 update, or delete command), the result of the lookup is the number of rows
7043 affected.
7044
7045
7046 9.25 More about SQLite
7047 ----------------------
7048
7049 SQLite is different to the other SQL lookups because a file name is required in
7050 addition to the SQL query. An SQLite database is a single file, and there is no
7051 daemon as in the other SQL databases. The interface to Exim requires the name
7052 of the file, as an absolute path, to be given at the start of the query. It is
7053 separated from the query by white space. This means that the path name cannot
7054 contain white space. Here is a lookup expansion example:
7055
7056 ${lookup sqlite {/some/thing/sqlitedb \
7057 select name from aliases where id='userx';}}
7058
7059 In a list, the syntax is similar. For example:
7060
7061 domainlist relay_to_domains = sqlite;/some/thing/sqlitedb \
7062 select * from relays where ip='$sender_host_address';
7063
7064 The only character affected by the quote_sqlite operator is a single quote,
7065 which it doubles.
7066
7067 The SQLite library handles multiple simultaneous accesses to the database
7068 internally. Multiple readers are permitted, but only one process can update at
7069 once. Attempts to access the database while it is being updated are rejected
7070 after a timeout period, during which the SQLite library waits for the lock to
7071 be released. In Exim, the default timeout is set to 5 seconds, but it can be
7072 changed by means of the sqlite_lock_timeout option.
7073
7074
7075
7076 ===============================================================================
7077 10. DOMAIN, HOST, ADDRESS, AND LOCAL PART LISTS
7078
7079 A number of Exim configuration options contain lists of domains, hosts, email
7080 addresses, or local parts. For example, the hold_domains option contains a list
7081 of domains whose delivery is currently suspended. These lists are also used as
7082 data in ACL statements (see chapter 42), and as arguments to expansion
7083 conditions such as match_domain.
7084
7085 Each item in one of these lists is a pattern to be matched against a domain,
7086 host, email address, or local part, respectively. In the sections below, the
7087 different types of pattern for each case are described, but first we cover some
7088 general facilities that apply to all four kinds of list.
7089
7090
7091 10.1 Expansion of lists
7092 -----------------------
7093
7094 Each list is expanded as a single string before it is used. The result of
7095 expansion must be a list, possibly containing empty items, which is split up
7096 into separate items for matching. By default, colon is the separator character,
7097 but this can be varied if necessary. See sections 6.19 and 6.21 for details of
7098 the list syntax; the second of these discusses the way to specify empty list
7099 items.
7100
7101 If the string expansion is forced to fail, Exim behaves as if the item it is
7102 testing (domain, host, address, or local part) is not in the list. Other
7103 expansion failures cause temporary errors.
7104
7105 If an item in a list is a regular expression, backslashes, dollars and possibly
7106 other special characters in the expression must be protected against
7107 misinterpretation by the string expander. The easiest way to do this is to use
7108 the "\N" expansion feature to indicate that the contents of the regular
7109 expression should not be expanded. For example, in an ACL you might have:
7110
7111 deny senders = \N^\d{8}\w@.*\.baddomain\.example$\N : \
7112 ${lookup{$domain}lsearch{/badsenders/bydomain}}
7113
7114 The first item is a regular expression that is protected from expansion by "\
7115 N", whereas the second uses the expansion to obtain a list of unwanted senders
7116 based on the receiving domain.
7117
7118
7119 10.2 Negated items in lists
7120 ---------------------------
7121
7122 Items in a list may be positive or negative. Negative items are indicated by a
7123 leading exclamation mark, which may be followed by optional white space. A list
7124 defines a set of items (domains, etc). When Exim processes one of these lists,
7125 it is trying to find out whether a domain, host, address, or local part
7126 (respectively) is in the set that is defined by the list. It works like this:
7127
7128 The list is scanned from left to right. If a positive item is matched, the
7129 subject that is being checked is in the set; if a negative item is matched, the
7130 subject is not in the set. If the end of the list is reached without the
7131 subject having matched any of the patterns, it is in the set if the last item
7132 was a negative one, but not if it was a positive one. For example, the list in
7133
7134 domainlist relay_to_domains = !a.b.c : *.b.c
7135
7136 matches any domain ending in .b.c except for a.b.c. Domains that match neither
7137 a.b.c nor *.b.c do not match, because the last item in the list is positive.
7138 However, if the setting were
7139
7140 domainlist relay_to_domains = !a.b.c
7141
7142 then all domains other than a.b.c would match because the last item in the list
7143 is negative. In other words, a list that ends with a negative item behaves as
7144 if it had an extra item ":*" on the end.
7145
7146 Another way of thinking about positive and negative items in lists is to read
7147 the connector as "or" after a positive item and as "and" after a negative item.
7148
7149
7150 10.3 File names in lists
7151 ------------------------
7152
7153 If an item in a domain, host, address, or local part list is an absolute file
7154 name (beginning with a slash character), each line of the file is read and
7155 processed as if it were an independent item in the list, except that further
7156 file names are not allowed, and no expansion of the data from the file takes
7157 place. Empty lines in the file are ignored, and the file may also contain
7158 comment lines:
7159
7160 * For domain and host lists, if a # character appears anywhere in a line of
7161 the file, it and all following characters are ignored.
7162
7163 * Because local parts may legitimately contain # characters, a comment in an
7164 address list or local part list file is recognized only if # is preceded by
7165 white space or the start of the line. For example:
7166
7167 not#comment@x.y.z # but this is a comment
7168
7169 Putting a file name in a list has the same effect as inserting each line of the
7170 file as an item in the list (blank lines and comments excepted). However, there
7171 is one important difference: the file is read each time the list is processed,
7172 so if its contents vary over time, Exim's behaviour changes.
7173
7174 If a file name is preceded by an exclamation mark, the sense of any match
7175 within the file is inverted. For example, if
7176
7177 hold_domains = !/etc/nohold-domains
7178
7179 and the file contains the lines
7180
7181 !a.b.c
7182 *.b.c
7183
7184 then a.b.c is in the set of domains defined by hold_domains, whereas any domain
7185 matching "*.b.c" is not.
7186
7187
7188 10.4 An lsearch file is not an out-of-line list
7189 -----------------------------------------------
7190
7191 As will be described in the sections that follow, lookups can be used in lists
7192 to provide indexed methods of checking list membership. There has been some
7193 confusion about the way lsearch lookups work in lists. Because an lsearch file
7194 contains plain text and is scanned sequentially, it is sometimes thought that
7195 it is allowed to contain wild cards and other kinds of non-constant pattern.
7196 This is not the case. The keys in an lsearch file are always fixed strings,
7197 just as for any other single-key lookup type.
7198
7199 If you want to use a file to contain wild-card patterns that form part of a
7200 list, just give the file name on its own, without a search type, as described
7201 in the previous section. You could also use the wildlsearch or nwildlsearch,
7202 but there is no advantage in doing this.
7203
7204
7205 10.5 Named lists
7206 ----------------
7207
7208 A list of domains, hosts, email addresses, or local parts can be given a name
7209 which is then used to refer to the list elsewhere in the configuration. This is
7210 particularly convenient if the same list is required in several different
7211 places. It also allows lists to be given meaningful names, which can improve
7212 the readability of the configuration. For example, it is conventional to define
7213 a domain list called local_domains for all the domains that are handled locally
7214 on a host, using a configuration line such as
7215
7216 domainlist local_domains = localhost:my.dom.example
7217
7218 Named lists are referenced by giving their name preceded by a plus sign, so,
7219 for example, a router that is intended to handle local domains would be
7220 configured with the line
7221
7222 domains = +local_domains
7223
7224 The first router in a configuration is often one that handles all domains
7225 except the local ones, using a configuration with a negated item like this:
7226
7227 dnslookup:
7228 driver = dnslookup
7229 domains = ! +local_domains
7230 transport = remote_smtp
7231 no_more
7232
7233 The four kinds of named list are created by configuration lines starting with
7234 the words domainlist, hostlist, addresslist, or localpartlist, respectively.
7235 Then there follows the name that you are defining, followed by an equals sign
7236 and the list itself. For example:
7237
7238 hostlist relay_from_hosts = 192.168.23.0/24 : my.friend.example
7239 addresslist bad_senders = cdb;/etc/badsenders
7240
7241 A named list may refer to other named lists:
7242
7243 domainlist dom1 = first.example : second.example
7244 domainlist dom2 = +dom1 : third.example
7245 domainlist dom3 = fourth.example : +dom2 : fifth.example
7246
7247 Warning: If the last item in a referenced list is a negative one, the effect
7248 may not be what you intended, because the negation does not propagate out to
7249 the higher level. For example, consider:
7250
7251 domainlist dom1 = !a.b
7252 domainlist dom2 = +dom1 : *.b
7253
7254 The second list specifies "either in the dom1 list or *.b". The first list
7255 specifies just "not a.b", so the domain x.y matches it. That means it matches
7256 the second list as well. The effect is not the same as
7257
7258 domainlist dom2 = !a.b : *.b
7259
7260 where x.y does not match. It's best to avoid negation altogether in referenced
7261 lists if you can.
7262
7263 Named lists may have a performance advantage. When Exim is routing an address
7264 or checking an incoming message, it caches the result of tests on named lists.
7265 So, if you have a setting such as
7266
7267 domains = +local_domains
7268
7269 on several of your routers or in several ACL statements, the actual test is
7270 done only for the first one. However, the caching works only if there are no
7271 expansions within the list itself or any sublists that it references. In other
7272 words, caching happens only for lists that are known to be the same each time
7273 they are referenced.
7274
7275 By default, there may be up to 16 named lists of each type. This limit can be
7276 extended by changing a compile-time variable. The use of domain and host lists
7277 is recommended for concepts such as local domains, relay domains, and relay
7278 hosts. The default configuration is set up like this.
7279
7280
7281 10.6 Named lists compared with macros
7282 -------------------------------------
7283
7284 At first sight, named lists might seem to be no different from macros in the
7285 configuration file. However, macros are just textual substitutions. If you
7286 write
7287
7288 ALIST = host1 : host2
7289 auth_advertise_hosts = !ALIST
7290
7291 it probably won't do what you want, because that is exactly the same as
7292
7293 auth_advertise_hosts = !host1 : host2
7294
7295 Notice that the second host name is not negated. However, if you use a host
7296 list, and write
7297
7298 hostlist alist = host1 : host2
7299 auth_advertise_hosts = ! +alist
7300
7301 the negation applies to the whole list, and so that is equivalent to
7302
7303 auth_advertise_hosts = !host1 : !host2
7304
7305
7306 10.7 Named list caching
7307 -----------------------
7308
7309 While processing a message, Exim caches the result of checking a named list if
7310 it is sure that the list is the same each time. In practice, this means that
7311 the cache operates only if the list contains no $ characters, which guarantees
7312 that it will not change when it is expanded. Sometimes, however, you may have
7313 an expanded list that you know will be the same each time within a given
7314 message. For example:
7315
7316 domainlist special_domains = \
7317 ${lookup{$sender_host_address}cdb{/some/file}}
7318
7319 This provides a list of domains that depends only on the sending host's IP
7320 address. If this domain list is referenced a number of times (for example, in
7321 several ACL lines, or in several routers) the result of the check is not cached
7322 by default, because Exim does not know that it is going to be the same list
7323 each time.
7324
7325 By appending "_cache" to "domainlist" you can tell Exim to go ahead and cache
7326 the result anyway. For example:
7327
7328 domainlist_cache special_domains = ${lookup{...
7329
7330 If you do this, you should be absolutely sure that caching is going to do the
7331 right thing in all cases. When in doubt, leave it out.
7332
7333
7334 10.8 Domain lists
7335 -----------------
7336
7337 Domain lists contain patterns that are to be matched against a mail domain. The
7338 following types of item may appear in domain lists:
7339
7340 * If a pattern consists of a single @ character, it matches the local host
7341 name, as set by the primary_hostname option (or defaulted). This makes it
7342 possible to use the same configuration file on several different hosts that
7343 differ only in their names.
7344
7345 * If a pattern consists of the string "@[]" it matches an IP address enclosed
7346 in square brackets (as in an email address that contains a domain literal),
7347 but only if that IP address is recognized as local for email routing
7348 purposes. The local_interfaces and extra_local_interfaces options can be
7349 used to control which of a host's several IP addresses are treated as
7350 local. In today's Internet, the use of domain literals is controversial.
7351
7352 * If a pattern consists of the string "@mx_any" it matches any domain that
7353 has an MX record pointing to the local host or to any host that is listed
7354 in hosts_treat_as_local. The items "@mx_primary" and "@mx_secondary" are
7355 similar, except that the first matches only when a primary MX target is the
7356 local host, and the second only when no primary MX target is the local
7357 host, but a secondary MX target is. "Primary" means an MX record with the
7358 lowest preference value - there may of course be more than one of them.
7359
7360 The MX lookup that takes place when matching a pattern of this type is
7361 performed with the resolver options for widening names turned off. Thus,
7362 for example, a single-component domain will not be expanded by adding the
7363 resolver's default domain. See the qualify_single and search_parents
7364 options of the dnslookup router for a discussion of domain widening.
7365
7366 Sometimes you may want to ignore certain IP addresses when using one of
7367 these patterns. You can specify this by following the pattern with "/ignore
7368 ="<ip list>, where <ip list> is a list of IP addresses. These addresses are
7369 ignored when processing the pattern (compare the ignore_target_hosts option
7370 on a router). For example:
7371
7372 domains = @mx_any/ignore=127.0.0.1
7373
7374 This example matches any domain that has an MX record pointing to one of
7375 the local host's IP addresses other than 127.0.0.1.
7376
7377 The list of IP addresses is in fact processed by the same code that
7378 processes host lists, so it may contain CIDR-coded network specifications
7379 and it may also contain negative items.
7380
7381 Because the list of IP addresses is a sublist within a domain list, you
7382 have to be careful about delimiters if there is more than one address. Like
7383 any other list, the default delimiter can be changed. Thus, you might have:
7384
7385 domains = @mx_any/ignore=<;127.0.0.1;0.0.0.0 : \
7386 an.other.domain : ...
7387
7388 so that the sublist uses semicolons for delimiters. When IPv6 addresses are
7389 involved, it is easiest to change the delimiter for the main list as well:
7390
7391 domains = <? @mx_any/ignore=<;127.0.0.1;::1 ? \
7392 an.other.domain ? ...
7393
7394 * If a pattern starts with an asterisk, the remaining characters of the
7395 pattern are compared with the terminating characters of the domain. The use
7396 of "*" in domain lists differs from its use in partial matching lookups. In
7397 a domain list, the character following the asterisk need not be a dot,
7398 whereas partial matching works only in terms of dot-separated components.
7399 For example, a domain list item such as "*key.ex" matches donkey.ex as well
7400 as cipher.key.ex.
7401
7402 * If a pattern starts with a circumflex character, it is treated as a regular
7403 expression, and matched against the domain using a regular expression
7404 matching function. The circumflex is treated as part of the regular
7405 expression. Email domains are case-independent, so this regular expression
7406 match is by default case-independent, but you can make it case-dependent by
7407 starting it with "(?-i)". References to descriptions of the syntax of
7408 regular expressions are given in chapter 8.
7409
7410 Warning: Because domain lists are expanded before being processed, you must
7411 escape any backslash and dollar characters in the regular expression, or
7412 use the special "\N" sequence (see chapter 11) to specify that it is not to
7413 be expanded (unless you really do want to build a regular expression by
7414 expansion, of course).
7415
7416 * If a pattern starts with the name of a single-key lookup type followed by a
7417 semicolon (for example, "dbm;" or "lsearch;"), the remainder of the pattern
7418 must be a file name in a suitable format for the lookup type. For example,
7419 for "cdb;" it must be an absolute path:
7420
7421 domains = cdb;/etc/mail/local_domains.cdb
7422
7423 The appropriate type of lookup is done on the file using the domain name as
7424 the key. In most cases, the data that is looked up is not used; Exim is
7425 interested only in whether or not the key is present in the file. However,
7426 when a lookup is used for the domains option on a router or a domains
7427 condition in an ACL statement, the data is preserved in the $domain_data
7428 variable and can be referred to in other router options or other statements
7429 in the same ACL.
7430
7431 * Any of the single-key lookup type names may be preceded by "partial"<n>"-",
7432 where the <n> is optional, for example,
7433
7434 domains = partial-dbm;/partial/domains
7435
7436 This causes partial matching logic to be invoked; a description of how this
7437 works is given in section 9.7.
7438
7439 * Any of the single-key lookup types may be followed by an asterisk. This
7440 causes a default lookup for a key consisting of a single asterisk to be
7441 done if the original lookup fails. This is not a useful feature when using
7442 a domain list to select particular domains (because any domain would
7443 match), but it might have value if the result of the lookup is being used
7444 via the $domain_data expansion variable.
7445
7446 * If the pattern starts with the name of a query-style lookup type followed
7447 by a semicolon (for example, "nisplus;" or "ldap;"), the remainder of the
7448 pattern must be an appropriate query for the lookup type, as described in
7449 chapter 9. For example:
7450
7451 hold_domains = mysql;select domain from holdlist \
7452 where domain = '${quote_mysql:$domain}';
7453
7454 In most cases, the data that is looked up is not used (so for an SQL query,
7455 for example, it doesn't matter what field you select). Exim is interested
7456 only in whether or not the query succeeds. However, when a lookup is used
7457 for the domains option on a router, the data is preserved in the
7458 $domain_data variable and can be referred to in other options.
7459
7460 * If none of the above cases apply, a caseless textual comparison is made
7461 between the pattern and the domain.
7462
7463 Here is an example that uses several different kinds of pattern:
7464
7465 domainlist funny_domains = \
7466 @ : \
7467 lib.unseen.edu : \
7468 *.foundation.fict.example : \
7469 \N^[1-2]\d{3}\.fict\.example$\N : \
7470 partial-dbm;/opt/data/penguin/book : \
7471 nis;domains.byname : \
7472 nisplus;[name=$domain,status=local],domains.org_dir
7473
7474 There are obvious processing trade-offs among the various matching modes. Using
7475 an asterisk is faster than a regular expression, and listing a few names
7476 explicitly probably is too. The use of a file or database lookup is expensive,
7477 but may be the only option if hundreds of names are required. Because the
7478 patterns are tested in order, it makes sense to put the most commonly matched
7479 patterns earlier.
7480
7481
7482 10.9 Host lists
7483 ---------------
7484
7485 Host lists are used to control what remote hosts are allowed to do. For
7486 example, some hosts may be allowed to use the local host as a relay, and some
7487 may be permitted to use the SMTP ETRN command. Hosts can be identified in two
7488 different ways, by name or by IP address. In a host list, some types of pattern
7489 are matched to a host name, and some are matched to an IP address. You need to
7490 be particularly careful with this when single-key lookups are involved, to
7491 ensure that the right value is being used as the key.
7492
7493
7494 10.10 Special host list patterns
7495 --------------------------------
7496
7497 If a host list item is the empty string, it matches only when no remote host is
7498 involved. This is the case when a message is being received from a local
7499 process using SMTP on the standard input, that is, when a TCP/IP connection is
7500 not used.
7501
7502 The special pattern "*" in a host list matches any host or no host. Neither the
7503 IP address nor the name is actually inspected.
7504
7505
7506 10.11 Host list patterns that match by IP address
7507 -------------------------------------------------
7508
7509 If an IPv4 host calls an IPv6 host and the call is accepted on an IPv6 socket,
7510 the incoming address actually appears in the IPv6 host as "::ffff:"<v4address>.
7511 When such an address is tested against a host list, it is converted into a
7512 traditional IPv4 address first. (Not all operating systems accept IPv4 calls on
7513 IPv6 sockets, as there have been some security concerns.)
7514
7515 The following types of pattern in a host list check the remote host by
7516 inspecting its IP address:
7517
7518 * If the pattern is a plain domain name (not a regular expression, not
7519 starting with *, not a lookup of any kind), Exim calls the operating system
7520 function to find the associated IP address(es). Exim uses the newer
7521 getipnodebyname() function when available, otherwise gethostbyname(). This
7522 typically causes a forward DNS lookup of the name. The result is compared
7523 with the IP address of the subject host.
7524
7525 If there is a temporary problem (such as a DNS timeout) with the host name
7526 lookup, a temporary error occurs. For example, if the list is being used in
7527 an ACL condition, the ACL gives a "defer" response, usually leading to a
7528 temporary SMTP error code. If no IP address can be found for the host name,
7529 what happens is described in section 10.14 below.
7530
7531 * If the pattern is "@", the primary host name is substituted and used as a
7532 domain name, as just described.
7533
7534 * If the pattern is an IP address, it is matched against the IP address of
7535 the subject host. IPv4 addresses are given in the normal "dotted-quad"
7536 notation. IPv6 addresses can be given in colon-separated format, but the
7537 colons have to be doubled so as not to be taken as item separators when the
7538 default list separator is used. IPv6 addresses are recognized even when
7539 Exim is compiled without IPv6 support. This means that if they appear in a
7540 host list on an IPv4-only host, Exim will not treat them as host names.
7541 They are just addresses that can never match a client host.
7542
7543 * If the pattern is "@[]", it matches the IP address of any IP interface on
7544 the local host. For example, if the local host is an IPv4 host with one
7545 interface address 10.45.23.56, these two ACL statements have the same
7546 effect:
7547
7548 accept hosts = 127.0.0.1 : 10.45.23.56
7549 accept hosts = @[]
7550
7551 * If the pattern is an IP address followed by a slash and a mask length (for
7552 example 10.11.42.0/24), it is matched against the IP address of the subject
7553 host under the given mask. This allows, an entire network of hosts to be
7554 included (or excluded) by a single item. The mask uses CIDR notation; it
7555 specifies the number of address bits that must match, starting from the
7556 most significant end of the address.
7557
7558 Note: The mask is not a count of addresses, nor is it the high number of a
7559 range of addresses. It is the number of bits in the network portion of the
7560 address. The above example specifies a 24-bit netmask, so it matches all
7561 256 addresses in the 10.11.42.0 network. An item such as
7562
7563 192.168.23.236/31
7564
7565 matches just two addresses, 192.168.23.236 and 192.168.23.237. A mask value
7566 of 32 for an IPv4 address is the same as no mask at all; just a single
7567 address matches.
7568
7569 Here is another example which shows an IPv4 and an IPv6 network:
7570
7571 recipient_unqualified_hosts = 192.168.0.0/16: \
7572 3ffe::ffff::836f::::/48
7573
7574 The doubling of list separator characters applies only when these items
7575 appear inline in a host list. It is not required when indirecting via a
7576 file. For example:
7577
7578 recipient_unqualified_hosts = /opt/exim/unqualnets
7579
7580 could make use of a file containing
7581
7582 172.16.0.0/12
7583 3ffe:ffff:836f::/48
7584
7585 to have exactly the same effect as the previous example. When listing IPv6
7586 addresses inline, it is usually more convenient to use the facility for
7587 changing separator characters. This list contains the same two networks:
7588
7589 recipient_unqualified_hosts = <; 172.16.0.0/12; \
7590 3ffe:ffff:836f::/48
7591
7592 The separator is changed to semicolon by the leading "<;" at the start of
7593 the list.
7594
7595
7596 10.12 Host list patterns for single-key lookups by host address
7597 ---------------------------------------------------------------
7598
7599 When a host is to be identified by a single-key lookup of its complete IP
7600 address, the pattern takes this form:
7601
7602 net-<single-key-search-type>;<search-data>
7603
7604 For example:
7605
7606 hosts_lookup = net-cdb;/hosts-by-ip.db
7607
7608 The text form of the IP address of the subject host is used as the lookup key.
7609 IPv6 addresses are converted to an unabbreviated form, using lower case
7610 letters, with dots as separators because colon is the key terminator in lsearch
7611 files. [Colons can in fact be used in keys in lsearch files by quoting the
7612 keys, but this is a facility that was added later.] The data returned by the
7613 lookup is not used.
7614
7615 Single-key lookups can also be performed using masked IP addresses, using
7616 patterns of this form:
7617
7618 net<number>-<single-key-search-type>;<search-data>
7619
7620 For example:
7621
7622 net24-dbm;/networks.db
7623
7624 The IP address of the subject host is masked using <number> as the mask length.
7625 A textual string is constructed from the masked value, followed by the mask,
7626 and this is used as the lookup key. For example, if the host's IP address is
7627 192.168.34.6, the key that is looked up for the above example is "192.168.34.0/
7628 24".
7629
7630 When an IPv6 address is converted to a string, dots are normally used instead
7631 of colons, so that keys in lsearch files need not contain colons (which
7632 terminate lsearch keys). This was implemented some time before the ability to
7633 quote keys was made available in lsearch files. However, the more recently
7634 implemented iplsearch files do require colons in IPv6 keys (notated using the
7635 quoting facility) so as to distinguish them from IPv4 keys. For this reason,
7636 when the lookup type is iplsearch, IPv6 addresses are converted using colons
7637 and not dots. In all cases, full, unabbreviated IPv6 addresses are always used.
7638
7639 Ideally, it would be nice to tidy up this anomalous situation by changing to
7640 colons in all cases, given that quoting is now available for lsearch. However,
7641 this would be an incompatible change that might break some existing
7642 configurations.
7643
7644 Warning: Specifying net32- (for an IPv4 address) or net128- (for an IPv6
7645 address) is not the same as specifying just net- without a number. In the
7646 former case the key strings include the mask value, whereas in the latter case
7647 the IP address is used on its own.
7648
7649
7650 10.13 Host list patterns that match by host name
7651 ------------------------------------------------
7652
7653 There are several types of pattern that require Exim to know the name of the
7654 remote host. These are either wildcard patterns or lookups by name. (If a
7655 complete hostname is given without any wildcarding, it is used to find an IP
7656 address to match against, as described in section 10.11 above.)
7657
7658 If the remote host name is not already known when Exim encounters one of these
7659 patterns, it has to be found from the IP address. Although many sites on the
7660 Internet are conscientious about maintaining reverse DNS data for their hosts,
7661 there are also many that do not do this. Consequently, a name cannot always be
7662 found, and this may lead to unwanted effects. Take care when configuring host
7663 lists with wildcarded name patterns. Consider what will happen if a name cannot
7664 be found.
7665
7666 Because of the problems of determining host names from IP addresses, matching
7667 against host names is not as common as matching against IP addresses.
7668
7669 By default, in order to find a host name, Exim first does a reverse DNS lookup;
7670 if no name is found in the DNS, the system function (gethostbyaddr() or
7671 getipnodebyaddr() if available) is tried. The order in which these lookups are
7672 done can be changed by setting the host_lookup_order option. For security, once
7673 Exim has found one or more names, it looks up the IP addresses for these names
7674 and compares them with the IP address that it started with. Only those names
7675 whose IP addresses match are accepted. Any other names are discarded. If no
7676 names are left, Exim behaves as if the host name cannot be found. In the most
7677 common case there is only one name and one IP address.
7678
7679 There are some options that control what happens if a host name cannot be
7680 found. These are described in section 10.14 below.
7681
7682 As a result of aliasing, hosts may have more than one name. When processing any
7683 of the following types of pattern, all the host's names are checked:
7684
7685 * If a pattern starts with "*" the remainder of the item must match the end
7686 of the host name. For example, "*.b.c" matches all hosts whose names end in
7687 .b.c. This special simple form is provided because this is a very common
7688 requirement. Other kinds of wildcarding require the use of a regular
7689 expression.
7690
7691 * If the item starts with "^" it is taken to be a regular expression which is
7692 matched against the host name. Host names are case-independent, so this
7693 regular expression match is by default case-independent, but you can make
7694 it case-dependent by starting it with "(?-i)". References to descriptions
7695 of the syntax of regular expressions are given in chapter 8. For example,
7696
7697 ^(a|b)\.c\.d$
7698
7699 is a regular expression that matches either of the two hosts a.c.d or b.c.d
7700 . When a regular expression is used in a host list, you must take care that
7701 backslash and dollar characters are not misinterpreted as part of the
7702 string expansion. The simplest way to do this is to use "\N" to mark that
7703 part of the string as non-expandable. For example:
7704
7705 sender_unqualified_hosts = \N^(a|b)\.c\.d$\N : ....
7706
7707 Warning: If you want to match a complete host name, you must include the
7708 "$" terminating metacharacter in the regular expression, as in the above
7709 example. Without it, a match at the start of the host name is all that is
7710 required.
7711
7712
7713 10.14 Behaviour when an IP address or name cannot be found
7714 ----------------------------------------------------------
7715
7716 While processing a host list, Exim may need to look up an IP address from a
7717 name (see section 10.11), or it may need to look up a host name from an IP
7718 address (see section 10.13). In either case, the behaviour when it fails to
7719 find the information it is seeking is the same.
7720
7721 Note: This section applies to permanent lookup failures. It does not apply to
7722 temporary DNS errors, whose handling is described in the next section.
7723
7724 Exim parses a host list from left to right. If it encounters a permanent lookup
7725 failure in any item in the host list before it has found a match, Exim treats
7726 it as a failure and the default behavior is as if the host does not match the
7727 list. This may not always be what you want to happen. To change Exim's
7728 behaviour, the special items "+include_unknown" or "+ignore_unknown" may appear
7729 in the list (at top level - they are not recognized in an indirected file).
7730
7731 * If any item that follows "+include_unknown" requires information that
7732 cannot found, Exim behaves as if the host does match the list. For example,
7733
7734 host_reject_connection = +include_unknown:*.enemy.ex
7735
7736 rejects connections from any host whose name matches "*.enemy.ex", and also
7737 any hosts whose name it cannot find.
7738
7739 * If any item that follows "+ignore_unknown" requires information that cannot
7740 be found, Exim ignores that item and proceeds to the rest of the list. For
7741 example:
7742
7743 accept hosts = +ignore_unknown : friend.example : \
7744 192.168.4.5
7745
7746 accepts from any host whose name is friend.example and from 192.168.4.5,
7747 whether or not its host name can be found. Without "+ignore_unknown", if no
7748 name can be found for 192.168.4.5, it is rejected.
7749
7750 Both "+include_unknown" and "+ignore_unknown" may appear in the same list. The
7751 effect of each one lasts until the next, or until the end of the list.
7752
7753
7754 10.15 Mixing wildcarded host names and addresses in host lists
7755 --------------------------------------------------------------
7756
7757 This section explains the host/ip processing logic with the same concepts as
7758 the previous section, but specifically addresses what happens when a wildcarded
7759 hostname is one of the items in the hostlist.
7760
7761 * If you have name lookups or wildcarded host names and IP addresses in the
7762 same host list, you should normally put the IP addresses first. For
7763 example, in an ACL you could have:
7764
7765 accept hosts = 10.9.8.7 : *.friend.example
7766
7767 The reason you normally would order it this way lies in the left-to-right
7768 way that Exim processes lists. It can test IP addresses without doing any
7769 DNS lookups, but when it reaches an item that requires a host name, it
7770 fails if it cannot find a host name to compare with the pattern. If the
7771 above list is given in the opposite order, the accept statement fails for a
7772 host whose name cannot be found, even if its IP address is 10.9.8.7.
7773
7774 * If you really do want to do the name check first, and still recognize the
7775 IP address, you can rewrite the ACL like this:
7776
7777 accept hosts = *.friend.example
7778 accept hosts = 10.9.8.7
7779
7780 If the first accept fails, Exim goes on to try the second one. See chapter
7781 42 for details of ACLs. Alternatively, you can use "+ignore_unknown", which
7782 was discussed in depth in the first example in this section.
7783
7784
7785 10.16 Temporary DNS errors when looking up host information
7786 -----------------------------------------------------------
7787
7788 A temporary DNS lookup failure normally causes a defer action (except when
7789 dns_again_means_nonexist converts it into a permanent error). However, host
7790 lists can include "+ignore_defer" and "+include_defer", analagous to
7791 "+ignore_unknown" and "+include_unknown", as described in the previous section.
7792 These options should be used with care, probably only in non-critical host
7793 lists such as whitelists.
7794
7795
7796 10.17 Host list patterns for single-key lookups by host name
7797 ------------------------------------------------------------
7798
7799 If a pattern is of the form
7800
7801 <single-key-search-type>;<search-data>
7802
7803 for example
7804
7805 dbm;/host/accept/list
7806
7807 a single-key lookup is performed, using the host name as its key. If the lookup
7808 succeeds, the host matches the item. The actual data that is looked up is not
7809 used.
7810
7811 Reminder: With this kind of pattern, you must have host names as keys in the
7812 file, not IP addresses. If you want to do lookups based on IP addresses, you
7813 must precede the search type with "net-" (see section 10.12). There is,
7814 however, no reason why you could not use two items in the same list, one doing
7815 an address lookup and one doing a name lookup, both using the same file.
7816
7817
7818 10.18 Host list patterns for query-style lookups
7819 ------------------------------------------------
7820
7821 If a pattern is of the form
7822
7823 <query-style-search-type>;<query>
7824
7825 the query is obeyed, and if it succeeds, the host matches the item. The actual
7826 data that is looked up is not used. The variables $sender_host_address and
7827 $sender_host_name can be used in the query. For example:
7828
7829 hosts_lookup = pgsql;\
7830 select ip from hostlist where ip='$sender_host_address'
7831
7832 The value of $sender_host_address for an IPv6 address contains colons. You can
7833 use the sg expansion item to change this if you need to. If you want to use
7834 masked IP addresses in database queries, you can use the mask expansion
7835 operator.
7836
7837 If the query contains a reference to $sender_host_name, Exim automatically
7838 looks up the host name if it has not already done so. (See section 10.13 for
7839 comments on finding host names.)
7840
7841 Historical note: prior to release 4.30, Exim would always attempt to find a
7842 host name before running the query, unless the search type was preceded by
7843 "net-". This is no longer the case. For backwards compatibility, "net-" is
7844 still recognized for query-style lookups, but its presence or absence has no
7845 effect. (Of course, for single-key lookups, "net-" is important. See section
7846 10.12.)
7847
7848
7849 10.19 Address lists
7850 -------------------
7851
7852 Address lists contain patterns that are matched against mail addresses. There
7853 is one special case to be considered: the sender address of a bounce message is
7854 always empty. You can test for this by providing an empty item in an address
7855 list. For example, you can set up a router to process bounce messages by using
7856 this option setting:
7857
7858 senders = :
7859
7860 The presence of the colon creates an empty item. If you do not provide any
7861 data, the list is empty and matches nothing. The empty sender can also be
7862 detected by a regular expression that matches an empty string, and by a
7863 query-style lookup that succeeds when $sender_address is empty.
7864
7865 Non-empty items in an address list can be straightforward email addresses. For
7866 example:
7867
7868 senders = jbc@askone.example : hs@anacreon.example
7869
7870 A certain amount of wildcarding is permitted. If a pattern contains an @
7871 character, but is not a regular expression and does not begin with a
7872 semicolon-terminated lookup type (described below), the local part of the
7873 subject address is compared with the local part of the pattern, which may start
7874 with an asterisk. If the local parts match, the domain is checked in exactly
7875 the same way as for a pattern in a domain list. For example, the domain can be
7876 wildcarded, refer to a named list, or be a lookup:
7877
7878 deny senders = *@*.spamming.site:\
7879 *@+hostile_domains:\
7880 bozo@partial-lsearch;/list/of/dodgy/sites:\
7881 *@dbm;/bad/domains.db
7882
7883 If a local part that begins with an exclamation mark is required, it has to be
7884 specified using a regular expression, because otherwise the exclamation mark is
7885 treated as a sign of negation, as is standard in lists.
7886
7887 If a non-empty pattern that is not a regular expression or a lookup does not
7888 contain an @ character, it is matched against the domain part of the subject
7889 address. The only two formats that are recognized this way are a literal
7890 domain, or a domain pattern that starts with *. In both these cases, the effect
7891 is the same as if "*@" preceded the pattern. For example:
7892
7893 deny senders = enemy.domain : *.enemy.domain
7894
7895 The following kinds of more complicated address list pattern can match any
7896 address, including the empty address that is characteristic of bounce message
7897 senders:
7898
7899 * If (after expansion) a pattern starts with "^", a regular expression match
7900 is done against the complete address, with the pattern as the regular
7901 expression. You must take care that backslash and dollar characters are not
7902 misinterpreted as part of the string expansion. The simplest way to do this
7903 is to use "\N" to mark that part of the string as non-expandable. For
7904 example:
7905
7906 deny senders = \N^.*this.*@example\.com$\N : \
7907 \N^\d{8}.+@spamhaus.example$\N : ...
7908
7909 The "\N" sequences are removed by the expansion, so these items do indeed
7910 start with "^" by the time they are being interpreted as address patterns.
7911
7912 * Complete addresses can be looked up by using a pattern that starts with a
7913 lookup type terminated by a semicolon, followed by the data for the lookup.
7914 For example:
7915
7916 deny senders = cdb;/etc/blocked.senders : \
7917 mysql;select address from blocked where \
7918 address='${quote_mysql:$sender_address}'
7919
7920 Both query-style and single-key lookup types can be used. For a single-key
7921 lookup type, Exim uses the complete address as the key. However, empty keys
7922 are not supported for single-key lookups, so a match against the empty
7923 address always fails. This restriction does not apply to query-style
7924 lookups.
7925
7926 Partial matching for single-key lookups (section 9.7) cannot be used, and
7927 is ignored if specified, with an entry being written to the panic log.
7928 However, you can configure lookup defaults, as described in section 9.6,
7929 but this is useful only for the "*@" type of default. For example, with
7930 this lookup:
7931
7932 accept senders = lsearch*@;/some/file
7933
7934 the file could contains lines like this:
7935
7936 user1@domain1.example
7937 *@domain2.example
7938
7939 and for the sender address nimrod@jaeger.example, the sequence of keys that
7940 are tried is:
7941
7942 nimrod@jaeger.example
7943 *@jaeger.example
7944 *
7945
7946 Warning 1: Do not include a line keyed by "*" in the file, because that
7947 would mean that every address matches, thus rendering the test useless.
7948
7949 Warning 2: Do not confuse these two kinds of item:
7950
7951 deny recipients = dbm*@;/some/file
7952 deny recipients = *@dbm;/some/file
7953
7954 The first does a whole address lookup, with defaulting, as just described,
7955 because it starts with a lookup type. The second matches the local part and
7956 domain independently, as described in a bullet point below.
7957
7958 The following kinds of address list pattern can match only non-empty addresses.
7959 If the subject address is empty, a match against any of these pattern types
7960 always fails.
7961
7962 * If a pattern starts with "@@" followed by a single-key lookup item (for
7963 example, "@@lsearch;/some/file"), the address that is being checked is
7964 split into a local part and a domain. The domain is looked up in the file.
7965 If it is not found, there is no match. If it is found, the data that is
7966 looked up from the file is treated as a colon-separated list of local part
7967 patterns, each of which is matched against the subject local part in turn.
7968
7969 The lookup may be a partial one, and/or one involving a search for a
7970 default keyed by "*" (see section 9.6). The local part patterns that are
7971 looked up can be regular expressions or begin with "*", or even be further
7972 lookups. They may also be independently negated. For example, with
7973
7974 deny senders = @@dbm;/etc/reject-by-domain
7975
7976 the data from which the DBM file is built could contain lines like
7977
7978 baddomain.com: !postmaster : *
7979
7980 to reject all senders except postmaster from that domain.
7981
7982 If a local part that actually begins with an exclamation mark is required,
7983 it has to be specified using a regular expression. In lsearch files, an
7984 entry may be split over several lines by indenting the second and
7985 subsequent lines, but the separating colon must still be included at line
7986 breaks. White space surrounding the colons is ignored. For example:
7987
7988 aol.com: spammer1 : spammer2 : ^[0-9]+$ :
7989 spammer3 : spammer4
7990
7991 As in all colon-separated lists in Exim, a colon can be included in an item
7992 by doubling.
7993
7994 If the last item in the list starts with a right angle-bracket, the
7995 remainder of the item is taken as a new key to look up in order to obtain a
7996 continuation list of local parts. The new key can be any sequence of
7997 characters. Thus one might have entries like
7998
7999 aol.com: spammer1 : spammer 2 : >*
8000 xyz.com: spammer3 : >*
8001 *: ^\d{8}$
8002
8003 in a file that was searched with @@dbm*, to specify a match for 8-digit
8004 local parts for all domains, in addition to the specific local parts listed
8005 for each domain. Of course, using this feature costs another lookup each
8006 time a chain is followed, but the effort needed to maintain the data is
8007 reduced.
8008
8009 It is possible to construct loops using this facility, and in order to
8010 catch them, the chains may be no more than fifty items long.
8011
8012 * The @@<lookup> style of item can also be used with a query-style lookup,
8013 but in this case, the chaining facility is not available. The lookup can
8014 only return a single list of local parts.
8015
8016 Warning: There is an important difference between the address list items in
8017 these two examples:
8018
8019 senders = +my_list
8020 senders = *@+my_list
8021
8022 In the first one, "my_list" is a named address list, whereas in the second
8023 example it is a named domain list.
8024
8025
8026 10.20 Case of letters in address lists
8027 --------------------------------------
8028
8029 Domains in email addresses are always handled caselessly, but for local parts
8030 case may be significant on some systems (see caseful_local_part for how Exim
8031 deals with this when routing addresses). However, RFC 2505 (Anti-Spam
8032 Recommendations for SMTP MTAs) suggests that matching of addresses to blocking
8033 lists should be done in a case-independent manner. Since most address lists in
8034 Exim are used for this kind of control, Exim attempts to do this by default.
8035
8036 The domain portion of an address is always lowercased before matching it to an
8037 address list. The local part is lowercased by default, and any string
8038 comparisons that take place are done caselessly. This means that the data in
8039 the address list itself, in files included as plain file names, and in any file
8040 that is looked up using the "@@" mechanism, can be in any case. However, the
8041 keys in files that are looked up by a search type other than lsearch (which
8042 works caselessly) must be in lower case, because these lookups are not
8043 case-independent.
8044
8045 To allow for the possibility of caseful address list matching, if an item in an
8046 address list is the string "+caseful", the original case of the local part is
8047 restored for any comparisons that follow, and string comparisons are no longer
8048 case-independent. This does not affect the domain, which remains in lower case.
8049 However, although independent matches on the domain alone are still performed
8050 caselessly, regular expressions that match against an entire address become
8051 case-sensitive after "+caseful" has been seen.
8052
8053
8054 10.21 Local part lists
8055 ----------------------
8056
8057 Case-sensitivity in local part lists is handled in the same way as for address
8058 lists, as just described. The "+caseful" item can be used if required. In a
8059 setting of the local_parts option in a router with caseful_local_part set
8060 false, the subject is lowercased and the matching is initially
8061 case-insensitive. In this case, "+caseful" will restore case-sensitive matching
8062 in the local part list, but not elsewhere in the router. If caseful_local_part
8063 is set true in a router, matching in the local_parts option is case-sensitive
8064 from the start.
8065
8066 If a local part list is indirected to a file (see section 10.3), comments are
8067 handled in the same way as address lists - they are recognized only if the # is
8068 preceded by white space or the start of the line. Otherwise, local part lists
8069 are matched in the same way as domain lists, except that the special items that
8070 refer to the local host ("@", "@[]", "@mx_any", "@mx_primary", and
8071 "@mx_secondary") are not recognized. Refer to section 10.8 for details of the
8072 other available item types.
8073
8074
8075
8076 ===============================================================================
8077 11. STRING EXPANSIONS
8078
8079 Many strings in Exim's run time configuration are expanded before use. Some of
8080 them are expanded every time they are used; others are expanded only once.
8081
8082 When a string is being expanded it is copied verbatim from left to right except
8083 when a dollar or backslash character is encountered. A dollar specifies the
8084 start of a portion of the string that is interpreted and replaced as described
8085 below in section 11.5 onwards. Backslash is used as an escape character, as
8086 described in the following section.
8087
8088 Whether a string is expanded depends upon the context. Usually this is solely
8089 dependent upon the option for which a value is sought; in this documentation,
8090 options for which string expansion is performed are marked with * after the
8091 data type. ACL rules always expand strings. A couple of expansion conditions do
8092 not expand some of the brace-delimited branches, for security reasons.
8093
8094
8095 11.1 Literal text in expanded strings
8096 -------------------------------------
8097
8098 An uninterpreted dollar can be included in an expanded string by putting a
8099 backslash in front of it. A backslash can be used to prevent any special
8100 character being treated specially in an expansion, including backslash itself.
8101 If the string appears in quotes in the configuration file, two backslashes are
8102 required because the quotes themselves cause interpretation of backslashes when
8103 the string is read in (see section 6.16).
8104
8105 A portion of the string can specified as non-expandable by placing it between
8106 two occurrences of "\N". This is particularly useful for protecting regular
8107 expressions, which often contain backslashes and dollar signs. For example:
8108
8109 deny senders = \N^\d{8}[a-z]@some\.site\.example$\N
8110
8111 On encountering the first "\N", the expander copies subsequent characters
8112 without interpretation until it reaches the next "\N" or the end of the string.
8113
8114
8115 11.2 Character escape sequences in expanded strings
8116 ---------------------------------------------------
8117
8118 A backslash followed by one of the letters "n", "r", or "t" in an expanded
8119 string is recognized as an escape sequence for the character newline, carriage
8120 return, or tab, respectively. A backslash followed by up to three octal digits
8121 is recognized as an octal encoding for a single character, and a backslash
8122 followed by "x" and up to two hexadecimal digits is a hexadecimal encoding.
8123
8124 These escape sequences are also recognized in quoted strings when they are read
8125 in. Their interpretation in expansions as well is useful for unquoted strings,
8126 and for other cases such as looked-up strings that are then expanded.
8127
8128
8129 11.3 Testing string expansions
8130 ------------------------------
8131
8132 Many expansions can be tested by calling Exim with the -be option. This takes
8133 the command arguments, or lines from the standard input if there are no
8134 arguments, runs them through the string expansion code, and writes the results
8135 to the standard output. Variables based on configuration values are set up, but
8136 since no message is being processed, variables such as $local_part have no
8137 value. Nevertheless the -be option can be useful for checking out file and
8138 database lookups, and the use of expansion operators such as sg, substr and
8139 nhash.
8140
8141 Exim gives up its root privilege when it is called with the -be option, and
8142 instead runs under the uid and gid it was called with, to prevent users from
8143 using -be for reading files to which they do not have access.
8144
8145 If you want to test expansions that include variables whose values are taken
8146 from a message, there are two other options that can be used. The -bem option
8147 is like -be except that it is followed by a file name. The file is read as a
8148 message before doing the test expansions. For example:
8149
8150 exim -bem /tmp/test.message '$h_subject:'
8151
8152 The -Mset option is used in conjunction with -be and is followed by an Exim
8153 message identifier. For example:
8154
8155 exim -be -Mset 1GrA8W-0004WS-LQ '$recipients'
8156
8157 This loads the message from Exim's spool before doing the test expansions, and
8158 is therefore restricted to admin users.
8159
8160
8161 11.4 Forced expansion failure
8162 -----------------------------
8163
8164 A number of expansions that are described in the following section have
8165 alternative "true" and "false" substrings, enclosed in brace characters (which
8166 are sometimes called "curly brackets"). Which of the two strings is used
8167 depends on some condition that is evaluated as part of the expansion. If,
8168 instead of a "false" substring, the word "fail" is used (not in braces), the
8169 entire string expansion fails in a way that can be detected by the code that
8170 requested the expansion. This is called "forced expansion failure", and its
8171 consequences depend on the circumstances. In some cases it is no different from
8172 any other expansion failure, but in others a different action may be taken.
8173 Such variations are mentioned in the documentation of the option that is being
8174 expanded.
8175
8176
8177 11.5 Expansion items
8178 --------------------
8179
8180 The following items are recognized in expanded strings. White space may be used
8181 between sub-items that are keywords or substrings enclosed in braces inside an
8182 outer set of braces, to improve readability. Warning: Within braces, white
8183 space is significant.
8184
8185 $<variable name> or ${<variable name>}
8186
8187 Substitute the contents of the named variable, for example:
8188
8189 $local_part
8190 ${domain}
8191
8192 The second form can be used to separate the name from subsequent
8193 alphanumeric characters. This form (using braces) is available only for
8194 variables; it does not apply to message headers. The names of the variables
8195 are given in section 11.9 below. If the name of a non-existent variable is
8196 given, the expansion fails.
8197
8198 ${<op>:<string>}
8199
8200 The string is first itself expanded, and then the operation specified by <
8201 op> is applied to it. For example:
8202
8203 ${lc:$local_part}
8204
8205 The string starts with the first character after the colon, which may be
8206 leading white space. A list of operators is given in section 11.6 below.
8207 The operator notation is used for simple expansion items that have just one
8208 argument, because it reduces the number of braces and therefore makes the
8209 string easier to understand.
8210
8211 $bheader_<header name>: or $bh_<header name>:
8212
8213 This item inserts "basic" header lines. It is described with the header
8214 expansion item below.
8215
8216 ${acl{<name>}{<arg>}...}
8217
8218 The name and zero to nine argument strings are first expanded separately.
8219 The expanded arguments are assigned to the variables $acl_arg1 to $acl_arg9
8220 in order. Any unused are made empty. The variable $acl_narg is set to the
8221 number of arguments. The named ACL (see chapter 42) is called and may use
8222 the variables; if another acl expansion is used the values are restored
8223 after it returns. If the ACL sets a value using a "message =" modifier and
8224 returns accept or deny, the value becomes the result of the expansion. If
8225 no message is set and the ACL returns accept or deny the expansion result
8226 is an empty string. If the ACL returns defer the result is a forced-fail.
8227 Otherwise the expansion fails.
8228
8229 ${certextract{<field>}{<certificate>}{<string2>}{<string3>}}
8230
8231 The <certificate> must be a variable of type certificate. The field name is
8232 expanded and used to retrive the relevant field from the certificate.
8233 Supported fields are:
8234
8235 version
8236 serial_number
8237 subject RFC4514 DN
8238 issuer RFC4514 DN
8239 notbefore time
8240 notafter time
8241 sig_algorithm
8242 signature
8243 subj_altname tagged list
8244 ocsp_uri list
8245 crl_uri list
8246
8247 If the field is found, <string2> is expanded, and replaces the whole item;
8248 otherwise <string3> is used. During the expansion of <string2> the variable
8249 $value contains the value that has been extracted. Afterwards, it is
8250 restored to any previous value it might have had.
8251
8252 If {<string3>} is omitted, the item is replaced by an empty string if the
8253 key is not found. If {<string2>} is also omitted, the value that was
8254 extracted is used.
8255
8256 Some field names take optional modifiers, appended and separated by commas.
8257
8258 The field selectors marked as "RFC4514" above output a Distinguished Name
8259 string which is not quite parseable by Exim as a comma-separated tagged
8260 list (the exceptions being elements containin commas). RDN elements of a
8261 single type may be selected by a modifier of the type label; if so the
8262 expansion result is a list (newline-separated by default). The separator
8263 may be changed by another modifer of a right angle-bracket followed
8264 immediately by the new separator. Recognised RDN type labels include "CN",
8265 "O", "OU" and "DC".
8266
8267 The field selectors marked as "time" above may output a number of seconds
8268 since epoch if the modifier "int" is used.
8269
8270 The field selectors marked as "list" above return a list, newline-separated
8271 by default, (embedded separator characters in elements are doubled). The
8272 separator may be changed by a modifier of a right angle-bracket followed
8273 immediately by the new separator.
8274
8275 The field selectors marked as "tagged" above prefix each list element with
8276 a type string and an equals sign. Elements of only one type may be selected
8277 by a modifier which is one of "dns", "uri" or "mail"; if so the elenment
8278 tags are omitted.
8279
8280 If not otherwise noted field values are presented in human-readable form.
8281
8282 ${dlfunc{<file>}{<function>}{<arg>}{<arg>}...}
8283
8284 This expansion dynamically loads and then calls a locally-written C
8285 function. This functionality is available only if Exim is compiled with
8286
8287 EXPAND_DLFUNC=yes
8288
8289 set in Local/Makefile. Once loaded, Exim remembers the dynamically loaded
8290 object so that it doesn't reload the same object file in the same Exim
8291 process (but of course Exim does start new processes frequently).
8292
8293 There may be from zero to eight arguments to the function. When compiling a
8294 local function that is to be called in this way, local_scan.h should be
8295 included. The Exim variables and functions that are defined by that API are
8296 also available for dynamically loaded functions. The function itself must
8297 have the following type:
8298
8299 int dlfunction(uschar **yield, int argc, uschar *argv[])
8300
8301 Where "uschar" is a typedef for "unsigned char" in local_scan.h. The
8302 function should return one of the following values:
8303
8304 "OK": Success. The string that is placed in the variable yield is put into
8305 the expanded string that is being built.
8306
8307 "FAIL": A non-forced expansion failure occurs, with the error message taken
8308 from yield, if it is set.
8309
8310 "FAIL_FORCED": A forced expansion failure occurs, with the error message
8311 taken from yield if it is set.
8312
8313 "ERROR": Same as "FAIL", except that a panic log entry is written.
8314
8315 When compiling a function that is to be used in this way with gcc, you need
8316 to add -shared to the gcc command. Also, in the Exim build-time
8317 configuration, you must add -export-dynamic to EXTRALIBS.
8318
8319 ${extract{<key>}{<string1>}{<string2>}{<string3>}}
8320
8321 The key and <string1> are first expanded separately. Leading and trailing
8322 white space is removed from the key (but not from any of the strings). The
8323 key must not consist entirely of digits. The expanded <string1> must be of
8324 the form:
8325
8326 <key1> = <value1> <key2> = <value2> ...
8327
8328 where the equals signs and spaces (but not both) are optional. If any of
8329 the values contain white space, they must be enclosed in double quotes, and
8330 any values that are enclosed in double quotes are subject to escape
8331 processing as described in section 6.16. The expanded <string1> is searched
8332 for the value that corresponds to the key. The search is case-insensitive.
8333 If the key is found, <string2> is expanded, and replaces the whole item;
8334 otherwise <string3> is used. During the expansion of <string2> the variable
8335 $value contains the value that has been extracted. Afterwards, it is
8336 restored to any previous value it might have had.
8337
8338 If {<string3>} is omitted, the item is replaced by an empty string if the
8339 key is not found. If {<string2>} is also omitted, the value that was
8340 extracted is used. Thus, for example, these two expansions are identical,
8341 and yield "2001":
8342
8343 ${extract{gid}{uid=1984 gid=2001}}
8344 ${extract{gid}{uid=1984 gid=2001}{$value}}
8345
8346 Instead of {<string3>} the word "fail" (not in curly brackets) can appear,
8347 for example:
8348
8349 ${extract{Z}{A=... B=...}{$value} fail }
8350
8351 This forces an expansion failure (see section 11.4); {<string2>} must be
8352 present for "fail" to be recognized.
8353
8354 ${extract{<number>}{<separators>}{<string1>}{<string2>}{<string3>}}
8355
8356 The <number> argument must consist entirely of decimal digits, apart from
8357 leading and trailing white space, which is ignored. This is what
8358 distinguishes this form of extract from the previous kind. It behaves in
8359 the same way, except that, instead of extracting a named field, it extracts
8360 from <string1> the field whose number is given as the first argument. You
8361 can use $value in <string2> or "fail" instead of <string3> as before.
8362
8363 The fields in the string are separated by any one of the characters in the
8364 separator string. These may include space or tab characters. The first
8365 field is numbered one. If the number is negative, the fields are counted
8366 from the end of the string, with the rightmost one numbered -1. If the
8367 number given is zero, the entire string is returned. If the modulus of the
8368 number is greater than the number of fields in the string, the result is
8369 the expansion of <string3>, or the empty string if <string3> is not
8370 provided. For example:
8371
8372 ${extract{2}{:}{x:42:99:& Mailer::/bin/bash}}
8373
8374 yields "42", and
8375
8376 ${extract{-4}{:}{x:42:99:& Mailer::/bin/bash}}
8377
8378 yields "99". Two successive separators mean that the field between them is
8379 empty (for example, the fifth field above).
8380
8381 ${filter{<string>}{<condition>}}
8382
8383 After expansion, <string> is interpreted as a list, colon-separated by
8384 default, but the separator can be changed in the usual way. For each item
8385 in this list, its value is place in $item, and then the condition is
8386 evaluated. If the condition is true, $item is added to the output as an
8387 item in a new list; if the condition is false, the item is discarded. The
8388 separator used for the output list is the same as the one used for the
8389 input, but a separator setting is not included in the output. For example:
8390
8391 ${filter{a:b:c}{!eq{$item}{b}}
8392
8393 yields "a:c". At the end of the expansion, the value of $item is restored
8394 to what it was before. See also the map and reduce expansion items.
8395
8396 ${hash{<string1>}{<string2>}{<string3>}}
8397
8398 This is a textual hashing function, and was the first to be implemented in
8399 early versions of Exim. In current releases, there are other hashing
8400 functions (numeric, MD5, and SHA-1), which are described below.
8401
8402 The first two strings, after expansion, must be numbers. Call them <m> and
8403 <n>. If you are using fixed values for these numbers, that is, if <string1>
8404 and <string2> do not change when they are expanded, you can use the simpler
8405 operator notation that avoids some of the braces:
8406
8407 ${hash_<n>_<m>:<string>}
8408
8409 The second number is optional (in both notations). If <n> is greater than
8410 or equal to the length of the string, the expansion item returns the
8411 string. Otherwise it computes a new string of length <n> by applying a
8412 hashing function to the string. The new string consists of characters taken
8413 from the first <m> characters of the string
8414
8415 abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQWRSTUVWXYZ0123456789
8416
8417 If <m> is not present the value 26 is used, so that only lower case letters
8418 appear. For example:
8419
8420 $hash{3}{monty}} yields jmg
8421 $hash{5}{monty}} yields monty
8422 $hash{4}{62}{monty python}} yields fbWx
8423
8424 $header_<header name>: or $h_<header name>:, $bheader_<header name>: or $bh_<
8425 header name>:, $rheader_<header name>: or $rh_<header name>:
8426
8427 Substitute the contents of the named message header line, for example
8428
8429 $header_reply-to:
8430
8431 The newline that terminates a header line is not included in the expansion,
8432 but internal newlines (caused by splitting the header line over several
8433 physical lines) may be present.
8434
8435 The difference between rheader, bheader, and header is in the way the data
8436 in the header line is interpreted.
8437
8438 * rheader gives the original "raw" content of the header line, with no
8439 processing at all, and without the removal of leading and trailing
8440 white space.
8441
8442 * bheader removes leading and trailing white space, and then decodes
8443 base64 or quoted-printable MIME "words" within the header text, but
8444 does no character set translation. If decoding of what looks
8445 superficially like a MIME "word" fails, the raw string is returned. If
8446 decoding produces a binary zero character, it is replaced by a question
8447 mark - this is what Exim does for binary zeros that are actually
8448 received in header lines.
8449
8450 * header tries to translate the string as decoded by bheader to a
8451 standard character set. This is an attempt to produce the same string
8452 as would be displayed on a user's MUA. If translation fails, the
8453 bheader string is returned. Translation is attempted only on operating
8454 systems that support the iconv() function. This is indicated by the
8455 compile-time macro HAVE_ICONV in a system Makefile or in Local/Makefile
8456 .
8457
8458 In a filter file, the target character set for header can be specified by a
8459 command of the following form:
8460
8461 headers charset "UTF-8"
8462
8463 This command affects all references to $h_ (or $header_) expansions in
8464 subsequently obeyed filter commands. In the absence of this command, the
8465 target character set in a filter is taken from the setting of the
8466 headers_charset option in the runtime configuration. The value of this
8467 option defaults to the value of HEADERS_CHARSET in Local/Makefile. The
8468 ultimate default is ISO-8859-1.
8469
8470 Header names follow the syntax of RFC 2822, which states that they may
8471 contain any printing characters except space and colon. Consequently, curly
8472 brackets do not terminate header names, and should not be used to enclose
8473 them as if they were variables. Attempting to do so causes a syntax error.
8474
8475 Only header lines that are common to all copies of a message are visible to
8476 this mechanism. These are the original header lines that are received with
8477 the message, and any that are added by an ACL statement or by a system
8478 filter. Header lines that are added to a particular copy of a message by a
8479 router or transport are not accessible.
8480
8481 For incoming SMTP messages, no header lines are visible in ACLs that are
8482 obeyed before the DATA ACL, because the header structure is not set up
8483 until the message is received. Header lines that are added in a RCPT ACL
8484 (for example) are saved until the message's incoming header lines are
8485 available, at which point they are added. When a DATA ACL is running,
8486 however, header lines added by earlier ACLs are visible.
8487
8488 Upper case and lower case letters are synonymous in header names. If the
8489 following character is white space, the terminating colon may be omitted,
8490 but this is not recommended, because you may then forget it when it is
8491 needed. When white space terminates the header name, it is included in the
8492 expanded string. If the message does not contain the given header, the
8493 expansion item is replaced by an empty string. (See the def condition in
8494 section 11.7 for a means of testing for the existence of a header.)
8495
8496 If there is more than one header with the same name, they are all
8497 concatenated to form the substitution string, up to a maximum length of
8498 64K. Unless rheader is being used, leading and trailing white space is
8499 removed from each header before concatenation, and a completely empty
8500 header is ignored. A newline character is then inserted between non-empty
8501 headers, but there is no newline at the very end. For the header and
8502 bheader expansion, for those headers that contain lists of addresses, a
8503 comma is also inserted at the junctions between headers. This does not
8504 happen for the rheader expansion.
8505
8506 ${hmac{<hashname>}{<secret>}{<string>}}
8507
8508 This function uses cryptographic hashing (either MD5 or SHA-1) to convert a
8509 shared secret and some text into a message authentication code, as
8510 specified in RFC 2104. This differs from "${md5:secret_text...}" or "$
8511 {sha1:secret_text...}" in that the hmac step adds a signature to the
8512 cryptographic hash, allowing for authentication that is not possible with
8513 MD5 or SHA-1 alone. The hash name must expand to either "md5" or "sha1" at
8514 present. For example:
8515
8516 ${hmac{md5}{somesecret}{$primary_hostname $tod_log}}
8517
8518 For the hostname mail.example.com and time 2002-10-17 11:30:59, this
8519 produces:
8520
8521 dd97e3ba5d1a61b5006108f8c8252953
8522
8523 As an example of how this might be used, you might put in the main part of
8524 an Exim configuration:
8525
8526 SPAMSCAN_SECRET=cohgheeLei2thahw
8527
8528 In a router or a transport you could then have:
8529
8530 headers_add = \
8531 X-Spam-Scanned: ${primary_hostname} ${message_exim_id} \
8532 ${hmac{md5}{SPAMSCAN_SECRET}\
8533 {${primary_hostname},${message_exim_id},$h_message-id:}}
8534
8535 Then given a message, you can check where it was scanned by looking at the
8536 X-Spam-Scanned: header line. If you know the secret, you can check that
8537 this header line is authentic by recomputing the authentication code from
8538 the host name, message ID and the Message-id: header line. This can be done
8539 using Exim's -be option, or by other means, for example by using the
8540 hmac_md5_hex() function in Perl.
8541
8542 ${if <condition> {<string1>}{<string2>}}
8543
8544 If <condition> is true, <string1> is expanded and replaces the whole item;
8545 otherwise <string2> is used. The available conditions are described in
8546 section 11.7 below. For example:
8547
8548 ${if eq {$local_part}{postmaster} {yes}{no} }
8549
8550 The second string need not be present; if it is not and the condition is
8551 not true, the item is replaced with nothing. Alternatively, the word "fail"
8552 may be present instead of the second string (without any curly brackets).
8553 In this case, the expansion is forced to fail if the condition is not true
8554 (see section 11.4).
8555
8556 If both strings are omitted, the result is the string "true" if the
8557 condition is true, and the empty string if the condition is false. This
8558 makes it less cumbersome to write custom ACL and router conditions. For
8559 example, instead of
8560
8561 condition = ${if >{$acl_m4}{3}{true}{false}}
8562
8563 you can use
8564
8565 condition = ${if >{$acl_m4}{3}}
8566
8567 ${length{<string1>}{<string2>}}
8568
8569 The length item is used to extract the initial portion of a string. Both
8570 strings are expanded, and the first one must yield a number, <n>, say. If
8571 you are using a fixed value for the number, that is, if <string1> does not
8572 change when expanded, you can use the simpler operator notation that avoids
8573 some of the braces:
8574
8575 ${length_<n>:<string>}
8576
8577 The result of this item is either the first <n> characters or the whole of
8578 <string2>, whichever is the shorter. Do not confuse length with strlen,
8579 which gives the length of a string.
8580
8581 ${listextract{<number>}{<string1>}{<string2>}{<string3>}}
8582
8583 The <number> argument must consist entirely of decimal digits, apart from
8584 an optional leading minus, and leading and trailing white space (which is
8585 ignored).
8586
8587 After expansion, <string1> is interpreted as a list, colon-separated by
8588 default, but the separator can be changed in the usual way.
8589
8590 The first field of the list is numbered one. If the number is negative, the
8591 fields are counted from the end of the list, with the rightmost one
8592 numbered -1. The numbered element of the list is extracted and placed in
8593 $value, then <string2> is expanded as the result.
8594
8595 If the modulus of the number is zero or greater than the number of fields
8596 in the string, the result is the expansion of <string3>.
8597
8598 For example:
8599
8600 ${listextract{2}{x:42:99}}
8601
8602 yields "42", and
8603
8604 ${listextract{-3}{<, x,42,99,& Mailer,,/bin/bash}{result: $value}}
8605
8606 yields "result: 99".
8607
8608 If {<string3>} is omitted, an empty string is used for string3. If {<
8609 string2>} is also omitted, the value that was extracted is used. You can
8610 use "fail" instead of {<string3>} as in a string extract.
8611
8612 ${lookup{<key>} <search type> {<file>} {<string1>} {<string2>}}
8613
8614 This is the first of one of two different types of lookup item, which are
8615 both described in the next item.
8616
8617 ${lookup <search type> {<query>} {<string1>} {<string2>}}
8618
8619 The two forms of lookup item specify data lookups in files and databases,
8620 as discussed in chapter 9. The first form is used for single-key lookups,
8621 and the second is used for query-style lookups. The <key>, <file>, and <
8622 query> strings are expanded before use.
8623
8624 If there is any white space in a lookup item which is part of a filter
8625 command, a retry or rewrite rule, a routing rule for the manualroute
8626 router, or any other place where white space is significant, the lookup
8627 item must be enclosed in double quotes. The use of data lookups in users'
8628 filter files may be locked out by the system administrator.
8629
8630 If the lookup succeeds, <string1> is expanded and replaces the entire item.
8631 During its expansion, the variable $value contains the data returned by the
8632 lookup. Afterwards it reverts to the value it had previously (at the outer
8633 level it is empty). If the lookup fails, <string2> is expanded and replaces
8634 the entire item. If {<string2>} is omitted, the replacement is the empty
8635 string on failure. If <string2> is provided, it can itself be a nested
8636 lookup, thus providing a mechanism for looking up a default value when the
8637 original lookup fails.
8638
8639 If a nested lookup is used as part of <string1>, $value contains the data
8640 for the outer lookup while the parameters of the second lookup are
8641 expanded, and also while <string2> of the second lookup is expanded, should
8642 the second lookup fail. Instead of {<string2>} the word "fail" can appear,
8643 and in this case, if the lookup fails, the entire expansion is forced to
8644 fail (see section 11.4). If both {<string1>} and {<string2>} are omitted,
8645 the result is the looked up value in the case of a successful lookup, and
8646 nothing in the case of failure.
8647
8648 For single-key lookups, the string "partial" is permitted to precede the
8649 search type in order to do partial matching, and * or *@ may follow a
8650 search type to request default lookups if the key does not match (see
8651 sections 9.6 and 9.7 for details).
8652
8653 If a partial search is used, the variables $1 and $2 contain the wild and
8654 non-wild parts of the key during the expansion of the replacement text.
8655 They return to their previous values at the end of the lookup item.
8656
8657 This example looks up the postmaster alias in the conventional alias file:
8658
8659 ${lookup {postmaster} lsearch {/etc/aliases} {$value}}
8660
8661 This example uses NIS+ to look up the full name of the user corresponding
8662 to the local part of an address, forcing the expansion to fail if it is not
8663 found:
8664
8665 ${lookup nisplus {[name=$local_part],passwd.org_dir:gcos} \
8666 {$value}fail}
8667
8668 ${map{<string1>}{<string2>}}
8669
8670 After expansion, <string1> is interpreted as a list, colon-separated by
8671 default, but the separator can be changed in the usual way. For each item
8672 in this list, its value is place in $item, and then <string2> is expanded
8673 and added to the output as an item in a new list. The separator used for
8674 the output list is the same as the one used for the input, but a separator
8675 setting is not included in the output. For example:
8676
8677 ${map{a:b:c}{[$item]}} ${map{<- x-y-z}{($item)}}
8678
8679 expands to "[a]:[b]:[c] (x)-(y)-(z)". At the end of the expansion, the
8680 value of $item is restored to what it was before. See also the filter and
8681 reduce expansion items.
8682
8683 ${nhash{<string1>}{<string2>}{<string3>}}
8684
8685 The three strings are expanded; the first two must yield numbers. Call them
8686 <n> and <m>. If you are using fixed values for these numbers, that is, if <
8687 string1> and <string2> do not change when they are expanded, you can use
8688 the simpler operator notation that avoids some of the braces:
8689
8690 ${nhash_<n>_<m>:<string>}
8691
8692 The second number is optional (in both notations). If there is only one
8693 number, the result is a number in the range 0-<n>-1. Otherwise, the string
8694 is processed by a div/mod hash function that returns two numbers, separated
8695 by a slash, in the ranges 0 to <n>-1 and 0 to <m>-1, respectively. For
8696 example,
8697
8698 ${nhash{8}{64}{supercalifragilisticexpialidocious}}
8699
8700 returns the string "6/33".
8701
8702 ${perl{<subroutine>}{<arg>}{<arg>}...}
8703
8704 This item is available only if Exim has been built to include an embedded
8705 Perl interpreter. The subroutine name and the arguments are first
8706 separately expanded, and then the Perl subroutine is called with those
8707 arguments. No additional arguments need be given; the maximum number
8708 permitted, including the name of the subroutine, is nine.
8709
8710 The return value of the subroutine is inserted into the expanded string,
8711 unless the return value is undef. In that case, the expansion fails in the
8712 same way as an explicit "fail" on a lookup item. The return value is a
8713 scalar. Whatever you return is evaluated in a scalar context. For example,
8714 if you return the name of a Perl vector, the return value is the size of
8715 the vector, not its contents.
8716
8717 If the subroutine exits by calling Perl's die function, the expansion fails
8718 with the error message that was passed to die. More details of the embedded
8719 Perl facility are given in chapter 12.
8720
8721 The redirect router has an option called forbid_filter_perl which locks out
8722 the use of this expansion item in filter files.
8723
8724 ${prvs{<address>}{<secret>}{<keynumber>}}
8725
8726 The first argument is a complete email address and the second is secret
8727 keystring. The third argument, specifying a key number, is optional. If
8728 absent, it defaults to 0. The result of the expansion is a prvs-signed
8729 email address, to be typically used with the return_path option on an smtp
8730 transport as part of a bounce address tag validation (BATV) scheme. For
8731 more discussion and an example, see section 42.51.
8732
8733 ${prvscheck{<address>}{<secret>}{<string>}}
8734
8735 This expansion item is the complement of the prvs item. It is used for
8736 checking prvs-signed addresses. If the expansion of the first argument does
8737 not yield a syntactically valid prvs-signed address, the whole item expands
8738 to the empty string. When the first argument does expand to a syntactically
8739 valid prvs-signed address, the second argument is expanded, with the
8740 prvs-decoded version of the address and the key number extracted from the
8741 address in the variables $prvscheck_address and $prvscheck_keynum,
8742 respectively.
8743
8744 These two variables can be used in the expansion of the second argument to
8745 retrieve the secret. The validity of the prvs-signed address is then
8746 checked against the secret. The result is stored in the variable
8747 $prvscheck_result, which is empty for failure or "1" for success.
8748
8749 The third argument is optional; if it is missing, it defaults to an empty
8750 string. This argument is now expanded. If the result is an empty string,
8751 the result of the expansion is the decoded version of the address. This is
8752 the case whether or not the signature was valid. Otherwise, the result of
8753 the expansion is the expansion of the third argument.
8754
8755 All three variables can be used in the expansion of the third argument.
8756 However, once the expansion is complete, only $prvscheck_result remains
8757 set. For more discussion and an example, see section 42.51.
8758
8759 ${readfile{<file name>}{<eol string>}}
8760
8761 The file name and end-of-line string are first expanded separately. The
8762 file is then read, and its contents replace the entire item. All newline
8763 characters in the file are replaced by the end-of-line string if it is
8764 present. Otherwise, newlines are left in the string. String expansion is
8765 not applied to the contents of the file. If you want this, you must wrap
8766 the item in an expand operator. If the file cannot be read, the string
8767 expansion fails.
8768
8769 The redirect router has an option called forbid_filter_readfile which locks
8770 out the use of this expansion item in filter files.
8771
8772 ${readsocket{<name>}{<request>}{<timeout>}{<eol string>}{<fail string>}}
8773
8774 This item inserts data from a Unix domain or Internet socket into the
8775 expanded string. The minimal way of using it uses just two arguments, as in
8776 these examples:
8777
8778 ${readsocket{/socket/name}{request string}}
8779 ${readsocket{inet:some.host:1234}{request string}}
8780
8781 For a Unix domain socket, the first substring must be the path to the
8782 socket. For an Internet socket, the first substring must contain "inet:"
8783 followed by a host name or IP address, followed by a colon and a port,
8784 which can be a number or the name of a TCP port in /etc/services. An IP
8785 address may optionally be enclosed in square brackets. This is best for
8786 IPv6 addresses. For example:
8787
8788 ${readsocket{inet:[::1]:1234}{request string}}
8789
8790 Only a single host name may be given, but if looking it up yields more than
8791 one IP address, they are each tried in turn until a connection is made. For
8792 both kinds of socket, Exim makes a connection, writes the request string
8793 (unless it is an empty string) and reads from the socket until an
8794 end-of-file is read. A timeout of 5 seconds is applied. Additional,
8795 optional arguments extend what can be done. Firstly, you can vary the
8796 timeout. For example:
8797
8798 ${readsocket{/socket/name}{request string}{3s}}
8799
8800 A fourth argument allows you to change any newlines that are in the data
8801 that is read, in the same way as for readfile (see above). This example
8802 turns them into spaces:
8803
8804 ${readsocket{inet:127.0.0.1:3294}{request string}{3s}{ }}
8805
8806 As with all expansions, the substrings are expanded before the processing
8807 happens. Errors in these sub-expansions cause the expansion to fail. In
8808 addition, the following errors can occur:
8809
8810 * Failure to create a socket file descriptor;
8811
8812 * Failure to connect the socket;
8813
8814 * Failure to write the request string;
8815
8816 * Timeout on reading from the socket.
8817
8818 By default, any of these errors causes the expansion to fail. However, if
8819 you supply a fifth substring, it is expanded and used when any of the above
8820 errors occurs. For example:
8821
8822 ${readsocket{/socket/name}{request string}{3s}{\n}\
8823 {socket failure}}
8824
8825 You can test for the existence of a Unix domain socket by wrapping this
8826 expansion in "${if exists", but there is a race condition between that test
8827 and the actual opening of the socket, so it is safer to use the fifth
8828 argument if you want to be absolutely sure of avoiding an expansion error
8829 for a non-existent Unix domain socket, or a failure to connect to an
8830 Internet socket.
8831
8832 The redirect router has an option called forbid_filter_readsocket which
8833 locks out the use of this expansion item in filter files.
8834
8835 ${reduce{<string1>}{<string2>}{<string3>}}
8836
8837 This operation reduces a list to a single, scalar string. After expansion,
8838 <string1> is interpreted as a list, colon-separated by default, but the
8839 separator can be changed in the usual way. Then <string2> is expanded and
8840 assigned to the $value variable. After this, each item in the <string1>
8841 list is assigned to $item in turn, and <string3> is expanded for each of
8842 them. The result of that expansion is assigned to $value before the next
8843 iteration. When the end of the list is reached, the final value of $value
8844 is added to the expansion output. The reduce expansion item can be used in
8845 a number of ways. For example, to add up a list of numbers:
8846
8847 ${reduce {<, 1,2,3}{0}{${eval:$value+$item}}}
8848
8849 The result of that expansion would be "6". The maximum of a list of numbers
8850 can be found:
8851
8852 ${reduce {3:0:9:4:6}{0}{${if >{$item}{$value}{$item}{$value}}}}
8853
8854 At the end of a reduce expansion, the values of $item and $value are
8855 restored to what they were before. See also the filter and map expansion
8856 items.
8857
8858 $rheader_<header name>: or $rh_<header name>:
8859
8860 This item inserts "raw" header lines. It is described with the header
8861 expansion item above.
8862
8863 ${run{<command> <args>}{<string1>}{<string2>}}
8864
8865 The command and its arguments are first expanded as one string. The string
8866 is split apart into individual arguments by spaces, and then the command is
8867 run in a separate process, but under the same uid and gid. As in other
8868 command executions from Exim, a shell is not used by default. If the
8869 command requires a shell, you must explicitly code it.
8870
8871 Since the arguments are split by spaces, when there is a variable expansion
8872 which has an empty result, it will cause the situation that the argument
8873 will simply be omitted when the program is actually executed by Exim. If
8874 the script/program requires a specific number of arguments and the expanded
8875 variable could possibly result in this empty expansion, the variable must
8876 be quoted. This is more difficult if the expanded variable itself could
8877 result in a string containing quotes, because it would interfere with the
8878 quotes around the command arguments. A possible guard against this is to
8879 wrap the variable in the sg operator to change any quote marks to some
8880 other character.
8881
8882 The standard input for the command exists, but is empty. The standard
8883 output and standard error are set to the same file descriptor. If the
8884 command succeeds (gives a zero return code) <string1> is expanded and
8885 replaces the entire item; during this expansion, the standard output/error
8886 from the command is in the variable $value. If the command fails, <string2
8887 >, if present, is expanded and used. Once again, during the expansion, the
8888 standard output/error from the command is in the variable $value.
8889
8890 If <string2> is absent, the result is empty. Alternatively, <string2> can
8891 be the word "fail" (not in braces) to force expansion failure if the
8892 command does not succeed. If both strings are omitted, the result is
8893 contents of the standard output/error on success, and nothing on failure.
8894
8895 The standard output/error of the command is put in the variable $value. In
8896 this ACL example, the output of a command is logged for the admin to
8897 troubleshoot:
8898
8899 warn condition = ${run{/usr/bin/id}{yes}{no}}
8900 log_message = Output of id: $value
8901
8902 If the command requires shell idioms, such as the > redirect operator, the
8903 shell must be invoked directly, such as with:
8904
8905 ${run{/bin/bash -c "/usr/bin/id >/tmp/id"}{yes}{yes}}
8906
8907 The return code from the command is put in the variable $runrc, and this
8908 remains set afterwards, so in a filter file you can do things like this:
8909
8910 if "${run{x y z}{}}$runrc" is 1 then ...
8911 elif $runrc is 2 then ...
8912 ...
8913 endif
8914
8915 If execution of the command fails (for example, the command does not
8916 exist), the return code is 127 - the same code that shells use for
8917 non-existent commands.
8918
8919 Warning: In a router or transport, you cannot assume the order in which
8920 option values are expanded, except for those preconditions whose order of
8921 testing is documented. Therefore, you cannot reliably expect to set $runrc
8922 by the expansion of one option, and use it in another.
8923
8924 The redirect router has an option called forbid_filter_run which locks out
8925 the use of this expansion item in filter files.
8926
8927 ${sg{<subject>}{<regex>}{<replacement>}}
8928
8929 This item works like Perl's substitution operator (s) with the global (/g)
8930 option; hence its name. However, unlike the Perl equivalent, Exim does not
8931 modify the subject string; instead it returns the modified string for
8932 insertion into the overall expansion. The item takes three arguments: the
8933 subject string, a regular expression, and a substitution string. For
8934 example:
8935
8936 ${sg{abcdefabcdef}{abc}{xyz}}
8937
8938 yields "xyzdefxyzdef". Because all three arguments are expanded before use,
8939 if any $ or \ characters are required in the regular expression or in the
8940 substitution string, they have to be escaped. For example:
8941
8942 ${sg{abcdef}{^(...)(...)\$}{\$2\$1}}
8943
8944 yields "defabc", and
8945
8946 ${sg{1=A 4=D 3=C}{\N(\d+)=\N}{K\$1=}}
8947
8948 yields "K1=A K4=D K3=C". Note the use of "\N" to protect the contents of
8949 the regular expression from string expansion.
8950
8951 ${substr{<string1>}{<string2>}{<string3>}}
8952
8953 The three strings are expanded; the first two must yield numbers. Call them
8954 <n> and <m>. If you are using fixed values for these numbers, that is, if <
8955 string1> and <string2> do not change when they are expanded, you can use
8956 the simpler operator notation that avoids some of the braces:
8957
8958 ${substr_<n>_<m>:<string>}
8959
8960 The second number is optional (in both notations). If it is absent in the
8961 simpler format, the preceding underscore must also be omitted.
8962
8963 The substr item can be used to extract more general substrings than length.
8964 The first number, <n>, is a starting offset, and <m> is the length
8965 required. For example
8966
8967 ${substr{3}{2}{$local_part}}
8968
8969 If the starting offset is greater than the string length the result is the
8970 null string; if the length plus starting offset is greater than the string
8971 length, the result is the right-hand part of the string, starting from the
8972 given offset. The first character in the string has offset zero.
8973
8974 The substr expansion item can take negative offset values to count from the
8975 right-hand end of its operand. The last character is offset -1, the
8976 second-last is offset -2, and so on. Thus, for example,
8977
8978 ${substr{-5}{2}{1234567}}
8979
8980 yields "34". If the absolute value of a negative offset is greater than the
8981 length of the string, the substring starts at the beginning of the string,
8982 and the length is reduced by the amount of overshoot. Thus, for example,
8983
8984 ${substr{-5}{2}{12}}
8985
8986 yields an empty string, but
8987
8988 ${substr{-3}{2}{12}}
8989
8990 yields "1".
8991
8992 When the second number is omitted from substr, the remainder of the string
8993 is taken if the offset is positive. If it is negative, all characters in
8994 the string preceding the offset point are taken. For example, an offset of
8995 -1 and no length, as in these semantically identical examples:
8996
8997 ${substr_-1:abcde}
8998 ${substr{-1}{abcde}}
8999
9000 yields all but the last character of the string, that is, "abcd".
9001
9002 ${tr{<subject>}{<characters>}{<replacements>}}
9003
9004 This item does single-character translation on its subject string. The
9005 second argument is a list of characters to be translated in the subject
9006 string. Each matching character is replaced by the corresponding character
9007 from the replacement list. For example
9008
9009 ${tr{abcdea}{ac}{13}}
9010
9011 yields "1b3de1". If there are duplicates in the second character string,
9012 the last occurrence is used. If the third string is shorter than the
9013 second, its last character is replicated. However, if it is empty, no
9014 translation takes place.
9015
9016
9017 11.6 Expansion operators
9018 ------------------------
9019
9020 For expansion items that perform transformations on a single argument string,
9021 the "operator" notation is used because it is simpler and uses fewer braces.
9022 The substring is first expanded before the operation is applied to it. The
9023 following operations can be performed:
9024
9025 ${address:<string>}
9026
9027 The string is interpreted as an RFC 2822 address, as it might appear in a
9028 header line, and the effective address is extracted from it. If the string
9029 does not parse successfully, the result is empty.
9030
9031 ${addresses:<string>}
9032
9033 The string (after expansion) is interpreted as a list of addresses in RFC
9034 2822 format, such as can be found in a To: or Cc: header line. The
9035 operative address (local-part@domain) is extracted from each item, and the
9036 result of the expansion is a colon-separated list, with appropriate
9037 doubling of colons should any happen to be present in the email addresses.
9038 Syntactically invalid RFC2822 address items are omitted from the output.
9039
9040 It is possible to specify a character other than colon for the output
9041 separator by starting the string with > followed by the new separator
9042 character. For example:
9043
9044 ${addresses:>& Chief <ceo@up.stairs>, sec@base.ment (dogsbody)}
9045
9046 expands to "ceo@up.stairs&sec@base.ment". Compare the address (singular)
9047 expansion item, which extracts the working address from a single RFC2822
9048 address. See the filter, map, and reduce items for ways of processing
9049 lists.
9050
9051 To clarify "list of addresses in RFC 2822 format" mentioned above, Exim
9052 follows a strict interpretation of header line formatting. Exim parses the
9053 bare, unquoted portion of an email address and if it finds a comma, treats
9054 it as an email address seperator. For the example header line:
9055
9056 From: =?iso-8859-2?Q?Last=2C_First?= <user@example.com>
9057
9058 The first example below demonstrates that Q-encoded email addresses are
9059 parsed properly if it is given the raw header (in this example,
9060 "$rheader_from:"). It does not see the comma because it's still encoded as
9061 "=2C". The second example below is passed the contents of "$header_from:",
9062 meaning it gets de-mimed. Exim sees the decoded "," so it treats it as two
9063 email addresses. The third example shows that the presence of a comma is
9064 skipped when it is quoted.
9065
9066 # exim -be '${addresses:From: \
9067 =?iso-8859-2?Q?Last=2C_First?= <user@example.com>}'
9068 user@example.com
9069 # exim -be '${addresses:From: Last, First <user@example.com>}'
9070 Last:user@example.com
9071 # exim -be '${addresses:From: "Last, First" <user@example.com>}'
9072 user@example.com
9073
9074 ${base62:<digits>}
9075
9076 The string must consist entirely of decimal digits. The number is converted
9077 to base 62 and output as a string of six characters, including leading
9078 zeros. In the few operating environments where Exim uses base 36 instead of
9079 base 62 for its message identifiers (because those systems do not have
9080 case-sensitive file names), base 36 is used by this operator, despite its
9081 name. Note: Just to be absolutely clear: this is not base64 encoding.
9082
9083 ${base62d:<base-62 digits>}
9084
9085 The string must consist entirely of base-62 digits, or, in operating
9086 environments where Exim uses base 36 instead of base 62 for its message
9087 identifiers, base-36 digits. The number is converted to decimal and output
9088 as a string.
9089
9090 ${domain:<string>}
9091
9092 The string is interpreted as an RFC 2822 address and the domain is
9093 extracted from it. If the string does not parse successfully, the result is
9094 empty.
9095
9096 ${escape:<string>}
9097
9098 If the string contains any non-printing characters, they are converted to
9099 escape sequences starting with a backslash. Whether characters with the
9100 most significant bit set (so-called "8-bit characters") count as printing
9101 or not is controlled by the print_topbitchars option.
9102
9103 ${eval:<string>} and ${eval10:<string>}
9104
9105 These items supports simple arithmetic and bitwise logical operations in
9106 expansion strings. The string (after expansion) must be a conventional
9107 arithmetic expression, but it is limited to basic arithmetic operators,
9108 bitwise logical operators, and parentheses. All operations are carried out
9109 using integer arithmetic. The operator priorities are as follows (the same
9110 as in the C programming language):
9111
9112 highest: not (~), negate (-)
9113 multiply (*), divide (/), remainder (%)
9114 plus (+), minus (-)
9115 shift-left (<<), shift-right (>>)
9116 and (&)
9117 xor (^)
9118 lowest: or (|)
9119
9120 Binary operators with the same priority are evaluated from left to right.
9121 White space is permitted before or after operators.
9122
9123 For eval, numbers may be decimal, octal (starting with "0") or hexadecimal
9124 (starting with "0x"). For eval10, all numbers are taken as decimal, even if
9125 they start with a leading zero; hexadecimal numbers are not permitted. This
9126 can be useful when processing numbers extracted from dates or times, which
9127 often do have leading zeros.
9128
9129 A number may be followed by "K", "M" or "G" to multiply it by 1024,
9130 1024*1024 or 1024*1024*1024, respectively. Negative numbers are supported.
9131 The result of the computation is a decimal representation of the answer
9132 (without "K", "M" or "G"). For example:
9133
9134 ${eval:1+1} yields 2
9135 ${eval:1+2*3} yields 7
9136 ${eval:(1+2)*3} yields 9
9137 ${eval:2+42%5} yields 4
9138 ${eval:0xc&5} yields 4
9139 ${eval:0xc|5} yields 13
9140 ${eval:0xc^5} yields 9
9141 ${eval:0xc>>1} yields 6
9142 ${eval:0xc<<1} yields 24
9143 ${eval:~255&0x1234} yields 4608
9144 ${eval:-(~255&0x1234)} yields -4608
9145
9146 As a more realistic example, in an ACL you might have
9147
9148 deny message = Too many bad recipients
9149 condition = \
9150 ${if and { \
9151 {>{$rcpt_count}{10}} \
9152 { \
9153 < \
9154 {$recipients_count} \
9155 {${eval:$rcpt_count/2}} \
9156 } \
9157 }{yes}{no}}
9158
9159 The condition is true if there have been more than 10 RCPT commands and
9160 fewer than half of them have resulted in a valid recipient.
9161
9162 ${expand:<string>}
9163
9164 The expand operator causes a string to be expanded for a second time. For
9165 example,
9166
9167 ${expand:${lookup{$domain}dbm{/some/file}{$value}}}
9168
9169 first looks up a string in a file while expanding the operand for expand,
9170 and then re-expands what it has found.
9171
9172 ${from_utf8:<string>}
9173
9174 The world is slowly moving towards Unicode, although there are no standards
9175 for email yet. However, other applications (including some databases) are
9176 starting to store data in Unicode, using UTF-8 encoding. This operator
9177 converts from a UTF-8 string to an ISO-8859-1 string. UTF-8 code values
9178 greater than 255 are converted to underscores. The input must be a valid
9179 UTF-8 string. If it is not, the result is an undefined sequence of bytes.
9180
9181 Unicode code points with values less than 256 are compatible with ASCII and
9182 ISO-8859-1 (also known as Latin-1). For example, character 169 is the
9183 copyright symbol in both cases, though the way it is encoded is different.
9184 In UTF-8, more than one byte is needed for characters with code values
9185 greater than 127, whereas ISO-8859-1 is a single-byte encoding (but thereby
9186 limited to 256 characters). This makes translation from UTF-8 to ISO-8859-1
9187 straightforward.
9188
9189 ${hash_<n>_<m>:<string>}
9190
9191 The hash operator is a simpler interface to the hashing function that can
9192 be used when the two parameters are fixed numbers (as opposed to strings
9193 that change when expanded). The effect is the same as
9194
9195 ${hash{<n>}{<m>}{<string>}}
9196
9197 See the description of the general hash item above for details. The
9198 abbreviation h can be used when hash is used as an operator.
9199
9200 ${hex2b64:<hexstring>}
9201
9202 This operator converts a hex string into one that is base64 encoded. This
9203 can be useful for processing the output of the MD5 and SHA-1 hashing
9204 functions.
9205
9206 ${hexquote:<string>}
9207
9208 This operator converts non-printable characters in a string into a hex
9209 escape form. Byte values between 33 (!) and 126 (~) inclusive are left as
9210 is, and other byte values are converted to "\xNN", for example a byte value
9211 127 is converted to "\x7f".
9212
9213 ${lc:<string>}
9214
9215 This forces the letters in the string into lower-case, for example:
9216
9217 ${lc:$local_part}
9218
9219 ${length_<number>:<string>}
9220
9221 The length operator is a simpler interface to the length function that can
9222 be used when the parameter is a fixed number (as opposed to a string that
9223 changes when expanded). The effect is the same as
9224
9225 ${length{<number>}{<string>}}
9226
9227 See the description of the general length item above for details. Note that
9228 length is not the same as strlen. The abbreviation l can be used when
9229 length is used as an operator.
9230
9231 ${listcount:<string>}
9232
9233 The string is interpreted as a list and the number of items is returned.
9234
9235 ${listnamed:<name>} and ${listnamed_<type>:<name>}
9236
9237 The name is interpreted as a named list and the content of the list is
9238 returned, expanding any referenced lists, re-quoting as needed for
9239 colon-separation. If the optional type is given it must be one of "a", "d",
9240 "h" or "l" and selects address-, domain-, host- or localpart- lists to
9241 search among respectively. Otherwise all types are searched in an undefined
9242 order and the first matching list is returned.
9243
9244 ${local_part:<string>}
9245
9246 The string is interpreted as an RFC 2822 address and the local part is
9247 extracted from it. If the string does not parse successfully, the result is
9248 empty.
9249
9250 ${mask:<IP address>/<bit count>}
9251
9252 If the form of the string to be operated on is not an IP address followed
9253 by a slash and an integer (that is, a network address in CIDR notation),
9254 the expansion fails. Otherwise, this operator converts the IP address to
9255 binary, masks off the least significant bits according to the bit count,
9256 and converts the result back to text, with mask appended. For example,
9257
9258 ${mask:10.111.131.206/28}
9259
9260 returns the string "10.111.131.192/28". Since this operation is expected to
9261 be mostly used for looking up masked addresses in files, the result for an
9262 IPv6 address uses dots to separate components instead of colons, because
9263 colon terminates a key string in lsearch files. So, for example,
9264
9265 ${mask:3ffe:ffff:836f:0a00:000a:0800:200a:c031/99}
9266
9267 returns the string
9268
9269 3ffe.ffff.836f.0a00.000a.0800.2000.0000/99
9270
9271 Letters in IPv6 addresses are always output in lower case.
9272
9273 ${md5:<string>}
9274
9275 The md5 operator computes the MD5 hash value of the string, and returns it
9276 as a 32-digit hexadecimal number, in which any letters are in lower case.
9277
9278 ${nhash_<n>_<m>:<string>}
9279
9280 The nhash operator is a simpler interface to the numeric hashing function
9281 that can be used when the two parameters are fixed numbers (as opposed to
9282 strings that change when expanded). The effect is the same as
9283
9284 ${nhash{<n>}{<m>}{<string>}}
9285
9286 See the description of the general nhash item above for details.
9287
9288 ${quote:<string>}
9289
9290 The quote operator puts its argument into double quotes if it is an empty
9291 string or contains anything other than letters, digits, underscores, dots,
9292 and hyphens. Any occurrences of double quotes and backslashes are escaped
9293 with a backslash. Newlines and carriage returns are converted to "\n" and "
9294 \r", respectively For example,
9295
9296 ${quote:ab"*"cd}
9297
9298 becomes
9299
9300 "ab\"*\"cd"
9301
9302 The place where this is useful is when the argument is a substitution from
9303 a variable or a message header.
9304
9305 ${quote_local_part:<string>}
9306
9307 This operator is like quote, except that it quotes the string only if
9308 required to do so by the rules of RFC 2822 for quoting local parts. For
9309 example, a plus sign would not cause quoting (but it would for quote). If
9310 you are creating a new email address from the contents of $local_part (or
9311 any other unknown data), you should always use this operator.
9312
9313 ${quote_<lookup-type>:<string>}
9314
9315 This operator applies lookup-specific quoting rules to the string. Each
9316 query-style lookup type has its own quoting rules which are described with
9317 the lookups in chapter 9. For example,
9318
9319 ${quote_ldap:two * two}
9320
9321 returns
9322
9323 two%20%5C2A%20two
9324
9325 For single-key lookup types, no quoting is ever necessary and this operator
9326 yields an unchanged string.
9327
9328 ${randint:<n>}
9329
9330 This operator returns a somewhat random number which is less than the
9331 supplied number and is at least 0. The quality of this randomness depends
9332 on how Exim was built; the values are not suitable for keying material. If
9333 Exim is linked against OpenSSL then RAND_pseudo_bytes() is used. If Exim is
9334 linked against GnuTLS then gnutls_rnd(GNUTLS_RND_NONCE) is used, for
9335 versions of GnuTLS with that function. Otherwise, the implementation may be
9336 arc4random(), random() seeded by srandomdev() or srandom(), or a custom
9337 implementation even weaker than random().
9338
9339 ${reverse_ip:<ipaddr>}
9340
9341 This operator reverses an IP address; for IPv4 addresses, the result is in
9342 dotted-quad decimal form, while for IPv6 addreses the result is in
9343 dotted-nibble hexadecimal form. In both cases, this is the "natural" form
9344 for DNS. For example,
9345
9346 ${reverse_ip:192.0.2.4}
9347 ${reverse_ip:2001:0db8:c42:9:1:abcd:192.0.2.127}
9348
9349 returns
9350
9351 4.2.0.192
9352 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
9353
9354 ${rfc2047:<string>}
9355
9356 This operator encodes text according to the rules of RFC 2047. This is an
9357 encoding that is used in header lines to encode non-ASCII characters. It is
9358 assumed that the input string is in the encoding specified by the
9359 headers_charset option, which defaults to ISO-8859-1. If the string
9360 contains only characters in the range 33-126, and no instances of the
9361 characters
9362
9363 ? = ( ) < > @ , ; : \ " . [ ] _
9364
9365 it is not modified. Otherwise, the result is the RFC 2047 encoding of the
9366 string, using as many "encoded words" as necessary to encode all the
9367 characters.
9368
9369 ${rfc2047d:<string>}
9370
9371 This operator decodes strings that are encoded as per RFC 2047. Binary zero
9372 bytes are replaced by question marks. Characters are converted into the
9373 character set defined by headers_charset. Overlong RFC 2047 "words" are not
9374 recognized unless check_rfc2047_length is set false.
9375
9376 Note: If you use $header_xxx: (or $h_xxx:) to access a header line, RFC
9377 2047 decoding is done automatically. You do not need to use this operator
9378 as well.
9379
9380 ${rxquote:<string>}
9381
9382 The rxquote operator inserts a backslash before any non-alphanumeric
9383 characters in its argument. This is useful when substituting the values of
9384 variables or headers inside regular expressions.
9385
9386 ${sha1:<string>}
9387
9388 The sha1 operator computes the SHA-1 hash value of the string, and returns
9389 it as a 40-digit hexadecimal number, in which any letters are in upper
9390 case.
9391
9392 ${sha256:<certificate>}
9393
9394 The sha256 operator computes the SHA-256 hash fingerprint of the
9395 certificate, and returns it as a 64-digit hexadecimal number, in which any
9396 letters are in upper case. Only arguments which are a single variable of
9397 certificate type are supported.
9398
9399 ${stat:<string>}
9400
9401 The string, after expansion, must be a file path. A call to the stat()
9402 function is made for this path. If stat() fails, an error occurs and the
9403 expansion fails. If it succeeds, the data from the stat replaces the item,
9404 as a series of <name>=<value> pairs, where the values are all numerical,
9405 except for the value of "smode". The names are: "mode" (giving the mode as
9406 a 4-digit octal number), "smode" (giving the mode in symbolic format as a
9407 10-character string, as for the ls command), "inode", "device", "links",
9408 "uid", "gid", "size", "atime", "mtime", and "ctime". You can extract
9409 individual fields using the extract expansion item.
9410
9411 The use of the stat expansion in users' filter files can be locked out by
9412 the system administrator. Warning: The file size may be incorrect on 32-bit
9413 systems for files larger than 2GB.
9414
9415 ${str2b64:<string>}
9416
9417 This operator converts a string into one that is base64 encoded.
9418
9419 ${strlen:<string>}
9420
9421 The item is replace by the length of the expanded string, expressed as a
9422 decimal number. Note: Do not confuse strlen with length.
9423
9424 ${substr_<start>_<length>:<string>}
9425
9426 The substr operator is a simpler interface to the substr function that can
9427 be used when the two parameters are fixed numbers (as opposed to strings
9428 that change when expanded). The effect is the same as
9429
9430 ${substr{<start>}{<length>}{<string>}}
9431
9432 See the description of the general substr item above for details. The
9433 abbreviation s can be used when substr is used as an operator.
9434
9435 ${time_eval:<string>}
9436
9437 This item converts an Exim time interval such as "2d4h5m" into a number of
9438 seconds.
9439
9440 ${time_interval:<string>}
9441
9442 The argument (after sub-expansion) must be a sequence of decimal digits
9443 that represents an interval of time as a number of seconds. It is converted
9444 into a number of larger units and output in Exim's normal time format, for
9445 example, "1w3d4h2m6s".
9446
9447 ${uc:<string>}
9448
9449 This forces the letters in the string into upper-case.
9450
9451 ${utf8clean:<string>}
9452
9453 This replaces any invalid utf-8 sequence in the string by the character "?
9454 ".
9455
9456
9457 11.7 Expansion conditions
9458 -------------------------
9459
9460 The following conditions are available for testing by the ${if construct while
9461 expanding strings:
9462
9463 !<condition>
9464
9465 Preceding any condition with an exclamation mark negates the result of the
9466 condition.
9467
9468 <symbolic operator> {<string1>}{<string2>}
9469
9470 There are a number of symbolic operators for doing numeric comparisons.
9471 They are:
9472
9473 = equal
9474 == equal
9475 > greater
9476 >= greater or equal
9477 < less
9478 <= less or equal
9479
9480 For example:
9481
9482 ${if >{$message_size}{10M} ...
9483
9484 Note that the general negation operator provides for inequality testing.
9485 The two strings must take the form of optionally signed decimal integers,
9486 optionally followed by one of the letters "K", "M" or "G" (in either upper
9487 or lower case), signifying multiplication by 1024, 1024*1024 or
9488 1024*1024*1024, respectively. As a special case, the numerical value of an
9489 empty string is taken as zero.
9490
9491 In all cases, a relative comparator OP is testing if <string1> OP <string2
9492 >; the above example is checking if $message_size is larger than 10M, not
9493 if 10M is larger than $message_size.
9494
9495 acl {{<name>}{<arg1>}{<arg2>}...}
9496
9497 The name and zero to nine argument strings are first expanded separately.
9498 The expanded arguments are assigned to the variables $acl_arg1 to $acl_arg9
9499 in order. Any unused are made empty. The variable $acl_narg is set to the
9500 number of arguments. The named ACL (see chapter 42) is called and may use
9501 the variables; if another acl expansion is used the values are restored
9502 after it returns. If the ACL sets a value using a "message =" modifier the
9503 variable $value becomes the result of the expansion, otherwise it is empty.
9504 If the ACL returns accept the condition is true; if deny, false. If the ACL
9505 returns defer the result is a forced-fail.
9506
9507 bool {<string>}
9508
9509 This condition turns a string holding a true or false representation into a
9510 boolean state. It parses "true", "false", "yes" and "no"
9511 (case-insensitively); also integer numbers map to true if non-zero, false
9512 if zero. An empty string is treated as false. Leading and trailing
9513 whitespace is ignored; thus a string consisting only of whitespace is
9514 false. All other string values will result in expansion failure.
9515
9516 When combined with ACL variables, this expansion condition will let you
9517 make decisions in one place and act on those decisions in another place.
9518 For example:
9519
9520 ${if bool{$acl_m_privileged_sender} ...
9521
9522 bool_lax {<string>}
9523
9524 Like bool, this condition turns a string into a boolean state. But where
9525 bool accepts a strict set of strings, bool_lax uses the same loose
9526 definition that the Router condition option uses. The empty string and the
9527 values "false", "no" and "0" map to false, all others map to true. Leading
9528 and trailing whitespace is ignored.
9529
9530 Note that where "bool{00}" is false, "bool_lax{00}" is true.
9531
9532 crypteq {<string1>}{<string2>}
9533
9534 This condition is included in the Exim binary if it is built to support any
9535 authentication mechanisms (see chapter 33). Otherwise, it is necessary to
9536 define SUPPORT_CRYPTEQ in Local/Makefile to get crypteq included in the
9537 binary.
9538
9539 The crypteq condition has two arguments. The first is encrypted and
9540 compared against the second, which is already encrypted. The second string
9541 may be in the LDAP form for storing encrypted strings, which starts with
9542 the encryption type in curly brackets, followed by the data. If the second
9543 string does not begin with "{" it is assumed to be encrypted with crypt()
9544 or crypt16() (see below), since such strings cannot begin with "{".
9545 Typically this will be a field from a password file. An example of an
9546 encrypted string in LDAP form is:
9547
9548 {md5}CY9rzUYh03PK3k6DJie09g==
9549
9550 If such a string appears directly in an expansion, the curly brackets have
9551 to be quoted, because they are part of the expansion syntax. For example:
9552
9553 ${if crypteq {test}{\{md5\}CY9rzUYh03PK3k6DJie09g==}{yes}{no}}
9554
9555 The following encryption types (whose names are matched case-independently)
9556 are supported:
9557
9558 * {md5} computes the MD5 digest of the first string, and expresses this
9559 as printable characters to compare with the remainder of the second
9560 string. If the length of the comparison string is 24, Exim assumes that
9561 it is base64 encoded (as in the above example). If the length is 32,
9562 Exim assumes that it is a hexadecimal encoding of the MD5 digest. If
9563 the length not 24 or 32, the comparison fails.
9564
9565 * {sha1} computes the SHA-1 digest of the first string, and expresses
9566 this as printable characters to compare with the remainder of the
9567 second string. If the length of the comparison string is 28, Exim
9568 assumes that it is base64 encoded. If the length is 40, Exim assumes
9569 that it is a hexadecimal encoding of the SHA-1 digest. If the length is
9570 not 28 or 40, the comparison fails.
9571
9572 * {crypt} calls the crypt() function, which traditionally used to use
9573 only the first eight characters of the password. However, in modern
9574 operating systems this is no longer true, and in many cases the entire
9575 password is used, whatever its length.
9576
9577 * {crypt16} calls the crypt16() function, which was originally created to
9578 use up to 16 characters of the password in some operating systems.
9579 Again, in modern operating systems, more characters may be used.
9580
9581 Exim has its own version of crypt16(), which is just a double call to crypt
9582 (). For operating systems that have their own version, setting HAVE_CRYPT16
9583 in Local/Makefile when building Exim causes it to use the operating system
9584 version instead of its own. This option is set by default in the
9585 OS-dependent Makefile for those operating systems that are known to support
9586 crypt16().
9587
9588 Some years after Exim's crypt16() was implemented, a user discovered that
9589 it was not using the same algorithm as some operating systems' versions. It
9590 turns out that as well as crypt16() there is a function called bigcrypt()
9591 in some operating systems. This may or may not use the same algorithm, and
9592 both of them may be different to Exim's built-in crypt16().
9593
9594 However, since there is now a move away from the traditional crypt()
9595 functions towards using SHA1 and other algorithms, tidying up this area of
9596 Exim is seen as very low priority.
9597
9598 If you do not put a encryption type (in curly brackets) in a crypteq
9599 comparison, the default is usually either "{crypt}" or "{crypt16}", as
9600 determined by the setting of DEFAULT_CRYPT in Local/Makefile. The default
9601 default is "{crypt}". Whatever the default, you can always use either
9602 function by specifying it explicitly in curly brackets.
9603
9604 def:<variable name>
9605
9606 The def condition must be followed by the name of one of the expansion
9607 variables defined in section 11.9. The condition is true if the variable
9608 does not contain the empty string. For example:
9609
9610 ${if def:sender_ident {from $sender_ident}}
9611
9612 Note that the variable name is given without a leading $ character. If the
9613 variable does not exist, the expansion fails.
9614
9615 def:header_<header name>: or def:h_<header name>:
9616
9617 This condition is true if a message is being processed and the named header
9618 exists in the message. For example,
9619
9620 ${if def:header_reply-to:{$h_reply-to:}{$h_from:}}
9621
9622 Note: No $ appears before header_ or h_ in the condition, and the header
9623 name must be terminated by a colon if white space does not follow.
9624
9625 eq {<string1>}{<string2>}, eqi {<string1>}{<string2>}
9626
9627 The two substrings are first expanded. The condition is true if the two
9628 resulting strings are identical. For eq the comparison includes the case of
9629 letters, whereas for eqi the comparison is case-independent.
9630
9631 exists {<file name>}
9632
9633 The substring is first expanded and then interpreted as an absolute path.
9634 The condition is true if the named file (or directory) exists. The
9635 existence test is done by calling the stat() function. The use of the
9636 exists test in users' filter files may be locked out by the system
9637 administrator.
9638
9639 first_delivery
9640
9641 This condition, which has no data, is true during a message's first
9642 delivery attempt. It is false during any subsequent delivery attempts.
9643
9644 forall{<a list>}{<a condition>}, forany{<a list>}{<a condition>}
9645
9646 These conditions iterate over a list. The first argument is expanded to
9647 form the list. By default, the list separator is a colon, but it can be
9648 changed by the normal method. The second argument is interpreted as a
9649 condition that is to be applied to each item in the list in turn. During
9650 the interpretation of the condition, the current list item is placed in a
9651 variable called $item.
9652
9653 * For forany, interpretation stops if the condition is true for any item,
9654 and the result of the whole condition is true. If the condition is
9655 false for all items in the list, the overall condition is false.
9656
9657 * For forall, interpretation stops if the condition is false for any
9658 item, and the result of the whole condition is false. If the condition
9659 is true for all items in the list, the overall condition is true.
9660
9661 Note that negation of forany means that the condition must be false for all
9662 items for the overall condition to succeed, and negation of forall means
9663 that the condition must be false for at least one item. In this example,
9664 the list separator is changed to a comma:
9665
9666 ${if forany{<, $recipients}{match{$item}{^user3@}}{yes}{no}}
9667
9668 The value of $item is saved and restored while forany or forall is being
9669 processed, to enable these expansion items to be nested.
9670
9671 To scan a named list, expand it with the listnamed operator.
9672
9673 ge {<string1>}{<string2>}, gei {<string1>}{<string2>}
9674
9675 The two substrings are first expanded. The condition is true if the first
9676 string is lexically greater than or equal to the second string. For ge the
9677 comparison includes the case of letters, whereas for gei the comparison is
9678 case-independent.
9679
9680 gt {<string1>}{<string2>}, gti {<string1>}{<string2>}
9681
9682 The two substrings are first expanded. The condition is true if the first
9683 string is lexically greater than the second string. For gt the comparison
9684 includes the case of letters, whereas for gti the comparison is
9685 case-independent.
9686
9687 inlist {<string1>}{<string2>}, inlisti {<string1>}{<string2>}
9688
9689 Both strings are expanded; the second string is treated as a list of simple
9690 strings; if the first string is a member of the second, then the condition
9691 is true.
9692
9693 These are simpler to use versions of the more powerful forany condition.
9694 Examples, and the forany equivalents:
9695
9696 ${if inlist{needle}{foo:needle:bar}}
9697 ${if forany{foo:needle:bar}{eq{$item}{needle}}}
9698 ${if inlisti{Needle}{fOo:NeeDLE:bAr}}
9699 ${if forany{fOo:NeeDLE:bAr}{eqi{$item}{Needle}}}
9700
9701 isip {<string>}, isip4 {<string>}, isip6 {<string>}
9702
9703 The substring is first expanded, and then tested to see if it has the form
9704 of an IP address. Both IPv4 and IPv6 addresses are valid for isip, whereas
9705 isip4 and isip6 test specifically for IPv4 or IPv6 addresses.
9706
9707 For an IPv4 address, the test is for four dot-separated components, each of
9708 which consists of from one to three digits. For an IPv6 address, up to
9709 eight colon-separated components are permitted, each containing from one to
9710 four hexadecimal digits. There may be fewer than eight components if an
9711 empty component (adjacent colons) is present. Only one empty component is
9712 permitted.
9713
9714 Note: The checks are just on the form of the address; actual numerical
9715 values are not considered. Thus, for example, 999.999.999.999 passes the
9716 IPv4 check. The main use of these tests is to distinguish between IP
9717 addresses and host names, or between IPv4 and IPv6 addresses. For example,
9718 you could use
9719
9720 ${if isip4{$sender_host_address}...
9721
9722 to test which IP version an incoming SMTP connection is using.
9723
9724 ldapauth {<ldap query>}
9725
9726 This condition supports user authentication using LDAP. See section 9.13
9727 for details of how to use LDAP in lookups and the syntax of queries. For
9728 this use, the query must contain a user name and password. The query itself
9729 is not used, and can be empty. The condition is true if the password is not
9730 empty, and the user name and password are accepted by the LDAP server. An
9731 empty password is rejected without calling LDAP because LDAP binds with an
9732 empty password are considered anonymous regardless of the username, and
9733 will succeed in most configurations. See chapter 33 for details of SMTP
9734 authentication, and chapter 34 for an example of how this can be used.
9735
9736 le {<string1>}{<string2>}, lei {<string1>}{<string2>}
9737
9738 The two substrings are first expanded. The condition is true if the first
9739 string is lexically less than or equal to the second string. For le the
9740 comparison includes the case of letters, whereas for lei the comparison is
9741 case-independent.
9742
9743 lt {<string1>}{<string2>}, lti {<string1>}{<string2>}
9744
9745 The two substrings are first expanded. The condition is true if the first
9746 string is lexically less than the second string. For lt the comparison
9747 includes the case of letters, whereas for lti the comparison is
9748 case-independent.
9749
9750 match {<string1>}{<string2>}
9751
9752 The two substrings are first expanded. The second is then treated as a
9753 regular expression and applied to the first. Because of the pre-expansion,
9754 if the regular expression contains dollar, or backslash characters, they
9755 must be escaped. Care must also be taken if the regular expression contains
9756 braces (curly brackets). A closing brace must be escaped so that it is not
9757 taken as a premature termination of <string2>. The easiest approach is to
9758 use the "\N" feature to disable expansion of the regular expression. For
9759 example,
9760
9761 ${if match {$local_part}{\N^\d{3}\N} ...
9762
9763 If the whole expansion string is in double quotes, further escaping of
9764 backslashes is also required.
9765
9766 The condition is true if the regular expression match succeeds. The regular
9767 expression is not required to begin with a circumflex metacharacter, but if
9768 there is no circumflex, the expression is not anchored, and it may match
9769 anywhere in the subject, not just at the start. If you want the pattern to
9770 match at the end of the subject, you must include the "$" metacharacter at
9771 an appropriate point.
9772
9773 At the start of an if expansion the values of the numeric variable
9774 substitutions $1 etc. are remembered. Obeying a match condition that
9775 succeeds causes them to be reset to the substrings of that condition and
9776 they will have these values during the expansion of the success string. At
9777 the end of the if expansion, the previous values are restored. After
9778 testing a combination of conditions using or, the subsequent values of the
9779 numeric variables are those of the condition that succeeded.
9780
9781 match_address {<string1>}{<string2>}
9782
9783 See match_local_part.
9784
9785 match_domain {<string1>}{<string2>}
9786
9787 See match_local_part.
9788
9789 match_ip {<string1>}{<string2>}
9790
9791 This condition matches an IP address to a list of IP address patterns. It
9792 must be followed by two argument strings. The first (after expansion) must
9793 be an IP address or an empty string. The second (not expanded) is a
9794 restricted host list that can match only an IP address, not a host name.
9795 For example:
9796
9797 ${if match_ip{$sender_host_address}{1.2.3.4:5.6.7.8}{...}{...}}
9798
9799 The specific types of host list item that are permitted in the list are:
9800
9801 * An IP address, optionally with a CIDR mask.
9802
9803 * A single asterisk, which matches any IP address.
9804
9805 * An empty item, which matches only if the IP address is empty. This
9806 could be useful for testing for a locally submitted message or one from
9807 specific hosts in a single test such as
9808
9809 ${if match_ip{$sender_host_address}{:4.3.2.1:...}{...}{...}}
9810
9811 where the first item in the list is the empty string.
9812
9813 * The item @[] matches any of the local host's interface addresses.
9814
9815 * Single-key lookups are assumed to be like "net-" style lookups in host
9816 lists, even if "net-" is not specified. There is never any attempt to
9817 turn the IP address into a host name. The most common type of linear
9818 search for match_ip is likely to be iplsearch, in which the file can
9819 contain CIDR masks. For example:
9820
9821 ${if match_ip{$sender_host_address}{iplsearch;/some/file}...
9822
9823 It is of course possible to use other kinds of lookup, and in such a
9824 case, you do need to specify the "net-" prefix if you want to specify a
9825 specific address mask, for example:
9826
9827 ${if match_ip{$sender_host_address}{net24-dbm;/some/file}...
9828
9829 However, unless you are combining a match_ip condition with others, it
9830 is just as easy to use the fact that a lookup is itself a condition,
9831 and write:
9832
9833 ${lookup{${mask:$sender_host_address/24}}dbm{/a/file}...
9834
9835 Note that <string2> is not itself subject to string expansion, unless Exim
9836 was built with the EXPAND_LISTMATCH_RHS option.
9837
9838 Consult section 10.11 for further details of these patterns.
9839
9840 match_local_part {<string1>}{<string2>}
9841
9842 This condition, together with match_address and match_domain, make it
9843 possible to test domain, address, and local part lists within expansions.
9844 Each condition requires two arguments: an item and a list to match. A
9845 trivial example is:
9846
9847 ${if match_domain{a.b.c}{x.y.z:a.b.c:p.q.r}{yes}{no}}
9848
9849 In each case, the second argument may contain any of the allowable items
9850 for a list of the appropriate type. Also, because the second argument
9851 (after expansion) is a standard form of list, it is possible to refer to a
9852 named list. Thus, you can use conditions like this:
9853
9854 ${if match_domain{$domain}{+local_domains}{...
9855
9856 For address lists, the matching starts off caselessly, but the "+caseful"
9857 item can be used, as in all address lists, to cause subsequent items to
9858 have their local parts matched casefully. Domains are always matched
9859 caselessly.
9860
9861 Note that <string2> is not itself subject to string expansion, unless Exim
9862 was built with the EXPAND_LISTMATCH_RHS option.
9863
9864 Note: Host lists are not supported in this way. This is because hosts have
9865 two identities: a name and an IP address, and it is not clear how to
9866 specify cleanly how such a test would work. However, IP addresses can be
9867 matched using match_ip.
9868
9869 pam {<string1>:<string2>:...}
9870
9871 Pluggable Authentication Modules (http://www.kernel.org/pub/linux/libs/pam/
9872 ) are a facility that is available in the latest releases of Solaris and in
9873 some GNU/Linux distributions. The Exim support, which is intended for use
9874 in conjunction with the SMTP AUTH command, is available only if Exim is
9875 compiled with
9876
9877 SUPPORT_PAM=yes
9878
9879 in Local/Makefile. You probably need to add -lpam to EXTRALIBS, and in some
9880 releases of GNU/Linux -ldl is also needed.
9881
9882 The argument string is first expanded, and the result must be a
9883 colon-separated list of strings. Leading and trailing white space is
9884 ignored. The PAM module is initialized with the service name "exim" and the
9885 user name taken from the first item in the colon-separated data string (<
9886 string1>). The remaining items in the data string are passed over in
9887 response to requests from the authentication function. In the simple case
9888 there will only be one request, for a password, so the data consists of
9889 just two strings.
9890
9891 There can be problems if any of the strings are permitted to contain colon
9892 characters. In the usual way, these have to be doubled to avoid being taken
9893 as separators. If the data is being inserted from a variable, the sg
9894 expansion item can be used to double any existing colons. For example, the
9895 configuration of a LOGIN authenticator might contain this setting:
9896
9897 server_condition = ${if pam{$auth1:${sg{$auth2}{:}{::}}}}
9898
9899 For a PLAIN authenticator you could use:
9900
9901 server_condition = ${if pam{$auth2:${sg{$auth3}{:}{::}}}}
9902
9903 In some operating systems, PAM authentication can be done only from a
9904 process running as root. Since Exim is running as the Exim user when
9905 receiving messages, this means that PAM cannot be used directly in those
9906 systems. A patched version of the pam_unix module that comes with the Linux
9907 PAM package is available from http://www.e-admin.de/pam_exim/. The patched
9908 module allows one special uid/gid combination, in addition to root, to
9909 authenticate. If you build the patched module to allow the Exim user and
9910 group, PAM can then be used from an Exim authenticator.
9911
9912 pwcheck {<string1>:<string2>}
9913
9914 This condition supports user authentication using the Cyrus pwcheck daemon.
9915 This is one way of making it possible for passwords to be checked by a
9916 process that is not running as root. Note: The use of pwcheck is now
9917 deprecated. Its replacement is saslauthd (see below).
9918
9919 The pwcheck support is not included in Exim by default. You need to specify
9920 the location of the pwcheck daemon's socket in Local/Makefile before
9921 building Exim. For example:
9922
9923 CYRUS_PWCHECK_SOCKET=/var/pwcheck/pwcheck
9924
9925 You do not need to install the full Cyrus software suite in order to use
9926 the pwcheck daemon. You can compile and install just the daemon alone from
9927 the Cyrus SASL library. Ensure that exim is the only user that has access
9928 to the /var/pwcheck directory.
9929
9930 The pwcheck condition takes one argument, which must be the user name and
9931 password, separated by a colon. For example, in a LOGIN authenticator
9932 configuration, you might have this:
9933
9934 server_condition = ${if pwcheck{$auth1:$auth2}}
9935
9936 Again, for a PLAIN authenticator configuration, this would be:
9937
9938 server_condition = ${if pwcheck{$auth2:$auth3}}
9939
9940 queue_running
9941
9942 This condition, which has no data, is true during delivery attempts that
9943 are initiated by queue runner processes, and false otherwise.
9944
9945 radius {<authentication string>}
9946
9947 Radius authentication (RFC 2865) is supported in a similar way to PAM. You
9948 must set RADIUS_CONFIG_FILE in Local/Makefile to specify the location of
9949 the Radius client configuration file in order to build Exim with Radius
9950 support.
9951
9952 With just that one setting, Exim expects to be linked with the radiusclient
9953 library, using the original API. If you are using release 0.4.0 or later of
9954 this library, you need to set
9955
9956 RADIUS_LIB_TYPE=RADIUSCLIENTNEW
9957
9958 in Local/Makefile when building Exim. You can also link Exim with the
9959 libradius library that comes with FreeBSD. To do this, set
9960
9961 RADIUS_LIB_TYPE=RADLIB
9962
9963 in Local/Makefile, in addition to setting RADIUS_CONFIGURE_FILE. You may
9964 also have to supply a suitable setting in EXTRALIBS so that the Radius
9965 library can be found when Exim is linked.
9966
9967 The string specified by RADIUS_CONFIG_FILE is expanded and passed to the
9968 Radius client library, which calls the Radius server. The condition is true
9969 if the authentication is successful. For example:
9970
9971 server_condition = ${if radius{<arguments>}}
9972
9973 saslauthd {{<user>}{<password>}{<service>}{<realm>}}
9974
9975 This condition supports user authentication using the Cyrus saslauthd
9976 daemon. This replaces the older pwcheck daemon, which is now deprecated.
9977 Using this daemon is one way of making it possible for passwords to be
9978 checked by a process that is not running as root.
9979
9980 The saslauthd support is not included in Exim by default. You need to
9981 specify the location of the saslauthd daemon's socket in Local/Makefile
9982 before building Exim. For example:
9983
9984 CYRUS_SASLAUTHD_SOCKET=/var/state/saslauthd/mux
9985
9986 You do not need to install the full Cyrus software suite in order to use
9987 the saslauthd daemon. You can compile and install just the daemon alone
9988 from the Cyrus SASL library.
9989
9990 Up to four arguments can be supplied to the saslauthd condition, but only
9991 two are mandatory. For example:
9992
9993 server_condition = ${if saslauthd{{$auth1}{$auth2}}}
9994
9995 The service and the realm are optional (which is why the arguments are
9996 enclosed in their own set of braces). For details of the meaning of the
9997 service and realm, and how to run the daemon, consult the Cyrus
9998 documentation.
9999
10000
10001 11.8 Combining expansion conditions
10002 -----------------------------------
10003
10004 Several conditions can be tested at once by combining them using the and and or
10005 combination conditions. Note that and and or are complete conditions on their
10006 own, and precede their lists of sub-conditions. Each sub-condition must be
10007 enclosed in braces within the overall braces that contain the list. No
10008 repetition of if is used.
10009
10010 or {{<cond1>}{<cond2>}...}
10011
10012 The sub-conditions are evaluated from left to right. The condition is true
10013 if any one of the sub-conditions is true. For example,
10014
10015 ${if or {{eq{$local_part}{spqr}}{eq{$domain}{testing.com}}}...
10016
10017 When a true sub-condition is found, the following ones are parsed but not
10018 evaluated. If there are several "match" sub-conditions the values of the
10019 numeric variables afterwards are taken from the first one that succeeds.
10020
10021 and {{<cond1>}{<cond2>}...}
10022
10023 The sub-conditions are evaluated from left to right. The condition is true
10024 if all of the sub-conditions are true. If there are several "match"
10025 sub-conditions, the values of the numeric variables afterwards are taken
10026 from the last one. When a false sub-condition is found, the following ones
10027 are parsed but not evaluated.
10028
10029
10030 11.9 Expansion variables
10031 ------------------------
10032
10033 This section contains an alphabetical list of all the expansion variables. Some
10034 of them are available only when Exim is compiled with specific options such as
10035 support for TLS or the content scanning extension.
10036
10037 $0, $1, etc
10038
10039 When a match expansion condition succeeds, these variables contain the
10040 captured substrings identified by the regular expression during subsequent
10041 processing of the success string of the containing if expansion item.
10042 However, they do not retain their values afterwards; in fact, their
10043 previous values are restored at the end of processing an if item. The
10044 numerical variables may also be set externally by some other matching
10045 process which precedes the expansion of the string. For example, the
10046 commands available in Exim filter files include an if command with its own
10047 regular expression matching condition.
10048
10049 $acl_arg1, $acl_arg2, etc
10050
10051 Within an acl condition, expansion condition or expansion item any
10052 arguments are copied to these variables, any unused variables being made
10053 empty.
10054
10055 $acl_c...
10056
10057 Values can be placed in these variables by the set modifier in an ACL. They
10058 can be given any name that starts with $acl_c and is at least six
10059 characters long, but the sixth character must be either a digit or an
10060 underscore. For example: $acl_c5, $acl_c_mycount. The values of the
10061 $acl_c... variables persist throughout the lifetime of an SMTP connection.
10062 They can be used to pass information between ACLs and between different
10063 invocations of the same ACL. When a message is received, the values of
10064 these variables are saved with the message, and can be accessed by filters,
10065 routers, and transports during subsequent delivery.
10066
10067 $acl_m...
10068
10069 These variables are like the $acl_c... variables, except that their values
10070 are reset after a message has been received. Thus, if several messages are
10071 received in one SMTP connection, $acl_m... values are not passed on from
10072 one message to the next, as $acl_c... values are. The $acl_m... variables
10073 are also reset by MAIL, RSET, EHLO, HELO, and after starting a TLS session.
10074 When a message is received, the values of these variables are saved with
10075 the message, and can be accessed by filters, routers, and transports during
10076 subsequent delivery.
10077
10078 $acl_narg
10079
10080 Within an acl condition, expansion condition or expansion item this
10081 variable has the number of arguments.
10082
10083 $acl_verify_message
10084
10085 After an address verification has failed, this variable contains the
10086 failure message. It retains its value for use in subsequent modifiers. The
10087 message can be preserved by coding like this:
10088
10089 warn !verify = sender
10090 set acl_m0 = $acl_verify_message
10091
10092 You can use $acl_verify_message during the expansion of the message or
10093 log_message modifiers, to include information about the verification
10094 failure.
10095
10096 $address_data
10097
10098 This variable is set by means of the address_data option in routers. The
10099 value then remains with the address while it is processed by subsequent
10100 routers and eventually a transport. If the transport is handling multiple
10101 addresses, the value from the first address is used. See chapter 15 for
10102 more details. Note: The contents of $address_data are visible in user
10103 filter files.
10104
10105 If $address_data is set when the routers are called from an ACL to verify a
10106 recipient address, the final value is still in the variable for subsequent
10107 conditions and modifiers of the ACL statement. If routing the address
10108 caused it to be redirected to just one address, the child address is also
10109 routed as part of the verification, and in this case the final value of
10110 $address_data is from the child's routing.
10111
10112 If $address_data is set when the routers are called from an ACL to verify a
10113 sender address, the final value is also preserved, but this time in
10114 $sender_address_data, to distinguish it from data from a recipient address.
10115
10116 In both cases (recipient and sender verification), the value does not
10117 persist after the end of the current ACL statement. If you want to preserve
10118 these values for longer, you can save them in ACL variables.
10119
10120 $address_file
10121
10122 When, as a result of aliasing, forwarding, or filtering, a message is
10123 directed to a specific file, this variable holds the name of the file when
10124 the transport is running. At other times, the variable is empty. For
10125 example, using the default configuration, if user r2d2 has a .forward file
10126 containing
10127
10128 /home/r2d2/savemail
10129
10130 then when the address_file transport is running, $address_file contains the
10131 text string "/home/r2d2/savemail". For Sieve filters, the value may be
10132 "inbox" or a relative folder name. It is then up to the transport
10133 configuration to generate an appropriate absolute path to the relevant
10134 file.
10135
10136 $address_pipe
10137
10138 When, as a result of aliasing or forwarding, a message is directed to a
10139 pipe, this variable holds the pipe command when the transport is running.
10140
10141 $auth1 - $auth3
10142
10143 These variables are used in SMTP authenticators (see chapters 34-40).
10144 Elsewhere, they are empty.
10145
10146 $authenticated_id
10147
10148 When a server successfully authenticates a client it may be configured to
10149 preserve some of the authentication information in the variable
10150 $authenticated_id (see chapter 33). For example, a user/password
10151 authenticator configuration might preserve the user name for use in the
10152 routers. Note that this is not the same information that is saved in
10153 $sender_host_authenticated. When a message is submitted locally (that is,
10154 not over a TCP connection) the value of $authenticated_id is normally the
10155 login name of the calling process. However, a trusted user can override
10156 this by means of the -oMai command line option.
10157
10158 $authenticated_fail_id
10159
10160 When an authentication attempt fails, the variable $authenticated_fail_id
10161 will contain the failed authentication id. If more than one authentication
10162 id is attempted, it will contain only the last one. The variable is
10163 available for processing in the ACL's, generally the quit or notquit ACL. A
10164 message to a local recipient could still be accepted without requiring
10165 authentication, which means this variable could also be visible in all of
10166 the ACL's as well.
10167
10168 $authenticated_sender
10169
10170 When acting as a server, Exim takes note of the AUTH= parameter on an
10171 incoming SMTP MAIL command if it believes the sender is sufficiently
10172 trusted, as described in section 33.2. Unless the data is the string "<>",
10173 it is set as the authenticated sender of the message, and the value is
10174 available during delivery in the $authenticated_sender variable. If the
10175 sender is not trusted, Exim accepts the syntax of AUTH=, but ignores the
10176 data.
10177
10178 When a message is submitted locally (that is, not over a TCP connection),
10179 the value of $authenticated_sender is an address constructed from the login
10180 name of the calling process and $qualify_domain, except that a trusted user
10181 can override this by means of the -oMas command line option.
10182
10183 $authentication_failed
10184
10185 This variable is set to "1" in an Exim server if a client issues an AUTH
10186 command that does not succeed. Otherwise it is set to "0". This makes it
10187 possible to distinguish between "did not try to authenticate" (
10188 $sender_host_authenticated is empty and $authentication_failed is set to
10189 "0") and "tried to authenticate but failed" ($sender_host_authenticated is
10190 empty and $authentication_failed is set to "1"). Failure includes any
10191 negative response to an AUTH command, including (for example) an attempt to
10192 use an undefined mechanism.
10193
10194 $av_failed
10195
10196 This variable is available when Exim is compiled with the content-scanning
10197 extension. It is set to "0" by default, but will be set to "1" if any
10198 problem occurs with the virus scanner (specified by av_scanner) during the
10199 ACL malware condition.
10200
10201 $body_linecount
10202
10203 When a message is being received or delivered, this variable contains the
10204 number of lines in the message's body. See also $message_linecount.
10205
10206 $body_zerocount
10207
10208 When a message is being received or delivered, this variable contains the
10209 number of binary zero bytes (ASCII NULs) in the message's body.
10210
10211 $bounce_recipient
10212
10213 This is set to the recipient address of a bounce message while Exim is
10214 creating it. It is useful if a customized bounce message text file is in
10215 use (see chapter 48).
10216
10217 $bounce_return_size_limit
10218
10219 This contains the value set in the bounce_return_size_limit option, rounded
10220 up to a multiple of 1000. It is useful when a customized error message text
10221 file is in use (see chapter 48).
10222
10223 $caller_gid
10224
10225 The real group id under which the process that called Exim was running.
10226 This is not the same as the group id of the originator of a message (see
10227 $originator_gid). If Exim re-execs itself, this variable in the new
10228 incarnation normally contains the Exim gid.
10229
10230 $caller_uid
10231
10232 The real user id under which the process that called Exim was running. This
10233 is not the same as the user id of the originator of a message (see
10234 $originator_uid). If Exim re-execs itself, this variable in the new
10235 incarnation normally contains the Exim uid.
10236
10237 $compile_date
10238
10239 The date on which the Exim binary was compiled.
10240
10241 $compile_number
10242
10243 The building process for Exim keeps a count of the number of times it has
10244 been compiled. This serves to distinguish different compilations of the
10245 same version of the program.
10246
10247 $demime_errorlevel
10248
10249 This variable is available when Exim is compiled with the content-scanning
10250 extension and the obsolete demime condition. For details, see section 43.6.
10251
10252 $demime_reason
10253
10254 This variable is available when Exim is compiled with the content-scanning
10255 extension and the obsolete demime condition. For details, see section 43.6.
10256
10257 $dnslist_domain, $dnslist_matched, $dnslist_text, $dnslist_value
10258
10259 When a DNS (black) list lookup succeeds, these variables are set to contain
10260 the following data from the lookup: the list's domain name, the key that
10261 was looked up, the contents of any associated TXT record, and the value
10262 from the main A record. See section 42.32 for more details.
10263
10264 $domain
10265
10266 When an address is being routed, or delivered on its own, this variable
10267 contains the domain. Uppercase letters in the domain are converted into
10268 lower case for $domain.
10269
10270 Global address rewriting happens when a message is received, so the value
10271 of $domain during routing and delivery is the value after rewriting.
10272 $domain is set during user filtering, but not during system filtering,
10273 because a message may have many recipients and the system filter is called
10274 just once.
10275
10276 When more than one address is being delivered at once (for example, several
10277 RCPT commands in one SMTP delivery), $domain is set only if they all have
10278 the same domain. Transports can be restricted to handling only one domain
10279 at a time if the value of $domain is required at transport time - this is
10280 the default for local transports. For further details of the environment in
10281 which local transports are run, see chapter 23.
10282
10283 At the end of a delivery, if all deferred addresses have the same domain,
10284 it is set in $domain during the expansion of delay_warning_condition.
10285
10286 The $domain variable is also used in some other circumstances:
10287
10288 * When an ACL is running for a RCPT command, $domain contains the domain
10289 of the recipient address. The domain of the sender address is in
10290 $sender_address_domain at both MAIL time and at RCPT time. $domain is
10291 not normally set during the running of the MAIL ACL. However, if the
10292 sender address is verified with a callout during the MAIL ACL, the
10293 sender domain is placed in $domain during the expansions of hosts,
10294 interface, and port in the smtp transport.
10295
10296 * When a rewrite item is being processed (see chapter 31), $domain
10297 contains the domain portion of the address that is being rewritten; it
10298 can be used in the expansion of the replacement address, for example,
10299 to rewrite domains by file lookup.
10300
10301 * With one important exception, whenever a domain list is being scanned,
10302 $domain contains the subject domain. Exception: When a domain list in a
10303 sender_domains condition in an ACL is being processed, the subject
10304 domain is in $sender_address_domain and not in $domain. It works this
10305 way so that, in a RCPT ACL, the sender domain list can be dependent on
10306 the recipient domain (which is what is in $domain at this time).
10307
10308 * When the smtp_etrn_command option is being expanded, $domain contains
10309 the complete argument of the ETRN command (see section 47.8).
10310
10311 $domain_data
10312
10313 When the domains option on a router matches a domain by means of a lookup,
10314 the data read by the lookup is available during the running of the router
10315 as $domain_data. In addition, if the driver routes the address to a
10316 transport, the value is available in that transport. If the transport is
10317 handling multiple addresses, the value from the first address is used.
10318
10319 $domain_data is also set when the domains condition in an ACL matches a
10320 domain by means of a lookup. The data read by the lookup is available
10321 during the rest of the ACL statement. In all other situations, this
10322 variable expands to nothing.
10323
10324 $exim_gid
10325
10326 This variable contains the numerical value of the Exim group id.
10327
10328 $exim_path
10329
10330 This variable contains the path to the Exim binary.
10331
10332 $exim_uid
10333
10334 This variable contains the numerical value of the Exim user id.
10335
10336 $found_extension
10337
10338 This variable is available when Exim is compiled with the content-scanning
10339 extension and the obsolete demime condition. For details, see section 43.6.
10340
10341 $header_<name>
10342
10343 This is not strictly an expansion variable. It is expansion syntax for
10344 inserting the message header line with the given name. Note that the name
10345 must be terminated by colon or white space, because it may contain a wide
10346 variety of characters. Note also that braces must not be used.
10347
10348 $headers_added
10349
10350 Within an ACL this variable contains the headers added so far by the ACL
10351 modifier add_header (section 42.24). The headers are a newline-separated
10352 list.
10353
10354 $home
10355
10356 When the check_local_user option is set for a router, the user's home
10357 directory is placed in $home when the check succeeds. In particular, this
10358 means it is set during the running of users' filter files. A router may
10359 also explicitly set a home directory for use by a transport; this can be
10360 overridden by a setting on the transport itself.
10361
10362 When running a filter test via the -bf option, $home is set to the value of
10363 the environment variable HOME.
10364
10365 $host
10366
10367 If a router assigns an address to a transport (any transport), and passes a
10368 list of hosts with the address, the value of $host when the transport
10369 starts to run is the name of the first host on the list. Note that this
10370 applies both to local and remote transports.
10371
10372 For the smtp transport, if there is more than one host, the value of $host
10373 changes as the transport works its way through the list. In particular,
10374 when the smtp transport is expanding its options for encryption using TLS,
10375 or for specifying a transport filter (see chapter 24), $host contains the
10376 name of the host to which it is connected.
10377
10378 When used in the client part of an authenticator configuration (see chapter
10379 33), $host contains the name of the server to which the client is
10380 connected.
10381
10382 $host_address
10383
10384 This variable is set to the remote host's IP address whenever $host is set
10385 for a remote connection. It is also set to the IP address that is being
10386 checked when the ignore_target_hosts option is being processed.
10387
10388 $host_data
10389
10390 If a hosts condition in an ACL is satisfied by means of a lookup, the
10391 result of the lookup is made available in the $host_data variable. This
10392 allows you, for example, to do things like this:
10393
10394 deny hosts = net-lsearch;/some/file
10395 message = $host_data
10396
10397 $host_lookup_deferred
10398
10399 This variable normally contains "0", as does $host_lookup_failed. When a
10400 message comes from a remote host and there is an attempt to look up the
10401 host's name from its IP address, and the attempt is not successful, one of
10402 these variables is set to "1".
10403
10404 * If the lookup receives a definite negative response (for example, a DNS
10405 lookup succeeded, but no records were found), $host_lookup_failed is
10406 set to "1".
10407
10408 * If there is any kind of problem during the lookup, such that Exim
10409 cannot tell whether or not the host name is defined (for example, a
10410 timeout for a DNS lookup), $host_lookup_deferred is set to "1".
10411
10412 Looking up a host's name from its IP address consists of more than just a
10413 single reverse lookup. Exim checks that a forward lookup of at least one of
10414 the names it receives from a reverse lookup yields the original IP address.
10415 If this is not the case, Exim does not accept the looked up name(s), and
10416 $host_lookup_failed is set to "1". Thus, being able to find a name from an
10417 IP address (for example, the existence of a PTR record in the DNS) is not
10418 sufficient on its own for the success of a host name lookup. If the reverse
10419 lookup succeeds, but there is a lookup problem such as a timeout when
10420 checking the result, the name is not accepted, and $host_lookup_deferred is
10421 set to "1". See also $sender_host_name.
10422
10423 $host_lookup_failed
10424
10425 See $host_lookup_deferred.
10426
10427 $inode
10428
10429 The only time this variable is set is while expanding the directory_file
10430 option in the appendfile transport. The variable contains the inode number
10431 of the temporary file which is about to be renamed. It can be used to
10432 construct a unique name for the file.
10433
10434 $interface_address
10435
10436 This is an obsolete name for $received_ip_address.
10437
10438 $interface_port
10439
10440 This is an obsolete name for $received_port.
10441
10442 $item
10443
10444 This variable is used during the expansion of forall and forany conditions
10445 (see section 11.7), and filter, map, and reduce items (see section 11.7).
10446 In other circumstances, it is empty.
10447
10448 $ldap_dn
10449
10450 This variable, which is available only when Exim is compiled with LDAP
10451 support, contains the DN from the last entry in the most recently
10452 successful LDAP lookup.
10453
10454 $load_average
10455
10456 This variable contains the system load average, multiplied by 1000 so that
10457 it is an integer. For example, if the load average is 0.21, the value of
10458 the variable is 210. The value is recomputed every time the variable is
10459 referenced.
10460
10461 $local_part
10462
10463 When an address is being routed, or delivered on its own, this variable
10464 contains the local part. When a number of addresses are being delivered
10465 together (for example, multiple RCPT commands in an SMTP session),
10466 $local_part is not set.
10467
10468 Global address rewriting happens when a message is received, so the value
10469 of $local_part during routing and delivery is the value after rewriting.
10470 $local_part is set during user filtering, but not during system filtering,
10471 because a message may have many recipients and the system filter is called
10472 just once.
10473
10474 If a local part prefix or suffix has been recognized, it is not included in
10475 the value of $local_part during routing and subsequent delivery. The values
10476 of any prefix or suffix are in $local_part_prefix and $local_part_suffix,
10477 respectively.
10478
10479 When a message is being delivered to a file, pipe, or autoreply transport
10480 as a result of aliasing or forwarding, $local_part is set to the local part
10481 of the parent address, not to the file name or command (see $address_file
10482 and $address_pipe).
10483
10484 When an ACL is running for a RCPT command, $local_part contains the local
10485 part of the recipient address.
10486
10487 When a rewrite item is being processed (see chapter 31), $local_part
10488 contains the local part of the address that is being rewritten; it can be
10489 used in the expansion of the replacement address, for example.
10490
10491 In all cases, all quoting is removed from the local part. For example, for
10492 both the addresses
10493
10494 "abc:xyz"@test.example
10495 abc\:xyz@test.example
10496
10497 the value of $local_part is
10498
10499 abc:xyz
10500
10501 If you use $local_part to create another address, you should always wrap it
10502 inside a quoting operator. For example, in a redirect router you could
10503 have:
10504
10505 data = ${quote_local_part:$local_part}@new.domain.example
10506
10507 Note: The value of $local_part is normally lower cased. If you want to
10508 process local parts in a case-dependent manner in a router, you can set the
10509 caseful_local_part option (see chapter 15).
10510
10511 $local_part_data
10512
10513 When the local_parts option on a router matches a local part by means of a
10514 lookup, the data read by the lookup is available during the running of the
10515 router as $local_part_data. In addition, if the driver routes the address
10516 to a transport, the value is available in that transport. If the transport
10517 is handling multiple addresses, the value from the first address is used.
10518
10519 $local_part_data is also set when the local_parts condition in an ACL
10520 matches a local part by means of a lookup. The data read by the lookup is
10521 available during the rest of the ACL statement. In all other situations,
10522 this variable expands to nothing.
10523
10524 $local_part_prefix
10525
10526 When an address is being routed or delivered, and a specific prefix for the
10527 local part was recognized, it is available in this variable, having been
10528 removed from $local_part.
10529
10530 $local_part_suffix
10531
10532 When an address is being routed or delivered, and a specific suffix for the
10533 local part was recognized, it is available in this variable, having been
10534 removed from $local_part.
10535
10536 $local_scan_data
10537
10538 This variable contains the text returned by the local_scan() function when
10539 a message is received. See chapter 44 for more details.
10540
10541 $local_user_gid
10542
10543 See $local_user_uid.
10544
10545 $local_user_uid
10546
10547 This variable and $local_user_gid are set to the uid and gid after the
10548 check_local_user router precondition succeeds. This means that their values
10549 are available for the remaining preconditions (senders, require_files, and
10550 condition), for the address_data expansion, and for any router-specific
10551 expansions. At all other times, the values in these variables are "(uid_t)
10552 (-1)" and "(gid_t)(-1)", respectively.
10553
10554 $localhost_number
10555
10556 This contains the expanded value of the localhost_number option. The
10557 expansion happens after the main options have been read.
10558
10559 $log_inodes
10560
10561 The number of free inodes in the disk partition where Exim's log files are
10562 being written. The value is recalculated whenever the variable is
10563 referenced. If the relevant file system does not have the concept of
10564 inodes, the value of is -1. See also the check_log_inodes option.
10565
10566 $log_space
10567
10568 The amount of free space (as a number of kilobytes) in the disk partition
10569 where Exim's log files are being written. The value is recalculated
10570 whenever the variable is referenced. If the operating system does not have
10571 the ability to find the amount of free space (only true for experimental
10572 systems), the space value is -1. See also the check_log_space option.
10573
10574 $lookup_dnssec_authenticated
10575
10576 This variable is set after a DNS lookup done by a dnsdb lookup expansion,
10577 dnslookup router or smtp transport. It will be empty if DNSSEC was not
10578 requested, "no" if the result was not labelled as authenticated data and
10579 "yes" if it was.
10580
10581 $mailstore_basename
10582
10583 This variable is set only when doing deliveries in "mailstore" format in
10584 the appendfile transport. During the expansion of the mailstore_prefix,
10585 mailstore_suffix, message_prefix, and message_suffix options, it contains
10586 the basename of the files that are being written, that is, the name without
10587 the ".tmp", ".env", or ".msg" suffix. At all other times, this variable is
10588 empty.
10589
10590 $malware_name
10591
10592 This variable is available when Exim is compiled with the content-scanning
10593 extension. It is set to the name of the virus that was found when the ACL
10594 malware condition is true (see section 43.1).
10595
10596 $max_received_linelength
10597
10598 This variable contains the number of bytes in the longest line that was
10599 received as part of the message, not counting the line termination
10600 character(s).
10601
10602 $message_age
10603
10604 This variable is set at the start of a delivery attempt to contain the
10605 number of seconds since the message was received. It does not change during
10606 a single delivery attempt.
10607
10608 $message_body
10609
10610 This variable contains the initial portion of a message's body while it is
10611 being delivered, and is intended mainly for use in filter files. The
10612 maximum number of characters of the body that are put into the variable is
10613 set by the message_body_visible configuration option; the default is 500.
10614
10615 By default, newlines are converted into spaces in $message_body, to make it
10616 easier to search for phrases that might be split over a line break.
10617 However, this can be disabled by setting message_body_newlines to be true.
10618 Binary zeros are always converted into spaces.
10619
10620 $message_body_end
10621
10622 This variable contains the final portion of a message's body while it is
10623 being delivered. The format and maximum size are as for $message_body.
10624
10625 $message_body_size
10626
10627 When a message is being delivered, this variable contains the size of the
10628 body in bytes. The count starts from the character after the blank line
10629 that separates the body from the header. Newlines are included in the
10630 count. See also $message_size, $body_linecount, and $body_zerocount.
10631
10632 $message_exim_id
10633
10634 When a message is being received or delivered, this variable contains the
10635 unique message id that is generated and used by Exim to identify the
10636 message. An id is not created for a message until after its header has been
10637 successfully received. Note: This is not the contents of the Message-ID:
10638 header line; it is the local id that Exim assigns to the message, for
10639 example: "1BXTIK-0001yO-VA".
10640
10641 $message_headers
10642
10643 This variable contains a concatenation of all the header lines when a
10644 message is being processed, except for lines added by routers or
10645 transports. The header lines are separated by newline characters. Their
10646 contents are decoded in the same way as a header line that is inserted by
10647 bheader.
10648
10649 $message_headers_raw
10650
10651 This variable is like $message_headers except that no processing of the
10652 contents of header lines is done.
10653
10654 $message_id
10655
10656 This is an old name for $message_exim_id, which is now deprecated.
10657
10658 $message_linecount
10659
10660 This variable contains the total number of lines in the header and body of
10661 the message. Compare $body_linecount, which is the count for the body only.
10662 During the DATA and content-scanning ACLs, $message_linecount contains the
10663 number of lines received. Before delivery happens (that is, before filters,
10664 routers, and transports run) the count is increased to include the
10665 Received: header line that Exim standardly adds, and also any other header
10666 lines that are added by ACLs. The blank line that separates the message
10667 header from the body is not counted.
10668
10669 As with the special case of $message_size, during the expansion of the
10670 appendfile transport's maildir_tag option in maildir format, the value of
10671 $message_linecount is the precise size of the number of newlines in the
10672 file that has been written (minus one for the blank line between the header
10673 and the body).
10674
10675 Here is an example of the use of this variable in a DATA ACL:
10676
10677 deny message = Too many lines in message header
10678 condition = \
10679 ${if <{250}{${eval:$message_linecount - $body_linecount}}}
10680
10681 In the MAIL and RCPT ACLs, the value is zero because at that stage the
10682 message has not yet been received.
10683
10684 $message_size
10685
10686 When a message is being processed, this variable contains its size in
10687 bytes. In most cases, the size includes those headers that were received
10688 with the message, but not those (such as Envelope-to:) that are added to
10689 individual deliveries as they are written. However, there is one special
10690 case: during the expansion of the maildir_tag option in the appendfile
10691 transport while doing a delivery in maildir format, the value of
10692 $message_size is the precise size of the file that has been written. See
10693 also $message_body_size, $body_linecount, and $body_zerocount.
10694
10695 While running a per message ACL (mail/rcpt/predata), $message_size contains
10696 the size supplied on the MAIL command, or -1 if no size was given. The
10697 value may not, of course, be truthful.
10698
10699 $mime_xxx
10700
10701 A number of variables whose names start with $mime are available when Exim
10702 is compiled with the content-scanning extension. For details, see section
10703 43.4.
10704
10705 $n0 - $n9
10706
10707 These variables are counters that can be incremented by means of the add
10708 command in filter files.
10709
10710 $original_domain
10711
10712 When a top-level address is being processed for delivery, this contains the
10713 same value as $domain. However, if a "child" address (for example,
10714 generated by an alias, forward, or filter file) is being processed, this
10715 variable contains the domain of the original address (lower cased). This
10716 differs from $parent_domain only when there is more than one level of
10717 aliasing or forwarding. When more than one address is being delivered in a
10718 single transport run, $original_domain is not set.
10719
10720 If a new address is created by means of a deliver command in a system
10721 filter, it is set up with an artificial "parent" address. This has the
10722 local part system-filter and the default qualify domain.
10723
10724 $original_local_part
10725
10726 When a top-level address is being processed for delivery, this contains the
10727 same value as $local_part, unless a prefix or suffix was removed from the
10728 local part, because $original_local_part always contains the full local
10729 part. When a "child" address (for example, generated by an alias, forward,
10730 or filter file) is being processed, this variable contains the full local
10731 part of the original address.
10732
10733 If the router that did the redirection processed the local part
10734 case-insensitively, the value in $original_local_part is in lower case.
10735 This variable differs from $parent_local_part only when there is more than
10736 one level of aliasing or forwarding. When more than one address is being
10737 delivered in a single transport run, $original_local_part is not set.
10738
10739 If a new address is created by means of a deliver command in a system
10740 filter, it is set up with an artificial "parent" address. This has the
10741 local part system-filter and the default qualify domain.
10742
10743 $originator_gid
10744
10745 This variable contains the value of $caller_gid that was set when the
10746 message was received. For messages received via the command line, this is
10747 the gid of the sending user. For messages received by SMTP over TCP/IP,
10748 this is normally the gid of the Exim user.
10749
10750 $originator_uid
10751
10752 The value of $caller_uid that was set when the message was received. For
10753 messages received via the command line, this is the uid of the sending
10754 user. For messages received by SMTP over TCP/IP, this is normally the uid
10755 of the Exim user.
10756
10757 $parent_domain
10758
10759 This variable is similar to $original_domain (see above), except that it
10760 refers to the immediately preceding parent address.
10761
10762 $parent_local_part
10763
10764 This variable is similar to $original_local_part (see above), except that
10765 it refers to the immediately preceding parent address.
10766
10767 $pid
10768
10769 This variable contains the current process id.
10770
10771 $pipe_addresses
10772
10773 This is not an expansion variable, but is mentioned here because the string
10774 "$pipe_addresses" is handled specially in the command specification for the
10775 pipe transport (chapter 29) and in transport filters (described under
10776 transport_filter in chapter 24). It cannot be used in general expansion
10777 strings, and provokes an "unknown variable" error if encountered.
10778
10779 $primary_hostname
10780
10781 This variable contains the value set by primary_hostname in the
10782 configuration file, or read by the uname() function. If uname() returns a
10783 single-component name, Exim calls gethostbyname() (or getipnodebyname()
10784 where available) in an attempt to acquire a fully qualified host name. See
10785 also $smtp_active_hostname.
10786
10787 $prvscheck_address
10788
10789 This variable is used in conjunction with the prvscheck expansion item,
10790 which is described in sections 11.5 and 42.51.
10791
10792 $prvscheck_keynum
10793
10794 This variable is used in conjunction with the prvscheck expansion item,
10795 which is described in sections 11.5 and 42.51.
10796
10797 $prvscheck_result
10798
10799 This variable is used in conjunction with the prvscheck expansion item,
10800 which is described in sections 11.5 and 42.51.
10801
10802 $qualify_domain
10803
10804 The value set for the qualify_domain option in the configuration file.
10805
10806 $qualify_recipient
10807
10808 The value set for the qualify_recipient option in the configuration file,
10809 or if not set, the value of $qualify_domain.
10810
10811 $rcpt_count
10812
10813 When a message is being received by SMTP, this variable contains the number
10814 of RCPT commands received for the current message. If this variable is used
10815 in a RCPT ACL, its value includes the current command.
10816
10817 $rcpt_defer_count
10818
10819 When a message is being received by SMTP, this variable contains the number
10820 of RCPT commands in the current message that have previously been rejected
10821 with a temporary (4xx) response.
10822
10823 $rcpt_fail_count
10824
10825 When a message is being received by SMTP, this variable contains the number
10826 of RCPT commands in the current message that have previously been rejected
10827 with a permanent (5xx) response.
10828
10829 $received_count
10830
10831 This variable contains the number of Received: header lines in the message,
10832 including the one added by Exim (so its value is always greater than zero).
10833 It is available in the DATA ACL, the non-SMTP ACL, and while routing and
10834 delivering.
10835
10836 $received_for
10837
10838 If there is only a single recipient address in an incoming message, this
10839 variable contains that address when the Received: header line is being
10840 built. The value is copied after recipient rewriting has happened, but
10841 before the local_scan() function is run.
10842
10843 $received_ip_address
10844
10845 As soon as an Exim server starts processing an incoming TCP/IP connection,
10846 this variable is set to the address of the local IP interface, and
10847 $received_port is set to the local port number. (The remote IP address and
10848 port are in $sender_host_address and $sender_host_port.) When testing with
10849 -bh, the port value is -1 unless it has been set using the -oMi command
10850 line option.
10851
10852 As well as being useful in ACLs (including the "connect" ACL), these
10853 variable could be used, for example, to make the file name for a TLS
10854 certificate depend on which interface and/or port is being used for the
10855 incoming connection. The values of $received_ip_address and $received_port
10856 are saved with any messages that are received, thus making these variables
10857 available at delivery time.
10858
10859 Note: There are no equivalent variables for outgoing connections, because
10860 the values are unknown (unless they are explicitly set by options of the
10861 smtp transport).
10862
10863 $received_port
10864
10865 See $received_ip_address.
10866
10867 $received_protocol
10868
10869 When a message is being processed, this variable contains the name of the
10870 protocol by which it was received. Most of the names used by Exim are
10871 defined by RFCs 821, 2821, and 3848. They start with "smtp" (the client
10872 used HELO) or "esmtp" (the client used EHLO). This can be followed by "s"
10873 for secure (encrypted) and/or "a" for authenticated. Thus, for example, if
10874 the protocol is set to "esmtpsa", the message was received over an
10875 encrypted SMTP connection and the client was successfully authenticated.
10876
10877 Exim uses the protocol name "smtps" for the case when encryption is
10878 automatically set up on connection without the use of STARTTLS (see
10879 tls_on_connect_ports), and the client uses HELO to initiate the encrypted
10880 SMTP session. The name "smtps" is also used for the rare situation where
10881 the client initially uses EHLO, sets up an encrypted connection using
10882 STARTTLS, and then uses HELO afterwards.
10883
10884 The -oMr option provides a way of specifying a custom protocol name for
10885 messages that are injected locally by trusted callers. This is commonly
10886 used to identify messages that are being re-injected after some kind of
10887 scanning.
10888
10889 $received_time
10890
10891 This variable contains the date and time when the current message was
10892 received, as a number of seconds since the start of the Unix epoch.
10893
10894 $recipient_data
10895
10896 This variable is set after an indexing lookup success in an ACL recipients
10897 condition. It contains the data from the lookup, and the value remains set
10898 until the next recipients test. Thus, you can do things like this:
10899
10900 require recipients = cdb*@;/some/file
10901 deny some further test involving $recipient_data
10902
10903 Warning: This variable is set only when a lookup is used as an indexing
10904 method in the address list, using the semicolon syntax as in the example
10905 above. The variable is not set for a lookup that is used as part of the
10906 string expansion that all such lists undergo before being interpreted.
10907
10908 $recipient_verify_failure
10909
10910 In an ACL, when a recipient verification fails, this variable contains
10911 information about the failure. It is set to one of the following words:
10912
10913 * "qualify": The address was unqualified (no domain), and the message was
10914 neither local nor came from an exempted host.
10915
10916 * "route": Routing failed.
10917
10918 * "mail": Routing succeeded, and a callout was attempted; rejection
10919 occurred at or before the MAIL command (that is, on initial connection,
10920 HELO, or MAIL).
10921
10922 * "recipient": The RCPT command in a callout was rejected.
10923
10924 * "postmaster": The postmaster check in a callout was rejected.
10925
10926 The main use of this variable is expected to be to distinguish between
10927 rejections of MAIL and rejections of RCPT.
10928
10929 $recipients
10930
10931 This variable contains a list of envelope recipients for a message. A comma
10932 and a space separate the addresses in the replacement text. However, the
10933 variable is not generally available, to prevent exposure of Bcc recipients
10934 in unprivileged users' filter files. You can use $recipients only in these
10935 cases:
10936
10937 1. In a system filter file.
10938
10939 2. In the ACLs associated with the DATA command and with non-SMTP
10940 messages, that is, the ACLs defined by acl_smtp_predata, acl_smtp_data,
10941 acl_smtp_mime, acl_not_smtp_start, acl_not_smtp, and acl_not_smtp_mime.
10942
10943 3. From within a local_scan() function.
10944
10945 $recipients_count
10946
10947 When a message is being processed, this variable contains the number of
10948 envelope recipients that came with the message. Duplicates are not excluded
10949 from the count. While a message is being received over SMTP, the number
10950 increases for each accepted recipient. It can be referenced in an ACL.
10951
10952 $regex_match_string
10953
10954 This variable is set to contain the matching regular expression after a
10955 regex ACL condition has matched (see section 43.5).
10956
10957 $reply_address
10958
10959 When a message is being processed, this variable contains the contents of
10960 the Reply-To: header line if one exists and it is not empty, or otherwise
10961 the contents of the From: header line. Apart from the removal of leading
10962 white space, the value is not processed in any way. In particular, no RFC
10963 2047 decoding or character code translation takes place.
10964
10965 $return_path
10966
10967 When a message is being delivered, this variable contains the return path -
10968 the sender field that will be sent as part of the envelope. It is not
10969 enclosed in <> characters. At the start of routing an address, $return_path
10970 has the same value as $sender_address, but if, for example, an incoming
10971 message to a mailing list has been expanded by a router which specifies a
10972 different address for bounce messages, $return_path subsequently contains
10973 the new bounce address, whereas $sender_address always contains the
10974 original sender address that was received with the message. In other words,
10975 $sender_address contains the incoming envelope sender, and $return_path
10976 contains the outgoing envelope sender.
10977
10978 $return_size_limit
10979
10980 This is an obsolete name for $bounce_return_size_limit.
10981
10982 $router_name
10983
10984 During the running of a router this variable contains its name.
10985
10986 $runrc
10987
10988 This variable contains the return code from a command that is run by the $
10989 {run...} expansion item. Warning: In a router or transport, you cannot
10990 assume the order in which option values are expanded, except for those
10991 preconditions whose order of testing is documented. Therefore, you cannot
10992 reliably expect to set $runrc by the expansion of one option, and use it in
10993 another.
10994
10995 $self_hostname
10996
10997 When an address is routed to a supposedly remote host that turns out to be
10998 the local host, what happens is controlled by the self generic router
10999 option. One of its values causes the address to be passed to another
11000 router. When this happens, $self_hostname is set to the name of the local
11001 host that the original router encountered. In other circumstances its
11002 contents are null.
11003
11004 $sender_address
11005
11006 When a message is being processed, this variable contains the sender's
11007 address that was received in the message's envelope. The case of letters in
11008 the address is retained, in both the local part and the domain. For bounce
11009 messages, the value of this variable is the empty string. See also
11010 $return_path.
11011
11012 $sender_address_data
11013
11014 If $address_data is set when the routers are called from an ACL to verify a
11015 sender address, the final value is preserved in $sender_address_data, to
11016 distinguish it from data from a recipient address. The value does not
11017 persist after the end of the current ACL statement. If you want to preserve
11018 it for longer, you can save it in an ACL variable.
11019
11020 $sender_address_domain
11021
11022 The domain portion of $sender_address.
11023
11024 $sender_address_local_part
11025
11026 The local part portion of $sender_address.
11027
11028 $sender_data
11029
11030 This variable is set after a lookup success in an ACL senders condition or
11031 in a router senders option. It contains the data from the lookup, and the
11032 value remains set until the next senders test. Thus, you can do things like
11033 this:
11034
11035 require senders = cdb*@;/some/file
11036 deny some further test involving $sender_data
11037
11038 Warning: This variable is set only when a lookup is used as an indexing
11039 method in the address list, using the semicolon syntax as in the example
11040 above. The variable is not set for a lookup that is used as part of the
11041 string expansion that all such lists undergo before being interpreted.
11042
11043 $sender_fullhost
11044
11045 When a message is received from a remote host, this variable contains the
11046 host name and IP address in a single string. It ends with the IP address in
11047 square brackets, followed by a colon and a port number if the logging of
11048 ports is enabled. The format of the rest of the string depends on whether
11049 the host issued a HELO or EHLO SMTP command, and whether the host name was
11050 verified by looking up its IP address. (Looking up the IP address can be
11051 forced by the host_lookup option, independent of verification.) A plain
11052 host name at the start of the string is a verified host name; if this is
11053 not present, verification either failed or was not requested. A host name
11054 in parentheses is the argument of a HELO or EHLO command. This is omitted
11055 if it is identical to the verified host name or to the host's IP address in
11056 square brackets.
11057
11058 $sender_helo_name
11059
11060 When a message is received from a remote host that has issued a HELO or
11061 EHLO command, the argument of that command is placed in this variable. It
11062 is also set if HELO or EHLO is used when a message is received using SMTP
11063 locally via the -bs or -bS options.
11064
11065 $sender_host_address
11066
11067 When a message is received from a remote host, this variable contains that
11068 host's IP address. For locally submitted messages, it is empty.
11069
11070 $sender_host_authenticated
11071
11072 This variable contains the name (not the public name) of the authenticator
11073 driver that successfully authenticated the client from which the message
11074 was received. It is empty if there was no successful authentication. See
11075 also $authenticated_id.
11076
11077 $sender_host_dnssec
11078
11079 If an attempt to populate $sender_host_name has been made (by reference,
11080 hosts_lookup or otherwise) then this boolean will have been set true if,
11081 and only if, the resolver library states that the reverse DNS was
11082 authenticated data. At all other times, this variable is false.
11083
11084 It is likely that you will need to coerce DNSSEC support on in the resolver
11085 library, by setting:
11086
11087 dns_dnssec_ok = 1
11088
11089 Exim does not perform DNSSEC validation itself, instead leaving that to a
11090 validating resolver (eg, unbound, or bind with suitable configuration).
11091
11092 Exim does not (currently) check to see if the forward DNS was also secured
11093 with DNSSEC, only the reverse DNS.
11094
11095 If you have changed host_lookup_order so that "bydns" is not the first
11096 mechanism in the list, then this variable will be false.
11097
11098 $sender_host_name
11099
11100 When a message is received from a remote host, this variable contains the
11101 host's name as obtained by looking up its IP address. For messages received
11102 by other means, this variable is empty.
11103
11104 If the host name has not previously been looked up, a reference to
11105 $sender_host_name triggers a lookup (for messages from remote hosts). A
11106 looked up name is accepted only if it leads back to the original IP address
11107 via a forward lookup. If either the reverse or the forward lookup fails to
11108 find any data, or if the forward lookup does not yield the original IP
11109 address, $sender_host_name remains empty, and $host_lookup_failed is set to
11110 "1".
11111
11112 However, if either of the lookups cannot be completed (for example, there
11113 is a DNS timeout), $host_lookup_deferred is set to "1", and
11114 $host_lookup_failed remains set to "0".
11115
11116 Once $host_lookup_failed is set to "1", Exim does not try to look up the
11117 host name again if there is a subsequent reference to $sender_host_name in
11118 the same Exim process, but it does try again if $host_lookup_deferred is
11119 set to "1".
11120
11121 Exim does not automatically look up every calling host's name. If you want
11122 maximum efficiency, you should arrange your configuration so that it avoids
11123 these lookups altogether. The lookup happens only if one or more of the
11124 following are true:
11125
11126 * A string containing $sender_host_name is expanded.
11127
11128 * The calling host matches the list in host_lookup. In the default
11129 configuration, this option is set to *, so it must be changed if
11130 lookups are to be avoided. (In the code, the default for host_lookup is
11131 unset.)
11132
11133 * Exim needs the host name in order to test an item in a host list. The
11134 items that require this are described in sections 10.13 and 10.17.
11135
11136 * The calling host matches helo_try_verify_hosts or helo_verify_hosts. In
11137 this case, the host name is required to compare with the name quoted in
11138 any EHLO or HELO commands that the client issues.
11139
11140 * The remote host issues a EHLO or HELO command that quotes one of the
11141 domains in helo_lookup_domains. The default value of this option is
11142
11143 helo_lookup_domains = @ : @[]
11144
11145 which causes a lookup if a remote host (incorrectly) gives the server's
11146 name or IP address in an EHLO or HELO command.
11147
11148 $sender_host_port
11149
11150 When a message is received from a remote host, this variable contains the
11151 port number that was used on the remote host.
11152
11153 $sender_ident
11154
11155 When a message is received from a remote host, this variable contains the
11156 identification received in response to an RFC 1413 request. When a message
11157 has been received locally, this variable contains the login name of the
11158 user that called Exim.
11159
11160 $sender_rate_xxx
11161
11162 A number of variables whose names begin $sender_rate_ are set as part of
11163 the ratelimit ACL condition. Details are given in section 42.38.
11164
11165 $sender_rcvhost
11166
11167 This is provided specifically for use in Received: headers. It starts with
11168 either the verified host name (as obtained from a reverse DNS lookup) or,
11169 if there is no verified host name, the IP address in square brackets. After
11170 that there may be text in parentheses. When the first item is a verified
11171 host name, the first thing in the parentheses is the IP address in square
11172 brackets, followed by a colon and a port number if port logging is enabled.
11173 When the first item is an IP address, the port is recorded as "port=xxxx"
11174 inside the parentheses.
11175
11176 There may also be items of the form "helo=xxxx" if HELO or EHLO was used
11177 and its argument was not identical to the real host name or IP address, and
11178 "ident=xxxx" if an RFC 1413 ident string is available. If all three items
11179 are present in the parentheses, a newline and tab are inserted into the
11180 string, to improve the formatting of the Received: header.
11181
11182 $sender_verify_failure
11183
11184 In an ACL, when a sender verification fails, this variable contains
11185 information about the failure. The details are the same as for
11186 $recipient_verify_failure.
11187
11188 $sending_ip_address
11189
11190 This variable is set whenever an outgoing SMTP connection to another host
11191 has been set up. It contains the IP address of the local interface that is
11192 being used. This is useful if a host that has more than one IP address
11193 wants to take on different personalities depending on which one is being
11194 used. For incoming connections, see $received_ip_address.
11195
11196 $sending_port
11197
11198 This variable is set whenever an outgoing SMTP connection to another host
11199 has been set up. It contains the local port that is being used. For
11200 incoming connections, see $received_port.
11201
11202 $smtp_active_hostname
11203
11204 During an incoming SMTP session, this variable contains the value of the
11205 active host name, as specified by the smtp_active_hostname option. The
11206 value of $smtp_active_hostname is saved with any message that is received,
11207 so its value can be consulted during routing and delivery.
11208
11209 $smtp_command
11210
11211 During the processing of an incoming SMTP command, this variable contains
11212 the entire command. This makes it possible to distinguish between HELO and
11213 EHLO in the HELO ACL, and also to distinguish between commands such as
11214 these:
11215
11216 MAIL FROM:<>
11217 MAIL FROM: <>
11218
11219 For a MAIL command, extra parameters such as SIZE can be inspected. For a
11220 RCPT command, the address in $smtp_command is the original address before
11221 any rewriting, whereas the values in $local_part and $domain are taken from
11222 the address after SMTP-time rewriting.
11223
11224 $smtp_command_argument
11225
11226 While an ACL is running to check an SMTP command, this variable contains
11227 the argument, that is, the text that follows the command name, with leading
11228 white space removed. Following the introduction of $smtp_command, this
11229 variable is somewhat redundant, but is retained for backwards
11230 compatibility.
11231
11232 $smtp_count_at_connection_start
11233
11234 This variable is set greater than zero only in processes spawned by the
11235 Exim daemon for handling incoming SMTP connections. The name is
11236 deliberately long, in order to emphasize what the contents are. When the
11237 daemon accepts a new connection, it increments this variable. A copy of the
11238 variable is passed to the child process that handles the connection, but
11239 its value is fixed, and never changes. It is only an approximation of how
11240 many incoming connections there actually are, because many other
11241 connections may come and go while a single connection is being processed.
11242 When a child process terminates, the daemon decrements its copy of the
11243 variable.
11244
11245 $sn0 - $sn9
11246
11247 These variables are copies of the values of the $n0 - $n9 accumulators that
11248 were current at the end of the system filter file. This allows a system
11249 filter file to set values that can be tested in users' filter files. For
11250 example, a system filter could set a value indicating how likely it is that
11251 a message is junk mail.
11252
11253 $spam_xxx
11254
11255 A number of variables whose names start with $spam are available when Exim
11256 is compiled with the content-scanning extension. For details, see section
11257 43.2.
11258
11259 $spool_directory
11260
11261 The name of Exim's spool directory.
11262
11263 $spool_inodes
11264
11265 The number of free inodes in the disk partition where Exim's spool files
11266 are being written. The value is recalculated whenever the variable is
11267 referenced. If the relevant file system does not have the concept of
11268 inodes, the value of is -1. See also the check_spool_inodes option.
11269
11270 $spool_space
11271
11272 The amount of free space (as a number of kilobytes) in the disk partition
11273 where Exim's spool files are being written. The value is recalculated
11274 whenever the variable is referenced. If the operating system does not have
11275 the ability to find the amount of free space (only true for experimental
11276 systems), the space value is -1. For example, to check in an ACL that there
11277 is at least 50 megabytes free on the spool, you could write:
11278
11279 condition = ${if > {$spool_space}{50000}}
11280
11281 See also the check_spool_space option.
11282
11283 $thisaddress
11284
11285 This variable is set only during the processing of the foranyaddress
11286 command in a filter file. Its use is explained in the description of that
11287 command, which can be found in the separate document entitled Exim's
11288 interfaces to mail filtering.
11289
11290 $tls_in_bits
11291
11292 Contains an approximation of the TLS cipher's bit-strength on the inbound
11293 connection; the meaning of this depends upon the TLS implementation used.
11294 If TLS has not been negotiated, the value will be 0. The value of this is
11295 automatically fed into the Cyrus SASL authenticator when acting as a
11296 server, to specify the "external SSF" (a SASL term).
11297
11298 The deprecated $tls_bits variable refers to the inbound side except when
11299 used in the context of an outbound SMTP delivery, when it refers to the
11300 outbound.
11301
11302 $tls_out_bits
11303
11304 Contains an approximation of the TLS cipher's bit-strength on an outbound
11305 SMTP connection; the meaning of this depends upon the TLS implementation
11306 used. If TLS has not been negotiated, the value will be 0.
11307
11308 $tls_in_ourcert
11309
11310 This variable refers to the certificate presented to the peer of an inbound
11311 connection when the message was received. It is only useful as the argument
11312 of a certextract expansion item, md5 or sha1 operator, or a def condition.
11313
11314 $tls_in_peercert
11315
11316 This variable refers to the certificate presented by the peer of an inbound
11317 connection when the message was received. It is only useful as the argument
11318 of a certextract expansion item, md5 or sha1 operator, or a def condition.
11319
11320 $tls_out_ourcert
11321
11322 This variable refers to the certificate presented to the peer of an
11323 outbound connection. It is only useful as the argument of a certextract
11324 expansion item, md5 or sha1 operator, or a def condition.
11325
11326 $tls_out_peercert
11327
11328 This variable refers to the certificate presented by the peer of an
11329 outbound connection. It is only useful as the argument of a certextract
11330 expansion item, md5 or sha1 operator, or a def condition.
11331
11332 $tls_in_certificate_verified
11333
11334 This variable is set to "1" if a TLS certificate was verified when the
11335 message was received, and "0" otherwise.
11336
11337 The deprecated $tls_certificate_verfied variable refers to the inbound side
11338 except when used in the context of an outbound SMTP delivery, when it
11339 refers to the outbound.
11340
11341 $tls_out_certificate_verified
11342
11343 This variable is set to "1" if a TLS certificate was verified when an
11344 outbound SMTP connection was made, and "0" otherwise.
11345
11346 $tls_in_cipher
11347
11348 When a message is received from a remote host over an encrypted SMTP
11349 connection, this variable is set to the cipher suite that was negotiated,
11350 for example DES-CBC3-SHA. In other circumstances, in particular, for
11351 message received over unencrypted connections, the variable is empty.
11352 Testing $tls_cipher for emptiness is one way of distinguishing between
11353 encrypted and non-encrypted connections during ACL processing.
11354
11355 The deprecated $tls_cipher variable is the same as $tls_in_cipher during
11356 message reception, but in the context of an outward SMTP delivery taking
11357 place via the smtp transport becomes the same as $tls_out_cipher.
11358
11359 $tls_out_cipher
11360
11361 This variable is cleared before any outgoing SMTP connection is made, and
11362 then set to the outgoing cipher suite if one is negotiated. See chapter 41
11363 for details of TLS support and chapter 30 for details of the smtp
11364 transport.
11365
11366 $tls_in_ocsp
11367
11368 When a message is received from a remote client connection the result of
11369 any OCSP request from the client is encoded in this variable:
11370
11371 0 OCSP proof was not requested (default value)
11372 1 No response to request
11373 2 Response not verified
11374 3 Verification failed
11375 4 Verification succeeded
11376
11377 $tls_out_ocsp
11378
11379 When a message is sent to a remote host connection the result of any OCSP
11380 request made is encoded in this variable. See $tls_in_ocsp for values.
11381
11382 $tls_in_peerdn
11383
11384 When a message is received from a remote host over an encrypted SMTP
11385 connection, and Exim is configured to request a certificate from the
11386 client, the value of the Distinguished Name of the certificate is made
11387 available in the $tls_in_peerdn during subsequent processing.
11388
11389 The deprecated $tls_peerdn variable refers to the inbound side except when
11390 used in the context of an outbound SMTP delivery, when it refers to the
11391 outbound.
11392
11393 $tls_out_peerdn
11394
11395 When a message is being delivered to a remote host over an encrypted SMTP
11396 connection, and Exim is configured to request a certificate from the
11397 server, the value of the Distinguished Name of the certificate is made
11398 available in the $tls_out_peerdn during subsequent processing.
11399
11400 $tls_in_sni
11401
11402 When a TLS session is being established, if the client sends the Server
11403 Name Indication extension, the value will be placed in this variable. If
11404 the variable appears in tls_certificate then this option and some others,
11405 described in 41.10, will be re-expanded early in the TLS session, to permit
11406 a different certificate to be presented (and optionally a different key to
11407 be used) to the client, based upon the value of the SNI extension.
11408
11409 The deprecated $tls_sni variable refers to the inbound side except when
11410 used in the context of an outbound SMTP delivery, when it refers to the
11411 outbound.
11412
11413 $tls_out_sni
11414
11415 During outbound SMTP deliveries, this variable reflects the value of the
11416 tls_sni option on the transport.
11417
11418 $tod_bsdinbox
11419
11420 The time of day and the date, in the format required for BSD-style mailbox
11421 files, for example: Thu Oct 17 17:14:09 1995.
11422
11423 $tod_epoch
11424
11425 The time and date as a number of seconds since the start of the Unix epoch.
11426
11427 $tod_epoch_l
11428
11429 The time and date as a number of microseconds since the start of the Unix
11430 epoch.
11431
11432 $tod_full
11433
11434 A full version of the time and date, for example: Wed, 16 Oct 1995 09:51:40
11435 +0100. The timezone is always given as a numerical offset from UTC, with
11436 positive values used for timezones that are ahead (east) of UTC, and
11437 negative values for those that are behind (west).
11438
11439 $tod_log
11440
11441 The time and date in the format used for writing Exim's log files, for
11442 example: 1995-10-12 15:32:29, but without a timezone.
11443
11444 $tod_logfile
11445
11446 This variable contains the date in the format yyyymmdd. This is the format
11447 that is used for datestamping log files when log_file_path contains the
11448 "%D" flag.
11449
11450 $tod_zone
11451
11452 This variable contains the numerical value of the local timezone, for
11453 example: -0500.
11454
11455 $tod_zulu
11456
11457 This variable contains the UTC date and time in "Zulu" format, as specified
11458 by ISO 8601, for example: 20030221154023Z.
11459
11460 $transport_name
11461
11462 During the running of a transport, this variable contains its name.
11463
11464 $value
11465
11466 This variable contains the result of an expansion lookup, extraction
11467 operation, or external command, as described above. It is also used during
11468 a reduce expansion.
11469
11470 $version_number
11471
11472 The version number of Exim.
11473
11474 $warn_message_delay
11475
11476 This variable is set only during the creation of a message warning about a
11477 delivery delay. Details of its use are explained in section 48.2.
11478
11479 $warn_message_recipients
11480
11481 This variable is set only during the creation of a message warning about a
11482 delivery delay. Details of its use are explained in section 48.2.
11483
11484
11485
11486 ===============================================================================
11487 12. EMBEDDED PERL
11488
11489 Exim can be built to include an embedded Perl interpreter. When this is done,
11490 Perl subroutines can be called as part of the string expansion process. To make
11491 use of the Perl support, you need version 5.004 or later of Perl installed on
11492 your system. To include the embedded interpreter in the Exim binary, include
11493 the line
11494
11495 EXIM_PERL = perl.o
11496
11497 in your Local/Makefile and then build Exim in the normal way.
11498
11499
11500 12.1 Setting up so Perl can be used
11501 -----------------------------------
11502
11503 Access to Perl subroutines is via a global configuration option called
11504 perl_startup and an expansion string operator ${perl ...}. If there is no
11505 perl_startup option in the Exim configuration file then no Perl interpreter is
11506 started and there is almost no overhead for Exim (since none of the Perl
11507 library will be paged in unless used). If there is a perl_startup option then
11508 the associated value is taken to be Perl code which is executed in a newly
11509 created Perl interpreter.
11510
11511 The value of perl_startup is not expanded in the Exim sense, so you do not need
11512 backslashes before any characters to escape special meanings. The option should
11513 usually be something like
11514
11515 perl_startup = do '/etc/exim.pl'
11516
11517 where /etc/exim.pl is Perl code which defines any subroutines you want to use
11518 from Exim. Exim can be configured either to start up a Perl interpreter as soon
11519 as it is entered, or to wait until the first time it is needed. Starting the
11520 interpreter at the beginning ensures that it is done while Exim still has its
11521 setuid privilege, but can impose an unnecessary overhead if Perl is not in fact
11522 used in a particular run. Also, note that this does not mean that Exim is
11523 necessarily running as root when Perl is called at a later time. By default,
11524 the interpreter is started only when it is needed, but this can be changed in
11525 two ways:
11526
11527 * Setting perl_at_start (a boolean option) in the configuration requests a
11528 startup when Exim is entered.
11529
11530 * The command line option -ps also requests a startup when Exim is entered,
11531 overriding the setting of perl_at_start.
11532
11533 There is also a command line option -pd (for delay) which suppresses the
11534 initial startup, even if perl_at_start is set.
11535
11536
11537 12.2 Calling Perl subroutines
11538 -----------------------------
11539
11540 When the configuration file includes a perl_startup option you can make use of
11541 the string expansion item to call the Perl subroutines that are defined by the
11542 perl_startup code. The operator is used in any of the following forms:
11543
11544 ${perl{foo}}
11545 ${perl{foo}{argument}}
11546 ${perl{foo}{argument1}{argument2} ... }
11547
11548 which calls the subroutine foo with the given arguments. A maximum of eight
11549 arguments may be passed. Passing more than this results in an expansion failure
11550 with an error message of the form
11551
11552 Too many arguments passed to Perl subroutine "foo" (max is 8)
11553
11554 The return value of the Perl subroutine is evaluated in a scalar context before
11555 it is passed back to Exim to be inserted into the expanded string. If the
11556 return value is undef, the expansion is forced to fail in the same way as an
11557 explicit "fail" on an if or lookup item. If the subroutine aborts by obeying
11558 Perl's die function, the expansion fails with the error message that was passed
11559 to die.
11560
11561
11562 12.3 Calling Exim functions from Perl
11563 -------------------------------------
11564
11565 Within any Perl code called from Exim, the function Exim::expand_string() is
11566 available to call back into Exim's string expansion function. For example, the
11567 Perl code
11568
11569 my $lp = Exim::expand_string('$local_part');
11570
11571 makes the current Exim $local_part available in the Perl variable $lp. Note
11572 those are single quotes and not double quotes to protect against $local_part
11573 being interpolated as a Perl variable.
11574
11575 If the string expansion is forced to fail by a "fail" item, the result of
11576 Exim::expand_string() is undef. If there is a syntax error in the expansion
11577 string, the Perl call from the original expansion string fails with an
11578 appropriate error message, in the same way as if die were used.
11579
11580 Two other Exim functions are available for use from within Perl code.
11581 Exim::debug_write() writes a string to the standard error stream if Exim's
11582 debugging is enabled. If you want a newline at the end, you must supply it.
11583 Exim::log_write() writes a string to Exim's main log, adding a leading
11584 timestamp. In this case, you should not supply a terminating newline.
11585
11586
11587 12.4 Use of standard output and error by Perl
11588 ---------------------------------------------
11589
11590 You should not write to the standard error or output streams from within your
11591 Perl code, as it is not defined how these are set up. In versions of Exim
11592 before 4.50, it is possible for the standard output or error to refer to the
11593 SMTP connection during message reception via the daemon. Writing to this stream
11594 is certain to cause chaos. From Exim 4.50 onwards, the standard output and
11595 error streams are connected to /dev/null in the daemon. The chaos is avoided,
11596 but the output is lost.
11597
11598 The Perl warn statement writes to the standard error stream by default. Calls
11599 to warn may be embedded in Perl modules that you use, but over which you have
11600 no control. When Exim starts up the Perl interpreter, it arranges for output
11601 from the warn statement to be written to the Exim main log. You can change this
11602 by including appropriate Perl magic somewhere in your Perl code. For example,
11603 to discard warn output completely, you need this:
11604
11605 $SIG{__WARN__} = sub { };
11606
11607 Whenever a warn is obeyed, the anonymous subroutine is called. In this example,
11608 the code for the subroutine is empty, so it does nothing, but you can include
11609 any Perl code that you like. The text of the warn message is passed as the
11610 first subroutine argument.
11611
11612
11613
11614 ===============================================================================
11615 13. STARTING THE DAEMON AND THE USE OF NETWORK INTERFACES
11616
11617 A host that is connected to a TCP/IP network may have one or more physical
11618 hardware network interfaces. Each of these interfaces may be configured as one
11619 or more "logical" interfaces, which are the entities that a program actually
11620 works with. Each of these logical interfaces is associated with an IP address.
11621 In addition, TCP/IP software supports "loopback" interfaces (127.0.0.1 in IPv4
11622 and ::1 in IPv6), which do not use any physical hardware. Exim requires
11623 knowledge about the host's interfaces for use in three different circumstances:
11624
11625 1. When a listening daemon is started, Exim needs to know which interfaces and
11626 ports to listen on.
11627
11628 2. When Exim is routing an address, it needs to know which IP addresses are
11629 associated with local interfaces. This is required for the correct
11630 processing of MX lists by removing the local host and others with the same
11631 or higher priority values. Also, Exim needs to detect cases when an address
11632 is routed to an IP address that in fact belongs to the local host. Unless
11633 the self router option or the allow_localhost option of the smtp transport
11634 is set (as appropriate), this is treated as an error situation.
11635
11636 3. When Exim connects to a remote host, it may need to know which interface to
11637 use for the outgoing connection.
11638
11639 Exim's default behaviour is likely to be appropriate in the vast majority of
11640 cases. If your host has only one interface, and you want all its IP addresses
11641 to be treated in the same way, and you are using only the standard SMTP port,
11642 you should not need to take any special action. The rest of this chapter does
11643 not apply to you.
11644
11645 In a more complicated situation you may want to listen only on certain
11646 interfaces, or on different ports, and for this reason there are a number of
11647 options that can be used to influence Exim's behaviour. The rest of this
11648 chapter describes how they operate.
11649
11650 When a message is received over TCP/IP, the interface and port that were
11651 actually used are set in $received_ip_address and $received_port.
11652
11653
11654 13.1 Starting a listening daemon
11655 --------------------------------
11656
11657 When a listening daemon is started (by means of the -bd command line option),
11658 the interfaces and ports on which it listens are controlled by the following
11659 options:
11660
11661 * daemon_smtp_ports contains a list of default ports or service names. (For
11662 backward compatibility, this option can also be specified in the singular.)
11663
11664 * local_interfaces contains list of interface IP addresses on which to
11665 listen. Each item may optionally also specify a port.
11666
11667 The default list separator in both cases is a colon, but this can be changed as
11668 described in section 6.19. When IPv6 addresses are involved, it is usually best
11669 to change the separator to avoid having to double all the colons. For example:
11670
11671 local_interfaces = <; 127.0.0.1 ; \
11672 192.168.23.65 ; \
11673 ::1 ; \
11674 3ffe:ffff:836f::fe86:a061
11675
11676 There are two different formats for specifying a port along with an IP address
11677 in local_interfaces:
11678
11679 1. The port is added onto the address with a dot separator. For example, to
11680 listen on port 1234 on two different IP addresses:
11681
11682 local_interfaces = <; 192.168.23.65.1234 ; \
11683 3ffe:ffff:836f::fe86:a061.1234
11684
11685 2. The IP address is enclosed in square brackets, and the port is added with a
11686 colon separator, for example:
11687
11688 local_interfaces = <; [192.168.23.65]:1234 ; \
11689 [3ffe:ffff:836f::fe86:a061]:1234
11690
11691 When a port is not specified, the value of daemon_smtp_ports is used. The
11692 default setting contains just one port:
11693
11694 daemon_smtp_ports = smtp
11695
11696 If more than one port is listed, each interface that does not have its own port
11697 specified listens on all of them. Ports that are listed in daemon_smtp_ports
11698 can be identified either by name (defined in /etc/services) or by number.
11699 However, when ports are given with individual IP addresses in local_interfaces,
11700 only numbers (not names) can be used.
11701
11702
11703 13.2 Special IP listening addresses
11704 -----------------------------------
11705
11706 The addresses 0.0.0.0 and ::0 are treated specially. They are interpreted as
11707 "all IPv4 interfaces" and "all IPv6 interfaces", respectively. In each case,
11708 Exim tells the TCP/IP stack to "listen on all IPvx interfaces" instead of
11709 setting up separate listening sockets for each interface. The default value of
11710 local_interfaces is
11711
11712 local_interfaces = 0.0.0.0
11713
11714 when Exim is built without IPv6 support; otherwise it is:
11715
11716 local_interfaces = <; ::0 ; 0.0.0.0
11717
11718 Thus, by default, Exim listens on all available interfaces, on the SMTP port.
11719
11720
11721 13.3 Overriding local_interfaces and daemon_smtp_ports
11722 ------------------------------------------------------
11723
11724 The -oX command line option can be used to override the values of
11725 daemon_smtp_ports and/or local_interfaces for a particular daemon instance.
11726 Another way of doing this would be to use macros and the -D option. However,
11727 -oX can be used by any admin user, whereas modification of the runtime
11728 configuration by -D is allowed only when the caller is root or exim.
11729
11730 The value of -oX is a list of items. The default colon separator can be changed
11731 in the usual way if required. If there are any items that do not contain dots
11732 or colons (that is, are not IP addresses), the value of daemon_smtp_ports is
11733 replaced by the list of those items. If there are any items that do contain
11734 dots or colons, the value of local_interfaces is replaced by those items. Thus,
11735 for example,
11736
11737 -oX 1225
11738
11739 overrides daemon_smtp_ports, but leaves local_interfaces unchanged, whereas
11740
11741 -oX 192.168.34.5.1125
11742
11743 overrides local_interfaces, leaving daemon_smtp_ports unchanged. (However,
11744 since local_interfaces now contains no items without ports, the value of
11745 daemon_smtp_ports is no longer relevant in this example.)
11746
11747
11748 13.4 Support for the obsolete SSMTP (or SMTPS) protocol
11749 -------------------------------------------------------
11750
11751 Exim supports the obsolete SSMTP protocol (also known as SMTPS) that was used
11752 before the STARTTLS command was standardized for SMTP. Some legacy clients
11753 still use this protocol. If the tls_on_connect_ports option is set to a list of
11754 port numbers or service names, connections to those ports must use SSMTP. The
11755 most common use of this option is expected to be
11756
11757 tls_on_connect_ports = 465
11758
11759 because 465 is the usual port number used by the legacy clients. There is also
11760 a command line option -tls-on-connect, which forces all ports to behave in this
11761 way when a daemon is started.
11762
11763 Warning: Setting tls_on_connect_ports does not of itself cause the daemon to
11764 listen on those ports. You must still specify them in daemon_smtp_ports,
11765 local_interfaces, or the -oX option. (This is because tls_on_connect_ports
11766 applies to inetd connections as well as to connections via the daemon.)
11767
11768
11769 13.5 IPv6 address scopes
11770 ------------------------
11771
11772 IPv6 addresses have "scopes", and a host with multiple hardware interfaces can,
11773 in principle, have the same link-local IPv6 address on different interfaces.
11774 Thus, additional information is needed, over and above the IP address, to
11775 distinguish individual interfaces. A convention of using a percent sign
11776 followed by something (often the interface name) has been adopted in some
11777 cases, leading to addresses like this:
11778
11779 fe80::202:b3ff:fe03:45c1%eth0
11780
11781 To accommodate this usage, a percent sign followed by an arbitrary string is
11782 allowed at the end of an IPv6 address. By default, Exim calls getaddrinfo() to
11783 convert a textual IPv6 address for actual use. This function recognizes the
11784 percent convention in operating systems that support it, and it processes the
11785 address appropriately. Unfortunately, some older libraries have problems with
11786 getaddrinfo(). If
11787
11788 IPV6_USE_INET_PTON=yes
11789
11790 is set in Local/Makefile (or an OS-dependent Makefile) when Exim is built, Exim
11791 uses inet_pton() to convert a textual IPv6 address for actual use, instead of
11792 getaddrinfo(). (Before version 4.14, it always used this function.) Of course,
11793 this means that the additional functionality of getaddrinfo() - recognizing
11794 scoped addresses - is lost.
11795
11796
11797 13.6 Disabling IPv6
11798 -------------------
11799
11800 Sometimes it happens that an Exim binary that was compiled with IPv6 support is
11801 run on a host whose kernel does not support IPv6. The binary will fall back to
11802 using IPv4, but it may waste resources looking up AAAA records, and trying to
11803 connect to IPv6 addresses, causing delays to mail delivery. If you set the
11804 disable_ipv6 option true, even if the Exim binary has IPv6 support, no IPv6
11805 activities take place. AAAA records are never looked up, and any IPv6 addresses
11806 that are listed in local_interfaces, data for the manualroute router, etc. are
11807 ignored. If IP literals are enabled, the ipliteral router declines to handle
11808 IPv6 literal addresses.
11809
11810 On the other hand, when IPv6 is in use, there may be times when you want to
11811 disable it for certain hosts or domains. You can use the dns_ipv4_lookup option
11812 to globally suppress the lookup of AAAA records for specified domains, and you
11813 can use the ignore_target_hosts generic router option to ignore IPv6 addresses
11814 in an individual router.
11815
11816
11817 13.7 Examples of starting a listening daemon
11818 --------------------------------------------
11819
11820 The default case in an IPv6 environment is
11821
11822 daemon_smtp_ports = smtp
11823 local_interfaces = <; ::0 ; 0.0.0.0
11824
11825 This specifies listening on the smtp port on all IPv6 and IPv4 interfaces.
11826 Either one or two sockets may be used, depending on the characteristics of the
11827 TCP/IP stack. (This is complicated and messy; for more information, read the
11828 comments in the daemon.c source file.)
11829
11830 To specify listening on ports 25 and 26 on all interfaces:
11831
11832 daemon_smtp_ports = 25 : 26
11833
11834 (leaving local_interfaces at the default setting) or, more explicitly:
11835
11836 local_interfaces = <; ::0.25 ; ::0.26 \
11837 0.0.0.0.25 ; 0.0.0.0.26
11838
11839 To listen on the default port on all IPv4 interfaces, and on port 26 on the
11840 IPv4 loopback address only:
11841
11842 local_interfaces = 0.0.0.0 : 127.0.0.1.26
11843
11844 To specify listening on the default port on specific interfaces only:
11845
11846 local_interfaces = 10.0.0.67 : 192.168.34.67
11847
11848 Warning: Such a setting excludes listening on the loopback interfaces.
11849
11850
11851 13.8 Recognizing the local host
11852 -------------------------------
11853
11854 The local_interfaces option is also used when Exim needs to determine whether
11855 or not an IP address refers to the local host. That is, the IP addresses of all
11856 the interfaces on which a daemon is listening are always treated as local.
11857
11858 For this usage, port numbers in local_interfaces are ignored. If either of the
11859 items 0.0.0.0 or ::0 are encountered, Exim gets a complete list of available
11860 interfaces from the operating system, and extracts the relevant (that is, IPv4
11861 or IPv6) addresses to use for checking.
11862
11863 Some systems set up large numbers of virtual interfaces in order to provide
11864 many virtual web servers. In this situation, you may want to listen for email
11865 on only a few of the available interfaces, but nevertheless treat all
11866 interfaces as local when routing. You can do this by setting
11867 extra_local_interfaces to a list of IP addresses, possibly including the "all"
11868 wildcard values. These addresses are recognized as local, but are not used for
11869 listening. Consider this example:
11870
11871 local_interfaces = <; 127.0.0.1 ; ::1 ; \
11872 192.168.53.235 ; \
11873 3ffe:2101:12:1:a00:20ff:fe86:a061
11874
11875 extra_local_interfaces = <; ::0 ; 0.0.0.0
11876
11877 The daemon listens on the loopback interfaces and just one IPv4 and one IPv6
11878 address, but all available interface addresses are treated as local when Exim
11879 is routing.
11880
11881 In some environments the local host name may be in an MX list, but with an IP
11882 address that is not assigned to any local interface. In other cases it may be
11883 desirable to treat other host names as if they referred to the local host. Both
11884 these cases can be handled by setting the hosts_treat_as_local option. This
11885 contains host names rather than IP addresses. When a host is referenced during
11886 routing, either via an MX record or directly, it is treated as the local host
11887 if its name matches hosts_treat_as_local, or if any of its IP addresses match
11888 local_interfaces or extra_local_interfaces.
11889
11890
11891 13.9 Delivering to a remote host
11892 --------------------------------
11893
11894 Delivery to a remote host is handled by the smtp transport. By default, it
11895 allows the system's TCP/IP functions to choose which interface to use (if there
11896 is more than one) when connecting to a remote host. However, the interface
11897 option can be set to specify which interface is used. See the description of
11898 the smtp transport in chapter 30 for more details.
11899
11900
11901
11902 ===============================================================================
11903 14. MAIN CONFIGURATION
11904
11905 The first part of the run time configuration file contains three types of item:
11906
11907 * Macro definitions: These lines start with an upper case letter. See section
11908 6.4 for details of macro processing.
11909
11910 * Named list definitions: These lines start with one of the words
11911 "domainlist", "hostlist", "addresslist", or "localpartlist". Their use is
11912 described in section 10.5.
11913
11914 * Main configuration settings: Each setting occupies one line of the file
11915 (with possible continuations). If any setting is preceded by the word
11916 "hide", the -bP command line option displays its value to admin users only.
11917 See section 6.10 for a description of the syntax of these option settings.
11918
11919 This chapter specifies all the main configuration options, along with their
11920 types and default values. For ease of finding a particular option, they appear
11921 in alphabetical order in section 14.23 below. However, because there are now so
11922 many options, they are first listed briefly in functional groups, as an aid to
11923 finding the name of the option you are looking for. Some options are listed in
11924 more than one group.
11925
11926
11927 14.1 Miscellaneous
11928 ------------------
11929
11930 bi_command to run for -bi command line option
11931 disable_ipv6 do no IPv6 processing
11932 keep_malformed for broken files - should not happen
11933 localhost_number for unique message ids in clusters
11934 message_body_newlines retain newlines in $message_body
11935 message_body_visible how much to show in $message_body
11936 mua_wrapper run in "MUA wrapper" mode
11937 print_topbitchars top-bit characters are printing
11938 timezone force time zone
11939
11940
11941 14.2 Exim parameters
11942 --------------------
11943
11944 exim_group override compiled-in value
11945 exim_path override compiled-in value
11946 exim_user override compiled-in value
11947 primary_hostname default from uname()
11948 split_spool_directory use multiple directories
11949 spool_directory override compiled-in value
11950
11951
11952 14.3 Privilege controls
11953 -----------------------
11954
11955 admin_groups groups that are Exim admin users
11956 deliver_drop_privilege drop root for delivery processes
11957 local_from_check insert Sender: if necessary
11958 local_from_prefix for testing From: for local sender
11959 local_from_suffix for testing From: for local sender
11960 local_sender_retain keep Sender: from untrusted user
11961 never_users do not run deliveries as these
11962 prod_requires_admin forced delivery requires admin user
11963 queue_list_requires_admin queue listing requires admin user
11964 trusted_groups groups that are trusted
11965 trusted_users users that are trusted
11966
11967
11968 14.4 Logging
11969 ------------
11970
11971 hosts_connection_nolog exemption from connect logging
11972 log_file_path override compiled-in value
11973 log_selector set/unset optional logging
11974 log_timezone add timezone to log lines
11975 message_logs create per-message logs
11976 preserve_message_logs after message completion
11977 process_log_path for SIGUSR1 and exiwhat
11978 syslog_duplication controls duplicate log lines on syslog
11979 syslog_facility set syslog "facility" field
11980 syslog_processname set syslog "ident" field
11981 syslog_timestamp timestamp syslog lines
11982 write_rejectlog control use of message log
11983
11984
11985 14.5 Frozen messages
11986 --------------------
11987
11988 auto_thaw sets time for retrying frozen messages
11989 freeze_tell send message when freezing
11990 move_frozen_messages to another directory
11991 timeout_frozen_after keep frozen messages only so long
11992
11993
11994 14.6 Data lookups
11995 -----------------
11996
11997 ibase_servers InterBase servers
11998 ldap_ca_cert_dir dir of CA certs to verify LDAP server's
11999 ldap_ca_cert_file file of CA certs to verify LDAP server's
12000 ldap_cert_file client cert file for LDAP
12001 ldap_cert_key client key file for LDAP
12002 ldap_cipher_suite TLS negotiation preference control
12003 ldap_default_servers used if no server in query
12004 ldap_require_cert action to take without LDAP server cert
12005 ldap_start_tls require TLS within LDAP
12006 ldap_version set protocol version
12007 lookup_open_max lookup files held open
12008 mysql_servers default MySQL servers
12009 oracle_servers Oracle servers
12010 pgsql_servers default PostgreSQL servers
12011 sqlite_lock_timeout as it says
12012
12013
12014 14.7 Message ids
12015 ----------------
12016
12017 message_id_header_domain used to build Message-ID: header
12018 message_id_header_text ditto
12019
12020
12021 14.8 Embedded Perl Startup
12022 --------------------------
12023
12024 perl_at_start always start the interpreter
12025 perl_startup code to obey when starting Perl
12026
12027
12028 14.9 Daemon
12029 -----------
12030
12031 daemon_smtp_ports default ports
12032 daemon_startup_retries number of times to retry
12033 daemon_startup_sleep time to sleep between tries
12034 extra_local_interfaces not necessarily listened on
12035 local_interfaces on which to listen, with optional ports
12036 pid_file_path override compiled-in value
12037 queue_run_max maximum simultaneous queue runners
12038
12039
12040 14.10 Resource control
12041 ----------------------
12042
12043 check_log_inodes before accepting a message
12044 check_log_space before accepting a message
12045 check_spool_inodes before accepting a message
12046 check_spool_space before accepting a message
12047 deliver_queue_load_max no queue deliveries if load high
12048 queue_only_load queue incoming if load high
12049 queue_only_load_latch don't re-evaluate load for each message
12050 queue_run_max maximum simultaneous queue runners
12051 remote_max_parallel parallel SMTP delivery per message
12052 smtp_accept_max simultaneous incoming connections
12053 smtp_accept_max_nonmail non-mail commands
12054 smtp_accept_max_nonmail_hosts hosts to which the limit applies
12055 smtp_accept_max_per_connection messages per connection
12056 smtp_accept_max_per_host connections from one host
12057 smtp_accept_queue queue mail if more connections
12058 smtp_accept_queue_per_connection queue if more messages per connection
12059 smtp_accept_reserve only reserve hosts if more connections
12060 smtp_check_spool_space from SIZE on MAIL command
12061 smtp_connect_backlog passed to TCP/IP stack
12062 smtp_load_reserve SMTP from reserved hosts if load high
12063 smtp_reserve_hosts these are the reserve hosts
12064
12065
12066 14.11 Policy controls
12067 ---------------------
12068
12069 acl_not_smtp ACL for non-SMTP messages
12070 acl_not_smtp_mime ACL for non-SMTP MIME parts
12071 acl_not_smtp_start ACL for start of non-SMTP message
12072 acl_smtp_auth ACL for AUTH
12073 acl_smtp_connect ACL for connection
12074 acl_smtp_data ACL for DATA
12075 acl_smtp_data_prdr ACL for DATA, per-recipient
12076 acl_smtp_dkim ACL for DKIM verification
12077 acl_smtp_etrn ACL for ETRN
12078 acl_smtp_expn ACL for EXPN
12079 acl_smtp_helo ACL for EHLO or HELO
12080 acl_smtp_mail ACL for MAIL
12081 acl_smtp_mailauth ACL for AUTH on MAIL command
12082 acl_smtp_mime ACL for MIME parts
12083 acl_smtp_predata ACL for start of data
12084 acl_smtp_quit ACL for QUIT
12085 acl_smtp_rcpt ACL for RCPT
12086 acl_smtp_starttls ACL for STARTTLS
12087 acl_smtp_vrfy ACL for VRFY
12088 av_scanner specify virus scanner
12089 check_rfc2047_length check length of RFC 2047 "encoded words"
12090 dns_csa_search_limit control CSA parent search depth
12091 dns_csa_use_reverse en/disable CSA IP reverse search
12092 header_maxsize total size of message header
12093 header_line_maxsize individual header line limit
12094 helo_accept_junk_hosts allow syntactic junk from these hosts
12095 helo_allow_chars allow illegal chars in HELO names
12096 helo_lookup_domains lookup hostname for these HELO names
12097 helo_try_verify_hosts HELO soft-checked for these hosts
12098 helo_verify_hosts HELO hard-checked for these hosts
12099 host_lookup host name looked up for these hosts
12100 host_lookup_order order of DNS and local name lookups
12101 host_reject_connection reject connection from these hosts
12102 hosts_treat_as_local useful in some cluster configurations
12103 local_scan_timeout timeout for local_scan()
12104 message_size_limit for all messages
12105 percent_hack_domains recognize %-hack for these domains
12106 spamd_address set interface to SpamAssassin
12107 strict_acl_vars object to unset ACL variables
12108
12109
12110 14.12 Callout cache
12111 -------------------
12112
12113 callout_domain_negative_expire timeout for negative domain cache item
12114 callout_domain_positive_expire timeout for positive domain cache item
12115 callout_negative_expire timeout for negative address cache item
12116 callout_positive_expire timeout for positive address cache item
12117 callout_random_local_part string to use for "random" testing
12118
12119
12120 14.13 TLS
12121 ---------
12122
12123 gnutls_compat_mode use GnuTLS compatibility mode
12124 gnutls_allow_auto_pkcs11 allow GnuTLS to autoload PKCS11 modules
12125 openssl_options adjust OpenSSL compatibility options
12126 tls_advertise_hosts advertise TLS to these hosts
12127 tls_certificate location of server certificate
12128 tls_crl certificate revocation list
12129 tls_dh_max_bits clamp D-H bit count suggestion
12130 tls_dhparam DH parameters for server
12131 tls_ocsp_file location of server certificate status proof
12132 tls_on_connect_ports specify SSMTP (SMTPS) ports
12133 tls_privatekey location of server private key
12134 tls_remember_esmtp don't reset after starting TLS
12135 tls_require_ciphers specify acceptable ciphers
12136 tls_try_verify_hosts try to verify client certificate
12137 tls_verify_certificates expected client certificates
12138 tls_verify_hosts insist on client certificate verify
12139
12140
12141 14.14 Local user handling
12142 -------------------------
12143
12144 finduser_retries useful in NIS environments
12145 gecos_name used when creating Sender:
12146 gecos_pattern ditto
12147 max_username_length for systems that truncate
12148 unknown_login used when no login name found
12149 unknown_username ditto
12150 uucp_from_pattern for recognizing "From " lines
12151 uucp_from_sender ditto
12152
12153
12154 14.15 All incoming messages (SMTP and non-SMTP)
12155 -----------------------------------------------
12156
12157 header_maxsize total size of message header
12158 header_line_maxsize individual header line limit
12159 message_size_limit applies to all messages
12160 percent_hack_domains recognize %-hack for these domains
12161 received_header_text expanded to make Received:
12162 received_headers_max for mail loop detection
12163 recipients_max limit per message
12164 recipients_max_reject permanently reject excess recipients
12165
12166
12167 14.16 Non-SMTP incoming messages
12168 --------------------------------
12169
12170 receive_timeout for non-SMTP messages
12171
12172
12173 14.17 Incoming SMTP messages
12174 ----------------------------
12175
12176 See also the Policy controls section above.
12177
12178 host_lookup host name looked up for these hosts
12179 host_lookup_order order of DNS and local name lookups
12180 recipient_unqualified_hosts may send unqualified recipients
12181 rfc1413_hosts make ident calls to these hosts
12182 rfc1413_query_timeout zero disables ident calls
12183 sender_unqualified_hosts may send unqualified senders
12184 smtp_accept_keepalive some TCP/IP magic
12185 smtp_accept_max simultaneous incoming connections
12186 smtp_accept_max_nonmail non-mail commands
12187 smtp_accept_max_nonmail_hosts hosts to which the limit applies
12188 smtp_accept_max_per_connection messages per connection
12189 smtp_accept_max_per_host connections from one host
12190 smtp_accept_queue queue mail if more connections
12191 smtp_accept_queue_per_connection queue if more messages per connection
12192 smtp_accept_reserve only reserve hosts if more connections
12193 smtp_active_hostname host name to use in messages
12194 smtp_banner text for welcome banner
12195 smtp_check_spool_space from SIZE on MAIL command
12196 smtp_connect_backlog passed to TCP/IP stack
12197 smtp_enforce_sync of SMTP command/responses
12198 smtp_etrn_command what to run for ETRN
12199 smtp_etrn_serialize only one at once
12200 smtp_load_reserve only reserve hosts if this load
12201 smtp_max_unknown_commands before dropping connection
12202 smtp_ratelimit_hosts apply ratelimiting to these hosts
12203 smtp_ratelimit_mail ratelimit for MAIL commands
12204 smtp_ratelimit_rcpt ratelimit for RCPT commands
12205 smtp_receive_timeout per command or data line
12206 smtp_reserve_hosts these are the reserve hosts
12207 smtp_return_error_details give detail on rejections
12208
12209
12210 14.18 SMTP extensions
12211 ---------------------
12212
12213 accept_8bitmime advertise 8BITMIME
12214 auth_advertise_hosts advertise AUTH to these hosts
12215 ignore_fromline_hosts allow "From " from these hosts
12216 ignore_fromline_local allow "From " from local SMTP
12217 pipelining_advertise_hosts advertise pipelining to these hosts
12218 prdr_enable advertise PRDR to all hosts
12219 tls_advertise_hosts advertise TLS to these hosts
12220
12221
12222 14.19 Processing messages
12223 -------------------------
12224
12225 allow_domain_literals recognize domain literal syntax
12226 allow_mx_to_ip allow MX to point to IP address
12227 allow_utf8_domains in addresses
12228 check_rfc2047_length check length of RFC 2047 "encoded words"
12229 delivery_date_remove from incoming messages
12230 envelope_to_remove from incoming messages
12231 extract_addresses_remove_arguments affects -t processing
12232 headers_charset default for translations
12233 qualify_domain default for senders
12234 qualify_recipient default for recipients
12235 return_path_remove from incoming messages
12236 strip_excess_angle_brackets in addresses
12237 strip_trailing_dot at end of addresses
12238 untrusted_set_sender untrusted can set envelope sender
12239
12240
12241 14.20 System filter
12242 -------------------
12243
12244 system_filter locate system filter
12245 system_filter_directory_transport transport for delivery to a directory
12246 system_filter_file_transport transport for delivery to a file
12247 system_filter_group group for filter running
12248 system_filter_pipe_transport transport for delivery to a pipe
12249 system_filter_reply_transport transport for autoreply delivery
12250 system_filter_user user for filter running
12251
12252
12253 14.21 Routing and delivery
12254 --------------------------
12255
12256 disable_ipv6 do no IPv6 processing
12257 dns_again_means_nonexist for broken domains
12258 dns_check_names_pattern pre-DNS syntax check
12259 dns_dnssec_ok parameter for resolver
12260 dns_ipv4_lookup only v4 lookup for these domains
12261 dns_retrans parameter for resolver
12262 dns_retry parameter for resolver
12263 dns_use_edns0 parameter for resolver
12264 hold_domains hold delivery for these domains
12265 local_interfaces for routing checks
12266 queue_domains no immediate delivery for these
12267 queue_only no immediate delivery at all
12268 queue_only_file no immediate delivery if file exists
12269 queue_only_load no immediate delivery if load is high
12270 queue_only_load_latch don't re-evaluate load for each message
12271 queue_only_override allow command line to override
12272 queue_run_in_order order of arrival
12273 queue_run_max of simultaneous queue runners
12274 queue_smtp_domains no immediate SMTP delivery for these
12275 remote_max_parallel parallel SMTP delivery per message
12276 remote_sort_domains order of remote deliveries
12277 retry_data_expire timeout for retry data
12278 retry_interval_max safety net for retry rules
12279
12280
12281 14.22 Bounce and warning messages
12282 ---------------------------------
12283
12284 bounce_message_file content of bounce
12285 bounce_message_text content of bounce
12286 bounce_return_body include body if returning message
12287 bounce_return_message include original message in bounce
12288 bounce_return_size_limit limit on returned message
12289 bounce_sender_authentication send authenticated sender with bounce
12290 dsn_from set From: contents in bounces
12291 errors_copy copy bounce messages
12292 errors_reply_to Reply-to: in bounces
12293 delay_warning time schedule
12294 delay_warning_condition condition for warning messages
12295 ignore_bounce_errors_after discard undeliverable bounces
12296 smtp_return_error_details give detail on rejections
12297 warn_message_file content of warning message
12298
12299
12300 14.23 Alphabetical list of main options
12301 ---------------------------------------
12302
12303 Those options that undergo string expansion before use are marked with *.
12304
12305 +---------------+---------+-------------+-------------+
12306 |accept_8bitmime|Use: main|Type: boolean|Default: true|
12307 +---------------+---------+-------------+-------------+
12308
12309 This option causes Exim to send 8BITMIME in its response to an SMTP EHLO
12310 command, and to accept the BODY= parameter on MAIL commands. However, though
12311 Exim is 8-bit clean, it is not a protocol converter, and it takes no steps to
12312 do anything special with messages received by this route.
12313
12314 Historically Exim kept this option off by default, but the maintainers feel
12315 that in today's Internet, this causes more problems than it solves. It now
12316 defaults to true. A more detailed analysis of the issues is provided by Dan
12317 Bernstein:
12318
12319 http://cr.yp.to/smtp/8bitmime.html
12320
12321 To log received 8BITMIME status use
12322
12323 log_selector = +8bitmime
12324
12325 +------------+---------+-------------+--------------+
12326 |acl_not_smtp|Use: main|Type: string*|Default: unset|
12327 +------------+---------+-------------+--------------+
12328
12329 This option defines the ACL that is run when a non-SMTP message has been read
12330 and is on the point of being accepted. See chapter 42 for further details.
12331
12332 +-----------------+---------+-------------+--------------+
12333 |acl_not_smtp_mime|Use: main|Type: string*|Default: unset|
12334 +-----------------+---------+-------------+--------------+
12335
12336 This option defines the ACL that is run for individual MIME parts of non-SMTP
12337 messages. It operates in exactly the same way as acl_smtp_mime operates for
12338 SMTP messages.
12339
12340 +------------------+---------+-------------+--------------+
12341 |acl_not_smtp_start|Use: main|Type: string*|Default: unset|
12342 +------------------+---------+-------------+--------------+
12343
12344 This option defines the ACL that is run before Exim starts reading a non-SMTP
12345 message. See chapter 42 for further details.
12346
12347 +-------------+---------+-------------+--------------+
12348 |acl_smtp_auth|Use: main|Type: string*|Default: unset|
12349 +-------------+---------+-------------+--------------+
12350
12351 This option defines the ACL that is run when an SMTP AUTH command is received.
12352 See chapter 42 for further details.
12353
12354 +----------------+---------+-------------+--------------+
12355 |acl_smtp_connect|Use: main|Type: string*|Default: unset|
12356 +----------------+---------+-------------+--------------+
12357
12358 This option defines the ACL that is run when an SMTP connection is received.
12359 See chapter 42 for further details.
12360
12361 +-------------+---------+-------------+--------------+
12362 |acl_smtp_data|Use: main|Type: string*|Default: unset|
12363 +-------------+---------+-------------+--------------+
12364
12365 This option defines the ACL that is run after an SMTP DATA command has been
12366 processed and the message itself has been received, but before the final
12367 acknowledgment is sent. See chapter 42 for further details.
12368
12369 +------------------+---------+-------------+--------------+
12370 |acl_smtp_data_prdr|Use: main|Type: string*|Default: unset|
12371 +------------------+---------+-------------+--------------+
12372
12373 This option defines the ACL that, if the PRDR feature has been negotiated, is
12374 run for each recipient after an SMTP DATA command has been processed and the
12375 message itself has been received, but before the acknowledgment is sent. See
12376 chapter 42 for further details.
12377
12378 +-------------+---------+-------------+--------------+
12379 |acl_smtp_etrn|Use: main|Type: string*|Default: unset|
12380 +-------------+---------+-------------+--------------+
12381
12382 This option defines the ACL that is run when an SMTP ETRN command is received.
12383 See chapter 42 for further details.
12384
12385 +-------------+---------+-------------+--------------+
12386 |acl_smtp_expn|Use: main|Type: string*|Default: unset|
12387 +-------------+---------+-------------+--------------+
12388
12389 This option defines the ACL that is run when an SMTP EXPN command is received.
12390 See chapter 42 for further details.
12391
12392 +-------------+---------+-------------+--------------+
12393 |acl_smtp_helo|Use: main|Type: string*|Default: unset|
12394 +-------------+---------+-------------+--------------+
12395
12396 This option defines the ACL that is run when an SMTP EHLO or HELO command is
12397 received. See chapter 42 for further details.
12398
12399 +-------------+---------+-------------+--------------+
12400 |acl_smtp_mail|Use: main|Type: string*|Default: unset|
12401 +-------------+---------+-------------+--------------+
12402
12403 This option defines the ACL that is run when an SMTP MAIL command is received.
12404 See chapter 42 for further details.
12405
12406 +-----------------+---------+-------------+--------------+
12407 |acl_smtp_mailauth|Use: main|Type: string*|Default: unset|
12408 +-----------------+---------+-------------+--------------+
12409
12410 This option defines the ACL that is run when there is an AUTH parameter on a
12411 MAIL command. See chapter 42 for details of ACLs, and chapter 33 for details of
12412 authentication.
12413
12414 +-------------+---------+-------------+--------------+
12415 |acl_smtp_mime|Use: main|Type: string*|Default: unset|
12416 +-------------+---------+-------------+--------------+
12417
12418 This option is available when Exim is built with the content-scanning
12419 extension. It defines the ACL that is run for each MIME part in a message. See
12420 section 43.4 for details.
12421
12422 +----------------+---------+-------------+--------------+
12423 |acl_smtp_predata|Use: main|Type: string*|Default: unset|
12424 +----------------+---------+-------------+--------------+
12425
12426 This option defines the ACL that is run when an SMTP DATA command is received,
12427 before the message itself is received. See chapter 42 for further details.
12428
12429 +-------------+---------+-------------+--------------+
12430 |acl_smtp_quit|Use: main|Type: string*|Default: unset|
12431 +-------------+---------+-------------+--------------+
12432
12433 This option defines the ACL that is run when an SMTP QUIT command is received.
12434 See chapter 42 for further details.
12435
12436 +-------------+---------+-------------+--------------+
12437 |acl_smtp_rcpt|Use: main|Type: string*|Default: unset|
12438 +-------------+---------+-------------+--------------+
12439
12440 This option defines the ACL that is run when an SMTP RCPT command is received.
12441 See chapter 42 for further details.
12442
12443 +-----------------+---------+-------------+--------------+
12444 |acl_smtp_starttls|Use: main|Type: string*|Default: unset|
12445 +-----------------+---------+-------------+--------------+
12446
12447 This option defines the ACL that is run when an SMTP STARTTLS command is
12448 received. See chapter 42 for further details.
12449
12450 +-------------+---------+-------------+--------------+
12451 |acl_smtp_vrfy|Use: main|Type: string*|Default: unset|
12452 +-------------+---------+-------------+--------------+
12453
12454 This option defines the ACL that is run when an SMTP VRFY command is received.
12455 See chapter 42 for further details.
12456
12457 +------------+---------+------------------+--------------+
12458 |admin_groups|Use: main|Type: string list*|Default: unset|
12459 +------------+---------+------------------+--------------+
12460
12461 This option is expanded just once, at the start of Exim's processing. If the
12462 current group or any of the supplementary groups of an Exim caller is in this
12463 colon-separated list, the caller has admin privileges. If all your system
12464 programmers are in a specific group, for example, you can give them all Exim
12465 admin privileges by putting that group in admin_groups. However, this does not
12466 permit them to read Exim's spool files (whose group owner is the Exim gid). To
12467 permit this, you have to add individuals to the Exim group.
12468
12469 +---------------------+---------+-------------+--------------+
12470 |allow_domain_literals|Use: main|Type: boolean|Default: false|
12471 +---------------------+---------+-------------+--------------+
12472
12473 If this option is set, the RFC 2822 domain literal format is permitted in email
12474 addresses. The option is not set by default, because the domain literal format
12475 is not normally required these days, and few people know about it. It has,
12476 however, been exploited by mail abusers.
12477
12478 Unfortunately, it seems that some DNS black list maintainers are using this
12479 format to report black listing to postmasters. If you want to accept messages
12480 addressed to your hosts by IP address, you need to set allow_domain_literals
12481 true, and also to add "@[]" to the list of local domains (defined in the named
12482 domain list local_domains in the default configuration). This "magic string"
12483 matches the domain literal form of all the local host's IP addresses.
12484
12485 +--------------+---------+-------------+--------------+
12486 |allow_mx_to_ip|Use: main|Type: boolean|Default: false|
12487 +--------------+---------+-------------+--------------+
12488
12489 It appears that more and more DNS zone administrators are breaking the rules
12490 and putting domain names that look like IP addresses on the right hand side of
12491 MX records. Exim follows the rules and rejects this, giving an error message
12492 that explains the mis-configuration. However, some other MTAs support this
12493 practice, so to avoid "Why can't Exim do this?" complaints, allow_mx_to_ip
12494 exists, in order to enable this heinous activity. It is not recommended, except
12495 when you have no other choice.
12496
12497 +------------------+---------+-------------+--------------+
12498 |allow_utf8_domains|Use: main|Type: boolean|Default: false|
12499 +------------------+---------+-------------+--------------+
12500
12501 Lots of discussion is going on about internationalized domain names. One camp
12502 is strongly in favour of just using UTF-8 characters, and it seems that at
12503 least two other MTAs permit this. This option allows Exim users to experiment
12504 if they wish.
12505
12506 If it is set true, Exim's domain parsing function allows valid UTF-8
12507 multicharacters to appear in domain name components, in addition to letters,
12508 digits, and hyphens. However, just setting this option is not enough; if you
12509 want to look up these domain names in the DNS, you must also adjust the value
12510 of dns_check_names_pattern to match the extended form. A suitable setting is:
12511
12512 dns_check_names_pattern = (?i)^(?>(?(1)\.|())[a-z0-9\xc0-\xff]\
12513 (?>[-a-z0-9\x80-\xff]*[a-z0-9\x80-\xbf])?)+$
12514
12515 Alternatively, you can just disable this feature by setting
12516
12517 dns_check_names_pattern =
12518
12519 That is, set the option to an empty string so that no check is done.
12520
12521 +--------------------+---------+----------------+----------+
12522 |auth_advertise_hosts|Use: main|Type: host list*|Default: *|
12523 +--------------------+---------+----------------+----------+
12524
12525 If any server authentication mechanisms are configured, Exim advertises them in
12526 response to an EHLO command only if the calling host matches this list.
12527 Otherwise, Exim does not advertise AUTH. Exim does not accept AUTH commands
12528 from clients to which it has not advertised the availability of AUTH. The
12529 advertising of individual authentication mechanisms can be controlled by the
12530 use of the server_advertise_condition generic authenticator option on the
12531 individual authenticators. See chapter 33 for further details.
12532
12533 Certain mail clients (for example, Netscape) require the user to provide a name
12534 and password for authentication if AUTH is advertised, even though it may not
12535 be needed (the host may accept messages from hosts on its local LAN without
12536 authentication, for example). The auth_advertise_hosts option can be used to
12537 make these clients more friendly by excluding them from the set of hosts to
12538 which Exim advertises AUTH.
12539
12540 If you want to advertise the availability of AUTH only when the connection is
12541 encrypted using TLS, you can make use of the fact that the value of this option
12542 is expanded, with a setting like this:
12543
12544 auth_advertise_hosts = ${if eq{$tls_in_cipher}{}{}{*}}
12545
12546 If $tls_in_cipher is empty, the session is not encrypted, and the result of the
12547 expansion is empty, thus matching no hosts. Otherwise, the result of the
12548 expansion is *, which matches all hosts.
12549
12550 +---------+---------+----------+-----------+
12551 |auto_thaw|Use: main|Type: time|Default: 0s|
12552 +---------+---------+----------+-----------+
12553
12554 If this option is set to a time greater than zero, a queue runner will try a
12555 new delivery attempt on any frozen message, other than a bounce message, if
12556 this much time has passed since it was frozen. This may result in the message
12557 being re-frozen if nothing has changed since the last attempt. It is a way of
12558 saying "keep on trying, even though there are big problems".
12559
12560 Note: This is an old option, which predates timeout_frozen_after and
12561 ignore_bounce_errors_after. It is retained for compatibility, but it is not
12562 thought to be very useful any more, and its use should probably be avoided.
12563
12564 +----------+---------+------------+------------------+
12565 |av_scanner|Use: main|Type: string|Default: see below|
12566 +----------+---------+------------+------------------+
12567
12568 This option is available if Exim is built with the content-scanning extension.
12569 It specifies which anti-virus scanner to use. The default value is:
12570
12571 sophie:/var/run/sophie
12572
12573 If the value of av_scanner starts with a dollar character, it is expanded
12574 before use. See section 43.1 for further details.
12575
12576 +----------+---------+------------+--------------+
12577 |bi_command|Use: main|Type: string|Default: unset|
12578 +----------+---------+------------+--------------+
12579
12580 This option supplies the name of a command that is run when Exim is called with
12581 the -bi option (see chapter 5). The string value is just the command name, it
12582 is not a complete command line. If an argument is required, it must come from
12583 the -oA command line option.
12584
12585 +-------------------+---------+------------+--------------+
12586 |bounce_message_file|Use: main|Type: string|Default: unset|
12587 +-------------------+---------+------------+--------------+
12588
12589 This option defines a template file containing paragraphs of text to be used
12590 for constructing bounce messages. Details of the file's contents are given in
12591 chapter 48. See also warn_message_file.
12592
12593 +-------------------+---------+------------+--------------+
12594 |bounce_message_text|Use: main|Type: string|Default: unset|
12595 +-------------------+---------+------------+--------------+
12596
12597 When this option is set, its contents are included in the default bounce
12598 message immediately after "This message was created automatically by mail
12599 delivery software." It is not used if bounce_message_file is set.
12600
12601 +------------------+---------+-------------+-------------+
12602 |bounce_return_body|Use: main|Type: boolean|Default: true|
12603 +------------------+---------+-------------+-------------+
12604
12605 This option controls whether the body of an incoming message is included in a
12606 bounce message when bounce_return_message is true. The default setting causes
12607 the entire message, both header and body, to be returned (subject to the value
12608 of bounce_return_size_limit). If this option is false, only the message header
12609 is included. In the case of a non-SMTP message containing an error that is
12610 detected during reception, only those header lines preceding the point at which
12611 the error was detected are returned.
12612
12613 +---------------------+---------+-------------+-------------+
12614 |bounce_return_message|Use: main|Type: boolean|Default: true|
12615 +---------------------+---------+-------------+-------------+
12616
12617 If this option is set false, none of the original message is included in bounce
12618 messages generated by Exim. See also bounce_return_size_limit and
12619 bounce_return_body.
12620
12621 +------------------------+---------+-------------+-------------+
12622 |bounce_return_size_limit|Use: main|Type: integer|Default: 100K|
12623 +------------------------+---------+-------------+-------------+
12624
12625 This option sets a limit in bytes on the size of messages that are returned to
12626 senders as part of bounce messages when bounce_return_message is true. The
12627 limit should be less than the value of the global message_size_limit and of any
12628 message_size_limit settings on transports, to allow for the bounce text that
12629 Exim generates. If this option is set to zero there is no limit.
12630
12631 When the body of any message that is to be included in a bounce message is
12632 greater than the limit, it is truncated, and a comment pointing this out is
12633 added at the top. The actual cutoff may be greater than the value given, owing
12634 to the use of buffering for transferring the message in chunks (typically 8K in
12635 size). The idea is to save bandwidth on those undeliverable 15-megabyte
12636 messages.
12637
12638 +----------------------------+---------+------------+--------------+
12639 |bounce_sender_authentication|Use: main|Type: string|Default: unset|
12640 +----------------------------+---------+------------+--------------+
12641
12642 This option provides an authenticated sender address that is sent with any
12643 bounce messages generated by Exim that are sent over an authenticated SMTP
12644 connection. A typical setting might be:
12645
12646 bounce_sender_authentication = mailer-daemon@my.domain.example
12647
12648 which would cause bounce messages to be sent using the SMTP command:
12649
12650 MAIL FROM:<> AUTH=mailer-daemon@my.domain.example
12651
12652 The value of bounce_sender_authentication must always be a complete email
12653 address.
12654
12655 +------------------------------+---------+----------+-----------+
12656 |callout_domain_negative_expire|Use: main|Type: time|Default: 3h|
12657 +------------------------------+---------+----------+-----------+
12658
12659 This option specifies the expiry time for negative callout cache data for a
12660 domain. See section 42.45 for details of callout verification, and section
12661 42.47 for details of the caching.
12662
12663 +------------------------------+---------+----------+-----------+
12664 |callout_domain_positive_expire|Use: main|Type: time|Default: 7d|
12665 +------------------------------+---------+----------+-----------+
12666
12667 This option specifies the expiry time for positive callout cache data for a
12668 domain. See section 42.45 for details of callout verification, and section
12669 42.47 for details of the caching.
12670
12671 +-----------------------+---------+----------+-----------+
12672 |callout_negative_expire|Use: main|Type: time|Default: 2h|
12673 +-----------------------+---------+----------+-----------+
12674
12675 This option specifies the expiry time for negative callout cache data for an
12676 address. See section 42.45 for details of callout verification, and section
12677 42.47 for details of the caching.
12678
12679 +-----------------------+---------+----------+------------+
12680 |callout_positive_expire|Use: main|Type: time|Default: 24h|
12681 +-----------------------+---------+----------+------------+
12682
12683 This option specifies the expiry time for positive callout cache data for an
12684 address. See section 42.45 for details of callout verification, and section
12685 42.47 for details of the caching.
12686
12687 +-------------------------+---------+-------------+------------------+
12688 |callout_random_local_part|Use: main|Type: string*|Default: see below|
12689 +-------------------------+---------+-------------+------------------+
12690
12691 This option defines the "random" local part that can be used as part of callout
12692 verification. The default value is
12693
12694 $primary_hostname-$tod_epoch-testing
12695
12696 See section 42.46 for details of how this value is used.
12697
12698 +----------------+---------+-------------+----------+
12699 |check_log_inodes|Use: main|Type: integer|Default: 0|
12700 +----------------+---------+-------------+----------+
12701
12702 See check_spool_space below.
12703
12704 +---------------+---------+-------------+----------+
12705 |check_log_space|Use: main|Type: integer|Default: 0|
12706 +---------------+---------+-------------+----------+
12707
12708 See check_spool_space below.
12709
12710 +--------------------+---------+-------------+-------------+
12711 |check_rfc2047_length|Use: main|Type: boolean|Default: true|
12712 +--------------------+---------+-------------+-------------+
12713
12714 RFC 2047 defines a way of encoding non-ASCII characters in headers using a
12715 system of "encoded words". The RFC specifies a maximum length for an encoded
12716 word; strings to be encoded that exceed this length are supposed to use
12717 multiple encoded words. By default, Exim does not recognize encoded words that
12718 exceed the maximum length. However, it seems that some software, in violation
12719 of the RFC, generates overlong encoded words. If check_rfc2047_length is set
12720 false, Exim recognizes encoded words of any length.
12721
12722 +------------------+---------+-------------+----------+
12723 |check_spool_inodes|Use: main|Type: integer|Default: 0|
12724 +------------------+---------+-------------+----------+
12725
12726 See check_spool_space below.
12727
12728 +-----------------+---------+-------------+----------+
12729 |check_spool_space|Use: main|Type: integer|Default: 0|
12730 +-----------------+---------+-------------+----------+
12731
12732 The four check_... options allow for checking of disk resources before a
12733 message is accepted.
12734
12735 When any of these options are set, they apply to all incoming messages. If you
12736 want to apply different checks to different kinds of message, you can do so by
12737 testing the variables $log_inodes, $log_space, $spool_inodes, and $spool_space
12738 in an ACL with appropriate additional conditions.
12739
12740 check_spool_space and check_spool_inodes check the spool partition if either
12741 value is greater than zero, for example:
12742
12743 check_spool_space = 10M
12744 check_spool_inodes = 100
12745
12746 The spool partition is the one that contains the directory defined by
12747 SPOOL_DIRECTORY in Local/Makefile. It is used for holding messages in transit.
12748
12749 check_log_space and check_log_inodes check the partition in which log files are
12750 written if either is greater than zero. These should be set only if
12751 log_file_path and spool_directory refer to different partitions.
12752
12753 If there is less space or fewer inodes than requested, Exim refuses to accept
12754 incoming mail. In the case of SMTP input this is done by giving a 452 temporary
12755 error response to the MAIL command. If ESMTP is in use and there was a SIZE
12756 parameter on the MAIL command, its value is added to the check_spool_space
12757 value, and the check is performed even if check_spool_space is zero, unless
12758 no_smtp_check_spool_space is set.
12759
12760 The values for check_spool_space and check_log_space are held as a number of
12761 kilobytes. If a non-multiple of 1024 is specified, it is rounded up.
12762
12763 For non-SMTP input and for batched SMTP input, the test is done at start-up; on
12764 failure a message is written to stderr and Exim exits with a non-zero code, as
12765 it obviously cannot send an error message of any kind.
12766
12767 +-----------------+---------+------------+---------------+
12768 |daemon_smtp_ports|Use: main|Type: string|Default: "smtp"|
12769 +-----------------+---------+------------+---------------+
12770
12771 This option specifies one or more default SMTP ports on which the Exim daemon
12772 listens. See chapter 13 for details of how it is used. For backward
12773 compatibility, daemon_smtp_port (singular) is a synonym.
12774
12775 +----------------------+---------+-------------+----------+
12776 |daemon_startup_retries|Use: main|Type: integer|Default: 9|
12777 +----------------------+---------+-------------+----------+
12778
12779 This option, along with daemon_startup_sleep, controls the retrying done by the
12780 daemon at startup when it cannot immediately bind a listening socket (typically
12781 because the socket is already in use): daemon_startup_retries defines the
12782 number of retries after the first failure, and daemon_startup_sleep defines the
12783 length of time to wait between retries.
12784
12785 +--------------------+---------+----------+------------+
12786 |daemon_startup_sleep|Use: main|Type: time|Default: 30s|
12787 +--------------------+---------+----------+------------+
12788
12789 See daemon_startup_retries.
12790
12791 +-------------+---------+---------------+------------+
12792 |delay_warning|Use: main|Type: time list|Default: 24h|
12793 +-------------+---------+---------------+------------+
12794
12795 When a message is delayed, Exim sends a warning message to the sender at
12796 intervals specified by this option. The data is a colon-separated list of times
12797 after which to send warning messages. If the value of the option is an empty
12798 string or a zero time, no warnings are sent. Up to 10 times may be given. If a
12799 message has been on the queue for longer than the last time, the last interval
12800 between the times is used to compute subsequent warning times. For example,
12801 with
12802
12803 delay_warning = 4h:8h:24h
12804
12805 the first message is sent after 4 hours, the second after 8 hours, and the
12806 third one after 24 hours. After that, messages are sent every 16 hours, because
12807 that is the interval between the last two times on the list. If you set just
12808 one time, it specifies the repeat interval. For example, with:
12809
12810 delay_warning = 6h
12811
12812 messages are repeated every six hours. To stop warnings after a given time, set
12813 a very large time at the end of the list. For example:
12814
12815 delay_warning = 2h:12h:99d
12816
12817 Note that the option is only evaluated at the time a delivery attempt fails,
12818 which depends on retry and queue-runner configuration. Typically retries will
12819 be configured more frequently than warning messages.
12820
12821 +-----------------------+---------+-------------+------------------+
12822 |delay_warning_condition|Use: main|Type: string*|Default: see below|
12823 +-----------------------+---------+-------------+------------------+
12824
12825 The string is expanded at the time a warning message might be sent. If all the
12826 deferred addresses have the same domain, it is set in $domain during the
12827 expansion. Otherwise $domain is empty. If the result of the expansion is a
12828 forced failure, an empty string, or a string matching any of "0", "no" or
12829 "false" (the comparison being done caselessly) then the warning message is not
12830 sent. The default is:
12831
12832 delay_warning_condition = ${if or {\
12833 { !eq{$h_list-id:$h_list-post:$h_list-subscribe:}{} }\
12834 { match{$h_precedence:}{(?i)bulk|list|junk} }\
12835 { match{$h_auto-submitted:}{(?i)auto-generated|auto-replied} }\
12836 } {no}{yes}}
12837
12838 This suppresses the sending of warnings for messages that contain List-ID:,
12839 List-Post:, or List-Subscribe: headers, or have "bulk", "list" or "junk" in a
12840 Precedence: header, or have "auto-generated" or "auto-replied" in an
12841 Auto-Submitted: header.
12842
12843 +----------------------+---------+-------------+--------------+
12844 |deliver_drop_privilege|Use: main|Type: boolean|Default: false|
12845 +----------------------+---------+-------------+--------------+
12846
12847 If this option is set true, Exim drops its root privilege at the start of a
12848 delivery process, and runs as the Exim user throughout. This severely restricts
12849 the kinds of local delivery that are possible, but is viable in certain types
12850 of configuration. There is a discussion about the use of root privilege in
12851 chapter 54.
12852
12853 +----------------------+---------+-----------------+--------------+
12854 |deliver_queue_load_max|Use: main|Type: fixed-point|Default: unset|
12855 +----------------------+---------+-----------------+--------------+
12856
12857 When this option is set, a queue run is abandoned if the system load average
12858 becomes greater than the value of the option. The option has no effect on
12859 ancient operating systems on which Exim cannot determine the load average. See
12860 also queue_only_load and smtp_load_reserve.
12861
12862 +--------------------+---------+-------------+-------------+
12863 |delivery_date_remove|Use: main|Type: boolean|Default: true|
12864 +--------------------+---------+-------------+-------------+
12865
12866 Exim's transports have an option for adding a Delivery-date: header to a
12867 message when it is delivered, in exactly the same way as Return-path: is
12868 handled. Delivery-date: records the actual time of delivery. Such headers
12869 should not be present in incoming messages, and this option causes them to be
12870 removed at the time the message is received, to avoid any problems that might
12871 occur when a delivered message is subsequently sent on to some other recipient.
12872
12873 +-------------+---------+-------------+--------------+
12874 |disable_fsync|Use: main|Type: boolean|Default: false|
12875 +-------------+---------+-------------+--------------+
12876
12877 This option is available only if Exim was built with the compile-time option
12878 ENABLE_DISABLE_FSYNC. When this is not set, a reference to disable_fsync in a
12879 runtime configuration generates an "unknown option" error. You should not build
12880 Exim with ENABLE_DISABLE_FSYNC or set disable_fsync unless you really, really,
12881 really understand what you are doing. No pre-compiled distributions of Exim
12882 should ever make this option available.
12883
12884 When disable_fsync is set true, Exim no longer calls fsync() to force updated
12885 files' data to be written to disc before continuing. Unexpected events such as
12886 crashes and power outages may cause data to be lost or scrambled. Here be
12887 Dragons. Beware.
12888
12889 +------------+---------+-------------+--------------+
12890 |disable_ipv6|Use: main|Type: boolean|Default: false|
12891 +------------+---------+-------------+--------------+
12892
12893 If this option is set true, even if the Exim binary has IPv6 support, no IPv6
12894 activities take place. AAAA records are never looked up, and any IPv6 addresses
12895 that are listed in local_interfaces, data for the manualroute router, etc. are
12896 ignored. If IP literals are enabled, the ipliteral router declines to handle
12897 IPv6 literal addresses.
12898
12899 +------------------------+---------+------------------+--------------+
12900 |dns_again_means_nonexist|Use: main|Type: domain list*|Default: unset|
12901 +------------------------+---------+------------------+--------------+
12902
12903 DNS lookups give a "try again" response for the DNS errors "non-authoritative
12904 host not found" and "SERVERFAIL". This can cause Exim to keep trying to deliver
12905 a message, or to give repeated temporary errors to incoming mail. Sometimes the
12906 effect is caused by a badly set up name server and may persist for a long time.
12907 If a domain which exhibits this problem matches anything in
12908 dns_again_means_nonexist, it is treated as if it did not exist. This option
12909 should be used with care. You can make it apply to reverse lookups by a setting
12910 such as this:
12911
12912 dns_again_means_nonexist = *.in-addr.arpa
12913
12914 This option applies to all DNS lookups that Exim does. It also applies when the
12915 gethostbyname() or getipnodebyname() functions give temporary errors, since
12916 these are most likely to be caused by DNS lookup problems. The dnslookup router
12917 has some options of its own for controlling what happens when lookups for MX or
12918 SRV records give temporary errors. These more specific options are applied
12919 after this global option.
12920
12921 +-----------------------+---------+------------+------------------+
12922 |dns_check_names_pattern|Use: main|Type: string|Default: see below|
12923 +-----------------------+---------+------------+------------------+
12924
12925 When this option is set to a non-empty string, it causes Exim to check domain
12926 names for characters that are not allowed in host names before handing them to
12927 the DNS resolver, because some resolvers give temporary errors for names that
12928 contain unusual characters. If a domain name contains any unwanted characters,
12929 a "not found" result is forced, and the resolver is not called. The check is
12930 done by matching the domain name against a regular expression, which is the
12931 value of this option. The default pattern is
12932
12933 dns_check_names_pattern = \
12934 (?i)^(?>(?(1)\.|())[^\W_](?>[a-z0-9/-]*[^\W_])?)+$
12935
12936 which permits only letters, digits, slashes, and hyphens in components, but
12937 they must start and end with a letter or digit. Slashes are not, in fact,
12938 permitted in host names, but they are found in certain NS records (which can be
12939 accessed in Exim by using a dnsdb lookup). If you set allow_utf8_domains, you
12940 must modify this pattern, or set the option to an empty string.
12941
12942 +--------------------+---------+-------------+----------+
12943 |dns_csa_search_limit|Use: main|Type: integer|Default: 5|
12944 +--------------------+---------+-------------+----------+
12945
12946 This option controls the depth of parental searching for CSA SRV records in the
12947 DNS, as described in more detail in section 42.50.
12948
12949 +-------------------+---------+-------------+-------------+
12950 |dns_csa_use_reverse|Use: main|Type: boolean|Default: true|
12951 +-------------------+---------+-------------+-------------+
12952
12953 This option controls whether or not an IP address, given as a CSA domain, is
12954 reversed and looked up in the reverse DNS, as described in more detail in
12955 section 42.50.
12956
12957 +-------------+---------+-------------+-----------+
12958 |dns_dnssec_ok|Use: main|Type: integer|Default: -1|
12959 +-------------+---------+-------------+-----------+
12960
12961 If this option is set to a non-negative number then Exim will initialise the
12962 DNS resolver library to either use or not use DNSSEC, overriding the system
12963 default. A value of 0 coerces DNSSEC off, a value of 1 coerces DNSSEC on.
12964
12965 If the resolver library does not support DNSSEC then this option has no effect.
12966
12967 +---------------+---------+------------------+--------------+
12968 |dns_ipv4_lookup|Use: main|Type: domain list*|Default: unset|
12969 +---------------+---------+------------------+--------------+
12970
12971 When Exim is compiled with IPv6 support and disable_ipv6 is not set, it looks
12972 for IPv6 address records (AAAA records) as well as IPv4 address records (A
12973 records) when trying to find IP addresses for hosts, unless the host's domain
12974 matches this list.
12975
12976 This is a fudge to help with name servers that give big delays or otherwise do
12977 not work for the AAAA record type. In due course, when the world's name servers
12978 have all been upgraded, there should be no need for this option.
12979
12980 +-----------+---------+----------+-----------+
12981 |dns_retrans|Use: main|Type: time|Default: 0s|
12982 +-----------+---------+----------+-----------+
12983
12984 The options dns_retrans and dns_retry can be used to set the retransmission and
12985 retry parameters for DNS lookups. Values of zero (the defaults) leave the
12986 system default settings unchanged. The first value is the time between retries,
12987 and the second is the number of retries. It isn't totally clear exactly how
12988 these settings affect the total time a DNS lookup may take. I haven't found any
12989 documentation about timeouts on DNS lookups; these parameter values are
12990 available in the external resolver interface structure, but nowhere does it
12991 seem to describe how they are used or what you might want to set in them.
12992
12993 +---------+---------+-------------+----------+
12994 |dns_retry|Use: main|Type: integer|Default: 0|
12995 +---------+---------+-------------+----------+
12996
12997 See dns_retrans above.
12998
12999 +-------------+---------+-------------+-----------+
13000 |dns_use_edns0|Use: main|Type: integer|Default: -1|
13001 +-------------+---------+-------------+-----------+
13002
13003 If this option is set to a non-negative number then Exim will initialise the
13004 DNS resolver library to either use or not use EDNS0 extensions, overriding the
13005 system default. A value of 0 coerces EDNS0 off, a value of 1 coerces EDNS0 on.
13006
13007 If the resolver library does not support EDNS0 then this option has no effect.
13008
13009 +-------+---------+-------------+--------------+
13010 |drop_cr|Use: main|Type: boolean|Default: false|
13011 +-------+---------+-------------+--------------+
13012
13013 This is an obsolete option that is now a no-op. It used to affect the way Exim
13014 handled CR and LF characters in incoming messages. What happens now is
13015 described in section 46.2.
13016
13017 +--------+---------+-------------+------------------+
13018 |dsn_from|Use: main|Type: string*|Default: see below|
13019 +--------+---------+-------------+------------------+
13020
13021 This option can be used to vary the contents of From: header lines in bounces
13022 and other automatically generated messages ("Delivery Status Notifications" -
13023 hence the name of the option). The default setting is:
13024
13025 dsn_from = Mail Delivery System <Mailer-Daemon@$qualify_domain>
13026
13027 The value is expanded every time it is needed. If the expansion fails, a panic
13028 is logged, and the default value is used.
13029
13030 +------------------+---------+-------------+-------------+
13031 |envelope_to_remove|Use: main|Type: boolean|Default: true|
13032 +------------------+---------+-------------+-------------+
13033
13034 Exim's transports have an option for adding an Envelope-to: header to a message
13035 when it is delivered, in exactly the same way as Return-path: is handled.
13036 Envelope-to: records the original recipient address from the messages's
13037 envelope that caused the delivery to happen. Such headers should not be present
13038 in incoming messages, and this option causes them to be removed at the time the
13039 message is received, to avoid any problems that might occur when a delivered
13040 message is subsequently sent on to some other recipient.
13041
13042 +-----------+---------+------------------+--------------+
13043 |errors_copy|Use: main|Type: string list*|Default: unset|
13044 +-----------+---------+------------------+--------------+
13045
13046 Setting this option causes Exim to send bcc copies of bounce messages that it
13047 generates to other addresses. Note: This does not apply to bounce messages
13048 coming from elsewhere. The value of the option is a colon-separated list of
13049 items. Each item consists of a pattern, terminated by white space, followed by
13050 a comma-separated list of email addresses. If a pattern contains spaces, it
13051 must be enclosed in double quotes.
13052
13053 Each pattern is processed in the same way as a single item in an address list
13054 (see section 10.19). When a pattern matches the recipient of the bounce
13055 message, the message is copied to the addresses on the list. The items are
13056 scanned in order, and once a matching one is found, no further items are
13057 examined. For example:
13058
13059 errors_copy = spqr@mydomain postmaster@mydomain.example :\
13060 rqps@mydomain hostmaster@mydomain.example,\
13061 postmaster@mydomain.example
13062
13063 The address list is expanded before use. The expansion variables $local_part
13064 and $domain are set from the original recipient of the error message, and if
13065 there was any wildcard matching in the pattern, the expansion variables $0, $1,
13066 etc. are set in the normal way.
13067
13068 +---------------+---------+------------+--------------+
13069 |errors_reply_to|Use: main|Type: string|Default: unset|
13070 +---------------+---------+------------+--------------+
13071
13072 By default, Exim's bounce and delivery warning messages contain the header line
13073
13074 From: Mail Delivery System <Mailer-Daemon@qualify-domain>
13075
13076 where qualify-domain is the value of the qualify_domain option. A warning
13077 message that is generated by the quota_warn_message option in an appendfile
13078 transport may contain its own From: header line that overrides the default.
13079
13080 Experience shows that people reply to bounce messages. If the errors_reply_to
13081 option is set, a Reply-To: header is added to bounce and warning messages. For
13082 example:
13083
13084 errors_reply_to = postmaster@my.domain.example
13085
13086 The value of the option is not expanded. It must specify a valid RFC 2822
13087 address. However, if a warning message that is generated by the
13088 quota_warn_message option in an appendfile transport contain its own Reply-To:
13089 header line, the value of the errors_reply_to option is not used.
13090
13091 +----------+---------+------------+--------------------------------+
13092 |exim_group|Use: main|Type: string|Default: compile-time configured|
13093 +----------+---------+------------+--------------------------------+
13094
13095 This option changes the gid under which Exim runs when it gives up root
13096 privilege. The default value is compiled into the binary. The value of this
13097 option is used only when exim_user is also set. Unless it consists entirely of
13098 digits, the string is looked up using getgrnam(), and failure causes a
13099 configuration error. See chapter 54 for a discussion of security issues.
13100
13101 +---------+---------+------------+------------------+
13102 |exim_path|Use: main|Type: string|Default: see below|
13103 +---------+---------+------------+------------------+
13104
13105 This option specifies the path name of the Exim binary, which is used when Exim
13106 needs to re-exec itself. The default is set up to point to the file exim in the
13107 directory configured at compile time by the BIN_DIRECTORY setting. It is
13108 necessary to change exim_path if, exceptionally, Exim is run from some other
13109 place. Warning: Do not use a macro to define the value of this option, because
13110 you will break those Exim utilities that scan the configuration file to find
13111 where the binary is. (They then use the -bP option to extract option settings
13112 such as the value of spool_directory.)
13113
13114 +---------+---------+------------+--------------------------------+
13115 |exim_user|Use: main|Type: string|Default: compile-time configured|
13116 +---------+---------+------------+--------------------------------+
13117
13118 This option changes the uid under which Exim runs when it gives up root
13119 privilege. The default value is compiled into the binary. Ownership of the run
13120 time configuration file and the use of the -C and -D command line options is
13121 checked against the values in the binary, not what is set here.
13122
13123 Unless it consists entirely of digits, the string is looked up using getpwnam()
13124 , and failure causes a configuration error. If exim_group is not also supplied,
13125 the gid is taken from the result of getpwnam() if it is used. See chapter 54
13126 for a discussion of security issues.
13127
13128 +----------------------+---------+-----------------+--------------+
13129 |extra_local_interfaces|Use: main|Type: string list|Default: unset|
13130 +----------------------+---------+-----------------+--------------+
13131
13132 This option defines network interfaces that are to be considered local when
13133 routing, but which are not used for listening by the daemon. See section 13.8
13134 for details.
13135
13136 +-------------------------------------+---------+-------------+-------------+
13137 |extract_addresses_remove_ arguments|Use: main|Type: boolean|Default: true|
13138 +-------------------------------------+---------+-------------+-------------+
13139
13140 According to some Sendmail documentation (Sun, IRIX, HP-UX), if any addresses
13141 are present on the command line when the -t option is used to build an envelope
13142 from a message's To:, Cc: and Bcc: headers, the command line addresses are
13143 removed from the recipients list. This is also how Smail behaves. However,
13144 other Sendmail documentation (the O'Reilly book) states that command line
13145 addresses are added to those obtained from the header lines. When
13146 extract_addresses_remove_arguments is true (the default), Exim subtracts
13147 argument headers. If it is set false, Exim adds rather than removes argument
13148 addresses.
13149
13150 +----------------+---------+-------------+----------+
13151 |finduser_retries|Use: main|Type: integer|Default: 0|
13152 +----------------+---------+-------------+----------+
13153
13154 On systems running NIS or other schemes in which user and group information is
13155 distributed from a remote system, there can be times when getpwnam() and
13156 related functions fail, even when given valid data, because things time out.
13157 Unfortunately these failures cannot be distinguished from genuine "not found"
13158 errors. If finduser_retries is set greater than zero, Exim will try that many
13159 extra times to find a user or a group, waiting for one second between retries.
13160
13161 You should not set this option greater than zero if your user information is in
13162 a traditional /etc/passwd file, because it will cause Exim needlessly to search
13163 the file multiple times for non-existent users, and also cause delay.
13164
13165 +-----------+---------+----------------------------------+--------------+
13166 |freeze_tell|Use: main|Type: string list, comma separated|Default: unset|
13167 +-----------+---------+----------------------------------+--------------+
13168
13169 On encountering certain errors, or when configured to do so in a system filter,
13170 ACL, or special router, Exim freezes a message. This means that no further
13171 delivery attempts take place until an administrator thaws the message, or the
13172 auto_thaw, ignore_bounce_errors_after, or timeout_frozen_after feature cause it
13173 to be processed. If freeze_tell is set, Exim generates a warning message
13174 whenever it freezes something, unless the message it is freezing is a
13175 locally-generated bounce message. (Without this exception there is the
13176 possibility of looping.) The warning message is sent to the addresses supplied
13177 as the comma-separated value of this option. If several of the message's
13178 addresses cause freezing, only a single message is sent. If the freezing was
13179 automatic, the reason(s) for freezing can be found in the message log. If you
13180 configure freezing in a filter or ACL, you must arrange for any logging that
13181 you require.
13182
13183 +----------+---------+-------------+--------------+
13184 |gecos_name|Use: main|Type: string*|Default: unset|
13185 +----------+---------+-------------+--------------+
13186
13187 Some operating systems, notably HP-UX, use the "gecos" field in the system
13188 password file to hold other information in addition to users' real names. Exim
13189 looks up this field for use when it is creating Sender: or From: headers. If
13190 either gecos_pattern or gecos_name are unset, the contents of the field are
13191 used unchanged, except that, if an ampersand is encountered, it is replaced by
13192 the user's login name with the first character forced to upper case, since this
13193 is a convention that is observed on many systems.
13194
13195 When these options are set, gecos_pattern is treated as a regular expression
13196 that is to be applied to the field (again with & replaced by the login name),
13197 and if it matches, gecos_name is expanded and used as the user's name.
13198
13199 Numeric variables such as $1, $2, etc. can be used in the expansion to pick up
13200 sub-fields that were matched by the pattern. In HP-UX, where the user's name
13201 terminates at the first comma, the following can be used:
13202
13203 gecos_pattern = ([^,]*)
13204 gecos_name = $1
13205
13206 +-------------+---------+------------+--------------+
13207 |gecos_pattern|Use: main|Type: string|Default: unset|
13208 +-------------+---------+------------+--------------+
13209
13210 See gecos_name above.
13211
13212 +------------------+---------+-------------+--------------+
13213 |gnutls_compat_mode|Use: main|Type: boolean|Default: unset|
13214 +------------------+---------+-------------+--------------+
13215
13216 This option controls whether GnuTLS is used in compatibility mode in an Exim
13217 server. This reduces security slightly, but improves interworking with older
13218 implementations of TLS.
13219
13220 option gnutls_allow_auto_pkcs11 main boolean unset This option will let GnuTLS
13221 (2.12.0 or later) autoload PKCS11 modules with the p11-kit configuration files
13222 in /etc/pkcs11/modules/.
13223
13224 See http://www.gnutls.org/manual/gnutls.html#Smart-cards-and-HSMs for
13225 documentation.
13226
13227 +---------------+---------+------------+------------------+
13228 |headers_charset|Use: main|Type: string|Default: see below|
13229 +---------------+---------+------------+------------------+
13230
13231 This option sets a default character set for translating from encoded MIME
13232 "words" in header lines, when referenced by an $h_xxx expansion item. The
13233 default is the value of HEADERS_CHARSET in Local/Makefile. The ultimate default
13234 is ISO-8859-1. For more details see the description of header insertions in
13235 section 11.5.
13236
13237 +--------------+---------+-------------+------------------+
13238 |header_maxsize|Use: main|Type: integer|Default: see below|
13239 +--------------+---------+-------------+------------------+
13240
13241 This option controls the overall maximum size of a message's header section.
13242 The default is the value of HEADER_MAXSIZE in Local/Makefile; the default for
13243 that is 1M. Messages with larger header sections are rejected.
13244
13245 +-------------------+---------+-------------+----------+
13246 |header_line_maxsize|Use: main|Type: integer|Default: 0|
13247 +-------------------+---------+-------------+----------+
13248
13249 This option limits the length of any individual header line in a message, after
13250 all the continuations have been joined together. Messages with individual
13251 header lines that are longer than the limit are rejected. The default value of
13252 zero means "no limit".
13253
13254 +----------------------+---------+----------------+--------------+
13255 |helo_accept_junk_hosts|Use: main|Type: host list*|Default: unset|
13256 +----------------------+---------+----------------+--------------+
13257
13258 Exim checks the syntax of HELO and EHLO commands for incoming SMTP mail, and
13259 gives an error response for invalid data. Unfortunately, there are some SMTP
13260 clients that send syntactic junk. They can be accommodated by setting this
13261 option. Note that this is a syntax check only. See helo_verify_hosts if you
13262 want to do semantic checking. See also helo_allow_chars for a way of extending
13263 the permitted character set.
13264
13265 +----------------+---------+------------+--------------+
13266 |helo_allow_chars|Use: main|Type: string|Default: unset|
13267 +----------------+---------+------------+--------------+
13268
13269 This option can be set to a string of rogue characters that are permitted in
13270 all EHLO and HELO names in addition to the standard letters, digits, hyphens,
13271 and dots. If you really must allow underscores, you can set
13272
13273 helo_allow_chars = _
13274
13275 Note that the value is one string, not a list.
13276
13277 +-------------------+---------+------------------+----------------+
13278 |helo_lookup_domains|Use: main|Type: domain list*|Default: "@:@[]"|
13279 +-------------------+---------+------------------+----------------+
13280
13281 If the domain given by a client in a HELO or EHLO command matches this list, a
13282 reverse lookup is done in order to establish the host's true name. The default
13283 forces a lookup if the client host gives the server's name or any of its IP
13284 addresses (in brackets), something that broken clients have been seen to do.
13285
13286 +---------------------+---------+----------------+--------------+
13287 |helo_try_verify_hosts|Use: main|Type: host list*|Default: unset|
13288 +---------------------+---------+----------------+--------------+
13289
13290 By default, Exim just checks the syntax of HELO and EHLO commands (see
13291 helo_accept_junk_hosts and helo_allow_chars). However, some sites like to do
13292 more extensive checking of the data supplied by these commands. The ACL
13293 condition "verify = helo" is provided to make this possible. Formerly, it was
13294 necessary also to set this option (helo_try_verify_hosts) to force the check to
13295 occur. From release 4.53 onwards, this is no longer necessary. If the check has
13296 not been done before "verify = helo" is encountered, it is done at that time.
13297 Consequently, this option is obsolete. Its specification is retained here for
13298 backwards compatibility.
13299
13300 When an EHLO or HELO command is received, if the calling host matches
13301 helo_try_verify_hosts, Exim checks that the host name given in the HELO or EHLO
13302 command either:
13303
13304 * is an IP literal matching the calling address of the host, or
13305
13306 * matches the host name that Exim obtains by doing a reverse lookup of the
13307 calling host address, or
13308
13309 * when looked up using gethostbyname() (or getipnodebyname() when available)
13310 yields the calling host address.
13311
13312 However, the EHLO or HELO command is not rejected if any of the checks fail.
13313 Processing continues, but the result of the check is remembered, and can be
13314 detected later in an ACL by the "verify = helo" condition.
13315
13316 +-----------------+---------+----------------+--------------+
13317 |helo_verify_hosts|Use: main|Type: host list*|Default: unset|
13318 +-----------------+---------+----------------+--------------+
13319
13320 Like helo_try_verify_hosts, this option is obsolete, and retained only for
13321 backwards compatibility. For hosts that match this option, Exim checks the host
13322 name given in the HELO or EHLO in the same way as for helo_try_verify_hosts. If
13323 the check fails, the HELO or EHLO command is rejected with a 550 error, and
13324 entries are written to the main and reject logs. If a MAIL command is received
13325 before EHLO or HELO, it is rejected with a 503 error.
13326
13327 +------------+---------+------------------+--------------+
13328 |hold_domains|Use: main|Type: domain list*|Default: unset|
13329 +------------+---------+------------------+--------------+
13330
13331 This option allows mail for particular domains to be held on the queue
13332 manually. The option is overridden if a message delivery is forced with the -M,
13333 -qf, -Rf or -Sf options, and also while testing or verifying addresses using
13334 -bt or -bv. Otherwise, if a domain matches an item in hold_domains, no routing
13335 or delivery for that address is done, and it is deferred every time the message
13336 is looked at.
13337
13338 This option is intended as a temporary operational measure for delaying the
13339 delivery of mail while some problem is being sorted out, or some new
13340 configuration tested. If you just want to delay the processing of some domains
13341 until a queue run occurs, you should use queue_domains or queue_smtp_domains,
13342 not hold_domains.
13343
13344 A setting of hold_domains does not override Exim's code for removing messages
13345 from the queue if they have been there longer than the longest retry time in
13346 any retry rule. If you want to hold messages for longer than the normal retry
13347 times, insert a dummy retry rule with a long retry time.
13348
13349 +-----------+---------+----------------+--------------+
13350 |host_lookup|Use: main|Type: host list*|Default: unset|
13351 +-----------+---------+----------------+--------------+
13352
13353 Exim does not look up the name of a calling host from its IP address unless it
13354 is required to compare against some host list, or the host matches
13355 helo_try_verify_hosts or helo_verify_hosts, or the host matches this option
13356 (which normally contains IP addresses rather than host names). The default
13357 configuration file contains
13358
13359 host_lookup = *
13360
13361 which causes a lookup to happen for all hosts. If the expense of these lookups
13362 is felt to be too great, the setting can be changed or removed.
13363
13364 After a successful reverse lookup, Exim does a forward lookup on the name it
13365 has obtained, to verify that it yields the IP address that it started with. If
13366 this check fails, Exim behaves as if the name lookup failed.
13367
13368 After any kind of failure, the host name (in $sender_host_name) remains unset,
13369 and $host_lookup_failed is set to the string "1". See also
13370 dns_again_means_nonexist, helo_lookup_domains, and "verify =
13371 reverse_host_lookup" in ACLs.
13372
13373 +-----------------+---------+-----------------+-----------------------+
13374 |host_lookup_order|Use: main|Type: string list|Default: "bydns:byaddr"|
13375 +-----------------+---------+-----------------+-----------------------+
13376
13377 This option specifies the order of different lookup methods when Exim is trying
13378 to find a host name from an IP address. The default is to do a DNS lookup
13379 first, and then to try a local lookup (using gethostbyaddr() or equivalent) if
13380 that fails. You can change the order of these lookups, or omit one entirely, if
13381 you want.
13382
13383 Warning: The "byaddr" method does not always yield aliases when there are
13384 multiple PTR records in the DNS and the IP address is not listed in /etc/hosts.
13385 Different operating systems give different results in this case. That is why
13386 the default tries a DNS lookup first.
13387
13388 +----------------------+---------+----------------+--------------+
13389 |host_reject_connection|Use: main|Type: host list*|Default: unset|
13390 +----------------------+---------+----------------+--------------+
13391
13392 If this option is set, incoming SMTP calls from the hosts listed are rejected
13393 as soon as the connection is made. This option is obsolete, and retained only
13394 for backward compatibility, because nowadays the ACL specified by
13395 acl_smtp_connect can also reject incoming connections immediately.
13396
13397 The ability to give an immediate rejection (either by this option or using an
13398 ACL) is provided for use in unusual cases. Many hosts will just try again,
13399 sometimes without much delay. Normally, it is better to use an ACL to reject
13400 incoming messages at a later stage, such as after RCPT commands. See chapter 42
13401 .
13402
13403 +----------------------+---------+----------------+--------------+
13404 |hosts_connection_nolog|Use: main|Type: host list*|Default: unset|
13405 +----------------------+---------+----------------+--------------+
13406
13407 This option defines a list of hosts for which connection logging does not
13408 happen, even though the smtp_connection log selector is set. For example, you
13409 might want not to log SMTP connections from local processes, or from 127.0.0.1,
13410 or from your local LAN. This option is consulted in the main loop of the
13411 daemon; you should therefore strive to restrict its value to a short inline
13412 list of IP addresses and networks. To disable logging SMTP connections from
13413 local processes, you must create a host list with an empty item. For example:
13414
13415 hosts_connection_nolog = :
13416
13417 If the smtp_connection log selector is not set, this option has no effect.
13418
13419 +--------------------+---------+------------------+--------------+
13420 |hosts_treat_as_local|Use: main|Type: domain list*|Default: unset|
13421 +--------------------+---------+------------------+--------------+
13422
13423 If this option is set, any host names that match the domain list are treated as
13424 if they were the local host when Exim is scanning host lists obtained from MX
13425 records or other sources. Note that the value of this option is a domain list,
13426 not a host list, because it is always used to check host names, not IP
13427 addresses.
13428
13429 This option also applies when Exim is matching the special items "@mx_any",
13430 "@mx_primary", and "@mx_secondary" in a domain list (see section 10.8), and
13431 when checking the hosts option in the smtp transport for the local host (see
13432 the allow_localhost option in that transport). See also local_interfaces,
13433 extra_local_interfaces, and chapter 13, which contains a discussion about local
13434 network interfaces and recognizing the local host.
13435
13436 +-------------+---------+-----------------+--------------+
13437 |ibase_servers|Use: main|Type: string list|Default: unset|
13438 +-------------+---------+-----------------+--------------+
13439
13440 This option provides a list of InterBase servers and associated connection
13441 data, to be used in conjunction with ibase lookups (see section 9.21). The
13442 option is available only if Exim has been built with InterBase support.
13443
13444 +--------------------------+---------+----------+------------+
13445 |ignore_bounce_errors_after|Use: main|Type: time|Default: 10w|
13446 +--------------------------+---------+----------+------------+
13447
13448 This option affects the processing of bounce messages that cannot be delivered,
13449 that is, those that suffer a permanent delivery failure. (Bounce messages that
13450 suffer temporary delivery failures are of course retried in the usual way.)
13451
13452 After a permanent delivery failure, bounce messages are frozen, because there
13453 is no sender to whom they can be returned. When a frozen bounce message has
13454 been on the queue for more than the given time, it is unfrozen at the next
13455 queue run, and a further delivery is attempted. If delivery fails again, the
13456 bounce message is discarded. This makes it possible to keep failed bounce
13457 messages around for a shorter time than the normal maximum retry time for
13458 frozen messages. For example,
13459
13460 ignore_bounce_errors_after = 12h
13461
13462 retries failed bounce message deliveries after 12 hours, discarding any further
13463 failures. If the value of this option is set to a zero time period, bounce
13464 failures are discarded immediately. Setting a very long time (as in the default
13465 value) has the effect of disabling this option. For ways of automatically
13466 dealing with other kinds of frozen message, see auto_thaw and
13467 timeout_frozen_after.
13468
13469 +---------------------+---------+----------------+--------------+
13470 |ignore_fromline_hosts|Use: main|Type: host list*|Default: unset|
13471 +---------------------+---------+----------------+--------------+
13472
13473 Some broken SMTP clients insist on sending a UUCP-like "From " line before the
13474 headers of a message. By default this is treated as the start of the message's
13475 body, which means that any following headers are not recognized as such. Exim
13476 can be made to ignore it by setting ignore_fromline_hosts to match those hosts
13477 that insist on sending it. If the sender is actually a local process rather
13478 than a remote host, and is using -bs to inject the messages,
13479 ignore_fromline_local must be set to achieve this effect.
13480
13481 +---------------------+---------+-------------+--------------+
13482 |ignore_fromline_local|Use: main|Type: boolean|Default: false|
13483 +---------------------+---------+-------------+--------------+
13484
13485 See ignore_fromline_hosts above.
13486
13487 +--------------+---------+----------+-----------+
13488 |keep_malformed|Use: main|Type: time|Default: 4d|
13489 +--------------+---------+----------+-----------+
13490
13491 This option specifies the length of time to keep messages whose spool files
13492 have been corrupted in some way. This should, of course, never happen. At the
13493 next attempt to deliver such a message, it gets removed. The incident is
13494 logged.
13495
13496 +----------------+---------+------------+--------------+
13497 |ldap_ca_cert_dir|Use: main|Type: string|Default: unset|
13498 +----------------+---------+------------+--------------+
13499
13500 This option indicates which directory contains CA certificates for verifying a
13501 TLS certificate presented by an LDAP server. While Exim does not provide a
13502 default value, your SSL library may. Analogous to tls_verify_certificates but
13503 as a client-side option for LDAP and constrained to be a directory.
13504
13505 +-----------------+---------+------------+--------------+
13506 |ldap_ca_cert_file|Use: main|Type: string|Default: unset|
13507 +-----------------+---------+------------+--------------+
13508
13509 This option indicates which file contains CA certificates for verifying a TLS
13510 certificate presented by an LDAP server. While Exim does not provide a default
13511 value, your SSL library may. Analogous to tls_verify_certificates but as a
13512 client-side option for LDAP and constrained to be a file.
13513
13514 +--------------+---------+------------+--------------+
13515 |ldap_cert_file|Use: main|Type: string|Default: unset|
13516 +--------------+---------+------------+--------------+
13517
13518 This option indicates which file contains an TLS client certificate which Exim
13519 should present to the LDAP server during TLS negotiation. Should be used
13520 together with ldap_cert_key.
13521
13522 +-------------+---------+------------+--------------+
13523 |ldap_cert_key|Use: main|Type: string|Default: unset|
13524 +-------------+---------+------------+--------------+
13525
13526 This option indicates which file contains the secret/private key to use to
13527 prove identity to the LDAP server during TLS negotiation. Should be used
13528 together with ldap_cert_file, which contains the identity to be proven.
13529
13530 +-----------------+---------+------------+--------------+
13531 |ldap_cipher_suite|Use: main|Type: string|Default: unset|
13532 +-----------------+---------+------------+--------------+
13533
13534 This controls the TLS cipher-suite negotiation during TLS negotiation with the
13535 LDAP server. See 41.4 for more details of the format of cipher-suite options
13536 with OpenSSL (as used by LDAP client libraries).
13537
13538 +--------------------+---------+-----------------+--------------+
13539 |ldap_default_servers|Use: main|Type: string list|Default: unset|
13540 +--------------------+---------+-----------------+--------------+
13541
13542 This option provides a list of LDAP servers which are tried in turn when an
13543 LDAP query does not contain a server. See section 9.14 for details of LDAP
13544 queries. This option is available only when Exim has been built with LDAP
13545 support.
13546
13547 +-----------------+---------+------------+---------------+
13548 |ldap_require_cert|Use: main|Type: string|Default: unset.|
13549 +-----------------+---------+------------+---------------+
13550
13551 This should be one of the values "hard", "demand", "allow", "try" or "never". A
13552 value other than one of these is interpreted as "never". See the entry
13553 "TLS_REQCERT" in your system man page for ldap.conf(5). Although Exim does not
13554 set a default, the LDAP library probably defaults to hard/demand.
13555
13556 +--------------+---------+-------------+--------------+
13557 |ldap_start_tls|Use: main|Type: boolean|Default: false|
13558 +--------------+---------+-------------+--------------+
13559
13560 If set, Exim will attempt to negotiate TLS with the LDAP server when connecting
13561 on a regular LDAP port. This is the LDAP equivalent of SMTP's "STARTTLS". This
13562 is distinct from using "ldaps", which is the LDAP form of SSL-on-connect. In
13563 the event of failure to negotiate TLS, the action taken is controlled by
13564 ldap_require_cert.
13565
13566 +------------+---------+-------------+--------------+
13567 |ldap_version|Use: main|Type: integer|Default: unset|
13568 +------------+---------+-------------+--------------+
13569
13570 This option can be used to force Exim to set a specific protocol version for
13571 LDAP. If it option is unset, it is shown by the -bP command line option as -1.
13572 When this is the case, the default is 3 if LDAP_VERSION3 is defined in the LDAP
13573 headers; otherwise it is 2. This option is available only when Exim has been
13574 built with LDAP support.
13575
13576 +----------------+---------+-------------+-------------+
13577 |local_from_check|Use: main|Type: boolean|Default: true|
13578 +----------------+---------+-------------+-------------+
13579
13580 When a message is submitted locally (that is, not over a TCP/IP connection) by
13581 an untrusted user, Exim removes any existing Sender: header line, and checks
13582 that the From: header line matches the login of the calling user and the domain
13583 specified by qualify_domain.
13584
13585 Note: An unqualified address (no domain) in the From: header in a locally
13586 submitted message is automatically qualified by Exim, unless the -bnq command
13587 line option is used.
13588
13589 You can use local_from_prefix and local_from_suffix to permit affixes on the
13590 local part. If the From: header line does not match, Exim adds a Sender: header
13591 with an address constructed from the calling user's login and the default
13592 qualify domain.
13593
13594 If local_from_check is set false, the From: header check is disabled, and no
13595 Sender: header is ever added. If, in addition, you want to retain Sender:
13596 header lines supplied by untrusted users, you must also set local_sender_retain
13597 to be true.
13598
13599 These options affect only the header lines in the message. The envelope sender
13600 is still forced to be the login id at the qualify domain unless
13601 untrusted_set_sender permits the user to supply an envelope sender.
13602
13603 For messages received over TCP/IP, an ACL can specify "submission mode" to
13604 request similar header line checking. See section 46.16, which has more details
13605 about Sender: processing.
13606
13607 +-----------------+---------+------------+--------------+
13608 |local_from_prefix|Use: main|Type: string|Default: unset|
13609 +-----------------+---------+------------+--------------+
13610
13611 When Exim checks the From: header line of locally submitted messages for
13612 matching the login id (see local_from_check above), it can be configured to
13613 ignore certain prefixes and suffixes in the local part of the address. This is
13614 done by setting local_from_prefix and/or local_from_suffix to appropriate
13615 lists, in the same form as the local_part_prefix and local_part_suffix router
13616 options (see chapter 15). For example, if
13617
13618 local_from_prefix = *-
13619
13620 is set, a From: line containing
13621
13622 From: anything-user@your.domain.example
13623
13624 will not cause a Sender: header to be added if user@your.domain.example matches
13625 the actual sender address that is constructed from the login name and qualify
13626 domain.
13627
13628 +-----------------+---------+------------+--------------+
13629 |local_from_suffix|Use: main|Type: string|Default: unset|
13630 +-----------------+---------+------------+--------------+
13631
13632 See local_from_prefix above.
13633
13634 +----------------+---------+-----------------+------------------+
13635 |local_interfaces|Use: main|Type: string list|Default: see below|
13636 +----------------+---------+-----------------+------------------+
13637
13638 This option controls which network interfaces are used by the daemon for
13639 listening; they are also used to identify the local host when routing. Chapter
13640 13 contains a full description of this option and the related options
13641 daemon_smtp_ports, extra_local_interfaces, hosts_treat_as_local, and
13642 tls_on_connect_ports. The default value for local_interfaces is
13643
13644 local_interfaces = 0.0.0.0
13645
13646 when Exim is built without IPv6 support; otherwise it is
13647
13648 local_interfaces = <; ::0 ; 0.0.0.0
13649
13650 +------------------+---------+----------+-----------+
13651 |local_scan_timeout|Use: main|Type: time|Default: 5m|
13652 +------------------+---------+----------+-----------+
13653
13654 This timeout applies to the local_scan() function (see chapter 44). Zero means
13655 "no timeout". If the timeout is exceeded, the incoming message is rejected with
13656 a temporary error if it is an SMTP message. For a non-SMTP message, the message
13657 is dropped and Exim ends with a non-zero code. The incident is logged on the
13658 main and reject logs.
13659
13660 +-------------------+---------+-------------+--------------+
13661 |local_sender_retain|Use: main|Type: boolean|Default: false|
13662 +-------------------+---------+-------------+--------------+
13663
13664 When a message is submitted locally (that is, not over a TCP/IP connection) by
13665 an untrusted user, Exim removes any existing Sender: header line. If you do not
13666 want this to happen, you must set local_sender_retain, and you must also set
13667 local_from_check to be false (Exim will complain if you do not). See also the
13668 ACL modifier "control = suppress_local_fixups". Section 46.16 has more details
13669 about Sender: processing.
13670
13671 +----------------+---------+-------------+--------------+
13672 |localhost_number|Use: main|Type: string*|Default: unset|
13673 +----------------+---------+-------------+--------------+
13674
13675 Exim's message ids are normally unique only within the local host. If
13676 uniqueness among a set of hosts is required, each host must set a different
13677 value for the localhost_number option. The string is expanded immediately after
13678 reading the configuration file (so that a number can be computed from the host
13679 name, for example) and the result of the expansion must be a number in the
13680 range 0-16 (or 0-10 on operating systems with case-insensitive file systems).
13681 This is available in subsequent string expansions via the variable
13682 $localhost_number. When localhost_number is set, the final two characters of
13683 the message id, instead of just being a fractional part of the time, are
13684 computed from the time and the local host number as described in section 3.4.
13685
13686 +-------------+---------+------------------+----------------------------+
13687 |log_file_path|Use: main|Type: string list*|Default: set at compile time|
13688 +-------------+---------+------------------+----------------------------+
13689
13690 This option sets the path which is used to determine the names of Exim's log
13691 files, or indicates that logging is to be to syslog, or both. It is expanded
13692 when Exim is entered, so it can, for example, contain a reference to the host
13693 name. If no specific path is set for the log files at compile or run time, they
13694 are written in a sub-directory called log in Exim's spool directory. Chapter 51
13695 contains further details about Exim's logging, and section 51.1 describes how
13696 the contents of log_file_path are used. If this string is fixed at your
13697 installation (contains no expansion variables) it is recommended that you do
13698 not set this option in the configuration file, but instead supply the path
13699 using LOG_FILE_PATH in Local/Makefile so that it is available to Exim for
13700 logging errors detected early on - in particular, failure to read the
13701 configuration file.
13702
13703 +------------+---------+------------+--------------+
13704 |log_selector|Use: main|Type: string|Default: unset|
13705 +------------+---------+------------+--------------+
13706
13707 This option can be used to reduce or increase the number of things that Exim
13708 writes to its log files. Its argument is made up of names preceded by plus or
13709 minus characters. For example:
13710
13711 log_selector = +arguments -retry_defer
13712
13713 A list of possible names and what they control is given in the chapter on
13714 logging, in section 51.15.
13715
13716 +------------+---------+-------------+--------------+
13717 |log_timezone|Use: main|Type: boolean|Default: false|
13718 +------------+---------+-------------+--------------+
13719
13720 By default, the timestamps on log lines are in local time without the timezone.
13721 This means that if your timezone changes twice a year, the timestamps in log
13722 lines are ambiguous for an hour when the clocks go back. One way of avoiding
13723 this problem is to set the timezone to UTC. An alternative is to set
13724 log_timezone true. This turns on the addition of the timezone offset to
13725 timestamps in log lines. Turning on this option can add quite a lot to the size
13726 of log files because each line is extended by 6 characters. Note that the
13727 $tod_log variable contains the log timestamp without the zone, but there is
13728 another variable called $tod_zone that contains just the timezone offset.
13729
13730 +---------------+---------+-------------+-----------+
13731 |lookup_open_max|Use: main|Type: integer|Default: 25|
13732 +---------------+---------+-------------+-----------+
13733
13734 This option limits the number of simultaneously open files for single-key
13735 lookups that use regular files (that is, lsearch, dbm, and cdb). Exim normally
13736 keeps these files open during routing, because often the same file is required
13737 several times. If the limit is reached, Exim closes the least recently used
13738 file. Note that if you are using the ndbm library, it actually opens two files
13739 for each logical DBM database, though it still counts as one for the purposes
13740 of lookup_open_max. If you are getting "too many open files" errors with NDBM,
13741 you need to reduce the value of lookup_open_max.
13742
13743 +-------------------+---------+-------------+----------+
13744 |max_username_length|Use: main|Type: integer|Default: 0|
13745 +-------------------+---------+-------------+----------+
13746
13747 Some operating systems are broken in that they truncate long arguments to
13748 getpwnam() to eight characters, instead of returning "no such user". If this
13749 option is set greater than zero, any attempt to call getpwnam() with an
13750 argument that is longer behaves as if getpwnam() failed.
13751
13752 +---------------------+---------+----------+--------------+
13753 |message_body_newlines|Use: main|Type: bool|Default: false|
13754 +---------------------+---------+----------+--------------+
13755
13756 By default, newlines in the message body are replaced by spaces when setting
13757 the $message_body and $message_body_end expansion variables. If this option is
13758 set true, this no longer happens.
13759
13760 +--------------------+---------+-------------+------------+
13761 |message_body_visible|Use: main|Type: integer|Default: 500|
13762 +--------------------+---------+-------------+------------+
13763
13764 This option specifies how much of a message's body is to be included in the
13765 $message_body and $message_body_end expansion variables.
13766
13767 +------------------------+---------+-------------+--------------+
13768 |message_id_header_domain|Use: main|Type: string*|Default: unset|
13769 +------------------------+---------+-------------+--------------+
13770
13771 If this option is set, the string is expanded and used as the right hand side
13772 (domain) of the Message-ID: header that Exim creates if a locally-originated
13773 incoming message does not have one. "Locally-originated" means "not received
13774 over TCP/IP." Otherwise, the primary host name is used. Only letters, digits,
13775 dot and hyphen are accepted; any other characters are replaced by hyphens. If
13776 the expansion is forced to fail, or if the result is an empty string, the
13777 option is ignored.
13778
13779 +----------------------+---------+-------------+--------------+
13780 |message_id_header_text|Use: main|Type: string*|Default: unset|
13781 +----------------------+---------+-------------+--------------+
13782
13783 If this variable is set, the string is expanded and used to augment the text of
13784 the Message-id: header that Exim creates if a locally-originated incoming
13785 message does not have one. The text of this header is required by RFC 2822 to
13786 take the form of an address. By default, Exim uses its internal message id as
13787 the local part, and the primary host name as the domain. If this option is set,
13788 it is expanded, and provided the expansion is not forced to fail, and does not
13789 yield an empty string, the result is inserted into the header immediately
13790 before the @, separated from the internal message id by a dot. Any characters
13791 that are illegal in an address are automatically converted into hyphens. This
13792 means that variables such as $tod_log can be used, because the spaces and
13793 colons will become hyphens.
13794
13795 +------------+---------+-------------+-------------+
13796 |message_logs|Use: main|Type: boolean|Default: true|
13797 +------------+---------+-------------+-------------+
13798
13799 If this option is turned off, per-message log files are not created in the
13800 msglog spool sub-directory. This reduces the amount of disk I/O required by
13801 Exim, by reducing the number of files involved in handling a message from a
13802 minimum of four (header spool file, body spool file, delivery journal, and
13803 per-message log) to three. The other major I/O activity is Exim's main log,
13804 which is not affected by this option.
13805
13806 +------------------+---------+-------------+------------+
13807 |message_size_limit|Use: main|Type: string*|Default: 50M|
13808 +------------------+---------+-------------+------------+
13809
13810 This option limits the maximum size of message that Exim will process. The
13811 value is expanded for each incoming connection so, for example, it can be made
13812 to depend on the IP address of the remote host for messages arriving via TCP/
13813 IP. After expansion, the value must be a sequence of decimal digits, optionally
13814 followed by K or M.
13815
13816 Note: This limit cannot be made to depend on a message's sender or any other
13817 properties of an individual message, because it has to be advertised in the
13818 server's response to EHLO. String expansion failure causes a temporary error. A
13819 value of zero means no limit, but its use is not recommended. See also
13820 bounce_return_size_limit.
13821
13822 Incoming SMTP messages are failed with a 552 error if the limit is exceeded;
13823 locally-generated messages either get a stderr message or a delivery failure
13824 message to the sender, depending on the -oe setting. Rejection of an oversized
13825 message is logged in both the main and the reject logs. See also the generic
13826 transport option message_size_limit, which limits the size of message that an
13827 individual transport can process.
13828
13829 If you use a virus-scanner and set this option to to a value larger than the
13830 maximum size that your virus-scanner is configured to support, you may get
13831 failures triggered by large mails. The right size to configure for the
13832 virus-scanner depends upon what data is passed and the options in use but it's
13833 probably safest to just set it to a little larger than this value. Eg, with a
13834 default Exim message size of 50M and a default ClamAV StreamMaxLength of 10M,
13835 some problems may result.
13836
13837 A value of 0 will disable size limit checking; Exim will still advertise the
13838 SIZE extension in an EHLO response, but without a limit, so as to permit SMTP
13839 clients to still indicate the message size along with the MAIL verb.
13840
13841 +--------------------+---------+-------------+--------------+
13842 |move_frozen_messages|Use: main|Type: boolean|Default: false|
13843 +--------------------+---------+-------------+--------------+
13844
13845 This option, which is available only if Exim has been built with the setting
13846
13847 SUPPORT_MOVE_FROZEN_MESSAGES=yes
13848
13849 in Local/Makefile, causes frozen messages and their message logs to be moved
13850 from the input and msglog directories on the spool to Finput and Fmsglog,
13851 respectively. There is currently no support in Exim or the standard utilities
13852 for handling such moved messages, and they do not show up in lists generated by
13853 -bp or by the Exim monitor.
13854
13855 +-----------+---------+-------------+--------------+
13856 |mua_wrapper|Use: main|Type: boolean|Default: false|
13857 +-----------+---------+-------------+--------------+
13858
13859 Setting this option true causes Exim to run in a very restrictive mode in which
13860 it passes messages synchronously to a smart host. Chapter 50 contains a full
13861 description of this facility.
13862
13863 +-------------+---------+-----------------+--------------+
13864 |mysql_servers|Use: main|Type: string list|Default: unset|
13865 +-------------+---------+-----------------+--------------+
13866
13867 This option provides a list of MySQL servers and associated connection data, to
13868 be used in conjunction with mysql lookups (see section 9.21). The option is
13869 available only if Exim has been built with MySQL support.
13870
13871 +-----------+---------+------------------+--------------+
13872 |never_users|Use: main|Type: string list*|Default: unset|
13873 +-----------+---------+------------------+--------------+
13874
13875 This option is expanded just once, at the start of Exim's processing. Local
13876 message deliveries are normally run in processes that are setuid to the
13877 recipient, and remote deliveries are normally run under Exim's own uid and gid.
13878 It is usually desirable to prevent any deliveries from running as root, as a
13879 safety precaution.
13880
13881 When Exim is built, an option called FIXED_NEVER_USERS can be set to a list of
13882 users that must not be used for local deliveries. This list is fixed in the
13883 binary and cannot be overridden by the configuration file. By default, it
13884 contains just the single user name "root". The never_users runtime option can
13885 be used to add more users to the fixed list.
13886
13887 If a message is to be delivered as one of the users on the fixed list or the
13888 never_users list, an error occurs, and delivery is deferred. A common example
13889 is
13890
13891 never_users = root:daemon:bin
13892
13893 Including root is redundant if it is also on the fixed list, but it does no
13894 harm. This option overrides the pipe_as_creator option of the pipe transport
13895 driver.
13896
13897 +---------------+---------+-----------------+------------------+
13898 |openssl_options|Use: main|Type: string list|Default: +no_sslv2|
13899 +---------------+---------+-----------------+------------------+
13900
13901 This option allows an administrator to adjust the SSL options applied by
13902 OpenSSL to connections. It is given as a space-separated list of items, each
13903 one to be +added or -subtracted from the current value.
13904
13905 This option is only available if Exim is built against OpenSSL. The values
13906 available for this option vary according to the age of your OpenSSL install.
13907 The "all" value controls a subset of flags which are available, typically the
13908 bug workaround options. The SSL_CTX_set_options man page will list the values
13909 known on your system and Exim should support all the "bug workaround" options
13910 and many of the "modifying" options. The Exim names lose the leading "SSL_OP_"
13911 and are lower-cased.
13912
13913 Note that adjusting the options can have severe impact upon the security of SSL
13914 as used by Exim. It is possible to disable safety checks and shoot yourself in
13915 the foot in various unpleasant ways. This option should not be adjusted
13916 lightly. An unrecognised item will be detected at startup, by invoking Exim
13917 with the -bV flag.
13918
13919 Historical note: prior to release 4.80, Exim defaulted this value to
13920 "+dont_insert_empty_fragments", which may still be needed for compatibility
13921 with some clients, but which lowers security by increasing exposure to some now
13922 infamous attacks.
13923
13924 An example:
13925
13926 # Make both old MS and old Eudora happy:
13927 openssl_options = -all +microsoft_big_sslv3_buffer \
13928 +dont_insert_empty_fragments
13929
13930 Possible options may include:
13931
13932 * "all"
13933
13934 * "allow_unsafe_legacy_renegotiation"
13935
13936 * "cipher_server_preference"
13937
13938 * "dont_insert_empty_fragments"
13939
13940 * "ephemeral_rsa"
13941
13942 * "legacy_server_connect"
13943
13944 * "microsoft_big_sslv3_buffer"
13945
13946 * "microsoft_sess_id_bug"
13947
13948 * "msie_sslv2_rsa_padding"
13949
13950 * "netscape_challenge_bug"
13951
13952 * "netscape_reuse_cipher_change_bug"
13953
13954 * "no_compression"
13955
13956 * "no_session_resumption_on_renegotiation"
13957
13958 * "no_sslv2"
13959
13960 * "no_sslv3"
13961
13962 * "no_ticket"
13963
13964 * "no_tlsv1"
13965
13966 * "no_tlsv1_1"
13967
13968 * "no_tlsv1_2"
13969
13970 * "safari_ecdhe_ecdsa_bug"
13971
13972 * "single_dh_use"
13973
13974 * "single_ecdh_use"
13975
13976 * "ssleay_080_client_dh_bug"
13977
13978 * "sslref2_reuse_cert_type_bug"
13979
13980 * "tls_block_padding_bug"
13981
13982 * "tls_d5_bug"
13983
13984 * "tls_rollback_bug"
13985
13986 As an aside, the "safari_ecdhe_ecdsa_bug" item is a misnomer and affects all
13987 clients connecting using the MacOS SecureTransport TLS facility prior to MacOS
13988 10.8.4, including email clients. If you see old MacOS clients failing to
13989 negotiate TLS then this option value might help, provided that your OpenSSL
13990 release is new enough to contain this work-around. This may be a situation
13991 where you have to upgrade OpenSSL to get buggy clients working.
13992
13993 +--------------+---------+-----------------+--------------+
13994 |oracle_servers|Use: main|Type: string list|Default: unset|
13995 +--------------+---------+-----------------+--------------+
13996
13997 This option provides a list of Oracle servers and associated connection data,
13998 to be used in conjunction with oracle lookups (see section 9.21). The option is
13999 available only if Exim has been built with Oracle support.
14000
14001 +--------------------+---------+------------------+--------------+
14002 |percent_hack_domains|Use: main|Type: domain list*|Default: unset|
14003 +--------------------+---------+------------------+--------------+
14004
14005 The "percent hack" is the convention whereby a local part containing a percent
14006 sign is re-interpreted as a new email address, with the percent replaced by @.
14007 This is sometimes called "source routing", though that term is also applied to
14008 RFC 2822 addresses that begin with an @ character. If this option is set, Exim
14009 implements the percent facility for those domains listed, but no others. This
14010 happens before an incoming SMTP address is tested against an ACL.
14011
14012 Warning: The "percent hack" has often been abused by people who are trying to
14013 get round relaying restrictions. For this reason, it is best avoided if at all
14014 possible. Unfortunately, a number of less security-conscious MTAs implement it
14015 unconditionally. If you are running Exim on a gateway host, and routing mail
14016 through to internal MTAs without processing the local parts, it is a good idea
14017 to reject recipient addresses with percent characters in their local parts.
14018 Exim's default configuration does this.
14019
14020 +-------------+---------+-------------+--------------+
14021 |perl_at_start|Use: main|Type: boolean|Default: false|
14022 +-------------+---------+-------------+--------------+
14023
14024 This option is available only when Exim is built with an embedded Perl
14025 interpreter. See chapter 12 for details of its use.
14026
14027 +------------+---------+------------+--------------+
14028 |perl_startup|Use: main|Type: string|Default: unset|
14029 +------------+---------+------------+--------------+
14030
14031 This option is available only when Exim is built with an embedded Perl
14032 interpreter. See chapter 12 for details of its use.
14033
14034 +-------------+---------+-----------------+--------------+
14035 |pgsql_servers|Use: main|Type: string list|Default: unset|
14036 +-------------+---------+-----------------+--------------+
14037
14038 This option provides a list of PostgreSQL servers and associated connection
14039 data, to be used in conjunction with pgsql lookups (see section 9.21). The
14040 option is available only if Exim has been built with PostgreSQL support.
14041
14042 +-------------+---------+-------------+----------------------------+
14043 |pid_file_path|Use: main|Type: string*|Default: set at compile time|
14044 +-------------+---------+-------------+----------------------------+
14045
14046 This option sets the name of the file to which the Exim daemon writes its
14047 process id. The string is expanded, so it can contain, for example, references
14048 to the host name:
14049
14050 pid_file_path = /var/log/$primary_hostname/exim.pid
14051
14052 If no path is set, the pid is written to the file exim-daemon.pid in Exim's
14053 spool directory. The value set by the option can be overridden by the -oP
14054 command line option. A pid file is not written if a "non-standard" daemon is
14055 run by means of the -oX option, unless a path is explicitly supplied by -oP.
14056
14057 +--------------------------+---------+----------------+----------+
14058 |pipelining_advertise_hosts|Use: main|Type: host list*|Default: *|
14059 +--------------------------+---------+----------------+----------+
14060
14061 This option can be used to suppress the advertisement of the SMTP PIPELINING
14062 extension to specific hosts. See also the no_pipelining control in section
14063 42.22. When PIPELINING is not advertised and smtp_enforce_sync is true, an Exim
14064 server enforces strict synchronization for each SMTP command and response. When
14065 PIPELINING is advertised, Exim assumes that clients will use it; "out of order"
14066 commands that are "expected" do not count as protocol errors (see
14067 smtp_max_synprot_errors).
14068
14069 +-----------+---------+-------------+--------------+
14070 |prdr_enable|Use: main|Type: boolean|Default: false|
14071 +-----------+---------+-------------+--------------+
14072
14073 This option can be used to enable the Per-Recipient Data Response extension to
14074 SMTP, defined by Eric Hall. If the option is set, PRDR is advertised by Exim
14075 when operating as a server. If the client requests PRDR, and more than one
14076 recipient, for a message an additional ACL is called for each recipient after
14077 the message content is recieved. See section 42.9.
14078
14079 +---------------------+---------+-------------+--------------+
14080 |preserve_message_logs|Use: main|Type: boolean|Default: false|
14081 +---------------------+---------+-------------+--------------+
14082
14083 If this option is set, message log files are not deleted when messages are
14084 completed. Instead, they are moved to a sub-directory of the spool directory
14085 called msglog.OLD, where they remain available for statistical or debugging
14086 purposes. This is a dangerous option to set on systems with any appreciable
14087 volume of mail. Use with care!
14088
14089 +----------------+---------+------------+------------------+
14090 |primary_hostname|Use: main|Type: string|Default: see below|
14091 +----------------+---------+------------+------------------+
14092
14093 This specifies the name of the current host. It is used in the default EHLO or
14094 HELO command for outgoing SMTP messages (changeable via the helo_data option in
14095 the smtp transport), and as the default for qualify_domain. The value is also
14096 used by default in some SMTP response messages from an Exim server. This can be
14097 changed dynamically by setting smtp_active_hostname.
14098
14099 If primary_hostname is not set, Exim calls uname() to find the host name. If
14100 this fails, Exim panics and dies. If the name returned by uname() contains only
14101 one component, Exim passes it to gethostbyname() (or getipnodebyname() when
14102 available) in order to obtain the fully qualified version. The variable
14103 $primary_hostname contains the host name, whether set explicitly by this
14104 option, or defaulted.
14105
14106 +-----------------+---------+-------------+--------------+
14107 |print_topbitchars|Use: main|Type: boolean|Default: false|
14108 +-----------------+---------+-------------+--------------+
14109
14110 By default, Exim considers only those characters whose codes lie in the range
14111 32-126 to be printing characters. In a number of circumstances (for example,
14112 when writing log entries) non-printing characters are converted into escape
14113 sequences, primarily to avoid messing up the layout. If print_topbitchars is
14114 set, code values of 128 and above are also considered to be printing
14115 characters.
14116
14117 This option also affects the header syntax checks performed by the autoreply
14118 transport, and whether Exim uses RFC 2047 encoding of the user's full name when
14119 constructing From: and Sender: addresses (as described in section 46.18).
14120 Setting this option can cause Exim to generate eight bit message headers that
14121 do not conform to the standards.
14122
14123 +----------------+---------+------------+--------------+
14124 |process_log_path|Use: main|Type: string|Default: unset|
14125 +----------------+---------+------------+--------------+
14126
14127 This option sets the name of the file to which an Exim process writes its
14128 "process log" when sent a USR1 signal. This is used by the exiwhat utility
14129 script. If this option is unset, the file called exim-process.info in Exim's
14130 spool directory is used. The ability to specify the name explicitly can be
14131 useful in environments where two different Exims are running, using different
14132 spool directories.
14133
14134 +-------------------+---------+-------------+-------------+
14135 |prod_requires_admin|Use: main|Type: boolean|Default: true|
14136 +-------------------+---------+-------------+-------------+
14137
14138 The -M, -R, and -q command-line options require the caller to be an admin user
14139 unless prod_requires_admin is set false. See also queue_list_requires_admin.
14140
14141 +--------------+---------+------------+------------------+
14142 |qualify_domain|Use: main|Type: string|Default: see below|
14143 +--------------+---------+------------+------------------+
14144
14145 This option specifies the domain name that is added to any envelope sender
14146 addresses that do not have a domain qualification. It also applies to recipient
14147 addresses if qualify_recipient is not set. Unqualified addresses are accepted
14148 by default only for locally-generated messages. Qualification is also applied
14149 to addresses in header lines such as From: and To: for locally-generated
14150 messages, unless the -bnq command line option is used.
14151
14152 Messages from external sources must always contain fully qualified addresses,
14153 unless the sending host matches sender_unqualified_hosts or
14154 recipient_unqualified_hosts (as appropriate), in which case incoming addresses
14155 are qualified with qualify_domain or qualify_recipient as necessary.
14156 Internally, Exim always works with fully qualified envelope addresses. If
14157 qualify_domain is not set, it defaults to the primary_hostname value.
14158
14159 +-----------------+---------+------------+------------------+
14160 |qualify_recipient|Use: main|Type: string|Default: see below|
14161 +-----------------+---------+------------+------------------+
14162
14163 This option allows you to specify a different domain for qualifying recipient
14164 addresses to the one that is used for senders. See qualify_domain above.
14165
14166 +-------------+---------+------------------+--------------+
14167 |queue_domains|Use: main|Type: domain list*|Default: unset|
14168 +-------------+---------+------------------+--------------+
14169
14170 This option lists domains for which immediate delivery is not required. A
14171 delivery process is started whenever a message is received, but only those
14172 domains that do not match are processed. All other deliveries wait until the
14173 next queue run. See also hold_domains and queue_smtp_domains.
14174
14175 +-------------------------+---------+-------------+-------------+
14176 |queue_list_requires_admin|Use: main|Type: boolean|Default: true|
14177 +-------------------------+---------+-------------+-------------+
14178
14179 The -bp command-line option, which lists the messages that are on the queue,
14180 requires the caller to be an admin user unless queue_list_requires_admin is set
14181 false. See also prod_requires_admin.
14182
14183 +----------+---------+-------------+--------------+
14184 |queue_only|Use: main|Type: boolean|Default: false|
14185 +----------+---------+-------------+--------------+
14186
14187 If queue_only is set, a delivery process is not automatically started whenever
14188 a message is received. Instead, the message waits on the queue for the next
14189 queue run. Even if queue_only is false, incoming messages may not get delivered
14190 immediately when certain conditions (such as heavy load) occur.
14191
14192 The -odq command line has the same effect as queue_only. The -odb and -odi
14193 command line options override queue_only unless queue_only_override is set
14194 false. See also queue_only_file, queue_only_load, and smtp_accept_queue.
14195
14196 +---------------+---------+------------+--------------+
14197 |queue_only_file|Use: main|Type: string|Default: unset|
14198 +---------------+---------+------------+--------------+
14199
14200 This option can be set to a colon-separated list of absolute path names, each
14201 one optionally preceded by "smtp". When Exim is receiving a message, it tests
14202 for the existence of each listed path using a call to stat(). For each path
14203 that exists, the corresponding queueing option is set. For paths with no
14204 prefix, queue_only is set; for paths prefixed by "smtp", queue_smtp_domains is
14205 set to match all domains. So, for example,
14206
14207 queue_only_file = smtp/some/file
14208
14209 causes Exim to behave as if queue_smtp_domains were set to "*" whenever /some/
14210 file exists.
14211
14212 +---------------+---------+-----------------+--------------+
14213 |queue_only_load|Use: main|Type: fixed-point|Default: unset|
14214 +---------------+---------+-----------------+--------------+
14215
14216 If the system load average is higher than this value, incoming messages from
14217 all sources are queued, and no automatic deliveries are started. If this
14218 happens during local or remote SMTP input, all subsequent messages received on
14219 the same SMTP connection are queued by default, whatever happens to the load in
14220 the meantime, but this can be changed by setting queue_only_load_latch false.
14221
14222 Deliveries will subsequently be performed by queue runner processes. This
14223 option has no effect on ancient operating systems on which Exim cannot
14224 determine the load average. See also deliver_queue_load_max and
14225 smtp_load_reserve.
14226
14227 +---------------------+---------+-------------+-------------+
14228 |queue_only_load_latch|Use: main|Type: boolean|Default: true|
14229 +---------------------+---------+-------------+-------------+
14230
14231 When this option is true (the default), once one message has been queued
14232 because the load average is higher than the value set by queue_only_load, all
14233 subsequent messages received on the same SMTP connection are also queued. This
14234 is a deliberate choice; even though the load average may fall below the
14235 threshold, it doesn't seem right to deliver later messages on the same
14236 connection when not delivering earlier ones. However, there are special
14237 circumstances such as very long-lived connections from scanning appliances
14238 where this is not the best strategy. In such cases, queue_only_load_latch
14239 should be set false. This causes the value of the load average to be
14240 re-evaluated for each message.
14241
14242 +-------------------+---------+-------------+-------------+
14243 |queue_only_override|Use: main|Type: boolean|Default: true|
14244 +-------------------+---------+-------------+-------------+
14245
14246 When this option is true, the -odx command line options override the setting of
14247 queue_only or queue_only_file in the configuration file. If queue_only_override
14248 is set false, the -odx options cannot be used to override; they are accepted,
14249 but ignored.
14250
14251 +------------------+---------+-------------+--------------+
14252 |queue_run_in_order|Use: main|Type: boolean|Default: false|
14253 +------------------+---------+-------------+--------------+
14254
14255 If this option is set, queue runs happen in order of message arrival instead of
14256 in an arbitrary order. For this to happen, a complete list of the entire queue
14257 must be set up before the deliveries start. When the queue is all held in a
14258 single directory (the default), a single list is created for both the ordered
14259 and the non-ordered cases. However, if split_spool_directory is set, a single
14260 list is not created when queue_run_in_order is false. In this case, the
14261 sub-directories are processed one at a time (in a random order), and this
14262 avoids setting up one huge list for the whole queue. Thus, setting
14263 queue_run_in_order with split_spool_directory may degrade performance when the
14264 queue is large, because of the extra work in setting up the single, large list.
14265 In most situations, queue_run_in_order should not be set.
14266
14267 +-------------+---------+-------------+----------+
14268 |queue_run_max|Use: main|Type: integer|Default: 5|
14269 +-------------+---------+-------------+----------+
14270
14271 This controls the maximum number of queue runner processes that an Exim daemon
14272 can run simultaneously. This does not mean that it starts them all at once, but
14273 rather that if the maximum number are still running when the time comes to
14274 start another one, it refrains from starting another one. This can happen with
14275 very large queues and/or very sluggish deliveries. This option does not,
14276 however, interlock with other processes, so additional queue runners can be
14277 started by other means, or by killing and restarting the daemon.
14278
14279 Setting this option to zero does not suppress queue runs; rather, it disables
14280 the limit, allowing any number of simultaneous queue runner processes to be
14281 run. If you do not want queue runs to occur, omit the -qxx setting on the
14282 daemon's command line.
14283
14284 +------------------+---------+------------------+--------------+
14285 |queue_smtp_domains|Use: main|Type: domain list*|Default: unset|
14286 +------------------+---------+------------------+--------------+
14287
14288 When this option is set, a delivery process is started whenever a message is
14289 received, routing is performed, and local deliveries take place. However, if
14290 any SMTP deliveries are required for domains that match queue_smtp_domains,
14291 they are not immediately delivered, but instead the message waits on the queue
14292 for the next queue run. Since routing of the message has taken place, Exim
14293 knows to which remote hosts it must be delivered, and so when the queue run
14294 happens, multiple messages for the same host are delivered over a single SMTP
14295 connection. The -odqs command line option causes all SMTP deliveries to be
14296 queued in this way, and is equivalent to setting queue_smtp_domains to "*". See
14297 also hold_domains and queue_domains.
14298
14299 +---------------+---------+----------+-----------+
14300 |receive_timeout|Use: main|Type: time|Default: 0s|
14301 +---------------+---------+----------+-----------+
14302
14303 This option sets the timeout for accepting a non-SMTP message, that is, the
14304 maximum time that Exim waits when reading a message on the standard input. If
14305 the value is zero, it will wait for ever. This setting is overridden by the -or
14306 command line option. The timeout for incoming SMTP messages is controlled by
14307 smtp_receive_timeout.
14308
14309 +--------------------+---------+-------------+------------------+
14310 |received_header_text|Use: main|Type: string*|Default: see below|
14311 +--------------------+---------+-------------+------------------+
14312
14313 This string defines the contents of the Received: message header that is added
14314 to each message, except for the timestamp, which is automatically added on at
14315 the end (preceded by a semicolon). The string is expanded each time it is used.
14316 If the expansion yields an empty string, no Received: header line is added to
14317 the message. Otherwise, the string should start with the text "Received:" and
14318 conform to the RFC 2822 specification for Received: header lines. The default
14319 setting is:
14320
14321 received_header_text = Received: \
14322 ${if def:sender_rcvhost {from $sender_rcvhost\n\t}\
14323 {${if def:sender_ident \
14324 {from ${quote_local_part:$sender_ident} }}\
14325 ${if def:sender_helo_name {(helo=$sender_helo_name)\n\t}}}}\
14326 by $primary_hostname \
14327 ${if def:received_protocol {with $received_protocol}} \
14328 ${if def:tls_in_cipher {($tls_in_cipher)\n\t}}\
14329 (Exim $version_number)\n\t\
14330 ${if def:sender_address \
14331 {(envelope-from <$sender_address>)\n\t}}\
14332 id $message_exim_id\
14333 ${if def:received_for {\n\tfor $received_for}}
14334
14335 The reference to the TLS cipher is omitted when Exim is built without TLS
14336 support. The use of conditional expansions ensures that this works for both
14337 locally generated messages and messages received from remote hosts, giving
14338 header lines such as the following:
14339
14340 Received: from scrooge.carol.example ([192.168.12.25] ident=root)
14341 by marley.carol.example with esmtp (Exim 4.00)
14342 (envelope-from <bob@carol.example>)
14343 id 16IOWa-00019l-00
14344 for chas@dickens.example; Tue, 25 Dec 2001 14:43:44 +0000
14345 Received: by scrooge.carol.example with local (Exim 4.00)
14346 id 16IOWW-000083-00; Tue, 25 Dec 2001 14:43:41 +0000
14347
14348 Until the body of the message has been received, the timestamp is the time when
14349 the message started to be received. Once the body has arrived, and all policy
14350 checks have taken place, the timestamp is updated to the time at which the
14351 message was accepted.
14352
14353 +--------------------+---------+-------------+-----------+
14354 |received_headers_max|Use: main|Type: integer|Default: 30|
14355 +--------------------+---------+-------------+-----------+
14356
14357 When a message is to be delivered, the number of Received: headers is counted,
14358 and if it is greater than this parameter, a mail loop is assumed to have
14359 occurred, the delivery is abandoned, and an error message is generated. This
14360 applies to both local and remote deliveries.
14361
14362 +---------------------------+---------+----------------+--------------+
14363 |recipient_unqualified_hosts|Use: main|Type: host list*|Default: unset|
14364 +---------------------------+---------+----------------+--------------+
14365
14366 This option lists those hosts from which Exim is prepared to accept unqualified
14367 recipient addresses in message envelopes. The addresses are made fully
14368 qualified by the addition of the qualify_recipient value. This option also
14369 affects message header lines. Exim does not reject unqualified recipient
14370 addresses in headers, but it qualifies them only if the message came from a
14371 host that matches recipient_unqualified_hosts, or if the message was submitted
14372 locally (not using TCP/IP), and the -bnq option was not set.
14373
14374 +--------------+---------+-------------+----------+
14375 |recipients_max|Use: main|Type: integer|Default: 0|
14376 +--------------+---------+-------------+----------+
14377
14378 If this option is set greater than zero, it specifies the maximum number of
14379 original recipients for any message. Additional recipients that are generated
14380 by aliasing or forwarding do not count. SMTP messages get a 452 response for
14381 all recipients over the limit; earlier recipients are delivered as normal.
14382 Non-SMTP messages with too many recipients are failed, and no deliveries are
14383 done.
14384
14385 Note: The RFCs specify that an SMTP server should accept at least 100 RCPT
14386 commands in a single message.
14387
14388 +---------------------+---------+-------------+--------------+
14389 |recipients_max_reject|Use: main|Type: boolean|Default: false|
14390 +---------------------+---------+-------------+--------------+
14391
14392 If this option is set true, Exim rejects SMTP messages containing too many
14393 recipients by giving 552 errors to the surplus RCPT commands, and a 554 error
14394 to the eventual DATA command. Otherwise (the default) it gives a 452 error to
14395 the surplus RCPT commands and accepts the message on behalf of the initial set
14396 of recipients. The remote server should then re-send the message for the
14397 remaining recipients at a later time.
14398
14399 +-------------------+---------+-------------+----------+
14400 |remote_max_parallel|Use: main|Type: integer|Default: 2|
14401 +-------------------+---------+-------------+----------+
14402
14403 This option controls parallel delivery of one message to a number of remote
14404 hosts. If the value is less than 2, parallel delivery is disabled, and Exim
14405 does all the remote deliveries for a message one by one. Otherwise, if a single
14406 message has to be delivered to more than one remote host, or if several copies
14407 have to be sent to the same remote host, up to remote_max_parallel deliveries
14408 are done simultaneously. If more than remote_max_parallel deliveries are
14409 required, the maximum number of processes are started, and as each one
14410 finishes, another is begun. The order of starting processes is the same as if
14411 sequential delivery were being done, and can be controlled by the
14412 remote_sort_domains option. If parallel delivery takes place while running with
14413 debugging turned on, the debugging output from each delivery process is tagged
14414 with its process id.
14415
14416 This option controls only the maximum number of parallel deliveries for one
14417 message in one Exim delivery process. Because Exim has no central queue
14418 manager, there is no way of controlling the total number of simultaneous
14419 deliveries if the configuration allows a delivery attempt as soon as a message
14420 is received.
14421
14422 If you want to control the total number of deliveries on the system, you need
14423 to set the queue_only option. This ensures that all incoming messages are added
14424 to the queue without starting a delivery process. Then set up an Exim daemon to
14425 start queue runner processes at appropriate intervals (probably fairly often,
14426 for example, every minute), and limit the total number of queue runners by
14427 setting the queue_run_max parameter. Because each queue runner delivers only
14428 one message at a time, the maximum number of deliveries that can then take
14429 place at once is queue_run_max multiplied by remote_max_parallel.
14430
14431 If it is purely remote deliveries you want to control, use queue_smtp_domains
14432 instead of queue_only. This has the added benefit of doing the SMTP routing
14433 before queueing, so that several messages for the same host will eventually get
14434 delivered down the same connection.
14435
14436 +-------------------+---------+------------------+--------------+
14437 |remote_sort_domains|Use: main|Type: domain list*|Default: unset|
14438 +-------------------+---------+------------------+--------------+
14439
14440 When there are a number of remote deliveries for a message, they are sorted by
14441 domain into the order given by this list. For example,
14442
14443 remote_sort_domains = *.cam.ac.uk:*.uk
14444
14445 would attempt to deliver to all addresses in the cam.ac.uk domain first, then
14446 to those in the uk domain, then to any others.
14447
14448 +-----------------+---------+----------+-----------+
14449 |retry_data_expire|Use: main|Type: time|Default: 7d|
14450 +-----------------+---------+----------+-----------+
14451
14452 This option sets a "use before" time on retry information in Exim's hints
14453 database. Any older retry data is ignored. This means that, for example, once a
14454 host has not been tried for 7 days, Exim behaves as if it has no knowledge of
14455 past failures.
14456
14457 +------------------+---------+----------+------------+
14458 |retry_interval_max|Use: main|Type: time|Default: 24h|
14459 +------------------+---------+----------+------------+
14460
14461 Chapter 32 describes Exim's mechanisms for controlling the intervals between
14462 delivery attempts for messages that cannot be delivered straight away. This
14463 option sets an overall limit to the length of time between retries. It cannot
14464 be set greater than 24 hours; any attempt to do so forces the default value.
14465
14466 +------------------+---------+-------------+-------------+
14467 |return_path_remove|Use: main|Type: boolean|Default: true|
14468 +------------------+---------+-------------+-------------+
14469
14470 RFC 2821, section 4.4, states that an SMTP server must insert a Return-path:
14471 header line into a message when it makes a "final delivery". The Return-path:
14472 header preserves the sender address as received in the MAIL command. This
14473 description implies that this header should not be present in an incoming
14474 message. If return_path_remove is true, any existing Return-path: headers are
14475 removed from messages at the time they are received. Exim's transports have
14476 options for adding Return-path: headers at the time of delivery. They are
14477 normally used only for final local deliveries.
14478
14479 +-----------------+---------+-------------+-------------+
14480 |return_size_limit|Use: main|Type: integer|Default: 100K|
14481 +-----------------+---------+-------------+-------------+
14482
14483 This option is an obsolete synonym for bounce_return_size_limit.
14484
14485 +-------------+---------+----------------+----------+
14486 |rfc1413_hosts|Use: main|Type: host list*|Default: *|
14487 +-------------+---------+----------------+----------+
14488
14489 RFC 1413 identification calls are made to any client host which matches an item
14490 in the list.
14491
14492 +---------------------+---------+----------+-----------+
14493 |rfc1413_query_timeout|Use: main|Type: time|Default: 5s|
14494 +---------------------+---------+----------+-----------+
14495
14496 This sets the timeout on RFC 1413 identification calls. If it is set to zero,
14497 no RFC 1413 calls are ever made.
14498
14499 +------------------------+---------+----------------+--------------+
14500 |sender_unqualified_hosts|Use: main|Type: host list*|Default: unset|
14501 +------------------------+---------+----------------+--------------+
14502
14503 This option lists those hosts from which Exim is prepared to accept unqualified
14504 sender addresses. The addresses are made fully qualified by the addition of
14505 qualify_domain. This option also affects message header lines. Exim does not
14506 reject unqualified addresses in headers that contain sender addresses, but it
14507 qualifies them only if the message came from a host that matches
14508 sender_unqualified_hosts, or if the message was submitted locally (not using
14509 TCP/IP), and the -bnq option was not set.
14510
14511 +---------------------+---------+-------------+-------------+
14512 |smtp_accept_keepalive|Use: main|Type: boolean|Default: true|
14513 +---------------------+---------+-------------+-------------+
14514
14515 This option controls the setting of the SO_KEEPALIVE option on incoming TCP/IP
14516 socket connections. When set, it causes the kernel to probe idle connections
14517 periodically, by sending packets with "old" sequence numbers. The other end of
14518 the connection should send an acknowledgment if the connection is still okay or
14519 a reset if the connection has been aborted. The reason for doing this is that
14520 it has the beneficial effect of freeing up certain types of connection that can
14521 get stuck when the remote host is disconnected without tidying up the TCP/IP
14522 call properly. The keepalive mechanism takes several hours to detect
14523 unreachable hosts.
14524
14525 +---------------+---------+-------------+-----------+
14526 |smtp_accept_max|Use: main|Type: integer|Default: 20|
14527 +---------------+---------+-------------+-----------+
14528
14529 This option specifies the maximum number of simultaneous incoming SMTP calls
14530 that Exim will accept. It applies only to the listening daemon; there is no
14531 control (in Exim) when incoming SMTP is being handled by inetd. If the value is
14532 set to zero, no limit is applied. However, it is required to be non-zero if
14533 either smtp_accept_max_per_host or smtp_accept_queue is set. See also
14534 smtp_accept_reserve and smtp_load_reserve.
14535
14536 A new SMTP connection is immediately rejected if the smtp_accept_max limit has
14537 been reached. If not, Exim first checks smtp_accept_max_per_host. If that limit
14538 has not been reached for the client host, smtp_accept_reserve and
14539 smtp_load_reserve are then checked before accepting the connection.
14540
14541 +-----------------------+---------+-------------+-----------+
14542 |smtp_accept_max_nonmail|Use: main|Type: integer|Default: 10|
14543 +-----------------------+---------+-------------+-----------+
14544
14545 Exim counts the number of "non-mail" commands in an SMTP session, and drops the
14546 connection if there are too many. This option defines "too many". The check
14547 catches some denial-of-service attacks, repeated failing AUTHs, or a mad client
14548 looping sending EHLO, for example. The check is applied only if the client host
14549 matches smtp_accept_max_nonmail_hosts.
14550
14551 When a new message is expected, one occurrence of RSET is not counted. This
14552 allows a client to send one RSET between messages (this is not necessary, but
14553 some clients do it). Exim also allows one uncounted occurrence of HELO or EHLO,
14554 and one occurrence of STARTTLS between messages. After starting up a TLS
14555 session, another EHLO is expected, and so it too is not counted. The first
14556 occurrence of AUTH in a connection, or immediately following STARTTLS is not
14557 counted. Otherwise, all commands other than MAIL, RCPT, DATA, and QUIT are
14558 counted.
14559
14560 +-----------------------------+---------+----------------+----------+
14561 |smtp_accept_max_nonmail_hosts|Use: main|Type: host list*|Default: *|
14562 +-----------------------------+---------+----------------+----------+
14563
14564 You can control which hosts are subject to the smtp_accept_max_nonmail check by
14565 setting this option. The default value makes it apply to all hosts. By changing
14566 the value, you can exclude any badly-behaved hosts that you have to live with.
14567
14568 +------------------------------+---------+-------------+-------------+
14569 |smtp_accept_max_per_connection|Use: main|Type: integer|Default: 1000|
14570 +------------------------------+---------+-------------+-------------+
14571
14572 The value of this option limits the number of MAIL commands that Exim is
14573 prepared to accept over a single SMTP connection, whether or not each command
14574 results in the transfer of a message. After the limit is reached, a 421
14575 response is given to subsequent MAIL commands. This limit is a safety
14576 precaution against a client that goes mad (incidents of this type have been
14577 seen).
14578
14579 +------------------------+---------+-------------+--------------+
14580 |smtp_accept_max_per_host|Use: main|Type: string*|Default: unset|
14581 +------------------------+---------+-------------+--------------+
14582
14583 This option restricts the number of simultaneous IP connections from a single
14584 host (strictly, from a single IP address) to the Exim daemon. The option is
14585 expanded, to enable different limits to be applied to different hosts by
14586 reference to $sender_host_address. Once the limit is reached, additional
14587 connection attempts from the same host are rejected with error code 421. This
14588 is entirely independent of smtp_accept_reserve. The option's default value of
14589 zero imposes no limit. If this option is set greater than zero, it is required
14590 that smtp_accept_max be non-zero.
14591
14592 Warning: When setting this option you should not use any expansion
14593 constructions that take an appreciable amount of time. The expansion and test
14594 happen in the main daemon loop, in order to reject additional connections
14595 without forking additional processes (otherwise a denial-of-service attack
14596 could cause a vast number or processes to be created). While the daemon is
14597 doing this processing, it cannot accept any other incoming connections.
14598
14599 +-----------------+---------+-------------+----------+
14600 |smtp_accept_queue|Use: main|Type: integer|Default: 0|
14601 +-----------------+---------+-------------+----------+
14602
14603 If the number of simultaneous incoming SMTP connections being handled via the
14604 listening daemon exceeds this value, messages received by SMTP are just placed
14605 on the queue; no delivery processes are started automatically. The count is
14606 fixed at the start of an SMTP connection. It cannot be updated in the
14607 subprocess that receives messages, and so the queueing or not queueing applies
14608 to all messages received in the same connection.
14609
14610 A value of zero implies no limit, and clearly any non-zero value is useful only
14611 if it is less than the smtp_accept_max value (unless that is zero). See also
14612 queue_only, queue_only_load, queue_smtp_domains, and the various -odx command
14613 line options.
14614
14615 +--------------------------------+---------+-------------+-----------+
14616 |smtp_accept_queue_per_connection|Use: main|Type: integer|Default: 10|
14617 +--------------------------------+---------+-------------+-----------+
14618
14619 This option limits the number of delivery processes that Exim starts
14620 automatically when receiving messages via SMTP, whether via the daemon or by
14621 the use of -bs or -bS. If the value of the option is greater than zero, and the
14622 number of messages received in a single SMTP session exceeds this number,
14623 subsequent messages are placed on the queue, but no delivery processes are
14624 started. This helps to limit the number of Exim processes when a server
14625 restarts after downtime and there is a lot of mail waiting for it on other
14626 systems. On large systems, the default should probably be increased, and on
14627 dial-in client systems it should probably be set to zero (that is, disabled).
14628
14629 +-------------------+---------+-------------+----------+
14630 |smtp_accept_reserve|Use: main|Type: integer|Default: 0|
14631 +-------------------+---------+-------------+----------+
14632
14633 When smtp_accept_max is set greater than zero, this option specifies a number
14634 of SMTP connections that are reserved for connections from the hosts that are
14635 specified in smtp_reserve_hosts. The value set in smtp_accept_max includes this
14636 reserve pool. The specified hosts are not restricted to this number of
14637 connections; the option specifies a minimum number of connection slots for
14638 them, not a maximum. It is a guarantee that this group of hosts can always get
14639 at least smtp_accept_reserve connections. However, the limit specified by
14640 smtp_accept_max_per_host is still applied to each individual host.
14641
14642 For example, if smtp_accept_max is set to 50 and smtp_accept_reserve is set to
14643 5, once there are 45 active connections (from any hosts), new connections are
14644 accepted only from hosts listed in smtp_reserve_hosts, provided the other
14645 criteria for acceptance are met.
14646
14647 +--------------------+---------+-------------+--------------+
14648 |smtp_active_hostname|Use: main|Type: string*|Default: unset|
14649 +--------------------+---------+-------------+--------------+
14650
14651 This option is provided for multi-homed servers that want to masquerade as
14652 several different hosts. At the start of an incoming SMTP connection, its value
14653 is expanded and used instead of the value of $primary_hostname in SMTP
14654 responses. For example, it is used as domain name in the response to an
14655 incoming HELO or EHLO command.
14656
14657 The active hostname is placed in the $smtp_active_hostname variable, which is
14658 saved with any messages that are received. It is therefore available for use in
14659 routers and transports when the message is later delivered.
14660
14661 If this option is unset, or if its expansion is forced to fail, or if the
14662 expansion results in an empty string, the value of $primary_hostname is used.
14663 Other expansion failures cause a message to be written to the main and panic
14664 logs, and the SMTP command receives a temporary error. Typically, the value of
14665 smtp_active_hostname depends on the incoming interface address. For example:
14666
14667 smtp_active_hostname = ${if eq{$received_ip_address}{10.0.0.1}\
14668 {cox.mydomain}{box.mydomain}}
14669
14670 Although $smtp_active_hostname is primarily concerned with incoming messages,
14671 it is also used as the default for HELO commands in callout verification if
14672 there is no remote transport from which to obtain a helo_data value.
14673
14674 +-----------+---------+-------------+------------------+
14675 |smtp_banner|Use: main|Type: string*|Default: see below|
14676 +-----------+---------+-------------+------------------+
14677
14678 This string, which is expanded every time it is used, is output as the initial
14679 positive response to an SMTP connection. The default setting is:
14680
14681 smtp_banner = $smtp_active_hostname ESMTP Exim \
14682 $version_number $tod_full
14683
14684 Failure to expand the string causes a panic error. If you want to create a
14685 multiline response to the initial SMTP connection, use "\n" in the string at
14686 appropriate points, but not at the end. Note that the 220 code is not included
14687 in this string. Exim adds it automatically (several times in the case of a
14688 multiline response).
14689
14690 +----------------------+---------+-------------+-------------+
14691 |smtp_check_spool_space|Use: main|Type: boolean|Default: true|
14692 +----------------------+---------+-------------+-------------+
14693
14694 When this option is set, if an incoming SMTP session encounters the SIZE option
14695 on a MAIL command, it checks that there is enough space in the spool
14696 directory's partition to accept a message of that size, while still leaving
14697 free the amount specified by check_spool_space (even if that value is zero). If
14698 there isn't enough space, a temporary error code is returned.
14699
14700 +--------------------+---------+-------------+-----------+
14701 |smtp_connect_backlog|Use: main|Type: integer|Default: 20|
14702 +--------------------+---------+-------------+-----------+
14703
14704 This option specifies a maximum number of waiting SMTP connections. Exim passes
14705 this value to the TCP/IP system when it sets up its listener. Once this number
14706 of connections are waiting for the daemon's attention, subsequent connection
14707 attempts are refused at the TCP/IP level. At least, that is what the manuals
14708 say; in some circumstances such connection attempts have been observed to time
14709 out instead. For large systems it is probably a good idea to increase the value
14710 (to 50, say). It also gives some protection against denial-of-service attacks
14711 by SYN flooding.
14712
14713 +-----------------+---------+-------------+-------------+
14714 |smtp_enforce_sync|Use: main|Type: boolean|Default: true|
14715 +-----------------+---------+-------------+-------------+
14716
14717 The SMTP protocol specification requires the client to wait for a response from
14718 the server at certain points in the dialogue. Without PIPELINING these
14719 synchronization points are after every command; with PIPELINING they are fewer,
14720 but they still exist.
14721
14722 Some spamming sites send out a complete set of SMTP commands without waiting
14723 for any response. Exim protects against this by rejecting a message if the
14724 client has sent further input when it should not have. The error response "554
14725 SMTP synchronization error" is sent, and the connection is dropped. Testing for
14726 this error cannot be perfect because of transmission delays (unexpected input
14727 may be on its way but not yet received when Exim checks). However, it does
14728 detect many instances.
14729
14730 The check can be globally disabled by setting smtp_enforce_sync false. If you
14731 want to disable the check selectively (for example, only for certain hosts),
14732 you can do so by an appropriate use of a control modifier in an ACL (see
14733 section 42.22). See also pipelining_advertise_hosts.
14734
14735 +-----------------+---------+-------------+--------------+
14736 |smtp_etrn_command|Use: main|Type: string*|Default: unset|
14737 +-----------------+---------+-------------+--------------+
14738
14739 If this option is set, the given command is run whenever an SMTP ETRN command
14740 is received from a host that is permitted to issue such commands (see chapter
14741 42). The string is split up into separate arguments which are independently
14742 expanded. The expansion variable $domain is set to the argument of the ETRN
14743 command, and no syntax checking is done on it. For example:
14744
14745 smtp_etrn_command = /etc/etrn_command $domain \
14746 $sender_host_address
14747
14748 A new process is created to run the command, but Exim does not wait for it to
14749 complete. Consequently, its status cannot be checked. If the command cannot be
14750 run, a line is written to the panic log, but the ETRN caller still receives a
14751 250 success response. Exim is normally running under its own uid when receiving
14752 SMTP, so it is not possible for it to change the uid before running the
14753 command.
14754
14755 +-------------------+---------+-------------+-------------+
14756 |smtp_etrn_serialize|Use: main|Type: boolean|Default: true|
14757 +-------------------+---------+-------------+-------------+
14758
14759 When this option is set, it prevents the simultaneous execution of more than
14760 one identical command as a result of ETRN in an SMTP connection. See section
14761 47.8 for details.
14762
14763 +-----------------+---------+-----------------+--------------+
14764 |smtp_load_reserve|Use: main|Type: fixed-point|Default: unset|
14765 +-----------------+---------+-----------------+--------------+
14766
14767 If the system load average ever gets higher than this, incoming SMTP calls are
14768 accepted only from those hosts that match an entry in smtp_reserve_hosts. If
14769 smtp_reserve_hosts is not set, no incoming SMTP calls are accepted when the
14770 load is over the limit. The option has no effect on ancient operating systems
14771 on which Exim cannot determine the load average. See also
14772 deliver_queue_load_max and queue_only_load.
14773
14774 +-----------------------+---------+-------------+----------+
14775 |smtp_max_synprot_errors|Use: main|Type: integer|Default: 3|
14776 +-----------------------+---------+-------------+----------+
14777
14778 Exim rejects SMTP commands that contain syntax or protocol errors. In
14779 particular, a syntactically invalid email address, as in this command:
14780
14781 RCPT TO:<abc xyz@a.b.c>
14782
14783 causes immediate rejection of the command, before any other tests are done.
14784 (The ACL cannot be run if there is no valid address to set up for it.) An
14785 example of a protocol error is receiving RCPT before MAIL. If there are too
14786 many syntax or protocol errors in one SMTP session, the connection is dropped.
14787 The limit is set by this option.
14788
14789 When the PIPELINING extension to SMTP is in use, some protocol errors are
14790 "expected", for instance, a RCPT command after a rejected MAIL command. Exim
14791 assumes that PIPELINING will be used if it advertises it (see
14792 pipelining_advertise_hosts), and in this situation, "expected" errors do not
14793 count towards the limit.
14794
14795 +-------------------------+---------+-------------+----------+
14796 |smtp_max_unknown_commands|Use: main|Type: integer|Default: 3|
14797 +-------------------------+---------+-------------+----------+
14798
14799 If there are too many unrecognized commands in an incoming SMTP session, an
14800 Exim server drops the connection. This is a defence against some kinds of abuse
14801 that subvert web clients into making connections to SMTP ports; in these
14802 circumstances, a number of non-SMTP command lines are sent first.
14803
14804 +--------------------+---------+----------------+--------------+
14805 |smtp_ratelimit_hosts|Use: main|Type: host list*|Default: unset|
14806 +--------------------+---------+----------------+--------------+
14807
14808 Some sites find it helpful to be able to limit the rate at which certain hosts
14809 can send them messages, and the rate at which an individual message can specify
14810 recipients.
14811
14812 Exim has two rate-limiting facilities. This section describes the older
14813 facility, which can limit rates within a single connection. The newer ratelimit
14814 ACL condition can limit rates across all connections. See section 42.38 for
14815 details of the newer facility.
14816
14817 When a host matches smtp_ratelimit_hosts, the values of smtp_ratelimit_mail and
14818 smtp_ratelimit_rcpt are used to control the rate of acceptance of MAIL and RCPT
14819 commands in a single SMTP session, respectively. Each option, if set, must
14820 contain a set of four comma-separated values:
14821
14822 * A threshold, before which there is no rate limiting.
14823
14824 * An initial time delay. Unlike other times in Exim, numbers with decimal
14825 fractional parts are allowed here.
14826
14827 * A factor by which to increase the delay each time.
14828
14829 * A maximum value for the delay. This should normally be less than 5 minutes,
14830 because after that time, the client is liable to timeout the SMTP command.
14831
14832 For example, these settings have been used successfully at the site which first
14833 suggested this feature, for controlling mail from their customers:
14834
14835 smtp_ratelimit_mail = 2,0.5s,1.05,4m
14836 smtp_ratelimit_rcpt = 4,0.25s,1.015,4m
14837
14838 The first setting specifies delays that are applied to MAIL commands after two
14839 have been received over a single connection. The initial delay is 0.5 seconds,
14840 increasing by a factor of 1.05 each time. The second setting applies delays to
14841 RCPT commands when more than four occur in a single message.
14842
14843 +-------------------+---------+------------+--------------+
14844 |smtp_ratelimit_mail|Use: main|Type: string|Default: unset|
14845 +-------------------+---------+------------+--------------+
14846
14847 See smtp_ratelimit_hosts above.
14848
14849 +-------------------+---------+------------+--------------+
14850 |smtp_ratelimit_rcpt|Use: main|Type: string|Default: unset|
14851 +-------------------+---------+------------+--------------+
14852
14853 See smtp_ratelimit_hosts above.
14854
14855 +--------------------+---------+----------+-----------+
14856 |smtp_receive_timeout|Use: main|Type: time|Default: 5m|
14857 +--------------------+---------+----------+-----------+
14858
14859 This sets a timeout value for SMTP reception. It applies to all forms of SMTP
14860 input, including batch SMTP. If a line of input (either an SMTP command or a
14861 data line) is not received within this time, the SMTP connection is dropped and
14862 the message is abandoned. A line is written to the log containing one of the
14863 following messages:
14864
14865 SMTP command timeout on connection from...
14866 SMTP data timeout on connection from...
14867
14868 The former means that Exim was expecting to read an SMTP command; the latter
14869 means that it was in the DATA phase, reading the contents of a message.
14870
14871 The value set by this option can be overridden by the -os command-line option.
14872 A setting of zero time disables the timeout, but this should never be used for
14873 SMTP over TCP/IP. (It can be useful in some cases of local input using -bs or
14874 -bS.) For non-SMTP input, the reception timeout is controlled by
14875 receive_timeout and -or.
14876
14877 +------------------+---------+----------------+--------------+
14878 |smtp_reserve_hosts|Use: main|Type: host list*|Default: unset|
14879 +------------------+---------+----------------+--------------+
14880
14881 This option defines hosts for which SMTP connections are reserved; see
14882 smtp_accept_reserve and smtp_load_reserve above.
14883
14884 +-------------------------+---------+-------------+--------------+
14885 |smtp_return_error_details|Use: main|Type: boolean|Default: false|
14886 +-------------------------+---------+-------------+--------------+
14887
14888 In the default state, Exim uses bland messages such as "Administrative
14889 prohibition" when it rejects SMTP commands for policy reasons. Many sysadmins
14890 like this because it gives away little information to spammers. However, some
14891 other sysadmins who are applying strict checking policies want to give out much
14892 fuller information about failures. Setting smtp_return_error_details true
14893 causes Exim to be more forthcoming. For example, instead of "Administrative
14894 prohibition", it might give:
14895
14896 550-Rejected after DATA: '>' missing at end of address:
14897 550 failing address in "From" header is: <user@dom.ain
14898
14899 +-------------+---------+------------+------------------+
14900 |spamd_address|Use: main|Type: string|Default: see below|
14901 +-------------+---------+------------+------------------+
14902
14903 This option is available when Exim is compiled with the content-scanning
14904 extension. It specifies how Exim connects to SpamAssassin's spamd daemon. The
14905 default value is
14906
14907 127.0.0.1 783
14908
14909 See section 43.2 for more details.
14910
14911 +---------------------+---------+-------------+--------------+
14912 |split_spool_directory|Use: main|Type: boolean|Default: false|
14913 +---------------------+---------+-------------+--------------+
14914
14915 If this option is set, it causes Exim to split its input directory into 62
14916 subdirectories, each with a single alphanumeric character as its name. The
14917 sixth character of the message id is used to allocate messages to
14918 subdirectories; this is the least significant base-62 digit of the time of
14919 arrival of the message.
14920
14921 Splitting up the spool in this way may provide better performance on systems
14922 where there are long mail queues, by reducing the number of files in any one
14923 directory. The msglog directory is also split up in a similar way to the input
14924 directory; however, if preserve_message_logs is set, all old msglog files are
14925 still placed in the single directory msglog.OLD.
14926
14927 It is not necessary to take any special action for existing messages when
14928 changing split_spool_directory. Exim notices messages that are in the "wrong"
14929 place, and continues to process them. If the option is turned off after a
14930 period of being on, the subdirectories will eventually empty and be
14931 automatically deleted.
14932
14933 When split_spool_directory is set, the behaviour of queue runner processes
14934 changes. Instead of creating a list of all messages in the queue, and then
14935 trying to deliver each one in turn, it constructs a list of those in one
14936 sub-directory and tries to deliver them, before moving on to the next
14937 sub-directory. The sub-directories are processed in a random order. This
14938 spreads out the scanning of the input directories, and uses less memory. It is
14939 particularly beneficial when there are lots of messages on the queue. However,
14940 if queue_run_in_order is set, none of this new processing happens. The entire
14941 queue has to be scanned and sorted before any deliveries can start.
14942
14943 +---------------+---------+-------------+----------------------------+
14944 |spool_directory|Use: main|Type: string*|Default: set at compile time|
14945 +---------------+---------+-------------+----------------------------+
14946
14947 This defines the directory in which Exim keeps its spool, that is, the messages
14948 it is waiting to deliver. The default value is taken from the compile-time
14949 configuration setting, if there is one. If not, this option must be set. The
14950 string is expanded, so it can contain, for example, a reference to
14951 $primary_hostname.
14952
14953 If the spool directory name is fixed on your installation, it is recommended
14954 that you set it at build time rather than from this option, particularly if the
14955 log files are being written to the spool directory (see log_file_path).
14956 Otherwise log files cannot be used for errors that are detected early on, such
14957 as failures in the configuration file.
14958
14959 By using this option to override the compiled-in path, it is possible to run
14960 tests of Exim without using the standard spool.
14961
14962 +-------------------+---------+----------+-----------+
14963 |sqlite_lock_timeout|Use: main|Type: time|Default: 5s|
14964 +-------------------+---------+----------+-----------+
14965
14966 This option controls the timeout that the sqlite lookup uses when trying to
14967 access an SQLite database. See section 9.25 for more details.
14968
14969 +---------------+---------+-------------+--------------+
14970 |strict_acl_vars|Use: main|Type: boolean|Default: false|
14971 +---------------+---------+-------------+--------------+
14972
14973 This option controls what happens if a syntactically valid but undefined ACL
14974 variable is referenced. If it is false (the default), an empty string is
14975 substituted; if it is true, an error is generated. See section 42.19 for
14976 details of ACL variables.
14977
14978 +---------------------------+---------+-------------+--------------+
14979 |strip_excess_angle_brackets|Use: main|Type: boolean|Default: false|
14980 +---------------------------+---------+-------------+--------------+
14981
14982 If this option is set, redundant pairs of angle brackets round "route-addr"
14983 items in addresses are stripped. For example, <<xxx@a.b.c.d>> is treated as
14984 <xxx@a.b.c.d>. If this is in the envelope and the message is passed on to
14985 another MTA, the excess angle brackets are not passed on. If this option is not
14986 set, multiple pairs of angle brackets cause a syntax error.
14987
14988 +------------------+---------+-------------+--------------+
14989 |strip_trailing_dot|Use: main|Type: boolean|Default: false|
14990 +------------------+---------+-------------+--------------+
14991
14992 If this option is set, a trailing dot at the end of a domain in an address is
14993 ignored. If this is in the envelope and the message is passed on to another
14994 MTA, the dot is not passed on. If this option is not set, a dot at the end of a
14995 domain causes a syntax error. However, addresses in header lines are checked
14996 only when an ACL requests header syntax checking.
14997
14998 +------------------+---------+-------------+-------------+
14999 |syslog_duplication|Use: main|Type: boolean|Default: true|
15000 +------------------+---------+-------------+-------------+
15001
15002 When Exim is logging to syslog, it writes the log lines for its three separate
15003 logs at different syslog priorities so that they can in principle be separated
15004 on the logging hosts. Some installations do not require this separation, and in
15005 those cases, the duplication of certain log lines is a nuisance. If
15006 syslog_duplication is set false, only one copy of any particular log line is
15007 written to syslog. For lines that normally go to both the main log and the
15008 reject log, the reject log version (possibly containing message header lines)
15009 is written, at LOG_NOTICE priority. Lines that normally go to both the main and
15010 the panic log are written at the LOG_ALERT priority.
15011
15012 +---------------+---------+------------+--------------+
15013 |syslog_facility|Use: main|Type: string|Default: unset|
15014 +---------------+---------+------------+--------------+
15015
15016 This option sets the syslog "facility" name, used when Exim is logging to
15017 syslog. The value must be one of the strings "mail", "user", "news", "uucp",
15018 "daemon", or "localx" where x is a digit between 0 and 7. If this option is
15019 unset, "mail" is used. See chapter 51 for details of Exim's logging.
15020
15021 +------------------+---------+------------+---------------+
15022 |syslog_processname|Use: main|Type: string|Default: "exim"|
15023 +------------------+---------+------------+---------------+
15024
15025 This option sets the syslog "ident" name, used when Exim is logging to syslog.
15026 The value must be no longer than 32 characters. See chapter 51 for details of
15027 Exim's logging.
15028
15029 +----------------+---------+-------------+-------------+
15030 |syslog_timestamp|Use: main|Type: boolean|Default: true|
15031 +----------------+---------+-------------+-------------+
15032
15033 If syslog_timestamp is set false, the timestamps on Exim's log lines are
15034 omitted when these lines are sent to syslog. See chapter 51 for details of
15035 Exim's logging.
15036
15037 +-------------+---------+-------------+--------------+
15038 |system_filter|Use: main|Type: string*|Default: unset|
15039 +-------------+---------+-------------+--------------+
15040
15041 This option specifies an Exim filter file that is applied to all messages at
15042 the start of each delivery attempt, before any routing is done. System filters
15043 must be Exim filters; they cannot be Sieve filters. If the system filter
15044 generates any deliveries to files or pipes, or any new mail messages, the
15045 appropriate system_filter_..._transport option(s) must be set, to define which
15046 transports are to be used. Details of this facility are given in chapter 45.
15047
15048 +---------------------------------+---------+-------------+--------------+
15049 |system_filter_directory_transport|Use: main|Type: string*|Default: unset|
15050 +---------------------------------+---------+-------------+--------------+
15051
15052 This sets the name of the transport driver that is to be used when the save
15053 command in a system message filter specifies a path ending in "/", implying
15054 delivery of each message into a separate file in some directory. During the
15055 delivery, the variable $address_file contains the path name.
15056
15057 +----------------------------+---------+-------------+--------------+
15058 |system_filter_file_transport|Use: main|Type: string*|Default: unset|
15059 +----------------------------+---------+-------------+--------------+
15060
15061 This sets the name of the transport driver that is to be used when the save
15062 command in a system message filter specifies a path not ending in "/". During
15063 the delivery, the variable $address_file contains the path name.
15064
15065 +-------------------+---------+------------+--------------+
15066 |system_filter_group|Use: main|Type: string|Default: unset|
15067 +-------------------+---------+------------+--------------+
15068
15069 This option is used only when system_filter_user is also set. It sets the gid
15070 under which the system filter is run, overriding any gid that is associated
15071 with the user. The value may be numerical or symbolic.
15072
15073 +----------------------------+---------+-------------+--------------+
15074 |system_filter_pipe_transport|Use: main|Type: string*|Default: unset|
15075 +----------------------------+---------+-------------+--------------+
15076
15077 This specifies the transport driver that is to be used when a pipe command is
15078 used in a system filter. During the delivery, the variable $address_pipe
15079 contains the pipe command.
15080
15081 +-----------------------------+---------+-------------+--------------+
15082 |system_filter_reply_transport|Use: main|Type: string*|Default: unset|
15083 +-----------------------------+---------+-------------+--------------+
15084
15085 This specifies the transport driver that is to be used when a mail command is
15086 used in a system filter.
15087
15088 +------------------+---------+------------+--------------+
15089 |system_filter_user|Use: main|Type: string|Default: unset|
15090 +------------------+---------+------------+--------------+
15091
15092 If this option is set to root, the system filter is run in the main Exim
15093 delivery process, as root. Otherwise, the system filter runs in a separate
15094 process, as the given user, defaulting to the Exim run-time user. Unless the
15095 string consists entirely of digits, it is looked up in the password data.
15096 Failure to find the named user causes a configuration error. The gid is either
15097 taken from the password data, or specified by system_filter_group. When the uid
15098 is specified numerically, system_filter_group is required to be set.
15099
15100 If the system filter generates any pipe, file, or reply deliveries, the uid
15101 under which the filter is run is used when transporting them, unless a
15102 transport option overrides.
15103
15104 +-----------+---------+-------------+-------------+
15105 |tcp_nodelay|Use: main|Type: boolean|Default: true|
15106 +-----------+---------+-------------+-------------+
15107
15108 If this option is set false, it stops the Exim daemon setting the TCP_NODELAY
15109 option on its listening sockets. Setting TCP_NODELAY turns off the "Nagle
15110 algorithm", which is a way of improving network performance in interactive
15111 (character-by-character) situations. Turning it off should improve Exim's
15112 performance a bit, so that is what happens by default. However, it appears that
15113 some broken clients cannot cope, and time out. Hence this option. It affects
15114 only those sockets that are set up for listening by the daemon. Sockets created
15115 by the smtp transport for delivering mail always set TCP_NODELAY.
15116
15117 +--------------------+---------+----------+-----------+
15118 |timeout_frozen_after|Use: main|Type: time|Default: 0s|
15119 +--------------------+---------+----------+-----------+
15120
15121 If timeout_frozen_after is set to a time greater than zero, a frozen message of
15122 any kind that has been on the queue for longer than the given time is
15123 automatically cancelled at the next queue run. If the frozen message is a
15124 bounce message, it is just discarded; otherwise, a bounce is sent to the
15125 sender, in a similar manner to cancellation by the -Mg command line option. If
15126 you want to timeout frozen bounce messages earlier than other kinds of frozen
15127 message, see ignore_bounce_errors_after.
15128
15129 Note: the default value of zero means no timeouts; with this setting, frozen
15130 messages remain on the queue forever (except for any frozen bounce messages
15131 that are released by ignore_bounce_errors_after).
15132
15133 +--------+---------+------------+--------------+
15134 |timezone|Use: main|Type: string|Default: unset|
15135 +--------+---------+------------+--------------+
15136
15137 The value of timezone is used to set the environment variable TZ while running
15138 Exim (if it is different on entry). This ensures that all timestamps created by
15139 Exim are in the required timezone. If you want all your timestamps to be in UTC
15140 (aka GMT) you should set
15141
15142 timezone = UTC
15143
15144 The default value is taken from TIMEZONE_DEFAULT in Local/Makefile, or, if that
15145 is not set, from the value of the TZ environment variable when Exim is built.
15146 If timezone is set to the empty string, either at build or run time, any
15147 existing TZ variable is removed from the environment when Exim runs. This is
15148 appropriate behaviour for obtaining wall-clock time on some, but unfortunately
15149 not all, operating systems.
15150
15151 +-------------------+---------+----------------+--------------+
15152 |tls_advertise_hosts|Use: main|Type: host list*|Default: unset|
15153 +-------------------+---------+----------------+--------------+
15154
15155 When Exim is built with support for TLS encrypted connections, the availability
15156 of the STARTTLS command to set up an encrypted session is advertised in
15157 response to EHLO only to those client hosts that match this option. See chapter
15158 41 for details of Exim's support for TLS.
15159
15160 +---------------+---------+-------------+--------------+
15161 |tls_certificate|Use: main|Type: string*|Default: unset|
15162 +---------------+---------+-------------+--------------+
15163
15164 The value of this option is expanded, and must then be the absolute path to a
15165 file which contains the server's certificates. The server's private key is also
15166 assumed to be in this file if tls_privatekey is unset. See chapter 41 for
15167 further details.
15168
15169 Note: The certificates defined by this option are used only when Exim is
15170 receiving incoming messages as a server. If you want to supply certificates for
15171 use when sending messages as a client, you must set the tls_certificate option
15172 in the relevant smtp transport.
15173
15174 If the option contains $tls_out_sni and Exim is built against OpenSSL, then if
15175 the OpenSSL build supports TLS extensions and the TLS client sends the Server
15176 Name Indication extension, then this option and others documented in 41.10 will
15177 be re-expanded.
15178
15179 +-------+---------+-------------+--------------+
15180 |tls_crl|Use: main|Type: string*|Default: unset|
15181 +-------+---------+-------------+--------------+
15182
15183 This option specifies a certificate revocation list. The expanded value must be
15184 the name of a file that contains a CRL in PEM format.
15185
15186 See 41.10 for discussion of when this option might be re-expanded.
15187
15188 +---------------+---------+-------------+-------------+
15189 |tls_dh_max_bits|Use: main|Type: integer|Default: 2236|
15190 +---------------+---------+-------------+-------------+
15191
15192 The number of bits used for Diffie-Hellman key-exchange may be suggested by the
15193 chosen TLS library. That value might prove to be too high for interoperability.
15194 This option provides a maximum clamp on the value suggested, trading off
15195 security for interoperability.
15196
15197 The value must be at least 1024.
15198
15199 The value 2236 was chosen because, at time of adding the option, it was the
15200 hard-coded maximum value supported by the NSS cryptographic library, as used by
15201 Thunderbird, while GnuTLS was suggesting 2432 bits as normal.
15202
15203 If you prefer more security and are willing to break some clients, raise this
15204 number.
15205
15206 Note that the value passed to GnuTLS for *generating* a new prime may be a
15207 little less than this figure, because GnuTLS is inexact and may produce a
15208 larger prime than requested.
15209
15210 +-----------+---------+-------------+--------------+
15211 |tls_dhparam|Use: main|Type: string*|Default: unset|
15212 +-----------+---------+-------------+--------------+
15213
15214 The value of this option is expanded and indicates the source of DH parameters
15215 to be used by Exim.
15216
15217 If it is a filename starting with a "/", then it names a file from which DH
15218 parameters should be loaded. If the file exists, it should hold a PEM-encoded
15219 PKCS#3 representation of the DH prime. If the file does not exist, for OpenSSL
15220 it is an error. For GnuTLS, Exim will attempt to create the file and fill it
15221 with a generated DH prime. For OpenSSL, if the DH bit-count from loading the
15222 file is greater than tls_dh_max_bits then it will be ignored, and treated as
15223 though the tls_dhparam were set to "none".
15224
15225 If this option expands to the string "none", then no DH parameters will be
15226 loaded by Exim.
15227
15228 If this option expands to the string "historic" and Exim is using GnuTLS, then
15229 Exim will attempt to load a file from inside the spool directory. If the file
15230 does not exist, Exim will attempt to create it. See section 41.3 for further
15231 details.
15232
15233 If Exim is using OpenSSL and this option is empty or unset, then Exim will load
15234 a default DH prime; the default is the 2048 bit prime described in section 2.2
15235 of RFC 5114, "2048-bit MODP Group with 224-bit Prime Order Subgroup", which in
15236 IKE is assigned number 23.
15237
15238 Otherwise, the option must expand to the name used by Exim for any of a number
15239 of DH primes specified in RFC 2409, RFC 3526 and RFC 5114. As names, Exim uses
15240 "ike" followed by the number used by IKE, of "default" which corresponds to
15241 "ike23".
15242
15243 The available primes are: "ike1", "ike2", "ike5", "ike14", "ike15", "ike16",
15244 "ike17", "ike18", "ike22", "ike23" (aka "default") and "ike24".
15245
15246 Some of these will be too small to be accepted by clients. Some may be too
15247 large to be accepted by clients.
15248
15249 The TLS protocol does not negotiate an acceptable size for this; clients tend
15250 to hard-drop connections if what is offered by the server is unacceptable,
15251 whether too large or too small, and there's no provision for the client to tell
15252 the server what these constraints are. Thus, as a server operator, you need to
15253 make an educated guess as to what is most likely to work for your userbase.
15254
15255 Some known size constraints suggest that a bit-size in the range 2048 to 2236
15256 is most likely to maximise interoperability. The upper bound comes from
15257 applications using the Mozilla Network Security Services (NSS) library, which
15258 used to set its "DH_MAX_P_BITS" upper-bound to 2236. This affects many mail
15259 user agents (MUAs). The lower bound comes from Debian installs of Exim4 prior
15260 to the 4.80 release, as Debian used to patch Exim to raise the minimum
15261 acceptable bound from 1024 to 2048.
15262
15263 +-------------+---------+-------------+--------------+
15264 |tls_ocsp_file|Use: main|Type: string*|Default: unset|
15265 +-------------+---------+-------------+--------------+
15266
15267 This option must if set expand to the absolute path to a file which contains a
15268 current status proof for the server's certificate, as obtained from the
15269 Certificate Authority.
15270
15271 +--------------------+---------+-----------------+--------------+
15272 |tls_on_connect_ports|Use: main|Type: string list|Default: unset|
15273 +--------------------+---------+-----------------+--------------+
15274
15275 This option specifies a list of incoming SSMTP (aka SMTPS) ports that should
15276 operate the obsolete SSMTP (SMTPS) protocol, where a TLS session is immediately
15277 set up without waiting for the client to issue a STARTTLS command. For further
15278 details, see section 13.4.
15279
15280 +--------------+---------+-------------+--------------+
15281 |tls_privatekey|Use: main|Type: string*|Default: unset|
15282 +--------------+---------+-------------+--------------+
15283
15284 The value of this option is expanded, and must then be the absolute path to a
15285 file which contains the server's private key. If this option is unset, or if
15286 the expansion is forced to fail, or the result is an empty string, the private
15287 key is assumed to be in the same file as the server's certificates. See chapter
15288 41 for further details.
15289
15290 See 41.10 for discussion of when this option might be re-expanded.
15291
15292 +------------------+---------+-------------+--------------+
15293 |tls_remember_esmtp|Use: main|Type: boolean|Default: false|
15294 +------------------+---------+-------------+--------------+
15295
15296 If this option is set true, Exim violates the RFCs by remembering that it is in
15297 "esmtp" state after successfully negotiating a TLS session. This provides
15298 support for broken clients that fail to send a new EHLO after starting a TLS
15299 session.
15300
15301 +-------------------+---------+-------------+--------------+
15302 |tls_require_ciphers|Use: main|Type: string*|Default: unset|
15303 +-------------------+---------+-------------+--------------+
15304
15305 This option controls which ciphers can be used for incoming TLS connections.
15306 The smtp transport has an option of the same name for controlling outgoing
15307 connections. This option is expanded for each connection, so can be varied for
15308 different clients if required. The value of this option must be a list of
15309 permitted cipher suites. The OpenSSL and GnuTLS libraries handle cipher control
15310 in somewhat different ways. If GnuTLS is being used, the client controls the
15311 preference order of the available ciphers. Details are given in sections 41.4
15312 and 41.5.
15313
15314 +--------------------+---------+----------------+--------------+
15315 |tls_try_verify_hosts|Use: main|Type: host list*|Default: unset|
15316 +--------------------+---------+----------------+--------------+
15317
15318 See tls_verify_hosts below.
15319
15320 +-----------------------+---------+-------------+--------------+
15321 |tls_verify_certificates|Use: main|Type: string*|Default: unset|
15322 +-----------------------+---------+-------------+--------------+
15323
15324 The value of this option is expanded, and must then be the absolute path to a
15325 file containing permitted certificates for clients that match tls_verify_hosts
15326 or tls_try_verify_hosts. Alternatively, if you are using OpenSSL, you can set
15327 tls_verify_certificates to the name of a directory containing certificate
15328 files. This does not work with GnuTLS; the option must be set to the name of a
15329 single file if you are using GnuTLS.
15330
15331 These certificates should be for the certificate authorities trusted, rather
15332 than the public cert of individual clients. With both OpenSSL and GnuTLS, if
15333 the value is a file then the certificates are sent by Exim as a server to
15334 connecting clients, defining the list of accepted certificate authorities. Thus
15335 the values defined should be considered public data. To avoid this, use OpenSSL
15336 with a directory.
15337
15338 See 41.10 for discussion of when this option might be re-expanded.
15339
15340 A forced expansion failure or setting to an empty string is equivalent to being
15341 unset.
15342
15343 +----------------+---------+----------------+--------------+
15344 |tls_verify_hosts|Use: main|Type: host list*|Default: unset|
15345 +----------------+---------+----------------+--------------+
15346
15347 This option, along with tls_try_verify_hosts, controls the checking of
15348 certificates from clients. The expected certificates are defined by
15349 tls_verify_certificates, which must be set. A configuration error occurs if
15350 either tls_verify_hosts or tls_try_verify_hosts is set and
15351 tls_verify_certificates is not set.
15352
15353 Any client that matches tls_verify_hosts is constrained by
15354 tls_verify_certificates. When the client initiates a TLS session, it must
15355 present one of the listed certificates. If it does not, the connection is
15356 aborted. Warning: Including a host in tls_verify_hosts does not require the
15357 host to use TLS. It can still send SMTP commands through unencrypted
15358 connections. Forcing a client to use TLS has to be done separately using an ACL
15359 to reject inappropriate commands when the connection is not encrypted.
15360
15361 A weaker form of checking is provided by tls_try_verify_hosts. If a client
15362 matches this option (but not tls_verify_hosts), Exim requests a certificate and
15363 checks it against tls_verify_certificates, but does not abort the connection if
15364 there is no certificate or if it does not match. This state can be detected in
15365 an ACL, which makes it possible to implement policies such as "accept for relay
15366 only if a verified certificate has been received, but accept for local delivery
15367 if encrypted, even without a verified certificate".
15368
15369 Client hosts that match neither of these lists are not asked to present
15370 certificates.
15371
15372 +--------------+---------+------------------+--------------+
15373 |trusted_groups|Use: main|Type: string list*|Default: unset|
15374 +--------------+---------+------------------+--------------+
15375
15376 This option is expanded just once, at the start of Exim's processing. If this
15377 option is set, any process that is running in one of the listed groups, or
15378 which has one of them as a supplementary group, is trusted. The groups can be
15379 specified numerically or by name. See section 5.2 for details of what trusted
15380 callers are permitted to do. If neither trusted_groups nor trusted_users is
15381 set, only root and the Exim user are trusted.
15382
15383 +-------------+---------+------------------+--------------+
15384 |trusted_users|Use: main|Type: string list*|Default: unset|
15385 +-------------+---------+------------------+--------------+
15386
15387 This option is expanded just once, at the start of Exim's processing. If this
15388 option is set, any process that is running as one of the listed users is
15389 trusted. The users can be specified numerically or by name. See section 5.2 for
15390 details of what trusted callers are permitted to do. If neither trusted_groups
15391 nor trusted_users is set, only root and the Exim user are trusted.
15392
15393 +-------------+---------+-------------+--------------+
15394 |unknown_login|Use: main|Type: string*|Default: unset|
15395 +-------------+---------+-------------+--------------+
15396
15397 This is a specialized feature for use in unusual configurations. By default, if
15398 the uid of the caller of Exim cannot be looked up using getpwuid(), Exim gives
15399 up. The unknown_login option can be used to set a login name to be used in this
15400 circumstance. It is expanded, so values like user$caller_uid can be set. When
15401 unknown_login is used, the value of unknown_username is used for the user's
15402 real name (gecos field), unless this has been set by the -F option.
15403
15404 +----------------+---------+------------+--------------+
15405 |unknown_username|Use: main|Type: string|Default: unset|
15406 +----------------+---------+------------+--------------+
15407
15408 See unknown_login.
15409
15410 +--------------------+---------+-------------------+--------------+
15411 |untrusted_set_sender|Use: main|Type: address list*|Default: unset|
15412 +--------------------+---------+-------------------+--------------+
15413
15414 When an untrusted user submits a message to Exim using the standard input, Exim
15415 normally creates an envelope sender address from the user's login and the
15416 default qualification domain. Data from the -f option (for setting envelope
15417 senders on non-SMTP messages) or the SMTP MAIL command (if -bs or -bS is used)
15418 is ignored.
15419
15420 However, untrusted users are permitted to set an empty envelope sender address,
15421 to declare that a message should never generate any bounces. For example:
15422
15423 exim -f '<>' user@domain.example
15424
15425 The untrusted_set_sender option allows you to permit untrusted users to set
15426 other envelope sender addresses in a controlled way. When it is set, untrusted
15427 users are allowed to set envelope sender addresses that match any of the
15428 patterns in the list. Like all address lists, the string is expanded. The
15429 identity of the user is in $sender_ident, so you can, for example, restrict
15430 users to setting senders that start with their login ids followed by a hyphen
15431 by a setting like this:
15432
15433 untrusted_set_sender = ^$sender_ident-
15434
15435 If you want to allow untrusted users to set envelope sender addresses without
15436 restriction, you can use
15437
15438 untrusted_set_sender = *
15439
15440 The untrusted_set_sender option applies to all forms of local input, but only
15441 to the setting of the envelope sender. It does not permit untrusted users to
15442 use the other options which trusted user can use to override message
15443 parameters. Furthermore, it does not stop Exim from removing an existing
15444 Sender: header in the message, or from adding a Sender: header if necessary.
15445 See local_sender_retain and local_from_check for ways of overriding these
15446 actions. The handling of the Sender: header is also described in section 46.16.
15447
15448 The log line for a message's arrival shows the envelope sender following "<=".
15449 For local messages, the user's login always follows, after "U=". In -bp
15450 displays, and in the Exim monitor, if an untrusted user sets an envelope sender
15451 address, the user's login is shown in parentheses after the sender address.
15452
15453 +-----------------+---------+------------+------------------+
15454 |uucp_from_pattern|Use: main|Type: string|Default: see below|
15455 +-----------------+---------+------------+------------------+
15456
15457 Some applications that pass messages to an MTA via a command line interface use
15458 an initial line starting with "From " to pass the envelope sender. In
15459 particular, this is used by UUCP software. Exim recognizes such a line by means
15460 of a regular expression that is set in uucp_from_pattern. When the pattern
15461 matches, the sender address is constructed by expanding the contents of
15462 uucp_from_sender, provided that the caller of Exim is a trusted user. The
15463 default pattern recognizes lines in the following two forms:
15464
15465 From ph10 Fri Jan 5 12:35 GMT 1996
15466 From ph10 Fri, 7 Jan 97 14:00:00 GMT
15467
15468 The pattern can be seen by running
15469
15470 exim -bP uucp_from_pattern
15471
15472 It checks only up to the hours and minutes, and allows for a 2-digit or 4-digit
15473 year in the second case. The first word after "From " is matched in the regular
15474 expression by a parenthesized subpattern. The default value for
15475 uucp_from_sender is "$1", which therefore just uses this first word ("ph10" in
15476 the example above) as the message's sender. See also ignore_fromline_hosts.
15477
15478 +----------------+---------+-------------+-------------+
15479 |uucp_from_sender|Use: main|Type: string*|Default: "$1"|
15480 +----------------+---------+-------------+-------------+
15481
15482 See uucp_from_pattern above.
15483
15484 +-----------------+---------+------------+--------------+
15485 |warn_message_file|Use: main|Type: string|Default: unset|
15486 +-----------------+---------+------------+--------------+
15487
15488 This option defines a template file containing paragraphs of text to be used
15489 for constructing the warning message which is sent by Exim when a message has
15490 been on the queue for a specified amount of time, as specified by delay_warning
15491 . Details of the file's contents are given in chapter 48. See also
15492 bounce_message_file.
15493
15494 +---------------+---------+-------------+-------------+
15495 |write_rejectlog|Use: main|Type: boolean|Default: true|
15496 +---------------+---------+-------------+-------------+
15497
15498 If this option is set false, Exim no longer writes anything to the reject log.
15499 See chapter 51 for details of what Exim writes to its logs.
15500
15501
15502
15503 ===============================================================================
15504 15. GENERIC OPTIONS FOR ROUTERS
15505
15506 This chapter describes the generic options that apply to all routers. Those
15507 that are preconditions are marked with ** in the "use" field.
15508
15509 For a general description of how a router operates, see sections 3.10 and 3.12.
15510 The latter specifies the order in which the preconditions are tested. The order
15511 of expansion of the options that provide data for a transport is: errors_to,
15512 headers_add, headers_remove, transport.
15513
15514 +------------+------------+-------------+--------------+
15515 |address_data|Use: routers|Type: string*|Default: unset|
15516 +------------+------------+-------------+--------------+
15517
15518 The string is expanded just before the router is run, that is, after all the
15519 precondition tests have succeeded. If the expansion is forced to fail, the
15520 router declines, the value of address_data remains unchanged, and the more
15521 option controls what happens next. Other expansion failures cause delivery of
15522 the address to be deferred.
15523
15524 When the expansion succeeds, the value is retained with the address, and can be
15525 accessed using the variable $address_data in the current router, subsequent
15526 routers, and the eventual transport.
15527
15528 Warning: If the current or any subsequent router is a redirect router that runs
15529 a user's filter file, the contents of $address_data are accessible in the
15530 filter. This is not normally a problem, because such data is usually either not
15531 confidential or it "belongs" to the current user, but if you do put
15532 confidential data into $address_data you need to remember this point.
15533
15534 Even if the router declines or passes, the value of $address_data remains with
15535 the address, though it can be changed by another address_data setting on a
15536 subsequent router. If a router generates child addresses, the value of
15537 $address_data propagates to them. This also applies to the special kind of
15538 "child" that is generated by a router with the unseen option.
15539
15540 The idea of address_data is that you can use it to look up a lot of data for
15541 the address once, and then pick out parts of the data later. For example, you
15542 could use a single LDAP lookup to return a string of the form
15543
15544 uid=1234 gid=5678 mailbox=/mail/xyz forward=/home/xyz/.forward
15545
15546 In the transport you could pick out the mailbox by a setting such as
15547
15548 file = ${extract{mailbox}{$address_data}}
15549
15550 This makes the configuration file less messy, and also reduces the number of
15551 lookups (though Exim does cache lookups).
15552
15553 The address_data facility is also useful as a means of passing information from
15554 one router to another, and from a router to a transport. In addition, if
15555 $address_data is set by a router when verifying a recipient address from an
15556 ACL, it remains available for use in the rest of the ACL statement. After
15557 verifying a sender, the value is transferred to $sender_address_data.
15558
15559 +------------+--------------+-------------+-------------+
15560 |address_test|Use: routers**|Type: boolean|Default: true|
15561 +------------+--------------+-------------+-------------+
15562
15563 If this option is set false, the router is skipped when routing is being tested
15564 by means of the -bt command line option. This can be a convenience when your
15565 first router sends messages to an external scanner, because it saves you having
15566 to set the "already scanned" indicator when testing real address routing.
15567
15568 +--------------------+------------+-------------+--------------+
15569 |cannot_route_message|Use: routers|Type: string*|Default: unset|
15570 +--------------------+------------+-------------+--------------+
15571
15572 This option specifies a text message that is used when an address cannot be
15573 routed because Exim has run out of routers. The default message is "Unrouteable
15574 address". This option is useful only on routers that have more set false, or on
15575 the very last router in a configuration, because the value that is used is
15576 taken from the last router that is considered. This includes a router that is
15577 skipped because its preconditions are not met, as well as a router that
15578 declines. For example, using the default configuration, you could put:
15579
15580 cannot_route_message = Remote domain not found in DNS
15581
15582 on the first router, which is a dnslookup router with more set false, and
15583
15584 cannot_route_message = Unknown local user
15585
15586 on the final router that checks for local users. If string expansion fails for
15587 this option, the default message is used. Unless the expansion failure was
15588 explicitly forced, a message about the failure is written to the main and panic
15589 logs, in addition to the normal message about the routing failure.
15590
15591 +------------------+------------+-------------+--------------+
15592 |caseful_local_part|Use: routers|Type: boolean|Default: false|
15593 +------------------+------------+-------------+--------------+
15594
15595 By default, routers handle the local parts of addresses in a case-insensitive
15596 manner, though the actual case is preserved for transmission with the message.
15597 If you want the case of letters to be significant in a router, you must set
15598 this option true. For individual router options that contain address or local
15599 part lists (for example, local_parts), case-sensitive matching can be turned on
15600 by "+caseful" as a list item. See section 10.20 for more details.
15601
15602 The value of the $local_part variable is forced to lower case while a router is
15603 running unless caseful_local_part is set. When a router assigns an address to a
15604 transport, the value of $local_part when the transport runs is the same as it
15605 was in the router. Similarly, when a router generates child addresses by
15606 aliasing or forwarding, the values of $original_local_part and
15607 $parent_local_part are those that were used by the redirecting router.
15608
15609 This option applies to the processing of an address by a router. When a
15610 recipient address is being processed in an ACL, there is a separate control
15611 modifier that can be used to specify case-sensitive processing within the ACL
15612 (see section 42.22).
15613
15614 +----------------+--------------+-------------+--------------+
15615 |check_local_user|Use: routers**|Type: boolean|Default: false|
15616 +----------------+--------------+-------------+--------------+
15617
15618 When this option is true, Exim checks that the local part of the recipient
15619 address (with affixes removed if relevant) is the name of an account on the
15620 local system. The check is done by calling the getpwnam() function rather than
15621 trying to read /etc/passwd directly. This means that other methods of holding
15622 password data (such as NIS) are supported. If the local part is a local user,
15623 $home is set from the password data, and can be tested in other preconditions
15624 that are evaluated after this one (the order of evaluation is given in section
15625 3.12). However, the value of $home can be overridden by router_home_directory.
15626 If the local part is not a local user, the router is skipped.
15627
15628 If you want to check that the local part is either the name of a local user or
15629 matches something else, you cannot combine check_local_user with a setting of
15630 local_parts, because that specifies the logical and of the two conditions.
15631 However, you can use a passwd lookup in a local_parts setting to achieve this.
15632 For example:
15633
15634 local_parts = passwd;$local_part : lsearch;/etc/other/users
15635
15636 Note, however, that the side effects of check_local_user (such as setting up a
15637 home directory) do not occur when a passwd lookup is used in a local_parts (or
15638 any other) precondition.
15639
15640 +---------+--------------+-------------+--------------+
15641 |condition|Use: routers**|Type: string*|Default: unset|
15642 +---------+--------------+-------------+--------------+
15643
15644 This option specifies a general precondition test that has to succeed for the
15645 router to be called. The condition option is the last precondition to be
15646 evaluated (see section 3.12). The string is expanded, and if the result is a
15647 forced failure, or an empty string, or one of the strings "0" or "no" or
15648 "false" (checked without regard to the case of the letters), the router is
15649 skipped, and the address is offered to the next one.
15650
15651 If the result is any other value, the router is run (as this is the last
15652 precondition to be evaluated, all the other preconditions must be true).
15653
15654 This option is unusual in that multiple condition options may be present. All
15655 condition options must succeed.
15656
15657 The condition option provides a means of applying custom conditions to the
15658 running of routers. Note that in the case of a simple conditional expansion,
15659 the default expansion values are exactly what is wanted. For example:
15660
15661 condition = ${if >{$message_age}{600}}
15662
15663 Because of the default behaviour of the string expansion, this is equivalent to
15664
15665 condition = ${if >{$message_age}{600}{true}{}}
15666
15667 A multiple condition example, which succeeds:
15668
15669 condition = ${if >{$message_age}{600}}
15670 condition = ${if !eq{${lc:$local_part}}{postmaster}}
15671 condition = foobar
15672
15673 If the expansion fails (other than forced failure) delivery is deferred. Some
15674 of the other precondition options are common special cases that could in fact
15675 be specified using condition.
15676
15677 +-----------+------------+-------------+--------------+
15678 |debug_print|Use: routers|Type: string*|Default: unset|
15679 +-----------+------------+-------------+--------------+
15680
15681 If this option is set and debugging is enabled (see the -d command line option)
15682 or in address-testing mode (see the -bt command line option), the string is
15683 expanded and included in the debugging output. If expansion of the string
15684 fails, the error message is written to the debugging output, and Exim carries
15685 on processing. This option is provided to help with checking out the values of
15686 variables and so on when debugging router configurations. For example, if a
15687 condition option appears not to be working, debug_print can be used to output
15688 the variables it references. The output happens after checks for domains,
15689 local_parts, and check_local_user but before any other preconditions are
15690 tested. A newline is added to the text if it does not end with one. The
15691 variable $router_name contains the name of the router.
15692
15693 +---------------+------------+-------------+--------------+
15694 |disable_logging|Use: routers|Type: boolean|Default: false|
15695 +---------------+------------+-------------+--------------+
15696
15697 If this option is set true, nothing is logged for any routing errors or for any
15698 deliveries caused by this router. You should not set this option unless you
15699 really, really know what you are doing. See also the generic transport option
15700 of the same name.
15701
15702 +-------+--------------+------------------+--------------+
15703 |domains|Use: routers**|Type: domain list*|Default: unset|
15704 +-------+--------------+------------------+--------------+
15705
15706 If this option is set, the router is skipped unless the current domain matches
15707 the list. If the match is achieved by means of a file lookup, the data that the
15708 lookup returned for the domain is placed in $domain_data for use in string
15709 expansions of the driver's private options. See section 3.12 for a list of the
15710 order in which preconditions are evaluated.
15711
15712 +------+------------+------------+--------------+
15713 |driver|Use: routers|Type: string|Default: unset|
15714 +------+------------+------------+--------------+
15715
15716 This option must always be set. It specifies which of the available routers is
15717 to be used.
15718
15719 +---------+------------+-------------+--------------+
15720 |errors_to|Use: routers|Type: string*|Default: unset|
15721 +---------+------------+-------------+--------------+
15722
15723 If a router successfully handles an address, it may assign the address to a
15724 transport for delivery or it may generate child addresses. In both cases, if
15725 there is a delivery problem during later processing, the resulting bounce
15726 message is sent to the address that results from expanding this string,
15727 provided that the address verifies successfully. The errors_to option is
15728 expanded before headers_add, headers_remove, and transport.
15729
15730 The errors_to setting associated with an address can be overridden if it
15731 subsequently passes through other routers that have their own errors_to
15732 settings, or if the message is delivered by a transport with a return_path
15733 setting.
15734
15735 If errors_to is unset, or the expansion is forced to fail, or the result of the
15736 expansion fails to verify, the errors address associated with the incoming
15737 address is used. At top level, this is the envelope sender. A non-forced
15738 expansion failure causes delivery to be deferred.
15739
15740 If an address for which errors_to has been set ends up being delivered over
15741 SMTP, the envelope sender for that delivery is the errors_to value, so that any
15742 bounces that are generated by other MTAs on the delivery route are also sent
15743 there. You can set errors_to to the empty string by either of these settings:
15744
15745 errors_to =
15746 errors_to = ""
15747
15748 An expansion item that yields an empty string has the same effect. If you do
15749 this, a locally detected delivery error for addresses processed by this router
15750 no longer gives rise to a bounce message; the error is discarded. If the
15751 address is delivered to a remote host, the return path is set to "<>", unless
15752 overridden by the return_path option on the transport.
15753
15754 If for some reason you want to discard local errors, but use a non-empty MAIL
15755 command for remote delivery, you can preserve the original return path in
15756 $address_data in the router, and reinstate it in the transport by setting
15757 return_path.
15758
15759 The most common use of errors_to is to direct mailing list bounces to the
15760 manager of the list, as described in section 49.2, or to implement VERP
15761 (Variable Envelope Return Paths) (see section 49.6).
15762
15763 +----+--------------+-------------+-------------+
15764 |expn|Use: routers**|Type: boolean|Default: true|
15765 +----+--------------+-------------+-------------+
15766
15767 If this option is turned off, the router is skipped when testing an address as
15768 a result of processing an SMTP EXPN command. You might, for example, want to
15769 turn it off on a router for users' .forward files, while leaving it on for the
15770 system alias file. See section 3.12 for a list of the order in which
15771 preconditions are evaluated.
15772
15773 The use of the SMTP EXPN command is controlled by an ACL (see chapter 42). When
15774 Exim is running an EXPN command, it is similar to testing an address with -bt.
15775 Compare VRFY, whose counterpart is -bv.
15776
15777 +-----------+------------+-------------+--------------+
15778 |fail_verify|Use: routers|Type: boolean|Default: false|
15779 +-----------+------------+-------------+--------------+
15780
15781 Setting this option has the effect of setting both fail_verify_sender and
15782 fail_verify_recipient to the same value.
15783
15784 +---------------------+------------+-------------+--------------+
15785 |fail_verify_recipient|Use: routers|Type: boolean|Default: false|
15786 +---------------------+------------+-------------+--------------+
15787
15788 If this option is true and an address is accepted by this router when verifying
15789 a recipient, verification fails.
15790
15791 +------------------+------------+-------------+--------------+
15792 |fail_verify_sender|Use: routers|Type: boolean|Default: false|
15793 +------------------+------------+-------------+--------------+
15794
15795 If this option is true and an address is accepted by this router when verifying
15796 a sender, verification fails.
15797
15798 +--------------+------------+-----------------+--------------+
15799 |fallback_hosts|Use: routers|Type: string list|Default: unset|
15800 +--------------+------------+-----------------+--------------+
15801
15802 String expansion is not applied to this option. The argument must be a
15803 colon-separated list of host names or IP addresses. The list separator can be
15804 changed (see section 6.19), and a port can be specified with each name or
15805 address. In fact, the format of each item is exactly the same as defined for
15806 the list of hosts in a manualroute router (see section 20.5).
15807
15808 If a router queues an address for a remote transport, this host list is
15809 associated with the address, and used instead of the transport's fallback host
15810 list. If hosts_randomize is set on the transport, the order of the list is
15811 randomized for each use. See the fallback_hosts option of the smtp transport
15812 for further details.
15813
15814 +-----+------------+-------------+------------------+
15815 |group|Use: routers|Type: string*|Default: see below|
15816 +-----+------------+-------------+------------------+
15817
15818 When a router queues an address for a transport, and the transport does not
15819 specify a group, the group given here is used when running the delivery
15820 process. The group may be specified numerically or by name. If expansion fails,
15821 the error is logged and delivery is deferred. The default is unset, unless
15822 check_local_user is set, when the default is taken from the password
15823 information. See also initgroups and user and the discussion in chapter 23.
15824
15825 +-----------+------------+-----------+--------------+
15826 |headers_add|Use: routers|Type: list*|Default: unset|
15827 +-----------+------------+-----------+--------------+
15828
15829 This option specifies a list of text headers, newline-separated, that is
15830 associated with any addresses that are accepted by the router. Each item is
15831 separately expanded, at routing time. However, this option has no effect when
15832 an address is just being verified. The way in which the text is used to add
15833 header lines at transport time is described in section 46.17. New header lines
15834 are not actually added until the message is in the process of being
15835 transported. This means that references to header lines in string expansions in
15836 the transport's configuration do not "see" the added header lines.
15837
15838 The headers_add option is expanded after errors_to, but before headers_remove
15839 and transport. If an item is empty, or if an item expansion is forced to fail,
15840 the item has no effect. Other expansion failures are treated as configuration
15841 errors.
15842
15843 Unlike most options, headers_add can be specified multiple times for a router;
15844 all listed headers are added.
15845
15846 Warning 1: The headers_add option cannot be used for a redirect router that has
15847 the one_time option set.
15848
15849 Warning 2: If the unseen option is set on the router, all header additions are
15850 deleted when the address is passed on to subsequent routers. For a redirect
15851 router, if a generated address is the same as the incoming address, this can
15852 lead to duplicate addresses with different header modifications. Exim does not
15853 do duplicate deliveries (except, in certain circumstances, to pipes -- see
15854 section 22.7), but it is undefined which of the duplicates is discarded, so
15855 this ambiguous situation should be avoided. The repeat_use option of the
15856 redirect router may be of help.
15857
15858 +--------------+------------+-----------+--------------+
15859 |headers_remove|Use: routers|Type: list*|Default: unset|
15860 +--------------+------------+-----------+--------------+
15861
15862 This option specifies a list of text headers, colon-separated, that is
15863 associated with any addresses that are accepted by the router. Each item is
15864 separately expanded, at routing time. However, this option has no effect when
15865 an address is just being verified. The way in which the text is used to remove
15866 header lines at transport time is described in section 46.17. Header lines are
15867 not actually removed until the message is in the process of being transported.
15868 This means that references to header lines in string expansions in the
15869 transport's configuration still "see" the original header lines.
15870
15871 The headers_remove option is expanded after errors_to and headers_add, but
15872 before transport. If an item expansion is forced to fail, the item has no
15873 effect. Other expansion failures are treated as configuration errors.
15874
15875 Unlike most options, headers_remove can be specified multiple times for a
15876 router; all listed headers are removed.
15877
15878 Warning 1: The headers_remove option cannot be used for a redirect router that
15879 has the one_time option set.
15880
15881 Warning 2: If the unseen option is set on the router, all header removal
15882 requests are deleted when the address is passed on to subsequent routers, and
15883 this can lead to problems with duplicates -- see the similar warning for
15884 headers_add above.
15885
15886 +-------------------+------------+----------------+--------------+
15887 |ignore_target_hosts|Use: routers|Type: host list*|Default: unset|
15888 +-------------------+------------+----------------+--------------+
15889
15890 Although this option is a host list, it should normally contain IP address
15891 entries rather than names. If any host that is looked up by the router has an
15892 IP address that matches an item in this list, Exim behaves as if that IP
15893 address did not exist. This option allows you to cope with rogue DNS entries
15894 like
15895
15896 remote.domain.example. A 127.0.0.1
15897
15898 by setting
15899
15900 ignore_target_hosts = 127.0.0.1
15901
15902 on the relevant router. If all the hosts found by a dnslookup router are
15903 discarded in this way, the router declines. In a conventional configuration, an
15904 attempt to mail to such a domain would normally provoke the "unrouteable
15905 domain" error, and an attempt to verify an address in the domain would fail.
15906 Similarly, if ignore_target_hosts is set on an ipliteral router, the router
15907 declines if presented with one of the listed addresses.
15908
15909 You can use this option to disable the use of IPv4 or IPv6 for mail delivery by
15910 means of the first or the second of the following settings, respectively:
15911
15912 ignore_target_hosts = 0.0.0.0/0
15913 ignore_target_hosts = <; 0::0/0
15914
15915 The pattern in the first line matches all IPv4 addresses, whereas the pattern
15916 in the second line matches all IPv6 addresses.
15917
15918 This option may also be useful for ignoring link-local and site-local IPv6
15919 addresses. Because, like all host lists, the value of ignore_target_hosts is
15920 expanded before use as a list, it is possible to make it dependent on the
15921 domain that is being routed.
15922
15923 During its expansion, $host_address is set to the IP address that is being
15924 checked.
15925
15926 +----------+------------+-------------+--------------+
15927 |initgroups|Use: routers|Type: boolean|Default: false|
15928 +----------+------------+-------------+--------------+
15929
15930 If the router queues an address for a transport, and this option is true, and
15931 the uid supplied by the router is not overridden by the transport, the
15932 initgroups() function is called when running the transport to ensure that any
15933 additional groups associated with the uid are set up. See also group and user
15934 and the discussion in chapter 23.
15935
15936 +-----------------+--------------+-----------------+--------------+
15937 |local_part_prefix|Use: routers**|Type: string list|Default: unset|
15938 +-----------------+--------------+-----------------+--------------+
15939
15940 If this option is set, the router is skipped unless the local part starts with
15941 one of the given strings, or local_part_prefix_optional is true. See section
15942 3.12 for a list of the order in which preconditions are evaluated.
15943
15944 The list is scanned from left to right, and the first prefix that matches is
15945 used. A limited form of wildcard is available; if the prefix begins with an
15946 asterisk, it matches the longest possible sequence of arbitrary characters at
15947 the start of the local part. An asterisk should therefore always be followed by
15948 some character that does not occur in normal local parts. Wildcarding can be
15949 used to set up multiple user mailboxes, as described in section 49.8.
15950
15951 During the testing of the local_parts option, and while the router is running,
15952 the prefix is removed from the local part, and is available in the expansion
15953 variable $local_part_prefix. When a message is being delivered, if the router
15954 accepts the address, this remains true during subsequent delivery by a
15955 transport. In particular, the local part that is transmitted in the RCPT
15956 command for LMTP, SMTP, and BSMTP deliveries has the prefix removed by default.
15957 This behaviour can be overridden by setting rcpt_include_affixes true on the
15958 relevant transport.
15959
15960 When an address is being verified, local_part_prefix affects only the behaviour
15961 of the router. If the callout feature of verification is in use, this means
15962 that the full address, including the prefix, will be used during the callout.
15963
15964 The prefix facility is commonly used to handle local parts of the form
15965 owner-something. Another common use is to support local parts of the form
15966 real-username to bypass a user's .forward file - helpful when trying to tell a
15967 user their forwarding is broken - by placing a router like this one immediately
15968 before the router that handles .forward files:
15969
15970 real_localuser:
15971 driver = accept
15972 local_part_prefix = real-
15973 check_local_user
15974 transport = local_delivery
15975
15976 For security, it would probably be a good idea to restrict the use of this
15977 router to locally-generated messages, using a condition such as this:
15978
15979 condition = ${if match {$sender_host_address}\
15980 {\N^(|127\.0\.0\.1)$\N}}
15981
15982 If both local_part_prefix and local_part_suffix are set for a router, both
15983 conditions must be met if not optional. Care must be taken if wildcards are
15984 used in both a prefix and a suffix on the same router. Different separator
15985 characters must be used to avoid ambiguity.
15986
15987 +--------------------------+------------+-------------+--------------+
15988 |local_part_prefix_optional|Use: routers|Type: boolean|Default: false|
15989 +--------------------------+------------+-------------+--------------+
15990
15991 See local_part_prefix above.
15992
15993 +-----------------+--------------+-----------------+--------------+
15994 |local_part_suffix|Use: routers**|Type: string list|Default: unset|
15995 +-----------------+--------------+-----------------+--------------+
15996
15997 This option operates in the same way as local_part_prefix, except that the
15998 local part must end (rather than start) with the given string, the
15999 local_part_suffix_optional option determines whether the suffix is mandatory,
16000 and the wildcard * character, if present, must be the last character of the
16001 suffix. This option facility is commonly used to handle local parts of the form
16002 something-request and multiple user mailboxes of the form username-foo.
16003
16004 +--------------------------+------------+-------------+--------------+
16005 |local_part_suffix_optional|Use: routers|Type: boolean|Default: false|
16006 +--------------------------+------------+-------------+--------------+
16007
16008 See local_part_suffix above.
16009
16010 +-----------+--------------+----------------------+--------------+
16011 |local_parts|Use: routers**|Type: local part list*|Default: unset|
16012 +-----------+--------------+----------------------+--------------+
16013
16014 The router is run only if the local part of the address matches the list. See
16015 section 3.12 for a list of the order in which preconditions are evaluated, and
16016 section 10.21 for a discussion of local part lists. Because the string is
16017 expanded, it is possible to make it depend on the domain, for example:
16018
16019 local_parts = dbm;/usr/local/specials/$domain
16020
16021 If the match is achieved by a lookup, the data that the lookup returned for the
16022 local part is placed in the variable $local_part_data for use in expansions of
16023 the router's private options. You might use this option, for example, if you
16024 have a large number of local virtual domains, and you want to send all
16025 postmaster mail to the same place without having to set up an alias in each
16026 virtual domain:
16027
16028 postmaster:
16029 driver = redirect
16030 local_parts = postmaster
16031 data = postmaster@real.domain.example
16032
16033 +------------+------------+-------------+------------------+
16034 |log_as_local|Use: routers|Type: boolean|Default: see below|
16035 +------------+------------+-------------+------------------+
16036
16037 Exim has two logging styles for delivery, the idea being to make local
16038 deliveries stand out more visibly from remote ones. In the "local" style, the
16039 recipient address is given just as the local part, without a domain. The use of
16040 this style is controlled by this option. It defaults to true for the accept
16041 router, and false for all the others. This option applies only when a router
16042 assigns an address to a transport. It has no effect on routers that redirect
16043 addresses.
16044
16045 +----+------------+--------------+-------------+
16046 |more|Use: routers|Type: boolean*|Default: true|
16047 +----+------------+--------------+-------------+
16048
16049 The result of string expansion for this option must be a valid boolean value,
16050 that is, one of the strings "yes", "no", "true", or "false". Any other result
16051 causes an error, and delivery is deferred. If the expansion is forced to fail,
16052 the default value for the option (true) is used. Other failures cause delivery
16053 to be deferred.
16054
16055 If this option is set false, and the router declines to handle the address, no
16056 further routers are tried, routing fails, and the address is bounced. However,
16057 if the router explicitly passes an address to the following router by means of
16058 the setting
16059
16060 self = pass
16061
16062 or otherwise, the setting of more is ignored. Also, the setting of more does
16063 not affect the behaviour if one of the precondition tests fails. In that case,
16064 the address is always passed to the next router.
16065
16066 Note that address_data is not considered to be a precondition. If its expansion
16067 is forced to fail, the router declines, and the value of more controls what
16068 happens next.
16069
16070 +---------------+------------+-------------+--------------+
16071 |pass_on_timeout|Use: routers|Type: boolean|Default: false|
16072 +---------------+------------+-------------+--------------+
16073
16074 If a router times out during a host lookup, it normally causes deferral of the
16075 address. If pass_on_timeout is set, the address is passed on to the next
16076 router, overriding no_more. This may be helpful for systems that are
16077 intermittently connected to the Internet, or those that want to pass to a smart
16078 host any messages that cannot immediately be delivered.
16079
16080 There are occasional other temporary errors that can occur while doing DNS
16081 lookups. They are treated in the same way as a timeout, and this option applies
16082 to all of them.
16083
16084 +-----------+------------+------------+--------------+
16085 |pass_router|Use: routers|Type: string|Default: unset|
16086 +-----------+------------+------------+--------------+
16087
16088 Routers that recognize the generic self option (dnslookup, ipliteral, and
16089 manualroute) are able to return "pass", forcing routing to continue, and
16090 overriding a false setting of more. When one of these routers returns "pass",
16091 the address is normally handed on to the next router in sequence. This can be
16092 changed by setting pass_router to the name of another router. However (unlike
16093 redirect_router) the named router must be below the current router, to avoid
16094 loops. Note that this option applies only to the special case of "pass". It
16095 does not apply when a router returns "decline" because it cannot handle an
16096 address.
16097
16098 +---------------+------------+------------+--------------+
16099 |redirect_router|Use: routers|Type: string|Default: unset|
16100 +---------------+------------+------------+--------------+
16101
16102 Sometimes an administrator knows that it is pointless to reprocess addresses
16103 generated from alias or forward files with the same router again. For example,
16104 if an alias file translates real names into login ids there is no point
16105 searching the alias file a second time, especially if it is a large file.
16106
16107 The redirect_router option can be set to the name of any router instance. It
16108 causes the routing of any generated addresses to start at the named router
16109 instead of at the first router. This option has no effect if the router in
16110 which it is set does not generate new addresses.
16111
16112 +-------------+--------------+------------------+--------------+
16113 |require_files|Use: routers**|Type: string list*|Default: unset|
16114 +-------------+--------------+------------------+--------------+
16115
16116 This option provides a general mechanism for predicating the running of a
16117 router on the existence or non-existence of certain files or directories.
16118 Before running a router, as one of its precondition tests, Exim works its way
16119 through the require_files list, expanding each item separately.
16120
16121 Because the list is split before expansion, any colons in expansion items must
16122 be doubled, or the facility for using a different list separator must be used.
16123 If any expansion is forced to fail, the item is ignored. Other expansion
16124 failures cause routing of the address to be deferred.
16125
16126 If any expanded string is empty, it is ignored. Otherwise, except as described
16127 below, each string must be a fully qualified file path, optionally preceded by
16128 "!". The paths are passed to the stat() function to test for the existence of
16129 the files or directories. The router is skipped if any paths not preceded by "!
16130 " do not exist, or if any paths preceded by "!" do exist.
16131
16132 If stat() cannot determine whether a file exists or not, delivery of the
16133 message is deferred. This can happen when NFS-mounted filesystems are
16134 unavailable.
16135
16136 This option is checked after the domains, local_parts, and senders options, so
16137 you cannot use it to check for the existence of a file in which to look up a
16138 domain, local part, or sender. (See section 3.12 for a full list of the order
16139 in which preconditions are evaluated.) However, as these options are all
16140 expanded, you can use the exists expansion condition to make such tests. The
16141 require_files option is intended for checking files that the router may be
16142 going to use internally, or which are needed by a transport (for example
16143 .procmailrc).
16144
16145 During delivery, the stat() function is run as root, but there is a facility
16146 for some checking of the accessibility of a file by another user. This is not a
16147 proper permissions check, but just a "rough" check that operates as follows:
16148
16149 If an item in a require_files list does not contain any forward slash
16150 characters, it is taken to be the user (and optional group, separated by a
16151 comma) to be checked for subsequent files in the list. If no group is specified
16152 but the user is specified symbolically, the gid associated with the uid is
16153 used. For example:
16154
16155 require_files = mail:/some/file
16156 require_files = $local_part:$home/.procmailrc
16157
16158 If a user or group name in a require_files list does not exist, the
16159 require_files condition fails.
16160
16161 Exim performs the check by scanning along the components of the file path, and
16162 checking the access for the given uid and gid. It checks for "x" access on
16163 directories, and "r" access on the final file. Note that this means that file
16164 access control lists, if the operating system has them, are ignored.
16165
16166 Warning 1: When the router is being run to verify addresses for an incoming
16167 SMTP message, Exim is not running as root, but under its own uid. This may
16168 affect the result of a require_files check. In particular, stat() may yield the
16169 error EACCES ("Permission denied"). This means that the Exim user is not
16170 permitted to read one of the directories on the file's path.
16171
16172 Warning 2: Even when Exim is running as root while delivering a message, stat()
16173 can yield EACCES for a file in an NFS directory that is mounted without root
16174 access. In this case, if a check for access by a particular user is requested,
16175 Exim creates a subprocess that runs as that user, and tries the check again in
16176 that process.
16177
16178 The default action for handling an unresolved EACCES is to consider it to be
16179 caused by a configuration error, and routing is deferred because the existence
16180 or non-existence of the file cannot be determined. However, in some
16181 circumstances it may be desirable to treat this condition as if the file did
16182 not exist. If the file name (or the exclamation mark that precedes the file
16183 name for non-existence) is preceded by a plus sign, the EACCES error is treated
16184 as if the file did not exist. For example:
16185
16186 require_files = +/some/file
16187
16188 If the router is not an essential part of verification (for example, it handles
16189 users' .forward files), another solution is to set the verify option false so
16190 that the router is skipped when verifying.
16191
16192 +--------------------+------------+-------------+------------------+
16193 |retry_use_local_part|Use: routers|Type: boolean|Default: see below|
16194 +--------------------+------------+-------------+------------------+
16195
16196 When a delivery suffers a temporary routing failure, a retry record is created
16197 in Exim's hints database. For addresses whose routing depends only on the
16198 domain, the key for the retry record should not involve the local part, but for
16199 other addresses, both the domain and the local part should be included.
16200 Usually, remote routing is of the former kind, and local routing is of the
16201 latter kind.
16202
16203 This option controls whether the local part is used to form the key for retry
16204 hints for addresses that suffer temporary errors while being handled by this
16205 router. The default value is true for any router that has check_local_user set,
16206 and false otherwise. Note that this option does not apply to hints keys for
16207 transport delays; they are controlled by a generic transport option of the same
16208 name.
16209
16210 The setting of retry_use_local_part applies only to the router on which it
16211 appears. If the router generates child addresses, they are routed
16212 independently; this setting does not become attached to them.
16213
16214 +---------------------+------------+-------------+--------------+
16215 |router_home_directory|Use: routers|Type: string*|Default: unset|
16216 +---------------------+------------+-------------+--------------+
16217
16218 This option sets a home directory for use while the router is running. (Compare
16219 transport_home_directory, which sets a home directory for later transporting.)
16220 In particular, if used on a redirect router, this option sets a value for $home
16221 while a filter is running. The value is expanded; forced expansion failure
16222 causes the option to be ignored - other failures cause the router to defer.
16223
16224 Expansion of router_home_directory happens immediately after the
16225 check_local_user test (if configured), before any further expansions take
16226 place. (See section 3.12 for a list of the order in which preconditions are
16227 evaluated.) While the router is running, router_home_directory overrides the
16228 value of $home that came from check_local_user.
16229
16230 When a router accepts an address and assigns it to a local transport (including
16231 the cases when a redirect router generates a pipe, file, or autoreply
16232 delivery), the home directory setting for the transport is taken from the first
16233 of these values that is set:
16234
16235 * The home_directory option on the transport;
16236
16237 * The transport_home_directory option on the router;
16238
16239 * The password data if check_local_user is set on the router;
16240
16241 * The router_home_directory option on the router.
16242
16243 In other words, router_home_directory overrides the password data for the
16244 router, but not for the transport.
16245
16246 +----+------------+------------+---------------+
16247 |self|Use: routers|Type: string|Default: freeze|
16248 +----+------------+------------+---------------+
16249
16250 This option applies to those routers that use a recipient address to find a
16251 list of remote hosts. Currently, these are the dnslookup, ipliteral, and
16252 manualroute routers. Certain configurations of the queryprogram router can also
16253 specify a list of remote hosts. Usually such routers are configured to send the
16254 message to a remote host via an smtp transport. The self option specifies what
16255 happens when the first host on the list turns out to be the local host. The way
16256 in which Exim checks for the local host is described in section 13.8.
16257
16258 Normally this situation indicates either an error in Exim's configuration (for
16259 example, the router should be configured not to process this domain), or an
16260 error in the DNS (for example, the MX should not point to this host). For this
16261 reason, the default action is to log the incident, defer the address, and
16262 freeze the message. The following alternatives are provided for use in special
16263 cases:
16264
16265 defer
16266
16267 Delivery of the message is tried again later, but the message is not
16268 frozen.
16269
16270 reroute: <domain>
16271
16272 The domain is changed to the given domain, and the address is passed back
16273 to be reprocessed by the routers. No rewriting of headers takes place. This
16274 behaviour is essentially a redirection.
16275
16276 reroute: rewrite: <domain>
16277
16278 The domain is changed to the given domain, and the address is passed back
16279 to be reprocessed by the routers. Any headers that contain the original
16280 domain are rewritten.
16281
16282 pass
16283
16284 The router passes the address to the next router, or to the router named in
16285 the pass_router option if it is set. This overrides no_more. During
16286 subsequent routing and delivery, the variable $self_hostname contains the
16287 name of the local host that the router encountered. This can be used to
16288 distinguish between different cases for hosts with multiple names. The
16289 combination
16290
16291 self = pass
16292 no_more
16293
16294 ensures that only those addresses that routed to the local host are passed
16295 on. Without no_more, addresses that were declined for other reasons would
16296 also be passed to the next router.
16297
16298 fail
16299
16300 Delivery fails and an error report is generated.
16301
16302 send
16303
16304 The anomaly is ignored and the address is queued for the transport. This
16305 setting should be used with extreme caution. For an smtp transport, it
16306 makes sense only in cases where the program that is listening on the SMTP
16307 port is not this version of Exim. That is, it must be some other MTA, or
16308 Exim with a different configuration file that handles the domain in another
16309 way.
16310
16311 +-------+--------------+-------------------+--------------+
16312 |senders|Use: routers**|Type: address list*|Default: unset|
16313 +-------+--------------+-------------------+--------------+
16314
16315 If this option is set, the router is skipped unless the message's sender
16316 address matches something on the list. See section 3.12 for a list of the order
16317 in which preconditions are evaluated.
16318
16319 There are issues concerning verification when the running of routers is
16320 dependent on the sender. When Exim is verifying the address in an errors_to
16321 setting, it sets the sender to the null string. When using the -bt option to
16322 check a configuration file, it is necessary also to use the -f option to set an
16323 appropriate sender. For incoming mail, the sender is unset when verifying the
16324 sender, but is available when verifying any recipients. If the SMTP VRFY
16325 command is enabled, it must be used after MAIL if the sender address matters.
16326
16327 +--------------------+------------+-------------+--------------+
16328 |translate_ip_address|Use: routers|Type: string*|Default: unset|
16329 +--------------------+------------+-------------+--------------+
16330
16331 There exist some rare networking situations (for example, packet radio) where
16332 it is helpful to be able to translate IP addresses generated by normal routing
16333 mechanisms into other IP addresses, thus performing a kind of manual IP
16334 routing. This should be done only if the normal IP routing of the TCP/IP stack
16335 is inadequate or broken. Because this is an extremely uncommon requirement, the
16336 code to support this option is not included in the Exim binary unless
16337 SUPPORT_TRANSLATE_IP_ADDRESS=yes is set in Local/Makefile.
16338
16339 The translate_ip_address string is expanded for every IP address generated by
16340 the router, with the generated address set in $host_address. If the expansion
16341 is forced to fail, no action is taken. For any other expansion error, delivery
16342 of the message is deferred. If the result of the expansion is an IP address,
16343 that replaces the original address; otherwise the result is assumed to be a
16344 host name - this is looked up using gethostbyname() (or getipnodebyname() when
16345 available) to produce one or more replacement IP addresses. For example, to
16346 subvert all IP addresses in some specific networks, this could be added to a
16347 router:
16348
16349 translate_ip_address = \
16350 ${lookup{${mask:$host_address/26}}lsearch{/some/file}\
16351 {$value}fail}}
16352
16353 The file would contain lines like
16354
16355 10.2.3.128/26 some.host
16356 10.8.4.34/26 10.44.8.15
16357
16358 You should not make use of this facility unless you really understand what you
16359 are doing.
16360
16361 +---------+------------+-------------+--------------+
16362 |transport|Use: routers|Type: string*|Default: unset|
16363 +---------+------------+-------------+--------------+
16364
16365 This option specifies the transport to be used when a router accepts an address
16366 and sets it up for delivery. A transport is never needed if a router is used
16367 only for verification. The value of the option is expanded at routing time,
16368 after the expansion of errors_to, headers_add, and headers_remove, and result
16369 must be the name of one of the configured transports. If it is not, delivery is
16370 deferred.
16371
16372 The transport option is not used by the redirect router, but it does have some
16373 private options that set up transports for pipe and file deliveries (see
16374 chapter 22).
16375
16376 +---------------------------+------------+-------------+--------------+
16377 |transport_current_directory|Use: routers|Type: string*|Default: unset|
16378 +---------------------------+------------+-------------+--------------+
16379
16380 This option associates a current directory with any address that is routed to a
16381 local transport. This can happen either because a transport is explicitly
16382 configured for the router, or because it generates a delivery to a file or a
16383 pipe. During the delivery process (that is, at transport time), this option
16384 string is expanded and is set as the current directory, unless overridden by a
16385 setting on the transport. If the expansion fails for any reason, including
16386 forced failure, an error is logged, and delivery is deferred. See chapter 23
16387 for details of the local delivery environment.
16388
16389 +------------------------+------------+-------------+------------------+
16390 |transport_home_directory|Use: routers|Type: string*|Default: see below|
16391 +------------------------+------------+-------------+------------------+
16392
16393 This option associates a home directory with any address that is routed to a
16394 local transport. This can happen either because a transport is explicitly
16395 configured for the router, or because it generates a delivery to a file or a
16396 pipe. During the delivery process (that is, at transport time), the option
16397 string is expanded and is set as the home directory, unless overridden by a
16398 setting of home_directory on the transport. If the expansion fails for any
16399 reason, including forced failure, an error is logged, and delivery is deferred.
16400
16401 If the transport does not specify a home directory, and
16402 transport_home_directory is not set for the router, the home directory for the
16403 transport is taken from the password data if check_local_user is set for the
16404 router. Otherwise it is taken from router_home_directory if that option is set;
16405 if not, no home directory is set for the transport.
16406
16407 See chapter 23 for further details of the local delivery environment.
16408
16409 +------+------------+--------------+--------------+
16410 |unseen|Use: routers|Type: boolean*|Default: false|
16411 +------+------------+--------------+--------------+
16412
16413 The result of string expansion for this option must be a valid boolean value,
16414 that is, one of the strings "yes", "no", "true", or "false". Any other result
16415 causes an error, and delivery is deferred. If the expansion is forced to fail,
16416 the default value for the option (false) is used. Other failures cause delivery
16417 to be deferred.
16418
16419 When this option is set true, routing does not cease if the router accepts the
16420 address. Instead, a copy of the incoming address is passed to the next router,
16421 overriding a false setting of more. There is little point in setting more false
16422 if unseen is always true, but it may be useful in cases when the value of
16423 unseen contains expansion items (and therefore, presumably, is sometimes true
16424 and sometimes false).
16425
16426 Setting the unseen option has a similar effect to the unseen command qualifier
16427 in filter files. It can be used to cause copies of messages to be delivered to
16428 some other destination, while also carrying out a normal delivery. In effect,
16429 the current address is made into a "parent" that has two children - one that is
16430 delivered as specified by this router, and a clone that goes on to be routed
16431 further. For this reason, unseen may not be combined with the one_time option
16432 in a redirect router.
16433
16434 Warning: Header lines added to the address (or specified for removal) by this
16435 router or by previous routers affect the "unseen" copy of the message only. The
16436 clone that continues to be processed by further routers starts with no added
16437 headers and none specified for removal. For a redirect router, if a generated
16438 address is the same as the incoming address, this can lead to duplicate
16439 addresses with different header modifications. Exim does not do duplicate
16440 deliveries (except, in certain circumstances, to pipes -- see section 22.7),
16441 but it is undefined which of the duplicates is discarded, so this ambiguous
16442 situation should be avoided. The repeat_use option of the redirect router may
16443 be of help.
16444
16445 Unlike the handling of header modifications, any data that was set by the
16446 address_data option in the current or previous routers is passed on to
16447 subsequent routers.
16448
16449 +----+------------+-------------+------------------+
16450 |user|Use: routers|Type: string*|Default: see below|
16451 +----+------------+-------------+------------------+
16452
16453 When a router queues an address for a transport, and the transport does not
16454 specify a user, the user given here is used when running the delivery process.
16455 The user may be specified numerically or by name. If expansion fails, the error
16456 is logged and delivery is deferred. This user is also used by the redirect
16457 router when running a filter file. The default is unset, except when
16458 check_local_user is set. In this case, the default is taken from the password
16459 information. If the user is specified as a name, and group is not set, the
16460 group associated with the user is used. See also initgroups and group and the
16461 discussion in chapter 23.
16462
16463 +------+--------------+-------------+-------------+
16464 |verify|Use: routers**|Type: boolean|Default: true|
16465 +------+--------------+-------------+-------------+
16466
16467 Setting this option has the effect of setting verify_sender and
16468 verify_recipient to the same value.
16469
16470 +-----------+--------------+-------------+--------------+
16471 |verify_only|Use: routers**|Type: boolean|Default: false|
16472 +-----------+--------------+-------------+--------------+
16473
16474 If this option is set, the router is used only when verifying an address,
16475 delivering in cutthrough mode or testing with the -bv option, not when actually
16476 doing a delivery, testing with the -bt option, or running the SMTP EXPN
16477 command. It can be further restricted to verifying only senders or recipients
16478 by means of verify_sender and verify_recipient.
16479
16480 Warning: When the router is being run to verify addresses for an incoming SMTP
16481 message, Exim is not running as root, but under its own uid. If the router
16482 accesses any files, you need to make sure that they are accessible to the Exim
16483 user or group.
16484
16485 +----------------+--------------+-------------+-------------+
16486 |verify_recipient|Use: routers**|Type: boolean|Default: true|
16487 +----------------+--------------+-------------+-------------+
16488
16489 If this option is false, the router is skipped when verifying recipient
16490 addresses, delivering in cutthrough mode or testing recipient verification
16491 using -bv. See section 3.12 for a list of the order in which preconditions are
16492 evaluated.
16493
16494 +-------------+--------------+-------------+-------------+
16495 |verify_sender|Use: routers**|Type: boolean|Default: true|
16496 +-------------+--------------+-------------+-------------+
16497
16498 If this option is false, the router is skipped when verifying sender addresses
16499 or testing sender verification using -bvs. See section 3.12 for a list of the
16500 order in which preconditions are evaluated.
16501
16502
16503
16504 ===============================================================================
16505 16. THE ACCEPT ROUTER
16506
16507 The accept router has no private options of its own. Unless it is being used
16508 purely for verification (see verify_only) a transport is required to be defined
16509 by the generic transport option. If the preconditions that are specified by
16510 generic options are met, the router accepts the address and queues it for the
16511 given transport. The most common use of this router is for setting up
16512 deliveries to local mailboxes. For example:
16513
16514 localusers:
16515 driver = accept
16516 domains = mydomain.example
16517 check_local_user
16518 transport = local_delivery
16519
16520 The domains condition in this example checks the domain of the address, and
16521 check_local_user checks that the local part is the login of a local user. When
16522 both preconditions are met, the accept router runs, and queues the address for
16523 the local_delivery transport.
16524
16525
16526
16527 ===============================================================================
16528 17. THE DNSLOOKUP ROUTER
16529
16530 The dnslookup router looks up the hosts that handle mail for the recipient's
16531 domain in the DNS. A transport must always be set for this router, unless
16532 verify_only is set.
16533
16534 If SRV support is configured (see check_srv below), Exim first searches for SRV
16535 records. If none are found, or if SRV support is not configured, MX records are
16536 looked up. If no MX records exist, address records are sought. However,
16537 mx_domains can be set to disable the direct use of address records.
16538
16539 MX records of equal priority are sorted by Exim into a random order. Exim then
16540 looks for address records for the host names obtained from MX or SRV records.
16541 When a host has more than one IP address, they are sorted into a random order,
16542 except that IPv6 addresses are always sorted before IPv4 addresses. If all the
16543 IP addresses found are discarded by a setting of the ignore_target_hosts
16544 generic option, the router declines.
16545
16546 Unless they have the highest priority (lowest MX value), MX records that point
16547 to the local host, or to any host name that matches hosts_treat_as_local, are
16548 discarded, together with any other MX records of equal or lower priority.
16549
16550 If the host pointed to by the highest priority MX record, or looked up as an
16551 address record, is the local host, or matches hosts_treat_as_local, what
16552 happens is controlled by the generic self option.
16553
16554
16555 17.1 Problems with DNS lookups
16556 ------------------------------
16557
16558 There have been problems with DNS servers when SRV records are looked up. Some
16559 mis-behaving servers return a DNS error or timeout when a non-existent SRV
16560 record is sought. Similar problems have in the past been reported for MX
16561 records. The global dns_again_means_nonexist option can help with this problem,
16562 but it is heavy-handed because it is a global option.
16563
16564 For this reason, there are two options, srv_fail_domains and mx_fail_domains,
16565 that control what happens when a DNS lookup in a dnslookup router results in a
16566 DNS failure or a "try again" response. If an attempt to look up an SRV or MX
16567 record causes one of these results, and the domain matches the relevant list,
16568 Exim behaves as if the DNS had responded "no such record". In the case of an
16569 SRV lookup, this means that the router proceeds to look for MX records; in the
16570 case of an MX lookup, it proceeds to look for A or AAAA records, unless the
16571 domain matches mx_domains, in which case routing fails.
16572
16573
16574 17.2 Declining addresses by dnslookup
16575 -------------------------------------
16576
16577 There are a few cases where a dnslookup router will decline to accept an
16578 address; if such a router is expected to handle "all remaining non-local
16579 domains", then it is important to set no_more.
16580
16581 Reasons for a dnslookup router to decline currently include:
16582
16583 * The domain does not exist in DNS
16584
16585 * The domain exists but the MX record's host part is just "."; this is a
16586 common convention (borrowed from SRV) used to indicate that there is no
16587 such service for this domain and to not fall back to trying A/AAAA records.
16588
16589 * Ditto, but for SRV records, when check_srv is set on this router.
16590
16591 * MX record points to a non-existent host.
16592
16593 * MX record points to an IP address and the main section option
16594 allow_mx_to_ip is not set.
16595
16596 * MX records exist and point to valid hosts, but all hosts resolve only to
16597 addresses blocked by the ignore_target_hosts generic option on this router.
16598
16599 * The domain is not syntactically valid (see also allow_utf8_domains and
16600 dns_check_names_pattern for handling one variant of this)
16601
16602 * check_secondary_mx is set on this router but the local host can not be
16603 found in the MX records (see below)
16604
16605
16606 17.3 Private options for dnslookup
16607 ----------------------------------
16608
16609 The private options for the dnslookup router are as follows:
16610
16611 +------------------+--------------+-------------+--------------+
16612 |check_secondary_mx|Use: dnslookup|Type: boolean|Default: false|
16613 +------------------+--------------+-------------+--------------+
16614
16615 If this option is set, the router declines unless the local host is found in
16616 (and removed from) the list of hosts obtained by MX lookup. This can be used to
16617 process domains for which the local host is a secondary mail exchanger
16618 differently to other domains. The way in which Exim decides whether a host is
16619 the local host is described in section 13.8.
16620
16621 +---------+--------------+-------------+--------------+
16622 |check_srv|Use: dnslookup|Type: string*|Default: unset|
16623 +---------+--------------+-------------+--------------+
16624
16625 The dnslookup router supports the use of SRV records (see RFC 2782) in addition
16626 to MX and address records. The support is disabled by default. To enable SRV
16627 support, set the check_srv option to the name of the service required. For
16628 example,
16629
16630 check_srv = smtp
16631
16632 looks for SRV records that refer to the normal smtp service. The option is
16633 expanded, so the service name can vary from message to message or address to
16634 address. This might be helpful if SRV records are being used for a submission
16635 service. If the expansion is forced to fail, the check_srv option is ignored,
16636 and the router proceeds to look for MX records in the normal way.
16637
16638 When the expansion succeeds, the router searches first for SRV records for the
16639 given service (it assumes TCP protocol). A single SRV record with a host name
16640 that consists of just a single dot indicates "no such service for this domain";
16641 if this is encountered, the router declines. If other kinds of SRV record are
16642 found, they are used to construct a host list for delivery according to the
16643 rules of RFC 2782. MX records are not sought in this case.
16644
16645 When no SRV records are found, MX records (and address records) are sought in
16646 the traditional way. In other words, SRV records take precedence over MX
16647 records, just as MX records take precedence over address records. Note that
16648 this behaviour is not sanctioned by RFC 2782, though a previous draft RFC
16649 defined it. It is apparently believed that MX records are sufficient for email
16650 and that SRV records should not be used for this purpose. However, SRV records
16651 have an additional "weight" feature which some people might find useful when
16652 trying to split an SMTP load between hosts of different power.
16653
16654 See section 17.1 above for a discussion of Exim's behaviour when there is a DNS
16655 lookup error.
16656
16657 +----------------------+--------------+------------------+--------------+
16658 |dnssec_request_domains|Use: dnslookup|Type: domain list*|Default: unset|
16659 +----------------------+--------------+------------------+--------------+
16660
16661 DNS lookups for domains matching dnssec_request_domains will be done with the
16662 dnssec request bit set. This applies to all of the SRV, MX A6, AAAA, A lookup
16663 sequence.
16664
16665 +----------------------+--------------+------------------+--------------+
16666 |dnssec_require_domains|Use: dnslookup|Type: domain list*|Default: unset|
16667 +----------------------+--------------+------------------+--------------+
16668
16669 DNS lookups for domains matching dnssec_request_domains will be done with the
16670 dnssec request bit set. Any returns not having the Authenticated Data bit (AD
16671 bit) set wil be ignored and logged as a host-lookup failure. This applies to
16672 all of the SRV, MX A6, AAAA, A lookup sequence.
16673
16674 +----------+--------------+------------------+--------------+
16675 |mx_domains|Use: dnslookup|Type: domain list*|Default: unset|
16676 +----------+--------------+------------------+--------------+
16677
16678 A domain that matches mx_domains is required to have either an MX or an SRV
16679 record in order to be recognized. (The name of this option could be improved.)
16680 For example, if all the mail hosts in fict.example are known to have MX
16681 records, except for those in discworld.fict.example, you could use this
16682 setting:
16683
16684 mx_domains = ! *.discworld.fict.example : *.fict.example
16685
16686 This specifies that messages addressed to a domain that matches the list but
16687 has no MX record should be bounced immediately instead of being routed using
16688 the address record.
16689
16690 +---------------+--------------+------------------+--------------+
16691 |mx_fail_domains|Use: dnslookup|Type: domain list*|Default: unset|
16692 +---------------+--------------+------------------+--------------+
16693
16694 If the DNS lookup for MX records for one of the domains in this list causes a
16695 DNS lookup error, Exim behaves as if no MX records were found. See section 17.1
16696 for more discussion.
16697
16698 +--------------+--------------+-------------+-------------+
16699 |qualify_single|Use: dnslookup|Type: boolean|Default: true|
16700 +--------------+--------------+-------------+-------------+
16701
16702 When this option is true, the resolver option RES_DEFNAMES is set for DNS
16703 lookups. Typically, but not standardly, this causes the resolver to qualify
16704 single-component names with the default domain. For example, on a machine
16705 called dictionary.ref.example, the domain thesaurus would be changed to
16706 thesaurus.ref.example inside the resolver. For details of what your resolver
16707 actually does, consult your man pages for resolver and resolv.conf.
16708
16709 +---------------+--------------+-------------+-------------+
16710 |rewrite_headers|Use: dnslookup|Type: boolean|Default: true|
16711 +---------------+--------------+-------------+-------------+
16712
16713 If the domain name in the address that is being processed is not fully
16714 qualified, it may be expanded to its full form by a DNS lookup. For example, if
16715 an address is specified as dormouse@teaparty, the domain might be expanded to
16716 teaparty.wonderland.fict.example. Domain expansion can also occur as a result
16717 of setting the widen_domains option. If rewrite_headers is true, all
16718 occurrences of the abbreviated domain name in any Bcc:, Cc:, From:, Reply-to:,
16719 Sender:, and To: header lines of the message are rewritten with the full domain
16720 name.
16721
16722 This option should be turned off only when it is known that no message is ever
16723 going to be sent outside an environment where the abbreviation makes sense.
16724
16725 When an MX record is looked up in the DNS and matches a wildcard record, name
16726 servers normally return a record containing the name that has been looked up,
16727 making it impossible to detect whether a wildcard was present or not. However,
16728 some name servers have recently been seen to return the wildcard entry. If the
16729 name returned by a DNS lookup begins with an asterisk, it is not used for
16730 header rewriting.
16731
16732 +------------------------+--------------+-------------+--------------+
16733 |same_domain_copy_routing|Use: dnslookup|Type: boolean|Default: false|
16734 +------------------------+--------------+-------------+--------------+
16735
16736 Addresses with the same domain are normally routed by the dnslookup router to
16737 the same list of hosts. However, this cannot be presumed, because the router
16738 options and preconditions may refer to the local part of the address. By
16739 default, therefore, Exim routes each address in a message independently. DNS
16740 servers run caches, so repeated DNS lookups are not normally expensive, and in
16741 any case, personal messages rarely have more than a few recipients.
16742
16743 If you are running mailing lists with large numbers of subscribers at the same
16744 domain, and you are using a dnslookup router which is independent of the local
16745 part, you can set same_domain_copy_routing to bypass repeated DNS lookups for
16746 identical domains in one message. In this case, when dnslookup routes an
16747 address to a remote transport, any other unrouted addresses in the message that
16748 have the same domain are automatically given the same routing without
16749 processing them independently, provided the following conditions are met:
16750
16751 * No router that processed the address specified headers_add or
16752 headers_remove.
16753
16754 * The router did not change the address in any way, for example, by
16755 "widening" the domain.
16756
16757 +--------------+--------------+-------------+--------------+
16758 |search_parents|Use: dnslookup|Type: boolean|Default: false|
16759 +--------------+--------------+-------------+--------------+
16760
16761 When this option is true, the resolver option RES_DNSRCH is set for DNS
16762 lookups. This is different from the qualify_single option in that it applies to
16763 domains containing dots. Typically, but not standardly, it causes the resolver
16764 to search for the name in the current domain and in parent domains. For
16765 example, on a machine in the fict.example domain, if looking up
16766 teaparty.wonderland failed, the resolver would try
16767 teaparty.wonderland.fict.example. For details of what your resolver actually
16768 does, consult your man pages for resolver and resolv.conf.
16769
16770 Setting this option true can cause problems in domains that have a wildcard MX
16771 record, because any domain that does not have its own MX record matches the
16772 local wildcard.
16773
16774 +----------------+--------------+------------------+--------------+
16775 |srv_fail_domains|Use: dnslookup|Type: domain list*|Default: unset|
16776 +----------------+--------------+------------------+--------------+
16777
16778 If the DNS lookup for SRV records for one of the domains in this list causes a
16779 DNS lookup error, Exim behaves as if no SRV records were found. See section
16780 17.1 for more discussion.
16781
16782 +-------------+--------------+-----------------+--------------+
16783 |widen_domains|Use: dnslookup|Type: string list|Default: unset|
16784 +-------------+--------------+-----------------+--------------+
16785
16786 If a DNS lookup fails and this option is set, each of its strings in turn is
16787 added onto the end of the domain, and the lookup is tried again. For example,
16788 if
16789
16790 widen_domains = fict.example:ref.example
16791
16792 is set and a lookup of klingon.dictionary fails,
16793 klingon.dictionary.fict.example is looked up, and if this fails,
16794 klingon.dictionary.ref.example is tried. Note that the qualify_single and
16795 search_parents options can cause some widening to be undertaken inside the DNS
16796 resolver. widen_domains is not applied to sender addresses when verifying,
16797 unless rewrite_headers is false (not the default).
16798
16799
16800 17.4 Effect of qualify_single and search_parents
16801 ------------------------------------------------
16802
16803 When a domain from an envelope recipient is changed by the resolver as a result
16804 of the qualify_single or search_parents options, Exim rewrites the
16805 corresponding address in the message's header lines unless rewrite_headers is
16806 set false. Exim then re-routes the address, using the full domain.
16807
16808 These two options affect only the DNS lookup that takes place inside the router
16809 for the domain of the address that is being routed. They do not affect lookups
16810 such as that implied by
16811
16812 domains = @mx_any
16813
16814 that may happen while processing a router precondition before the router is
16815 entered. No widening ever takes place for these lookups.
16816
16817
16818
16819 ===============================================================================
16820 18. THE IPLITERAL ROUTER
16821
16822 This router has no private options. Unless it is being used purely for
16823 verification (see verify_only) a transport is required to be defined by the
16824 generic transport option. The router accepts the address if its domain part
16825 takes the form of an RFC 2822 domain literal. For example, the ipliteral router
16826 handles the address
16827
16828 root@[192.168.1.1]
16829
16830 by setting up delivery to the host with that IP address. IPv4 domain literals
16831 consist of an IPv4 address enclosed in square brackets. IPv6 domain literals
16832 are similar, but the address is preceded by "ipv6:". For example:
16833
16834 postmaster@[ipv6:fe80::a00:20ff:fe86:a061.5678]
16835
16836 Exim allows "ipv4:" before IPv4 addresses, for consistency, and on the grounds
16837 that sooner or later somebody will try it.
16838
16839 If the IP address matches something in ignore_target_hosts, the router
16840 declines. If an IP literal turns out to refer to the local host, the generic
16841 self option determines what happens.
16842
16843 The RFCs require support for domain literals; however, their use is
16844 controversial in today's Internet. If you want to use this router, you must
16845 also set the main configuration option allow_domain_literals. Otherwise, Exim
16846 will not recognize the domain literal syntax in addresses.
16847
16848
16849
16850 ===============================================================================
16851 19. THE IPLOOKUP ROUTER
16852
16853 The iplookup router was written to fulfil a specific requirement in Cambridge
16854 University (which in fact no longer exists). For this reason, it is not
16855 included in the binary of Exim by default. If you want to include it, you must
16856 set
16857
16858 ROUTER_IPLOOKUP=yes
16859
16860 in your Local/Makefile configuration file.
16861
16862 The iplookup router routes an address by sending it over a TCP or UDP
16863 connection to one or more specific hosts. The host can then return the same or
16864 a different address - in effect rewriting the recipient address in the
16865 message's envelope. The new address is then passed on to subsequent routers. If
16866 this process fails, the address can be passed on to other routers, or delivery
16867 can be deferred. Since iplookup is just a rewriting router, a transport must
16868 not be specified for it.
16869
16870 +-----+-------------+------------+--------------+
16871 |hosts|Use: iplookup|Type: string|Default: unset|
16872 +-----+-------------+------------+--------------+
16873
16874 This option must be supplied. Its value is a colon-separated list of host
16875 names. The hosts are looked up using gethostbyname() (or getipnodebyname() when
16876 available) and are tried in order until one responds to the query. If none
16877 respond, what happens is controlled by optional.
16878
16879 +--------+-------------+-------------+--------------+
16880 |optional|Use: iplookup|Type: boolean|Default: false|
16881 +--------+-------------+-------------+--------------+
16882
16883 If optional is true, if no response is obtained from any host, the address is
16884 passed to the next router, overriding no_more. If optional is false, delivery
16885 to the address is deferred.
16886
16887 +----+-------------+-------------+----------+
16888 |port|Use: iplookup|Type: integer|Default: 0|
16889 +----+-------------+-------------+----------+
16890
16891 This option must be supplied. It specifies the port number for the TCP or UDP
16892 call.
16893
16894 +--------+-------------+------------+------------+
16895 |protocol|Use: iplookup|Type: string|Default: udp|
16896 +--------+-------------+------------+------------+
16897
16898 This option can be set to "udp" or "tcp" to specify which of the two protocols
16899 is to be used.
16900
16901 +-----+-------------+-------------+------------------+
16902 |query|Use: iplookup|Type: string*|Default: see below|
16903 +-----+-------------+-------------+------------------+
16904
16905 This defines the content of the query that is sent to the remote hosts. The
16906 default value is:
16907
16908 $local_part@$domain $local_part@$domain
16909
16910 The repetition serves as a way of checking that a response is to the correct
16911 query in the default case (see response_pattern below).
16912
16913 +-------+-------------+-------------+--------------+
16914 |reroute|Use: iplookup|Type: string*|Default: unset|
16915 +-------+-------------+-------------+--------------+
16916
16917 If this option is not set, the rerouted address is precisely the byte string
16918 returned by the remote host, up to the first white space, if any. If set, the
16919 string is expanded to form the rerouted address. It can include parts matched
16920 in the response by response_pattern by means of numeric variables such as $1,
16921 $2, etc. The variable $0 refers to the entire input string, whether or not a
16922 pattern is in use. In all cases, the rerouted address must end up in the form
16923 local_part@domain.
16924
16925 +----------------+-------------+------------+--------------+
16926 |response_pattern|Use: iplookup|Type: string|Default: unset|
16927 +----------------+-------------+------------+--------------+
16928
16929 This option can be set to a regular expression that is applied to the string
16930 returned from the remote host. If the pattern does not match the response, the
16931 router declines. If response_pattern is not set, no checking of the response is
16932 done, unless the query was defaulted, in which case there is a check that the
16933 text returned after the first white space is the original address. This checks
16934 that the answer that has been received is in response to the correct question.
16935 For example, if the response is just a new domain, the following could be used:
16936
16937 response_pattern = ^([^@]+)$
16938 reroute = $local_part@$1
16939
16940 +-------+-------------+----------+-----------+
16941 |timeout|Use: iplookup|Type: time|Default: 5s|
16942 +-------+-------------+----------+-----------+
16943
16944 This specifies the amount of time to wait for a response from the remote
16945 machine. The same timeout is used for the connect() function for a TCP call. It
16946 does not apply to UDP.
16947
16948
16949
16950 ===============================================================================
16951 20. THE MANUALROUTE ROUTER
16952
16953 The manualroute router is so-called because it provides a way of manually
16954 routing an address according to its domain. It is mainly used when you want to
16955 route addresses to remote hosts according to your own rules, bypassing the
16956 normal DNS routing that looks up MX records. However, manualroute can also
16957 route to local transports, a facility that may be useful if you want to save
16958 messages for dial-in hosts in local files.
16959
16960 The manualroute router compares a list of domain patterns with the domain it is
16961 trying to route. If there is no match, the router declines. Each pattern has
16962 associated with it a list of hosts and some other optional data, which may
16963 include a transport. The combination of a pattern and its data is called a
16964 "routing rule". For patterns that do not have an associated transport, the
16965 generic transport option must specify a transport, unless the router is being
16966 used purely for verification (see verify_only).
16967
16968 In the case of verification, matching the domain pattern is sufficient for the
16969 router to accept the address. When actually routing an address for delivery, an
16970 address that matches a domain pattern is queued for the associated transport.
16971 If the transport is not a local one, a host list must be associated with the
16972 pattern; IP addresses are looked up for the hosts, and these are passed to the
16973 transport along with the mail address. For local transports, a host list is
16974 optional. If it is present, it is passed in $host as a single text string.
16975
16976 The list of routing rules can be provided as an inline string in route_list, or
16977 the data can be obtained by looking up the domain in a file or database by
16978 setting route_data. Only one of these settings may appear in any one instance
16979 of manualroute. The format of routing rules is described below, following the
16980 list of private options.
16981
16982
16983 20.1 Private options for manualroute
16984 ------------------------------------
16985
16986 The private options for the manualroute router are as follows:
16987
16988 +----------------+----------------+------------+--------------+
16989 |host_all_ignored|Use: manualroute|Type: string|Default: defer|
16990 +----------------+----------------+------------+--------------+
16991
16992 See host_find_failed.
16993
16994 +----------------+----------------+------------+---------------+
16995 |host_find_failed|Use: manualroute|Type: string|Default: freeze|
16996 +----------------+----------------+------------+---------------+
16997
16998 This option controls what happens when manualroute tries to find an IP address
16999 for a host, and the host does not exist. The option can be set to one of the
17000 following values:
17001
17002 decline
17003 defer
17004 fail
17005 freeze
17006 ignore
17007 pass
17008
17009 The default ("freeze") assumes that this state is a serious configuration
17010 error. The difference between "pass" and "decline" is that the former forces
17011 the address to be passed to the next router (or the router defined by
17012 pass_router), overriding no_more, whereas the latter passes the address to the
17013 next router only if more is true.
17014
17015 The value "ignore" causes Exim to completely ignore a host whose IP address
17016 cannot be found. If all the hosts in the list are ignored, the behaviour is
17017 controlled by the host_all_ignored option. This takes the same values as
17018 host_find_failed, except that it cannot be set to "ignore".
17019
17020 The host_find_failed option applies only to a definite "does not exist" state;
17021 if a host lookup gets a temporary error, delivery is deferred unless the
17022 generic pass_on_timeout option is set.
17023
17024 +---------------+----------------+-------------+--------------+
17025 |hosts_randomize|Use: manualroute|Type: boolean|Default: false|
17026 +---------------+----------------+-------------+--------------+
17027
17028 If this option is set, the order of the items in a host list in a routing rule
17029 is randomized each time the list is used, unless an option in the routing rule
17030 overrides (see below). Randomizing the order of a host list can be used to do
17031 crude load sharing. However, if more than one mail address is routed by the
17032 same router to the same host list, the host lists are considered to be the same
17033 (even though they may be randomized into different orders) for the purpose of
17034 deciding whether to batch the deliveries into a single SMTP transaction.
17035
17036 When hosts_randomize is true, a host list may be split into groups whose order
17037 is separately randomized. This makes it possible to set up MX-like behaviour.
17038 The boundaries between groups are indicated by an item that is just "+" in the
17039 host list. For example:
17040
17041 route_list = * host1:host2:host3:+:host4:host5
17042
17043 The order of the first three hosts and the order of the last two hosts is
17044 randomized for each use, but the first three always end up before the last two.
17045 If hosts_randomize is not set, a "+" item in the list is ignored. If a
17046 randomized host list is passed to an smtp transport that also has
17047 hosts_randomize set, the list is not re-randomized.
17048
17049 +----------+----------------+-------------+--------------+
17050 |route_data|Use: manualroute|Type: string*|Default: unset|
17051 +----------+----------------+-------------+--------------+
17052
17053 If this option is set, it must expand to yield the data part of a routing rule.
17054 Typically, the expansion string includes a lookup based on the domain. For
17055 example:
17056
17057 route_data = ${lookup{$domain}dbm{/etc/routes}}
17058
17059 If the expansion is forced to fail, or the result is an empty string, the
17060 router declines. Other kinds of expansion failure cause delivery to be
17061 deferred.
17062
17063 +----------+----------------+-----------------+--------------+
17064 |route_list|Use: manualroute|Type: string list|Default: unset|
17065 +----------+----------------+-----------------+--------------+
17066
17067 This string is a list of routing rules, in the form defined below. Note that,
17068 unlike most string lists, the items are separated by semicolons. This is so
17069 that they may contain colon-separated host lists.
17070
17071 +------------------------+----------------+-------------+--------------+
17072 |same_domain_copy_routing|Use: manualroute|Type: boolean|Default: false|
17073 +------------------------+----------------+-------------+--------------+
17074
17075 Addresses with the same domain are normally routed by the manualroute router to
17076 the same list of hosts. However, this cannot be presumed, because the router
17077 options and preconditions may refer to the local part of the address. By
17078 default, therefore, Exim routes each address in a message independently. DNS
17079 servers run caches, so repeated DNS lookups are not normally expensive, and in
17080 any case, personal messages rarely have more than a few recipients.
17081
17082 If you are running mailing lists with large numbers of subscribers at the same
17083 domain, and you are using a manualroute router which is independent of the
17084 local part, you can set same_domain_copy_routing to bypass repeated DNS lookups
17085 for identical domains in one message. In this case, when manualroute routes an
17086 address to a remote transport, any other unrouted addresses in the message that
17087 have the same domain are automatically given the same routing without
17088 processing them independently. However, this is only done if headers_add and
17089 headers_remove are unset.
17090
17091
17092 20.2 Routing rules in route_list
17093 --------------------------------
17094
17095 The value of route_list is a string consisting of a sequence of routing rules,
17096 separated by semicolons. If a semicolon is needed in a rule, it can be entered
17097 as two semicolons. Alternatively, the list separator can be changed as
17098 described (for colon-separated lists) in section 6.19. Empty rules are ignored.
17099 The format of each rule is
17100
17101 <domain pattern> <list of hosts> <options>
17102
17103 The following example contains two rules, each with a simple domain pattern and
17104 no options:
17105
17106 route_list = \
17107 dict.ref.example mail-1.ref.example:mail-2.ref.example ; \
17108 thes.ref.example mail-3.ref.example:mail-4.ref.example
17109
17110 The three parts of a rule are separated by white space. The pattern and the
17111 list of hosts can be enclosed in quotes if necessary, and if they are, the
17112 usual quoting rules apply. Each rule in a route_list must start with a single
17113 domain pattern, which is the only mandatory item in the rule. The pattern is in
17114 the same format as one item in a domain list (see section 10.8), except that it
17115 may not be the name of an interpolated file. That is, it may be wildcarded, or
17116 a regular expression, or a file or database lookup (with semicolons doubled,
17117 because of the use of semicolon as a separator in a route_list).
17118
17119 The rules in route_list are searched in order until one of the patterns matches
17120 the domain that is being routed. The list of hosts and then options are then
17121 used as described below. If there is no match, the router declines. When
17122 route_list is set, route_data must not be set.
17123
17124
17125 20.3 Routing rules in route_data
17126 --------------------------------
17127
17128 The use of route_list is convenient when there are only a small number of
17129 routing rules. For larger numbers, it is easier to use a file or database to
17130 hold the routing information, and use the route_data option instead. The value
17131 of route_data is a list of hosts, followed by (optional) options. Most
17132 commonly, route_data is set as a string that contains an expansion lookup. For
17133 example, suppose we place two routing rules in a file like this:
17134
17135 dict.ref.example: mail-1.ref.example:mail-2.ref.example
17136 thes.ref.example: mail-3.ref.example:mail-4.ref.example
17137
17138 This data can be accessed by setting
17139
17140 route_data = ${lookup{$domain}lsearch{/the/file/name}}
17141
17142 Failure of the lookup results in an empty string, causing the router to
17143 decline. However, you do not have to use a lookup in route_data. The only
17144 requirement is that the result of expanding the string is a list of hosts,
17145 possibly followed by options, separated by white space. The list of hosts must
17146 be enclosed in quotes if it contains white space.
17147
17148
17149 20.4 Format of the list of hosts
17150 --------------------------------
17151
17152 A list of hosts, whether obtained via route_data or route_list, is always
17153 separately expanded before use. If the expansion fails, the router declines.
17154 The result of the expansion must be a colon-separated list of names and/or IP
17155 addresses, optionally also including ports. The format of each item in the list
17156 is described in the next section. The list separator can be changed as
17157 described in section 6.19.
17158
17159 If the list of hosts was obtained from a route_list item, the following
17160 variables are set during its expansion:
17161
17162 * If the domain was matched against a regular expression, the numeric
17163 variables $1, $2, etc. may be set. For example:
17164
17165 route_list = ^domain(\d+) host-$1.text.example
17166
17167 * $0 is always set to the entire domain.
17168
17169 * $1 is also set when partial matching is done in a file lookup.
17170
17171 * If the pattern that matched the domain was a lookup item, the data that was
17172 looked up is available in the expansion variable $value. For example:
17173
17174 route_list = lsearch;;/some/file.routes $value
17175
17176 Note the doubling of the semicolon in the pattern that is necessary because
17177 semicolon is the default route list separator.
17178
17179
17180 20.5 Format of one host item
17181 ----------------------------
17182
17183 Each item in the list of hosts is either a host name or an IP address,
17184 optionally with an attached port number. When no port is given, an IP address
17185 is not enclosed in brackets. When a port is specified, it overrides the port
17186 specification on the transport. The port is separated from the name or address
17187 by a colon. This leads to some complications:
17188
17189 * Because colon is the default separator for the list of hosts, either the
17190 colon that specifies a port must be doubled, or the list separator must be
17191 changed. The following two examples have the same effect:
17192
17193 route_list = * "host1.tld::1225 : host2.tld::1226"
17194 route_list = * "<+ host1.tld:1225 + host2.tld:1226"
17195
17196 * When IPv6 addresses are involved, it gets worse, because they contain
17197 colons of their own. To make this case easier, it is permitted to enclose
17198 an IP address (either v4 or v6) in square brackets if a port number
17199 follows. For example:
17200
17201 route_list = * "</ [10.1.1.1]:1225 / [::1]:1226"
17202
17203
17204 20.6 How the list of hosts is used
17205 ----------------------------------
17206
17207 When an address is routed to an smtp transport by manualroute, each of the
17208 hosts is tried, in the order specified, when carrying out the SMTP delivery.
17209 However, the order can be changed by setting the hosts_randomize option, either
17210 on the router (see section 20.1 above), or on the transport.
17211
17212 Hosts may be listed by name or by IP address. An unadorned name in the list of
17213 hosts is interpreted as a host name. A name that is followed by "/MX" is
17214 interpreted as an indirection to a sublist of hosts obtained by looking up MX
17215 records in the DNS. For example:
17216
17217 route_list = * x.y.z:p.q.r/MX:e.f.g
17218
17219 If this feature is used with a port specifier, the port must come last. For
17220 example:
17221
17222 route_list = * dom1.tld/mx::1225
17223
17224 If the hosts_randomize option is set, the order of the items in the list is
17225 randomized before any lookups are done. Exim then scans the list; for any name
17226 that is not followed by "/MX" it looks up an IP address. If this turns out to
17227 be an interface on the local host and the item is not the first in the list,
17228 Exim discards it and any subsequent items. If it is the first item, what
17229 happens is controlled by the self option of the router.
17230
17231 A name on the list that is followed by "/MX" is replaced with the list of hosts
17232 obtained by looking up MX records for the name. This is always a DNS lookup;
17233 the bydns and byname options (see section 20.7 below) are not relevant here.
17234 The order of these hosts is determined by the preference values in the MX
17235 records, according to the usual rules. Because randomizing happens before the
17236 MX lookup, it does not affect the order that is defined by MX preferences.
17237
17238 If the local host is present in the sublist obtained from MX records, but is
17239 not the most preferred host in that list, it and any equally or less preferred
17240 hosts are removed before the sublist is inserted into the main list.
17241
17242 If the local host is the most preferred host in the MX list, what happens
17243 depends on where in the original list of hosts the "/MX" item appears. If it is
17244 not the first item (that is, there are previous hosts in the main list), Exim
17245 discards this name and any subsequent items in the main list.
17246
17247 If the MX item is first in the list of hosts, and the local host is the most
17248 preferred host, what happens is controlled by the self option of the router.
17249
17250 DNS failures when lookup up the MX records are treated in the same way as DNS
17251 failures when looking up IP addresses: pass_on_timeout and host_find_failed are
17252 used when relevant.
17253
17254 The generic ignore_target_hosts option applies to all hosts in the list,
17255 whether obtained from an MX lookup or not.
17256
17257
17258 20.7 How the options are used
17259 -----------------------------
17260
17261 The options are a sequence of words; in practice no more than three are ever
17262 present. One of the words can be the name of a transport; this overrides the
17263 transport option on the router for this particular routing rule only. The other
17264 words (if present) control randomization of the list of hosts on a per-rule
17265 basis, and how the IP addresses of the hosts are to be found when routing to a
17266 remote transport. These options are as follows:
17267
17268 * randomize: randomize the order of the hosts in this list, overriding the
17269 setting of hosts_randomize for this routing rule only.
17270
17271 * no_randomize: do not randomize the order of the hosts in this list,
17272 overriding the setting of hosts_randomize for this routing rule only.
17273
17274 * byname: use getipnodebyname() (gethostbyname() on older systems) to find IP
17275 addresses. This function may ultimately cause a DNS lookup, but it may also
17276 look in /etc/hosts or other sources of information.
17277
17278 * bydns: look up address records for the hosts directly in the DNS; fail if
17279 no address records are found. If there is a temporary DNS error (such as a
17280 timeout), delivery is deferred.
17281
17282 For example:
17283
17284 route_list = domain1 host1:host2:host3 randomize bydns;\
17285 domain2 host4:host5
17286
17287 If neither byname nor bydns is given, Exim behaves as follows: First, a DNS
17288 lookup is done. If this yields anything other than HOST_NOT_FOUND, that result
17289 is used. Otherwise, Exim goes on to try a call to getipnodebyname() or
17290 gethostbyname(), and the result of the lookup is the result of that call.
17291
17292 Warning: It has been discovered that on some systems, if a DNS lookup called
17293 via getipnodebyname() times out, HOST_NOT_FOUND is returned instead of
17294 TRY_AGAIN. That is why the default action is to try a DNS lookup first. Only if
17295 that gives a definite "no such host" is the local function called.
17296
17297 If no IP address for a host can be found, what happens is controlled by the
17298 host_find_failed option.
17299
17300 When an address is routed to a local transport, IP addresses are not looked up.
17301 The host list is passed to the transport in the $host variable.
17302
17303
17304 20.8 Manualroute examples
17305 -------------------------
17306
17307 In some of the examples that follow, the presence of the remote_smtp transport,
17308 as defined in the default configuration file, is assumed:
17309
17310 * The manualroute router can be used to forward all external mail to a smart
17311 host. If you have set up, in the main part of the configuration, a named
17312 domain list that contains your local domains, for example:
17313
17314 domainlist local_domains = my.domain.example
17315
17316 You can arrange for all other domains to be routed to a smart host by
17317 making your first router something like this:
17318
17319 smart_route:
17320 driver = manualroute
17321 domains = !+local_domains
17322 transport = remote_smtp
17323 route_list = * smarthost.ref.example
17324
17325 This causes all non-local addresses to be sent to the single host
17326 smarthost.ref.example. If a colon-separated list of smart hosts is given,
17327 they are tried in order (but you can use hosts_randomize to vary the order
17328 each time). Another way of configuring the same thing is this:
17329
17330 smart_route:
17331 driver = manualroute
17332 transport = remote_smtp
17333 route_list = !+local_domains smarthost.ref.example
17334
17335 There is no difference in behaviour between these two routers as they
17336 stand. However, they behave differently if no_more is added to them. In the
17337 first example, the router is skipped if the domain does not match the
17338 domains precondition; the following router is always tried. If the router
17339 runs, it always matches the domain and so can never decline. Therefore,
17340 no_more would have no effect. In the second case, the router is never
17341 skipped; it always runs. However, if it doesn't match the domain, it
17342 declines. In this case no_more would prevent subsequent routers from
17343 running.
17344
17345 * A mail hub is a host which receives mail for a number of domains via MX
17346 records in the DNS and delivers it via its own private routing mechanism.
17347 Often the final destinations are behind a firewall, with the mail hub being
17348 the one machine that can connect to machines both inside and outside the
17349 firewall. The manualroute router is usually used on a mail hub to route
17350 incoming messages to the correct hosts. For a small number of domains, the
17351 routing can be inline, using the route_list option, but for a larger number
17352 a file or database lookup is easier to manage.
17353
17354 If the domain names are in fact the names of the machines to which the mail
17355 is to be sent by the mail hub, the configuration can be quite simple. For
17356 example:
17357
17358 hub_route:
17359 driver = manualroute
17360 transport = remote_smtp
17361 route_list = *.rhodes.tvs.example $domain
17362
17363 This configuration routes domains that match "*.rhodes.tvs.example" to
17364 hosts whose names are the same as the mail domains. A similar approach can
17365 be taken if the host name can be obtained from the domain name by a string
17366 manipulation that the expansion facilities can handle. Otherwise, a lookup
17367 based on the domain can be used to find the host:
17368
17369 through_firewall:
17370 driver = manualroute
17371 transport = remote_smtp
17372 route_data = ${lookup {$domain} cdb {/internal/host/routes}}
17373
17374 The result of the lookup must be the name or IP address of the host (or
17375 hosts) to which the address is to be routed. If the lookup fails, the route
17376 data is empty, causing the router to decline. The address then passes to
17377 the next router.
17378
17379 * You can use manualroute to deliver messages to pipes or files in batched
17380 SMTP format for onward transportation by some other means. This is one way
17381 of storing mail for a dial-up host when it is not connected. The route list
17382 entry can be as simple as a single domain name in a configuration like
17383 this:
17384
17385 save_in_file:
17386 driver = manualroute
17387 transport = batchsmtp_appendfile
17388 route_list = saved.domain.example
17389
17390 though often a pattern is used to pick up more than one domain. If there
17391 are several domains or groups of domains with different transport
17392 requirements, different transports can be listed in the routing
17393 information:
17394
17395 save_in_file:
17396 driver = manualroute
17397 route_list = \
17398 *.saved.domain1.example $domain batch_appendfile; \
17399 *.saved.domain2.example \
17400 ${lookup{$domain}dbm{/domain2/hosts}{$value}fail} \
17401 batch_pipe
17402
17403 The first of these just passes the domain in the $host variable, which
17404 doesn't achieve much (since it is also in $domain), but the second does a
17405 file lookup to find a value to pass, causing the router to decline to
17406 handle the address if the lookup fails.
17407
17408 * Routing mail directly to UUCP software is a specific case of the use of
17409 manualroute in a gateway to another mail environment. This is an example of
17410 one way it can be done:
17411
17412 # Transport
17413 uucp:
17414 driver = pipe
17415 user = nobody
17416 command = /usr/local/bin/uux -r - \
17417 ${substr_-5:$host}!rmail ${local_part}
17418 return_fail_output = true
17419
17420 # Router
17421 uucphost:
17422 transport = uucp
17423 driver = manualroute
17424 route_data = \
17425 ${lookup{$domain}lsearch{/usr/local/exim/uucphosts}}
17426
17427 The file /usr/local/exim/uucphosts contains entries like
17428
17429 darksite.ethereal.example: darksite.UUCP
17430
17431 It can be set up more simply without adding and removing ".UUCP" but this
17432 way makes clear the distinction between the domain name
17433 darksite.ethereal.example and the UUCP host name darksite.
17434
17435
17436
17437 ===============================================================================
17438 21. THE QUERYPROGRAM ROUTER
17439
17440 The queryprogram router routes an address by running an external command and
17441 acting on its output. This is an expensive way to route, and is intended mainly
17442 for use in lightly-loaded systems, or for performing experiments. However, if
17443 it is possible to use the precondition options (domains, local_parts, etc) to
17444 skip this router for most addresses, it could sensibly be used in special
17445 cases, even on a busy host. There are the following private options:
17446
17447 +-------+-----------------+-------------+--------------+
17448 |command|Use: queryprogram|Type: string*|Default: unset|
17449 +-------+-----------------+-------------+--------------+
17450
17451 This option must be set. It specifies the command that is to be run. The
17452 command is split up into a command name and arguments, and then each is
17453 expanded separately (exactly as for a pipe transport, described in chapter 29).
17454
17455 +-------------+-----------------+------------+--------------+
17456 |command_group|Use: queryprogram|Type: string|Default: unset|
17457 +-------------+-----------------+------------+--------------+
17458
17459 This option specifies a gid to be set when running the command while routing an
17460 address for deliver. It must be set if command_user specifies a numerical uid.
17461 If it begins with a digit, it is interpreted as the numerical value of the gid.
17462 Otherwise it is looked up using getgrnam().
17463
17464 +------------+-----------------+------------+--------------+
17465 |command_user|Use: queryprogram|Type: string|Default: unset|
17466 +------------+-----------------+------------+--------------+
17467
17468 This option must be set. It specifies the uid which is set when running the
17469 command while routing an address for delivery. If the value begins with a
17470 digit, it is interpreted as the numerical value of the uid. Otherwise, it is
17471 looked up using getpwnam() to obtain a value for the uid and, if command_group
17472 is not set, a value for the gid also.
17473
17474 Warning: Changing uid and gid is possible only when Exim is running as root,
17475 which it does during a normal delivery in a conventional configuration.
17476 However, when an address is being verified during message reception, Exim is
17477 usually running as the Exim user, not as root. If the queryprogram router is
17478 called from a non-root process, Exim cannot change uid or gid before running
17479 the command. In this circumstance the command runs under the current uid and
17480 gid.
17481
17482 +-----------------+-----------------+------------+----------+
17483 |current_directory|Use: queryprogram|Type: string|Default: /|
17484 +-----------------+-----------------+------------+----------+
17485
17486 This option specifies an absolute path which is made the current directory
17487 before running the command.
17488
17489 +-------+-----------------+----------+-----------+
17490 |timeout|Use: queryprogram|Type: time|Default: 1h|
17491 +-------+-----------------+----------+-----------+
17492
17493 If the command does not complete within the timeout period, its process group
17494 is killed and the message is frozen. A value of zero time specifies no timeout.
17495
17496 The standard output of the command is connected to a pipe, which is read when
17497 the command terminates. It should consist of a single line of output,
17498 containing up to five fields, separated by white space. The maximum length of
17499 the line is 1023 characters. Longer lines are silently truncated. The first
17500 field is one of the following words (case-insensitive):
17501
17502 * Accept: routing succeeded; the remaining fields specify what to do (see
17503 below).
17504
17505 * Decline: the router declines; pass the address to the next router, unless
17506 no_more is set.
17507
17508 * Fail: routing failed; do not pass the address to any more routers. Any
17509 subsequent text on the line is an error message. If the router is run as
17510 part of address verification during an incoming SMTP message, the message
17511 is included in the SMTP response.
17512
17513 * Defer: routing could not be completed at this time; try again later. Any
17514 subsequent text on the line is an error message which is logged. It is not
17515 included in any SMTP response.
17516
17517 * Freeze: the same as defer, except that the message is frozen.
17518
17519 * Pass: pass the address to the next router (or the router specified by
17520 pass_router), overriding no_more.
17521
17522 * Redirect: the message is redirected. The remainder of the line is a list of
17523 new addresses, which are routed independently, starting with the first
17524 router, or the router specified by redirect_router, if set.
17525
17526 When the first word is accept, the remainder of the line consists of a number
17527 of keyed data values, as follows (split into two lines here, to fit on the
17528 page):
17529
17530 ACCEPT TRANSPORT=<transport> HOSTS=<list of hosts>
17531 LOOKUP=byname|bydns DATA=<text>
17532
17533 The data items can be given in any order, and all are optional. If no transport
17534 is included, the transport specified by the generic transport option is used.
17535 The list of hosts and the lookup type are needed only if the transport is an
17536 smtp transport that does not itself supply a list of hosts.
17537
17538 The format of the list of hosts is the same as for the manualroute router. As
17539 well as host names and IP addresses with optional port numbers, as described in
17540 section 20.5, it may contain names followed by "/MX" to specify sublists of
17541 hosts that are obtained by looking up MX records (see section 20.6).
17542
17543 If the lookup type is not specified, Exim behaves as follows when trying to
17544 find an IP address for each host: First, a DNS lookup is done. If this yields
17545 anything other than HOST_NOT_FOUND, that result is used. Otherwise, Exim goes
17546 on to try a call to getipnodebyname() or gethostbyname(), and the result of the
17547 lookup is the result of that call.
17548
17549 If the DATA field is set, its value is placed in the $address_data variable.
17550 For example, this return line
17551
17552 accept hosts=x1.y.example:x2.y.example data="rule1"
17553
17554 routes the address to the default transport, passing a list of two hosts. When
17555 the transport runs, the string "rule1" is in $address_data.
17556
17557
17558
17559 ===============================================================================
17560 22. THE REDIRECT ROUTER
17561
17562 The redirect router handles several kinds of address redirection. Its most
17563 common uses are for resolving local part aliases from a central alias file
17564 (usually called /etc/aliases) and for handling users' personal .forward files,
17565 but it has many other potential uses. The incoming address can be redirected in
17566 several different ways:
17567
17568 * It can be replaced by one or more new addresses which are themselves routed
17569 independently.
17570
17571 * It can be routed to be delivered to a given file or directory.
17572
17573 * It can be routed to be delivered to a specified pipe command.
17574
17575 * It can cause an automatic reply to be generated.
17576
17577 * It can be forced to fail, optionally with a custom error message.
17578
17579 * It can be temporarily deferred, optionally with a custom message.
17580
17581 * It can be discarded.
17582
17583 The generic transport option must not be set for redirect routers. However,
17584 there are some private options which define transports for delivery to files
17585 and pipes, and for generating autoreplies. See the file_transport,
17586 pipe_transport and reply_transport descriptions below.
17587
17588
17589 22.1 Redirection data
17590 ---------------------
17591
17592 The router operates by interpreting a text string which it obtains either by
17593 expanding the contents of the data option, or by reading the entire contents of
17594 a file whose name is given in the file option. These two options are mutually
17595 exclusive. The first is commonly used for handling system aliases, in a
17596 configuration like this:
17597
17598 system_aliases:
17599 driver = redirect
17600 data = ${lookup{$local_part}lsearch{/etc/aliases}}
17601
17602 If the lookup fails, the expanded string in this example is empty. When the
17603 expansion of data results in an empty string, the router declines. A forced
17604 expansion failure also causes the router to decline; other expansion failures
17605 cause delivery to be deferred.
17606
17607 A configuration using file is commonly used for handling users' .forward files,
17608 like this:
17609
17610 userforward:
17611 driver = redirect
17612 check_local_user
17613 file = $home/.forward
17614 no_verify
17615
17616 If the file does not exist, or causes no action to be taken (for example, it is
17617 empty or consists only of comments), the router declines. Warning: This is not
17618 the case when the file contains syntactically valid items that happen to yield
17619 empty addresses, for example, items containing only RFC 2822 address comments.
17620
17621
17622 22.2 Forward files and address verification
17623 -------------------------------------------
17624
17625 It is usual to set no_verify on redirect routers which handle users' .forward
17626 files, as in the example above. There are two reasons for this:
17627
17628 * When Exim is receiving an incoming SMTP message from a remote host, it is
17629 running under the Exim uid, not as root. Exim is unable to change uid to
17630 read the file as the user, and it may not be able to read it as the Exim
17631 user. So in practice the router may not be able to operate.
17632
17633 * However, even when the router can operate, the existence of a .forward file
17634 is unimportant when verifying an address. What should be checked is whether
17635 the local part is a valid user name or not. Cutting out the redirection
17636 processing saves some resources.
17637
17638
17639 22.3 Interpreting redirection data
17640 ----------------------------------
17641
17642 The contents of the data string, whether obtained from data or file, can be
17643 interpreted in two different ways:
17644
17645 * If the allow_filter option is set true, and the data begins with the text "
17646 #Exim filter" or "#Sieve filter", it is interpreted as a list of filtering
17647 instructions in the form of an Exim or Sieve filter file, respectively.
17648 Details of the syntax and semantics of filter files are described in a
17649 separate document entitled Exim's interfaces to mail filtering; this
17650 document is intended for use by end users.
17651
17652 * Otherwise, the data must be a comma-separated list of redirection items, as
17653 described in the next section.
17654
17655 When a message is redirected to a file (a "mail folder"), the file name given
17656 in a non-filter redirection list must always be an absolute path. A filter may
17657 generate a relative path - how this is handled depends on the transport's
17658 configuration. See section 26.1 for a discussion of this issue for the
17659 appendfile transport.
17660
17661
17662 22.4 Items in a non-filter redirection list
17663 -------------------------------------------
17664
17665 When the redirection data is not an Exim or Sieve filter, for example, if it
17666 comes from a conventional alias or forward file, it consists of a list of
17667 addresses, file names, pipe commands, or certain special items (see section
17668 22.6 below). The special items can be individually enabled or disabled by means
17669 of options whose names begin with allow_ or forbid_, depending on their default
17670 values. The items in the list are separated by commas or newlines. If a comma
17671 is required in an item, the entire item must be enclosed in double quotes.
17672
17673 Lines starting with a # character are comments, and are ignored, and # may also
17674 appear following a comma, in which case everything between the # and the next
17675 newline character is ignored.
17676
17677 If an item is entirely enclosed in double quotes, these are removed. Otherwise
17678 double quotes are retained because some forms of mail address require their use
17679 (but never to enclose the entire address). In the following description, "item"
17680 refers to what remains after any surrounding double quotes have been removed.
17681
17682 Warning: If you use an Exim expansion to construct a redirection address, and
17683 the expansion contains a reference to $local_part, you should make use of the
17684 quote_local_part expansion operator, in case the local part contains special
17685 characters. For example, to redirect all mail for the domain obsolete.example,
17686 retaining the existing local part, you could use this setting:
17687
17688 data = ${quote_local_part:$local_part}@newdomain.example
17689
17690
17691 22.5 Redirecting to a local mailbox
17692 -----------------------------------
17693
17694 A redirection item may safely be the same as the address currently under
17695 consideration. This does not cause a routing loop, because a router is
17696 automatically skipped if any ancestor of the address that is being processed is
17697 the same as the current address and was processed by the current router. Such
17698 an address is therefore passed to the following routers, so it is handled as if
17699 there were no redirection. When making this loop-avoidance test, the complete
17700 local part, including any prefix or suffix, is used.
17701
17702 Specifying the same local part without a domain is a common usage in personal
17703 filter files when the user wants to have messages delivered to the local
17704 mailbox and also forwarded elsewhere. For example, the user whose login is cleo
17705 might have a .forward file containing this:
17706
17707 cleo, cleopatra@egypt.example
17708
17709 For compatibility with other MTAs, such unqualified local parts may be preceded
17710 by "\", but this is not a requirement for loop prevention. However, it does
17711 make a difference if more than one domain is being handled synonymously.
17712
17713 If an item begins with "\" and the rest of the item parses as a valid RFC 2822
17714 address that does not include a domain, the item is qualified using the domain
17715 of the incoming address. In the absence of a leading "\", unqualified addresses
17716 are qualified using the value in qualify_recipient, but you can force the
17717 incoming domain to be used by setting qualify_preserve_domain.
17718
17719 Care must be taken if there are alias names for local users. Consider an MTA
17720 handling a single local domain where the system alias file contains:
17721
17722 Sam.Reman: spqr
17723
17724 Now suppose that Sam (whose login id is spqr) wants to save copies of messages
17725 in the local mailbox, and also forward copies elsewhere. He creates this
17726 forward file:
17727
17728 Sam.Reman, spqr@reme.elsewhere.example
17729
17730 With these settings, an incoming message addressed to Sam.Reman fails. The
17731 redirect router for system aliases does not process Sam.Reman the second time
17732 round, because it has previously routed it, and the following routers
17733 presumably cannot handle the alias. The forward file should really contain
17734
17735 spqr, spqr@reme.elsewhere.example
17736
17737 but because this is such a common error, the check_ancestor option (see below)
17738 exists to provide a way to get round it. This is normally set on a redirect
17739 router that is handling users' .forward files.
17740
17741
17742 22.6 Special items in redirection lists
17743 ---------------------------------------
17744
17745 In addition to addresses, the following types of item may appear in redirection
17746 lists (that is, in non-filter redirection data):
17747
17748 * An item is treated as a pipe command if it begins with "|" and does not
17749 parse as a valid RFC 2822 address that includes a domain. A transport for
17750 running the command must be specified by the pipe_transport option.
17751 Normally, either the router or the transport specifies a user and a group
17752 under which to run the delivery. The default is to use the Exim user and
17753 group.
17754
17755 Single or double quotes can be used for enclosing the individual arguments
17756 of the pipe command; no interpretation of escapes is done for single
17757 quotes. If the command contains a comma character, it is necessary to put
17758 the whole item in double quotes, for example:
17759
17760 "|/some/command ready,steady,go"
17761
17762 since items in redirection lists are terminated by commas. Do not, however,
17763 quote just the command. An item such as
17764
17765 |"/some/command ready,steady,go"
17766
17767 is interpreted as a pipe with a rather strange command name, and no
17768 arguments.
17769
17770 Note that the above example assumes that the text comes from a lookup
17771 source of some sort, so that the quotes are part of the data. If composing
17772 a redirect router with a data option directly specifying this command, the
17773 quotes will be used by the configuration parser to define the extent of one
17774 string, but will not be passed down into the redirect router itself. There
17775 are two main approaches to get around this: escape quotes to be part of the
17776 data itself, or avoid using this mechanism and instead create a custom
17777 transport with the command option set and reference that transport from an
17778 accept router.
17779
17780 * An item is interpreted as a path name if it begins with "/" and does not
17781 parse as a valid RFC 2822 address that includes a domain. For example,
17782
17783 /home/world/minbari
17784
17785 is treated as a file name, but
17786
17787 /s=molari/o=babylon/@x400gate.way
17788
17789 is treated as an address. For a file name, a transport must be specified
17790 using the file_transport option. However, if the generated path name ends
17791 with a forward slash character, it is interpreted as a directory name
17792 rather than a file name, and directory_transport is used instead.
17793
17794 Normally, either the router or the transport specifies a user and a group
17795 under which to run the delivery. The default is to use the Exim user and
17796 group.
17797
17798 However, if a redirection item is the path /dev/null, delivery to it is
17799 bypassed at a high level, and the log entry shows "**bypassed**" instead of
17800 a transport name. In this case the user and group are not used.
17801
17802 * If an item is of the form
17803
17804 :include:<path name>
17805
17806 a list of further items is taken from the given file and included at that
17807 point. Note: Such a file can not be a filter file; it is just an
17808 out-of-line addition to the list. The items in the included list are
17809 separated by commas or newlines and are not subject to expansion. If this
17810 is the first item in an alias list in an lsearch file, a colon must be used
17811 to terminate the alias name. This example is incorrect:
17812
17813 list1 :include:/opt/lists/list1
17814
17815 It must be given as
17816
17817 list1: :include:/opt/lists/list1
17818
17819 * Sometimes you want to throw away mail to a particular local part. Making
17820 the data option expand to an empty string does not work, because that
17821 causes the router to decline. Instead, the alias item :blackhole: can be
17822 used. It does what its name implies. No delivery is done, and no error
17823 message is generated. This has the same effect as specifing /dev/null as a
17824 destination, but it can be independently disabled.
17825
17826 Warning: If :blackhole: appears anywhere in a redirection list, no delivery
17827 is done for the original local part, even if other redirection items are
17828 present. If you are generating a multi-item list (for example, by reading a
17829 database) and need the ability to provide a no-op item, you must use /dev/
17830 null.
17831
17832 * An attempt to deliver a particular address can be deferred or forced to
17833 fail by redirection items of the form
17834
17835 :defer:
17836 :fail:
17837
17838 respectively. When a redirection list contains such an item, it applies to
17839 the entire redirection; any other items in the list are ignored. Any text
17840 following :fail: or :defer: is placed in the error text associated with the
17841 failure. For example, an alias file might contain:
17842
17843 X.Employee: :fail: Gone away, no forwarding address
17844
17845 In the case of an address that is being verified from an ACL or as the
17846 subject of a VRFY command, the text is included in the SMTP error response
17847 by default. The text is not included in the response to an EXPN command. In
17848 non-SMTP cases the text is included in the error message that Exim
17849 generates.
17850
17851 By default, Exim sends a 451 SMTP code for a :defer:, and 550 for :fail:.
17852 However, if the message starts with three digits followed by a space,
17853 optionally followed by an extended code of the form n.n.n, also followed by
17854 a space, and the very first digit is the same as the default error code,
17855 the code from the message is used instead. If the very first digit is
17856 incorrect, a panic error is logged, and the default code is used. You can
17857 suppress the use of the supplied code in a redirect router by setting the
17858 forbid_smtp_code option true. In this case, any SMTP code is quietly
17859 ignored.
17860
17861 In an ACL, an explicitly provided message overrides the default, but the
17862 default message is available in the variable $acl_verify_message and can
17863 therefore be included in a custom message if this is desired.
17864
17865 Normally the error text is the rest of the redirection list - a comma does
17866 not terminate it - but a newline does act as a terminator. Newlines are not
17867 normally present in alias expansions. In lsearch lookups they are removed
17868 as part of the continuation process, but they may exist in other kinds of
17869 lookup and in :include: files.
17870
17871 During routing for message delivery (as opposed to verification), a
17872 redirection containing :fail: causes an immediate failure of the incoming
17873 address, whereas :defer: causes the message to remain on the queue so that
17874 a subsequent delivery attempt can happen at a later time. If an address is
17875 deferred for too long, it will ultimately fail, because the normal retry
17876 rules still apply.
17877
17878 * Sometimes it is useful to use a single-key search type with a default (see
17879 chapter 9) to look up aliases. However, there may be a need for exceptions
17880 to the default. These can be handled by aliasing them to :unknown:. This
17881 differs from :fail: in that it causes the redirect router to decline,
17882 whereas :fail: forces routing to fail. A lookup which results in an empty
17883 redirection list has the same effect.
17884
17885
17886 22.7 Duplicate addresses
17887 ------------------------
17888
17889 Exim removes duplicate addresses from the list to which it is delivering, so as
17890 to deliver just one copy to each address. This does not apply to deliveries
17891 routed to pipes by different immediate parent addresses, but an indirect
17892 aliasing scheme of the type
17893
17894 pipe: |/some/command $local_part
17895 localpart1: pipe
17896 localpart2: pipe
17897
17898 does not work with a message that is addressed to both local parts, because
17899 when the second is aliased to the intermediate local part "pipe" it gets
17900 discarded as being the same as a previously handled address. However, a scheme
17901 such as
17902
17903 localpart1: |/some/command $local_part
17904 localpart2: |/some/command $local_part
17905
17906 does result in two different pipe deliveries, because the immediate parents of
17907 the pipes are distinct.
17908
17909
17910 22.8 Repeated redirection expansion
17911 -----------------------------------
17912
17913 When a message cannot be delivered to all of its recipients immediately,
17914 leading to two or more delivery attempts, redirection expansion is carried out
17915 afresh each time for those addresses whose children were not all previously
17916 delivered. If redirection is being used as a mailing list, this can lead to new
17917 members of the list receiving copies of old messages. The one_time option can
17918 be used to avoid this.
17919
17920
17921 22.9 Errors in redirection lists
17922 --------------------------------
17923
17924 If skip_syntax_errors is set, a malformed address that causes a parsing error
17925 is skipped, and an entry is written to the main log. This may be useful for
17926 mailing lists that are automatically managed. Otherwise, if an error is
17927 detected while generating the list of new addresses, the original address is
17928 deferred. See also syntax_errors_to.
17929
17930
17931 22.10 Private options for the redirect router
17932 ---------------------------------------------
17933
17934 The private options for the redirect router are as follows:
17935
17936 +-----------+-------------+-------------+--------------+
17937 |allow_defer|Use: redirect|Type: boolean|Default: false|
17938 +-----------+-------------+-------------+--------------+
17939
17940 Setting this option allows the use of :defer: in non-filter redirection data,
17941 or the defer command in an Exim filter file.
17942
17943 +----------+-------------+-------------+--------------+
17944 |allow_fail|Use: redirect|Type: boolean|Default: false|
17945 +----------+-------------+-------------+--------------+
17946
17947 If this option is true, the :fail: item can be used in a redirection list, and
17948 the fail command may be used in an Exim filter file.
17949
17950 +------------+-------------+-------------+--------------+
17951 |allow_filter|Use: redirect|Type: boolean|Default: false|
17952 +------------+-------------+-------------+--------------+
17953
17954 Setting this option allows Exim to interpret redirection data that starts with
17955 "#Exim filter" or "#Sieve filter" as a set of filtering instructions. There are
17956 some features of Exim filter files that some administrators may wish to lock
17957 out; see the forbid_filter_xxx options below.
17958
17959 It is also possible to lock out Exim filters or Sieve filters while allowing
17960 the other type; see forbid_exim_filter and forbid_sieve_filter.
17961
17962 The filter is run using the uid and gid set by the generic user and group
17963 options. These take their defaults from the password data if check_local_user
17964 is set, so in the normal case of users' personal filter files, the filter is
17965 run as the relevant user. When allow_filter is set true, Exim insists that
17966 either check_local_user or user is set.
17967
17968 +------------+-------------+-------------+--------------+
17969 |allow_freeze|Use: redirect|Type: boolean|Default: false|
17970 +------------+-------------+-------------+--------------+
17971
17972 Setting this option allows the use of the freeze command in an Exim filter.
17973 This command is more normally encountered in system filters, and is disabled by
17974 default for redirection filters because it isn't something you usually want to
17975 let ordinary users do.
17976
17977 +--------------+-------------+-------------+--------------+
17978 |check_ancestor|Use: redirect|Type: boolean|Default: false|
17979 +--------------+-------------+-------------+--------------+
17980
17981 This option is concerned with handling generated addresses that are the same as
17982 some address in the list of redirection ancestors of the current address.
17983 Although it is turned off by default in the code, it is set in the default
17984 configuration file for handling users' .forward files. It is recommended for
17985 this use of the redirect router.
17986
17987 When check_ancestor is set, if a generated address (including the domain) is
17988 the same as any ancestor of the current address, it is replaced by a copy of
17989 the current address. This helps in the case where local part A is aliased to B,
17990 and B has a .forward file pointing back to A. For example, within a single
17991 domain, the local part "Joe.Bloggs" is aliased to "jb" and jb/.forward
17992 contains:
17993
17994 \Joe.Bloggs, <other item(s)>
17995
17996 Without the check_ancestor setting, either local part ("jb" or "joe.bloggs")
17997 gets processed once by each router and so ends up as it was originally. If "jb"
17998 is the real mailbox name, mail to "jb" gets delivered (having been turned into
17999 "joe.bloggs" by the .forward file and back to "jb" by the alias), but mail to
18000 "joe.bloggs" fails. Setting check_ancestor on the redirect router that handles
18001 the .forward file prevents it from turning "jb" back into "joe.bloggs" when
18002 that was the original address. See also the repeat_use option below.
18003
18004 +-----------+-------------+-------------+------------------+
18005 |check_group|Use: redirect|Type: boolean|Default: see below|
18006 +-----------+-------------+-------------+------------------+
18007
18008 When the file option is used, the group owner of the file is checked only when
18009 this option is set. The permitted groups are those listed in the owngroups
18010 option, together with the user's default group if check_local_user is set. If
18011 the file has the wrong group, routing is deferred. The default setting for this
18012 option is true if check_local_user is set and the modemask option permits the
18013 group write bit, or if the owngroups option is set. Otherwise it is false, and
18014 no group check occurs.
18015
18016 +-----------+-------------+-------------+------------------+
18017 |check_owner|Use: redirect|Type: boolean|Default: see below|
18018 +-----------+-------------+-------------+------------------+
18019
18020 When the file option is used, the owner of the file is checked only when this
18021 option is set. If check_local_user is set, the local user is permitted;
18022 otherwise the owner must be one of those listed in the owners option. The
18023 default value for this option is true if check_local_user or owners is set.
18024 Otherwise the default is false, and no owner check occurs.
18025
18026 +----+-------------+-------------+--------------+
18027 |data|Use: redirect|Type: string*|Default: unset|
18028 +----+-------------+-------------+--------------+
18029
18030 This option is mutually exclusive with file. One or other of them must be set,
18031 but not both. The contents of data are expanded, and then used as the list of
18032 forwarding items, or as a set of filtering instructions. If the expansion is
18033 forced to fail, or the result is an empty string or a string that has no effect
18034 (consists entirely of comments), the router declines.
18035
18036 When filtering instructions are used, the string must begin with "#Exim
18037 filter", and all comments in the string, including this initial one, must be
18038 terminated with newline characters. For example:
18039
18040 data = #Exim filter\n\
18041 if $h_to: contains Exim then save $home/mail/exim endif
18042
18043 If you are reading the data from a database where newlines cannot be included,
18044 you can use the ${sg} expansion item to turn the escape string of your choice
18045 into a newline.
18046
18047 +-------------------+-------------+-------------+--------------+
18048 |directory_transport|Use: redirect|Type: string*|Default: unset|
18049 +-------------------+-------------+-------------+--------------+
18050
18051 A redirect router sets up a direct delivery to a directory when a path name
18052 ending with a slash is specified as a new "address". The transport used is
18053 specified by this option, which, after expansion, must be the name of a
18054 configured transport. This should normally be an appendfile transport.
18055
18056 +----+-------------+-------------+--------------+
18057 |file|Use: redirect|Type: string*|Default: unset|
18058 +----+-------------+-------------+--------------+
18059
18060 This option specifies the name of a file that contains the redirection data. It
18061 is mutually exclusive with the data option. The string is expanded before use;
18062 if the expansion is forced to fail, the router declines. Other expansion
18063 failures cause delivery to be deferred. The result of a successful expansion
18064 must be an absolute path. The entire file is read and used as the redirection
18065 data. If the data is an empty string or a string that has no effect (consists
18066 entirely of comments), the router declines.
18067
18068 If the attempt to open the file fails with a "does not exist" error, Exim runs
18069 a check on the containing directory, unless ignore_enotdir is true (see below).
18070 If the directory does not appear to exist, delivery is deferred. This can
18071 happen when users' .forward files are in NFS-mounted directories, and there is
18072 a mount problem. If the containing directory does exist, but the file does not,
18073 the router declines.
18074
18075 +--------------+-------------+-------------+--------------+
18076 |file_transport|Use: redirect|Type: string*|Default: unset|
18077 +--------------+-------------+-------------+--------------+
18078
18079 A redirect router sets up a direct delivery to a file when a path name not
18080 ending in a slash is specified as a new "address". The transport used is
18081 specified by this option, which, after expansion, must be the name of a
18082 configured transport. This should normally be an appendfile transport. When it
18083 is running, the file name is in $address_file.
18084
18085 +-------------------+-------------+-------------+-------------+
18086 |filter_prepend_home|Use: redirect|Type: boolean|Default: true|
18087 +-------------------+-------------+-------------+-------------+
18088
18089 When this option is true, if a save command in an Exim filter specifies a
18090 relative path, and $home is defined, it is automatically prepended to the
18091 relative path. If this option is set false, this action does not happen. The
18092 relative path is then passed to the transport unmodified.
18093
18094 +----------------+-------------+-------------+--------------+
18095 |forbid_blackhole|Use: redirect|Type: boolean|Default: false|
18096 +----------------+-------------+-------------+--------------+
18097
18098 If this option is true, the :blackhole: item may not appear in a redirection
18099 list.
18100
18101 +------------------+-------------+-------------+--------------+
18102 |forbid_exim_filter|Use: redirect|Type: boolean|Default: false|
18103 +------------------+-------------+-------------+--------------+
18104
18105 If this option is set true, only Sieve filters are permitted when allow_filter
18106 is true.
18107
18108 +-----------+-------------+-------------+--------------+
18109 |forbid_file|Use: redirect|Type: boolean|Default: false|
18110 +-----------+-------------+-------------+--------------+
18111
18112 If this option is true, this router may not generate a new address that
18113 specifies delivery to a local file or directory, either from a filter or from a
18114 conventional forward file. This option is forced to be true if one_time is set.
18115 It applies to Sieve filters as well as to Exim filters, but if true, it locks
18116 out the Sieve's "keep" facility.
18117
18118 +--------------------+-------------+-------------+--------------+
18119 |forbid_filter_dlfunc|Use: redirect|Type: boolean|Default: false|
18120 +--------------------+-------------+-------------+--------------+
18121
18122 If this option is true, string expansions in Exim filters are not allowed to
18123 make use of the dlfunc expansion facility to run dynamically loaded functions.
18124
18125 +------------------------+-------------+-------------+--------------+
18126 |forbid_filter_existstest|Use: redirect|Type: boolean|Default: false|
18127 +------------------------+-------------+-------------+--------------+
18128
18129 If this option is true, string expansions in Exim filters are not allowed to
18130 make use of the exists condition or the stat expansion item.
18131
18132 +----------------------+-------------+-------------+--------------+
18133 |forbid_filter_logwrite|Use: redirect|Type: boolean|Default: false|
18134 +----------------------+-------------+-------------+--------------+
18135
18136 If this option is true, use of the logging facility in Exim filters is not
18137 permitted. Logging is in any case available only if the filter is being run
18138 under some unprivileged uid (which is normally the case for ordinary users'
18139 .forward files).
18140
18141 +--------------------+-------------+-------------+--------------+
18142 |forbid_filter_lookup|Use: redirect|Type: boolean|Default: false|
18143 +--------------------+-------------+-------------+--------------+
18144
18145 If this option is true, string expansions in Exim filter files are not allowed
18146 to make use of lookup items.
18147
18148 +------------------+-------------+-------------+--------------+
18149 |forbid_filter_perl|Use: redirect|Type: boolean|Default: false|
18150 +------------------+-------------+-------------+--------------+
18151
18152 This option has an effect only if Exim is built with embedded Perl support. If
18153 it is true, string expansions in Exim filter files are not allowed to make use
18154 of the embedded Perl support.
18155
18156 +----------------------+-------------+-------------+--------------+
18157 |forbid_filter_readfile|Use: redirect|Type: boolean|Default: false|
18158 +----------------------+-------------+-------------+--------------+
18159
18160 If this option is true, string expansions in Exim filter files are not allowed
18161 to make use of readfile items.
18162
18163 +------------------------+-------------+-------------+--------------+
18164 |forbid_filter_readsocket|Use: redirect|Type: boolean|Default: false|
18165 +------------------------+-------------+-------------+--------------+
18166
18167 If this option is true, string expansions in Exim filter files are not allowed
18168 to make use of readsocket items.
18169
18170 +-------------------+-------------+-------------+--------------+
18171 |forbid_filter_reply|Use: redirect|Type: boolean|Default: false|
18172 +-------------------+-------------+-------------+--------------+
18173
18174 If this option is true, this router may not generate an automatic reply
18175 message. Automatic replies can be generated only from Exim or Sieve filter
18176 files, not from traditional forward files. This option is forced to be true if
18177 one_time is set.
18178
18179 +-----------------+-------------+-------------+--------------+
18180 |forbid_filter_run|Use: redirect|Type: boolean|Default: false|
18181 +-----------------+-------------+-------------+--------------+
18182
18183 If this option is true, string expansions in Exim filter files are not allowed
18184 to make use of run items.
18185
18186 +--------------+-------------+-------------+--------------+
18187 |forbid_include|Use: redirect|Type: boolean|Default: false|
18188 +--------------+-------------+-------------+--------------+
18189
18190 If this option is true, items of the form
18191
18192 :include:<path name>
18193
18194 are not permitted in non-filter redirection lists.
18195
18196 +-----------+-------------+-------------+--------------+
18197 |forbid_pipe|Use: redirect|Type: boolean|Default: false|
18198 +-----------+-------------+-------------+--------------+
18199
18200 If this option is true, this router may not generate a new address which
18201 specifies delivery to a pipe, either from an Exim filter or from a conventional
18202 forward file. This option is forced to be true if one_time is set.
18203
18204 +-------------------+-------------+-------------+--------------+
18205 |forbid_sieve_filter|Use: redirect|Type: boolean|Default: false|
18206 +-------------------+-------------+-------------+--------------+
18207
18208 If this option is set true, only Exim filters are permitted when allow_filter
18209 is true.
18210
18211 +----------------+-------------+-------------+--------------+
18212 |forbid_smtp_code|Use: redirect|Type: boolean|Default: false|
18213 +----------------+-------------+-------------+--------------+
18214
18215 If this option is set true, any SMTP error codes that are present at the start
18216 of messages specified for ":defer:" or ":fail:" are quietly ignored, and the
18217 default codes (451 and 550, respectively) are always used.
18218
18219 +--------------------+-------------+-------------+--------------+
18220 |hide_child_in_errmsg|Use: redirect|Type: boolean|Default: false|
18221 +--------------------+-------------+-------------+--------------+
18222
18223 If this option is true, it prevents Exim from quoting a child address if it
18224 generates a bounce or delay message for it. Instead it says "an address
18225 generated from <the top level address>". Of course, this applies only to
18226 bounces generated locally. If a message is forwarded to another host, its
18227 bounce may well quote the generated address.
18228
18229 +-------------+-------------+-------------+--------------+
18230 |ignore_eacces|Use: redirect|Type: boolean|Default: false|
18231 +-------------+-------------+-------------+--------------+
18232
18233 If this option is set and an attempt to open a redirection file yields the
18234 EACCES error (permission denied), the redirect router behaves as if the file
18235 did not exist.
18236
18237 +--------------+-------------+-------------+--------------+
18238 |ignore_enotdir|Use: redirect|Type: boolean|Default: false|
18239 +--------------+-------------+-------------+--------------+
18240
18241 If this option is set and an attempt to open a redirection file yields the
18242 ENOTDIR error (something on the path is not a directory), the redirect router
18243 behaves as if the file did not exist.
18244
18245 Setting ignore_enotdir has another effect as well: When a redirect router that
18246 has the file option set discovers that the file does not exist (the ENOENT
18247 error), it tries to stat() the parent directory, as a check against unmounted
18248 NFS directories. If the parent can not be statted, delivery is deferred.
18249 However, it seems wrong to do this check when ignore_enotdir is set, because
18250 that option tells Exim to ignore "something on the path is not a directory"
18251 (the ENOTDIR error). This is a confusing area, because it seems that some
18252 operating systems give ENOENT where others give ENOTDIR.
18253
18254 +-----------------+-------------+------------+--------------+
18255 |include_directory|Use: redirect|Type: string|Default: unset|
18256 +-----------------+-------------+------------+--------------+
18257
18258 If this option is set, the path names of any :include: items in a redirection
18259 list must start with this directory.
18260
18261 +--------+-------------+-------------------+------------+
18262 |modemask|Use: redirect|Type: octal integer|Default: 022|
18263 +--------+-------------+-------------------+------------+
18264
18265 This specifies mode bits which must not be set for a file specified by the file
18266 option. If any of the forbidden bits are set, delivery is deferred.
18267
18268 +--------+-------------+-------------+--------------+
18269 |one_time|Use: redirect|Type: boolean|Default: false|
18270 +--------+-------------+-------------+--------------+
18271
18272 Sometimes the fact that Exim re-evaluates aliases and reprocesses redirection
18273 files each time it tries to deliver a message causes a problem when one or more
18274 of the generated addresses fails be delivered at the first attempt. The problem
18275 is not one of duplicate delivery - Exim is clever enough to handle that - but
18276 of what happens when the redirection list changes during the time that the
18277 message is on Exim's queue. This is particularly true in the case of mailing
18278 lists, where new subscribers might receive copies of messages that were posted
18279 before they subscribed.
18280
18281 If one_time is set and any addresses generated by the router fail to deliver at
18282 the first attempt, the failing addresses are added to the message as "top
18283 level" addresses, and the parent address that generated them is marked
18284 "delivered". Thus, redirection does not happen again at the next delivery
18285 attempt.
18286
18287 Warning 1: Any header line addition or removal that is specified by this router
18288 would be lost if delivery did not succeed at the first attempt. For this
18289 reason, the headers_add and headers_remove generic options are not permitted
18290 when one_time is set.
18291
18292 Warning 2: To ensure that the router generates only addresses (as opposed to
18293 pipe or file deliveries or auto-replies) forbid_file, forbid_pipe, and
18294 forbid_filter_reply are forced to be true when one_time is set.
18295
18296 Warning 3: The unseen generic router option may not be set with one_time.
18297
18298 The original top-level address is remembered with each of the generated
18299 addresses, and is output in any log messages. However, any intermediate parent
18300 addresses are not recorded. This makes a difference to the log only if
18301 all_parents log selector is set. It is expected that one_time will typically be
18302 used for mailing lists, where there is normally just one level of expansion.
18303
18304 +------+-------------+-----------------+--------------+
18305 |owners|Use: redirect|Type: string list|Default: unset|
18306 +------+-------------+-----------------+--------------+
18307
18308 This specifies a list of permitted owners for the file specified by file. This
18309 list is in addition to the local user when check_local_user is set. See
18310 check_owner above.
18311
18312 +---------+-------------+-----------------+--------------+
18313 |owngroups|Use: redirect|Type: string list|Default: unset|
18314 +---------+-------------+-----------------+--------------+
18315
18316 This specifies a list of permitted groups for the file specified by file. The
18317 list is in addition to the local user's primary group when check_local_user is
18318 set. See check_group above.
18319
18320 +--------------+-------------+-------------+--------------+
18321 |pipe_transport|Use: redirect|Type: string*|Default: unset|
18322 +--------------+-------------+-------------+--------------+
18323
18324 A redirect router sets up a direct delivery to a pipe when a string starting
18325 with a vertical bar character is specified as a new "address". The transport
18326 used is specified by this option, which, after expansion, must be the name of a
18327 configured transport. This should normally be a pipe transport. When the
18328 transport is run, the pipe command is in $address_pipe.
18329
18330 +--------------+-------------+-------------+--------------+
18331 |qualify_domain|Use: redirect|Type: string*|Default: unset|
18332 +--------------+-------------+-------------+--------------+
18333
18334 If this option is set, and an unqualified address (one without a domain) is
18335 generated, and that address would normally be qualified by the global setting
18336 in qualify_recipient, it is instead qualified with the domain specified by
18337 expanding this string. If the expansion fails, the router declines. If you want
18338 to revert to the default, you can have the expansion generate
18339 $qualify_recipient.
18340
18341 This option applies to all unqualified addresses generated by Exim filters, but
18342 for traditional .forward files, it applies only to addresses that are not
18343 preceded by a backslash. Sieve filters cannot generate unqualified addresses.
18344
18345 +-----------------------+-------------+-------------+--------------+
18346 |qualify_preserve_domain|Use: redirect|Type: boolean|Default: false|
18347 +-----------------------+-------------+-------------+--------------+
18348
18349 If this option is set, the router's local qualify_domain option must not be set
18350 (a configuration error occurs if it is). If an unqualified address (one without
18351 a domain) is generated, it is qualified with the domain of the parent address
18352 (the immediately preceding ancestor) instead of the global qualify_recipient
18353 value. In the case of a traditional .forward file, this applies whether or not
18354 the address is preceded by a backslash.
18355
18356 +----------+-------------+-------------+-------------+
18357 |repeat_use|Use: redirect|Type: boolean|Default: true|
18358 +----------+-------------+-------------+-------------+
18359
18360 If this option is set false, the router is skipped for a child address that has
18361 any ancestor that was routed by this router. This test happens before any of
18362 the other preconditions are tested. Exim's default anti-looping rules skip only
18363 when the ancestor is the same as the current address. See also check_ancestor
18364 above and the generic redirect_router option.
18365
18366 +---------------+-------------+-------------+--------------+
18367 |reply_transport|Use: redirect|Type: string*|Default: unset|
18368 +---------------+-------------+-------------+--------------+
18369
18370 A redirect router sets up an automatic reply when a mail or vacation command is
18371 used in a filter file. The transport used is specified by this option, which,
18372 after expansion, must be the name of a configured transport. This should
18373 normally be an autoreply transport. Other transports are unlikely to do
18374 anything sensible or useful.
18375
18376 +-------+-------------+-------------+-------------+
18377 |rewrite|Use: redirect|Type: boolean|Default: true|
18378 +-------+-------------+-------------+-------------+
18379
18380 If this option is set false, addresses generated by the router are not subject
18381 to address rewriting. Otherwise, they are treated like new addresses and are
18382 rewritten according to the global rewriting rules.
18383
18384 +----------------+-------------+-------------+--------------+
18385 |sieve_subaddress|Use: redirect|Type: string*|Default: unset|
18386 +----------------+-------------+-------------+--------------+
18387
18388 The value of this option is passed to a Sieve filter to specify the :subaddress
18389 part of an address.
18390
18391 +-----------------+-------------+-------------+--------------+
18392 |sieve_useraddress|Use: redirect|Type: string*|Default: unset|
18393 +-----------------+-------------+-------------+--------------+
18394
18395 The value of this option is passed to a Sieve filter to specify the :user part
18396 of an address. However, if it is unset, the entire original local part
18397 (including any prefix or suffix) is used for :user.
18398
18399 +------------------------+-------------+-------------+--------------+
18400 |sieve_vacation_directory|Use: redirect|Type: string*|Default: unset|
18401 +------------------------+-------------+-------------+--------------+
18402
18403 To enable the "vacation" extension for Sieve filters, you must set
18404 sieve_vacation_directory to the directory where vacation databases are held (do
18405 not put anything else in that directory), and ensure that the reply_transport
18406 option refers to an autoreply transport. Each user needs their own directory;
18407 Exim will create it if necessary.
18408
18409 +------------------+-------------+-------------+--------------+
18410 |skip_syntax_errors|Use: redirect|Type: boolean|Default: false|
18411 +------------------+-------------+-------------+--------------+
18412
18413 If skip_syntax_errors is set, syntactically malformed addresses in non-filter
18414 redirection data are skipped, and each failing address is logged. If
18415 syntax_errors_to is set, a message is sent to the address it defines, giving
18416 details of the failures. If syntax_errors_text is set, its contents are
18417 expanded and placed at the head of the error message generated by
18418 syntax_errors_to. Usually it is appropriate to set syntax_errors_to to be the
18419 same address as the generic errors_to option. The skip_syntax_errors option is
18420 often used when handling mailing lists.
18421
18422 If all the addresses in a redirection list are skipped because of syntax
18423 errors, the router declines to handle the original address, and it is passed to
18424 the following routers.
18425
18426 If skip_syntax_errors is set when an Exim filter is interpreted, any syntax
18427 error in the filter causes filtering to be abandoned without any action being
18428 taken. The incident is logged, and the router declines to handle the address,
18429 so it is passed to the following routers.
18430
18431 Syntax errors in a Sieve filter file cause the "keep" action to occur. This
18432 action is specified by RFC 3028. The values of skip_syntax_errors,
18433 syntax_errors_to, and syntax_errors_text are not used.
18434
18435 skip_syntax_errors can be used to specify that errors in users' forward lists
18436 or filter files should not prevent delivery. The syntax_errors_to option, used
18437 with an address that does not get redirected, can be used to notify users of
18438 these errors, by means of a router like this:
18439
18440 userforward:
18441 driver = redirect
18442 allow_filter
18443 check_local_user
18444 file = $home/.forward
18445 file_transport = address_file
18446 pipe_transport = address_pipe
18447 reply_transport = address_reply
18448 no_verify
18449 skip_syntax_errors
18450 syntax_errors_to = real-$local_part@$domain
18451 syntax_errors_text = \
18452 This is an automatically generated message. An error has\n\
18453 been found in your .forward file. Details of the error are\n\
18454 reported below. While this error persists, you will receive\n\
18455 a copy of this message for every message that is addressed\n\
18456 to you. If your .forward file is a filter file, or if it is\n\
18457 a non-filter file containing no valid forwarding addresses,\n\
18458 a copy of each incoming message will be put in your normal\n\
18459 mailbox. If a non-filter file contains at least one valid\n\
18460 forwarding address, forwarding to the valid addresses will\n\
18461 happen, and those will be the only deliveries that occur.
18462
18463 You also need a router to ensure that local addresses that are prefixed by
18464 "real-" are recognized, but not forwarded or filtered. For example, you could
18465 put this immediately before the userforward router:
18466
18467 real_localuser:
18468 driver = accept
18469 check_local_user
18470 local_part_prefix = real-
18471 transport = local_delivery
18472
18473 For security, it would probably be a good idea to restrict the use of this
18474 router to locally-generated messages, using a condition such as this:
18475
18476 condition = ${if match {$sender_host_address}\
18477 {\N^(|127\.0\.0\.1)$\N}}
18478
18479 +------------------+-------------+-------------+--------------+
18480 |syntax_errors_text|Use: redirect|Type: string*|Default: unset|
18481 +------------------+-------------+-------------+--------------+
18482
18483 See skip_syntax_errors above.
18484
18485 +----------------+-------------+------------+--------------+
18486 |syntax_errors_to|Use: redirect|Type: string|Default: unset|
18487 +----------------+-------------+------------+--------------+
18488
18489 See skip_syntax_errors above.
18490
18491
18492
18493 ===============================================================================
18494 23. ENVIRONMENT FOR RUNNING LOCAL TRANSPORTS
18495
18496 Local transports handle deliveries to files and pipes. (The autoreply transport
18497 can be thought of as similar to a pipe.) Exim always runs transports in
18498 subprocesses, under specified uids and gids. Typical deliveries to local
18499 mailboxes run under the uid and gid of the local user.
18500
18501 Exim also sets a specific current directory while running the transport; for
18502 some transports a home directory setting is also relevant. The pipe transport
18503 is the only one that sets up environment variables; see section 29.4 for
18504 details.
18505
18506 The values used for the uid, gid, and the directories may come from several
18507 different places. In many cases, the router that handles the address associates
18508 settings with that address as a result of its check_local_user, group, or user
18509 options. However, values may also be given in the transport's own
18510 configuration, and these override anything that comes from the router.
18511
18512
18513 23.1 Concurrent deliveries
18514 --------------------------
18515
18516 If two different messages for the same local recipient arrive more or less
18517 simultaneously, the two delivery processes are likely to run concurrently. When
18518 the appendfile transport is used to write to a file, Exim applies locking rules
18519 to stop concurrent processes from writing to the same file at the same time.
18520
18521 However, when you use a pipe transport, it is up to you to arrange any locking
18522 that is needed. Here is a silly example:
18523
18524 my_transport:
18525 driver = pipe
18526 command = /bin/sh -c 'cat >>/some/file'
18527
18528 This is supposed to write the message at the end of the file. However, if two
18529 messages arrive at the same time, the file will be scrambled. You can use the
18530 exim_lock utility program (see section 52.15) to lock a file using the same
18531 algorithm that Exim itself uses.
18532
18533
18534 23.2 Uids and gids
18535 ------------------
18536
18537 All transports have the options group and user. If group is set, it overrides
18538 any group that the router set in the address, even if user is not set for the
18539 transport. This makes it possible, for example, to run local mail delivery
18540 under the uid of the recipient (set by the router), but in a special group (set
18541 by the transport). For example:
18542
18543 # Routers ...
18544 # User/group are set by check_local_user in this router
18545 local_users:
18546 driver = accept
18547 check_local_user
18548 transport = group_delivery
18549
18550 # Transports ...
18551 # This transport overrides the group
18552 group_delivery:
18553 driver = appendfile
18554 file = /var/spool/mail/$local_part
18555 group = mail
18556
18557 If user is set for a transport, its value overrides what is set in the address
18558 by the router. If user is non-numeric and group is not set, the gid associated
18559 with the user is used. If user is numeric, group must be set.
18560
18561 When the uid is taken from the transport's configuration, the initgroups()
18562 function is called for the groups associated with that uid if the initgroups
18563 option is set for the transport. When the uid is not specified by the
18564 transport, but is associated with the address by a router, the option for
18565 calling initgroups() is taken from the router configuration.
18566
18567 The pipe transport contains the special option pipe_as_creator. If this is set
18568 and user is not set, the uid of the process that called Exim to receive the
18569 message is used, and if group is not set, the corresponding original gid is
18570 also used.
18571
18572 This is the detailed preference order for obtaining a gid; the first of the
18573 following that is set is used:
18574
18575 * A group setting of the transport;
18576
18577 * A group setting of the router;
18578
18579 * A gid associated with a user setting of the router, either as a result of
18580 check_local_user or an explicit non-numeric user setting;
18581
18582 * The group associated with a non-numeric user setting of the transport;
18583
18584 * In a pipe transport, the creator's gid if deliver_as_creator is set and the
18585 uid is the creator's uid;
18586
18587 * The Exim gid if the Exim uid is being used as a default.
18588
18589 If, for example, the user is specified numerically on the router and there are
18590 no group settings, no gid is available. In this situation, an error occurs.
18591 This is different for the uid, for which there always is an ultimate default.
18592 The first of the following that is set is used:
18593
18594 * A user setting of the transport;
18595
18596 * In a pipe transport, the creator's uid if deliver_as_creator is set;
18597
18598 * A user setting of the router;
18599
18600 * A check_local_user setting of the router;
18601
18602 * The Exim uid.
18603
18604 Of course, an error will still occur if the uid that is chosen is on the
18605 never_users list.
18606
18607
18608 23.3 Current and home directories
18609 ---------------------------------
18610
18611 Routers may set current and home directories for local transports by means of
18612 the transport_current_directory and transport_home_directory options. However,
18613 if the transport's current_directory or home_directory options are set, they
18614 override the router's values. In detail, the home directory for a local
18615 transport is taken from the first of these values that is set:
18616
18617 * The home_directory option on the transport;
18618
18619 * The transport_home_directory option on the router;
18620
18621 * The password data if check_local_user is set on the router;
18622
18623 * The router_home_directory option on the router.
18624
18625 The current directory is taken from the first of these values that is set:
18626
18627 * The current_directory option on the transport;
18628
18629 * The transport_current_directory option on the router.
18630
18631 If neither the router nor the transport sets a current directory, Exim uses the
18632 value of the home directory, if it is set. Otherwise it sets the current
18633 directory to / before running a local transport.
18634
18635
18636 23.4 Expansion variables derived from the address
18637 -------------------------------------------------
18638
18639 Normally a local delivery is handling a single address, and in that case the
18640 variables such as $domain and $local_part are set during local deliveries.
18641 However, in some circumstances more than one address may be handled at once
18642 (for example, while writing batch SMTP for onward transmission by some other
18643 means). In this case, the variables associated with the local part are never
18644 set, $domain is set only if all the addresses have the same domain, and
18645 $original_domain is never set.
18646
18647
18648
18649 ===============================================================================
18650 24. GENERIC OPTIONS FOR TRANSPORTS
18651
18652 The following generic options apply to all transports:
18653
18654 +---------+---------------+-------------+--------------+
18655 |body_only|Use: transports|Type: boolean|Default: false|
18656 +---------+---------------+-------------+--------------+
18657
18658 If this option is set, the message's headers are not transported. It is
18659 mutually exclusive with headers_only. If it is used with the appendfile or pipe
18660 transports, the settings of message_prefix and message_suffix should be
18661 checked, because this option does not automatically suppress them.
18662
18663 +-----------------+---------------+-------------+--------------+
18664 |current_directory|Use: transports|Type: string*|Default: unset|
18665 +-----------------+---------------+-------------+--------------+
18666
18667 This specifies the current directory that is to be set while running the
18668 transport, overriding any value that may have been set by the router. If the
18669 expansion fails for any reason, including forced failure, an error is logged,
18670 and delivery is deferred.
18671
18672 +---------------+---------------+-------------+--------------+
18673 |disable_logging|Use: transports|Type: boolean|Default: false|
18674 +---------------+---------------+-------------+--------------+
18675
18676 If this option is set true, nothing is logged for any deliveries by the
18677 transport or for any transport errors. You should not set this option unless
18678 you really, really know what you are doing.
18679
18680 +-----------+---------------+-------------+--------------+
18681 |debug_print|Use: transports|Type: string*|Default: unset|
18682 +-----------+---------------+-------------+--------------+
18683
18684 If this option is set and debugging is enabled (see the -d command line
18685 option), the string is expanded and included in the debugging output when the
18686 transport is run. If expansion of the string fails, the error message is
18687 written to the debugging output, and Exim carries on processing. This facility
18688 is provided to help with checking out the values of variables and so on when
18689 debugging driver configurations. For example, if a headers_add option is not
18690 working properly, debug_print could be used to output the variables it
18691 references. A newline is added to the text if it does not end with one. The
18692 variables $transport_name and $router_name contain the name of the transport
18693 and the router that called it.
18694
18695 +-----------------+---------------+-------------+--------------+
18696 |delivery_date_add|Use: transports|Type: boolean|Default: false|
18697 +-----------------+---------------+-------------+--------------+
18698
18699 If this option is true, a Delivery-date: header is added to the message. This
18700 gives the actual time the delivery was made. As this is not a standard header,
18701 Exim has a configuration option (delivery_date_remove) which requests its
18702 removal from incoming messages, so that delivered messages can safely be resent
18703 to other recipients.
18704
18705 +------+---------------+------------+--------------+
18706 |driver|Use: transports|Type: string|Default: unset|
18707 +------+---------------+------------+--------------+
18708
18709 This specifies which of the available transport drivers is to be used. There is
18710 no default, and this option must be set for every transport.
18711
18712 +---------------+---------------+-------------+--------------+
18713 |envelope_to_add|Use: transports|Type: boolean|Default: false|
18714 +---------------+---------------+-------------+--------------+
18715
18716 If this option is true, an Envelope-to: header is added to the message. This
18717 gives the original address(es) in the incoming envelope that caused this
18718 delivery to happen. More than one address may be present if the transport is
18719 configured to handle several addresses at once, or if more than one original
18720 address was redirected to the same final address. As this is not a standard
18721 header, Exim has a configuration option (envelope_to_remove) which requests its
18722 removal from incoming messages, so that delivered messages can safely be resent
18723 to other recipients.
18724
18725 +-----+---------------+-------------+-------------------+
18726 |group|Use: transports|Type: string*|Default: Exim group|
18727 +-----+---------------+-------------+-------------------+
18728
18729 This option specifies a gid for running the transport process, overriding any
18730 value that the router supplies, and also overriding any value associated with
18731 user (see below).
18732
18733 +-----------+---------------+-----------+--------------+
18734 |headers_add|Use: transports|Type: list*|Default: unset|
18735 +-----------+---------------+-----------+--------------+
18736
18737 This option specifies a list of text headers, newline-separated, which are
18738 (separately) expanded and added to the header portion of a message as it is
18739 transported, as described in section 46.17. Additional header lines can also be
18740 specified by routers. If the result of the expansion is an empty string, or if
18741 the expansion is forced to fail, no action is taken. Other expansion failures
18742 are treated as errors and cause the delivery to be deferred.
18743
18744 Unlike most options, headers_add can be specified multiple times for a
18745 transport; all listed headers are added.
18746
18747 +------------+---------------+-------------+--------------+
18748 |headers_only|Use: transports|Type: boolean|Default: false|
18749 +------------+---------------+-------------+--------------+
18750
18751 If this option is set, the message's body is not transported. It is mutually
18752 exclusive with body_only. If it is used with the appendfile or pipe transports,
18753 the settings of message_prefix and message_suffix should be checked, since this
18754 option does not automatically suppress them.
18755
18756 +--------------+---------------+-----------+--------------+
18757 |headers_remove|Use: transports|Type: list*|Default: unset|
18758 +--------------+---------------+-----------+--------------+
18759
18760 This option specifies a list of header names, colon-separated; these headers
18761 are omitted from the message as it is transported, as described in section
18762 46.17. Header removal can also be specified by routers. Each list item is
18763 separately expanded. If the result of the expansion is an empty string, or if
18764 the expansion is forced to fail, no action is taken. Other expansion failures
18765 are treated as errors and cause the delivery to be deferred.
18766
18767 Unlike most options, headers_remove can be specified multiple times for a
18768 router; all listed headers are removed.
18769
18770 +---------------+---------------+------------+--------------+
18771 |headers_rewrite|Use: transports|Type: string|Default: unset|
18772 +---------------+---------------+------------+--------------+
18773
18774 This option allows addresses in header lines to be rewritten at transport time,
18775 that is, as the message is being copied to its destination. The contents of the
18776 option are a colon-separated list of rewriting rules. Each rule is in exactly
18777 the same form as one of the general rewriting rules that are applied when a
18778 message is received. These are described in chapter 31. For example,
18779
18780 headers_rewrite = a@b c@d f : \
18781 x@y w@z
18782
18783 changes a@b into c@d in From: header lines, and x@y into w@z in all
18784 address-bearing header lines. The rules are applied to the header lines just
18785 before they are written out at transport time, so they affect only those copies
18786 of the message that pass through the transport. However, only the message's
18787 original header lines, and any that were added by a system filter, are
18788 rewritten. If a router or transport adds header lines, they are not affected by
18789 this option. These rewriting rules are not applied to the envelope. You can
18790 change the return path using return_path, but you cannot change envelope
18791 recipients at this time.
18792
18793 +--------------+---------------+-------------+--------------+
18794 |home_directory|Use: transports|Type: string*|Default: unset|
18795 +--------------+---------------+-------------+--------------+
18796
18797 This option specifies a home directory setting for a local transport,
18798 overriding any value that may be set by the router. The home directory is
18799 placed in $home while expanding the transport's private options. It is also
18800 used as the current directory if no current directory is set by the
18801 current_directory option on the transport or the transport_current_directory
18802 option on the router. If the expansion fails for any reason, including forced
18803 failure, an error is logged, and delivery is deferred.
18804
18805 +----------+---------------+-------------+--------------+
18806 |initgroups|Use: transports|Type: boolean|Default: false|
18807 +----------+---------------+-------------+--------------+
18808
18809 If this option is true and the uid for the delivery process is provided by the
18810 transport, the initgroups() function is called when running the transport to
18811 ensure that any additional groups associated with the uid are set up.
18812
18813 +------------------+---------------+-------------+----------+
18814 |message_size_limit|Use: transports|Type: string*|Default: 0|
18815 +------------------+---------------+-------------+----------+
18816
18817 This option controls the size of messages passed through the transport. It is
18818 expanded before use; the result of the expansion must be a sequence of decimal
18819 digits, optionally followed by K or M. If the expansion fails for any reason,
18820 including forced failure, or if the result is not of the required form,
18821 delivery is deferred. If the value is greater than zero and the size of a
18822 message exceeds this limit, the address is failed. If there is any chance that
18823 the resulting bounce message could be routed to the same transport, you should
18824 ensure that return_size_limit is less than the transport's message_size_limit,
18825 as otherwise the bounce message will fail to get delivered.
18826
18827 +--------------------+---------------+-------------+--------------+
18828 |rcpt_include_affixes|Use: transports|Type: boolean|Default: false|
18829 +--------------------+---------------+-------------+--------------+
18830
18831 When this option is false (the default), and an address that has had any
18832 affixes (prefixes or suffixes) removed from the local part is delivered by any
18833 form of SMTP or LMTP, the affixes are not included. For example, if a router
18834 that contains
18835
18836 local_part_prefix = *-
18837
18838 routes the address abc-xyz@some.domain to an SMTP transport, the envelope is
18839 delivered with
18840
18841 RCPT TO:<xyz@some.domain>
18842
18843 This is also the case when an ACL-time callout is being used to verify a
18844 recipient address. However, if rcpt_include_affixes is set true, the whole
18845 local part is included in the RCPT command. This option applies to BSMTP
18846 deliveries by the appendfile and pipe transports as well as to the lmtp and
18847 smtp transports.
18848
18849 +--------------------+---------------+-------------+------------------+
18850 |retry_use_local_part|Use: transports|Type: boolean|Default: see below|
18851 +--------------------+---------------+-------------+------------------+
18852
18853 When a delivery suffers a temporary failure, a retry record is created in
18854 Exim's hints database. For remote deliveries, the key for the retry record is
18855 based on the name and/or IP address of the failing remote host. For local
18856 deliveries, the key is normally the entire address, including both the local
18857 part and the domain. This is suitable for most common cases of local delivery
18858 temporary failure - for example, exceeding a mailbox quota should delay only
18859 deliveries to that mailbox, not to the whole domain.
18860
18861 However, in some special cases you may want to treat a temporary local delivery
18862 as a failure associated with the domain, and not with a particular local part.
18863 (For example, if you are storing all mail for some domain in files.) You can do
18864 this by setting retry_use_local_part false.
18865
18866 For all the local transports, its default value is true. For remote transports,
18867 the default value is false for tidiness, but changing the value has no effect
18868 on a remote transport in the current implementation.
18869
18870 +-----------+---------------+-------------+--------------+
18871 |return_path|Use: transports|Type: string*|Default: unset|
18872 +-----------+---------------+-------------+--------------+
18873
18874 If this option is set, the string is expanded at transport time and replaces
18875 the existing return path (envelope sender) value in the copy of the message
18876 that is being delivered. An empty return path is permitted. This feature is
18877 designed for remote deliveries, where the value of this option is used in the
18878 SMTP MAIL command. If you set return_path for a local transport, the only
18879 effect is to change the address that is placed in the Return-path: header line,
18880 if one is added to the message (see the next option).
18881
18882 Note: A changed return path is not logged unless you add
18883 return_path_on_delivery to the log selector.
18884
18885 The expansion can refer to the existing value via $return_path. This is either
18886 the message's envelope sender, or an address set by the errors_to option on a
18887 router. If the expansion is forced to fail, no replacement occurs; if it fails
18888 for another reason, delivery is deferred. This option can be used to support
18889 VERP (Variable Envelope Return Paths) - see section 49.6.
18890
18891 Note: If a delivery error is detected locally, including the case when a remote
18892 server rejects a message at SMTP time, the bounce message is not sent to the
18893 value of this option. It is sent to the previously set errors address. This
18894 defaults to the incoming sender address, but can be changed by setting
18895 errors_to in a router.
18896
18897 +---------------+---------------+-------------+--------------+
18898 |return_path_add|Use: transports|Type: boolean|Default: false|
18899 +---------------+---------------+-------------+--------------+
18900
18901 If this option is true, a Return-path: header is added to the message. Although
18902 the return path is normally available in the prefix line of BSD mailboxes, this
18903 is commonly not displayed by MUAs, and so the user does not have easy access to
18904 it.
18905
18906 RFC 2821 states that the Return-path: header is added to a message "when the
18907 delivery SMTP server makes the final delivery". This implies that this header
18908 should not be present in incoming messages. Exim has a configuration option,
18909 return_path_remove, which requests removal of this header from incoming
18910 messages, so that delivered messages can safely be resent to other recipients.
18911
18912 +----------------+---------------+-------------+--------------+
18913 |shadow_condition|Use: transports|Type: string*|Default: unset|
18914 +----------------+---------------+-------------+--------------+
18915
18916 See shadow_transport below.
18917
18918 +----------------+---------------+------------+--------------+
18919 |shadow_transport|Use: transports|Type: string|Default: unset|
18920 +----------------+---------------+------------+--------------+
18921
18922 A local transport may set the shadow_transport option to the name of another
18923 local transport. Shadow remote transports are not supported.
18924
18925 Whenever a delivery to the main transport succeeds, and either shadow_condition
18926 is unset, or its expansion does not result in the empty string or one of the
18927 strings "0" or "no" or "false", the message is also passed to the shadow
18928 transport, with the same delivery address or addresses. If expansion fails, no
18929 action is taken except that non-forced expansion failures cause a log line to
18930 be written.
18931
18932 The result of the shadow transport is discarded and does not affect the
18933 subsequent processing of the message. Only a single level of shadowing is
18934 provided; the shadow_transport option is ignored on any transport when it is
18935 running as a shadow. Options concerned with output from pipes are also ignored.
18936 The log line for the successful delivery has an item added on the end, of the
18937 form
18938
18939 ST=<shadow transport name>
18940
18941 If the shadow transport did not succeed, the error message is put in
18942 parentheses afterwards. Shadow transports can be used for a number of different
18943 purposes, including keeping more detailed log information than Exim normally
18944 provides, and implementing automatic acknowledgment policies based on message
18945 headers that some sites insist on.
18946
18947 +----------------+---------------+-------------+--------------+
18948 |transport_filter|Use: transports|Type: string*|Default: unset|
18949 +----------------+---------------+-------------+--------------+
18950
18951 This option sets up a filtering (in the Unix shell sense) process for messages
18952 at transport time. It should not be confused with mail filtering as set up by
18953 individual users or via a system filter.
18954
18955 When the message is about to be written out, the command specified by
18956 transport_filter is started up in a separate, parallel process, and the entire
18957 message, including the header lines, is passed to it on its standard input
18958 (this in fact is done from a third process, to avoid deadlock). The command
18959 must be specified as an absolute path.
18960
18961 The lines of the message that are written to the transport filter are
18962 terminated by newline ("\n"). The message is passed to the filter before any
18963 SMTP-specific processing, such as turning "\n" into "\r\n" and escaping lines
18964 beginning with a dot, and also before any processing implied by the settings of
18965 check_string and escape_string in the appendfile or pipe transports.
18966
18967 The standard error for the filter process is set to the same destination as its
18968 standard output; this is read and written to the message's ultimate
18969 destination. The process that writes the message to the filter, the filter
18970 itself, and the original process that reads the result and delivers it are all
18971 run in parallel, like a shell pipeline.
18972
18973 The filter can perform any transformations it likes, but of course should take
18974 care not to break RFC 2822 syntax. Exim does not check the result, except to
18975 test for a final newline when SMTP is in use. All messages transmitted over
18976 SMTP must end with a newline, so Exim supplies one if it is missing.
18977
18978 A transport filter can be used to provide content-scanning on a per-user basis
18979 at delivery time if the only required effect of the scan is to modify the
18980 message. For example, a content scan could insert a new header line containing
18981 a spam score. This could be interpreted by a filter in the user's MUA. It is
18982 not possible to discard a message at this stage.
18983
18984 A problem might arise if the filter increases the size of a message that is
18985 being sent down an SMTP connection. If the receiving SMTP server has indicated
18986 support for the SIZE parameter, Exim will have sent the size of the message at
18987 the start of the SMTP session. If what is actually sent is substantially more,
18988 the server might reject the message. This can be worked round by setting the
18989 size_addition option on the smtp transport, either to allow for additions to
18990 the message, or to disable the use of SIZE altogether.
18991
18992 The value of the transport_filter option is the command string for starting the
18993 filter, which is run directly from Exim, not under a shell. The string is
18994 parsed by Exim in the same way as a command string for the pipe transport: Exim
18995 breaks it up into arguments and then expands each argument separately (see
18996 section 29.3). Any kind of expansion failure causes delivery to be deferred.
18997 The special argument $pipe_addresses is replaced by a number of arguments, one
18998 for each address that applies to this delivery. (This isn't an ideal name for
18999 this feature here, but as it was already implemented for the pipe transport, it
19000 seemed sensible not to change it.)
19001
19002 The expansion variables $host and $host_address are available when the
19003 transport is a remote one. They contain the name and IP address of the host to
19004 which the message is being sent. For example:
19005
19006 transport_filter = /some/directory/transport-filter.pl \
19007 $host $host_address $sender_address $pipe_addresses
19008
19009 Two problems arise if you want to use more complicated expansion items to
19010 generate transport filter commands, both of which due to the fact that the
19011 command is split up before expansion.
19012
19013 * If an expansion item contains white space, you must quote it, so that it is
19014 all part of the same command item. If the entire option setting is one such
19015 expansion item, you have to take care what kind of quoting you use. For
19016 example:
19017
19018 transport_filter = '/bin/cmd${if eq{$host}{a.b.c}{1}{2}}'
19019
19020 This runs the command /bin/cmd1 if the host name is a.b.c, and /bin/cmd2
19021 otherwise. If double quotes had been used, they would have been stripped by
19022 Exim when it read the option's value. When the value is used, if the single
19023 quotes were missing, the line would be split into two items, "/bin/cmd${if"
19024 and "eq{$host}{a.b.c}{1}{2}", and an error would occur when Exim tried to
19025 expand the first one.
19026
19027 * Except for the special case of $pipe_addresses that is mentioned above, an
19028 expansion cannot generate multiple arguments, or a command name followed by
19029 arguments. Consider this example:
19030
19031 transport_filter = ${lookup{$host}lsearch{/a/file}\
19032 {$value}{/bin/cat}}
19033
19034 The result of the lookup is interpreted as the name of the command, even if
19035 it contains white space. The simplest way round this is to use a shell:
19036
19037 transport_filter = /bin/sh -c ${lookup{$host}lsearch{/a/file}\
19038 {$value}{/bin/cat}}
19039
19040 The filter process is run under the same uid and gid as the normal delivery.
19041 For remote deliveries this is the Exim uid/gid by default. The command should
19042 normally yield a zero return code. Transport filters are not supposed to fail.
19043 A non-zero code is taken to mean that the transport filter encountered some
19044 serious problem. Delivery of the message is deferred; the message remains on
19045 the queue and is tried again later. It is not possible to cause a message to be
19046 bounced from a transport filter.
19047
19048 If a transport filter is set on an autoreply transport, the original message is
19049 passed through the filter as it is being copied into the newly generated
19050 message, which happens if the return_message option is set.
19051
19052 +------------------------+---------------+----------+-----------+
19053 |transport_filter_timeout|Use: transports|Type: time|Default: 5m|
19054 +------------------------+---------------+----------+-----------+
19055
19056 When Exim is reading the output of a transport filter, it applies a timeout
19057 that can be set by this option. Exceeding the timeout is normally treated as a
19058 temporary delivery failure. However, if a transport filter is used with a pipe
19059 transport, a timeout in the transport filter is treated in the same way as a
19060 timeout in the pipe command itself. By default, a timeout is a hard error, but
19061 if the pipe transport's timeout_defer option is set true, it becomes a
19062 temporary error.
19063
19064 +----+---------------+-------------+------------------+
19065 |user|Use: transports|Type: string*|Default: Exim user|
19066 +----+---------------+-------------+------------------+
19067
19068 This option specifies the user under whose uid the delivery process is to be
19069 run, overriding any uid that may have been set by the router. If the user is
19070 given as a name, the uid is looked up from the password data, and the
19071 associated group is taken as the value of the gid to be used if the group
19072 option is not set.
19073
19074 For deliveries that use local transports, a user and group are normally
19075 specified explicitly or implicitly (for example, as a result of
19076 check_local_user) by the router or transport.
19077
19078 For remote transports, you should leave this option unset unless you really are
19079 sure you know what you are doing. When a remote transport is running, it needs
19080 to be able to access Exim's hints databases, because each host may have its own
19081 retry data.
19082
19083
19084
19085 ===============================================================================
19086 25. ADDRESS BATCHING IN LOCAL TRANSPORTS
19087
19088 The only remote transport (smtp) is normally configured to handle more than one
19089 address at a time, so that when several addresses are routed to the same remote
19090 host, just one copy of the message is sent. Local transports, however, normally
19091 handle one address at a time. That is, a separate instance of the transport is
19092 run for each address that is routed to the transport. A separate copy of the
19093 message is delivered each time.
19094
19095 In special cases, it may be desirable to handle several addresses at once in a
19096 local transport, for example:
19097
19098 * In an appendfile transport, when storing messages in files for later
19099 delivery by some other means, a single copy of the message with multiple
19100 recipients saves space.
19101
19102 * In an lmtp transport, when delivering over "local SMTP" to some process, a
19103 single copy saves time, and is the normal way LMTP is expected to work.
19104
19105 * In a pipe transport, when passing the message to a scanner program or to
19106 some other delivery mechanism such as UUCP, multiple recipients may be
19107 acceptable.
19108
19109 These three local transports all have the same options for controlling multiple
19110 ("batched") deliveries, namely batch_max and batch_id. To save repeating the
19111 information for each transport, these options are described here.
19112
19113 The batch_max option specifies the maximum number of addresses that can be
19114 delivered together in a single run of the transport. Its default value is one
19115 (no batching). When more than one address is routed to a transport that has a
19116 batch_max value greater than one, the addresses are delivered in a batch (that
19117 is, in a single run of the transport with multiple recipients), subject to
19118 certain conditions:
19119
19120 * If any of the transport's options contain a reference to $local_part, no
19121 batching is possible.
19122
19123 * If any of the transport's options contain a reference to $domain, only
19124 addresses with the same domain are batched.
19125
19126 * If batch_id is set, it is expanded for each address, and only those
19127 addresses with the same expanded value are batched. This allows you to
19128 specify customized batching conditions. Failure of the expansion for any
19129 reason, including forced failure, disables batching, but it does not stop
19130 the delivery from taking place.
19131
19132 * Batched addresses must also have the same errors address (where to send
19133 delivery errors), the same header additions and removals, the same user and
19134 group for the transport, and if a host list is present, the first host must
19135 be the same.
19136
19137 In the case of the appendfile and pipe transports, batching applies both when
19138 the file or pipe command is specified in the transport, and when it is
19139 specified by a redirect router, but all the batched addresses must of course be
19140 routed to the same file or pipe command. These two transports have an option
19141 called use_bsmtp, which causes them to deliver the message in "batched SMTP"
19142 format, with the envelope represented as SMTP commands. The check_string and
19143 escape_string options are forced to the values
19144
19145 check_string = "."
19146 escape_string = ".."
19147
19148 when batched SMTP is in use. A full description of the batch SMTP mechanism is
19149 given in section 47.10. The lmtp transport does not have a use_bsmtp option,
19150 because it always delivers using the SMTP protocol.
19151
19152 If the generic envelope_to_add option is set for a batching transport, the
19153 Envelope-to: header that is added to the message contains all the addresses
19154 that are being processed together. If you are using a batching appendfile
19155 transport without use_bsmtp, the only way to preserve the recipient addresses
19156 is to set the envelope_to_add option.
19157
19158 If you are using a pipe transport without BSMTP, and setting the transport's
19159 command option, you can include $pipe_addresses as part of the command. This is
19160 not a true variable; it is a bit of magic that causes each of the recipient
19161 addresses to be inserted into the command as a separate argument. This provides
19162 a way of accessing all the addresses that are being delivered in the batch.
19163 Note: This is not possible for pipe commands that are specified by a redirect
19164 router.
19165
19166
19167
19168 ===============================================================================
19169 26. THE APPENDFILE TRANSPORT
19170
19171 The appendfile transport delivers a message by appending it to an existing
19172 file, or by creating an entirely new file in a specified directory. Single
19173 files to which messages are appended can be in the traditional Unix mailbox
19174 format, or optionally in the MBX format supported by the Pine MUA and
19175 University of Washington IMAP daemon, inter alia. When each message is being
19176 delivered as a separate file, "maildir" format can optionally be used to give
19177 added protection against failures that happen part-way through the delivery. A
19178 third form of separate-file delivery known as "mailstore" is also supported.
19179 For all file formats, Exim attempts to create as many levels of directory as
19180 necessary, provided that create_directory is set.
19181
19182 The code for the optional formats is not included in the Exim binary by
19183 default. It is necessary to set SUPPORT_MBX, SUPPORT_MAILDIR and/or
19184 SUPPORT_MAILSTORE in Local/Makefile to have the appropriate code included.
19185
19186 Exim recognizes system quota errors, and generates an appropriate message. Exim
19187 also supports its own quota control within the transport, for use when the
19188 system facility is unavailable or cannot be used for some reason.
19189
19190 If there is an error while appending to a file (for example, quota exceeded or
19191 partition filled), Exim attempts to reset the file's length and last
19192 modification time back to what they were before. If there is an error while
19193 creating an entirely new file, the new file is removed.
19194
19195 Before appending to a file, a number of security checks are made, and the file
19196 is locked. A detailed description is given below, after the list of private
19197 options.
19198
19199 The appendfile transport is most commonly used for local deliveries to users'
19200 mailboxes. However, it can also be used as a pseudo-remote transport for
19201 putting messages into files for remote delivery by some means other than Exim.
19202 "Batch SMTP" format is often used in this case (see the use_bsmtp option).
19203
19204
19205 26.1 The file and directory options
19206 -----------------------------------
19207
19208 The file option specifies a single file, to which the message is appended; the
19209 directory option specifies a directory, in which a new file containing the
19210 message is created. Only one of these two options can be set, and for normal
19211 deliveries to mailboxes, one of them must be set.
19212
19213 However, appendfile is also used for delivering messages to files or
19214 directories whose names (or parts of names) are obtained from alias,
19215 forwarding, or filtering operations (for example, a save command in a user's
19216 Exim filter). When such a transport is running, $local_part contains the local
19217 part that was aliased or forwarded, and $address_file contains the name (or
19218 partial name) of the file or directory generated by the redirection operation.
19219 There are two cases:
19220
19221 * If neither file nor directory is set, the redirection operation must
19222 specify an absolute path (one that begins with "/"). This is the most
19223 common case when users with local accounts use filtering to sort mail into
19224 different folders. See for example, the address_file transport in the
19225 default configuration. If the path ends with a slash, it is assumed to be
19226 the name of a directory. A delivery to a directory can also be forced by
19227 setting maildir_format or mailstore_format.
19228
19229 * If file or directory is set for a delivery from a redirection, it is used
19230 to determine the file or directory name for the delivery. Normally, the
19231 contents of $address_file are used in some way in the string expansion.
19232
19233 As an example of the second case, consider an environment where users do not
19234 have home directories. They may be permitted to use Exim filter commands of the
19235 form:
19236
19237 save folder23
19238
19239 or Sieve filter commands of the form:
19240
19241 require "fileinto";
19242 fileinto "folder23";
19243
19244 In this situation, the expansion of file or directory in the transport must
19245 transform the relative path into an appropriate absolute file name. In the case
19246 of Sieve filters, the name inbox must be handled. It is the name that is used
19247 as a result of a "keep" action in the filter. This example shows one way of
19248 handling this requirement:
19249
19250 file = ${if eq{$address_file}{inbox} \
19251 {/var/mail/$local_part} \
19252 {${if eq{${substr_0_1:$address_file}}{/} \
19253 {$address_file} \
19254 {$home/mail/$address_file} \
19255 }} \
19256 }
19257
19258 With this setting of file, inbox refers to the standard mailbox location,
19259 absolute paths are used without change, and other folders are in the mail
19260 directory within the home directory.
19261
19262 Note 1: While processing an Exim filter, a relative path such as folder23 is
19263 turned into an absolute path if a home directory is known to the router. In
19264 particular, this is the case if check_local_user is set. If you want to prevent
19265 this happening at routing time, you can set router_home_directory empty. This
19266 forces the router to pass the relative path to the transport.
19267
19268 Note 2: An absolute path in $address_file is not treated specially; the file or
19269 directory option is still used if it is set.
19270
19271
19272 26.2 Private options for appendfile
19273 -----------------------------------
19274
19275 +----------+---------------+-------------+--------------+
19276 |allow_fifo|Use: appendfile|Type: boolean|Default: false|
19277 +----------+---------------+-------------+--------------+
19278
19279 Setting this option permits delivery to named pipes (FIFOs) as well as to
19280 regular files. If no process is reading the named pipe at delivery time, the
19281 delivery is deferred.
19282
19283 +-------------+---------------+-------------+--------------+
19284 |allow_symlink|Use: appendfile|Type: boolean|Default: false|
19285 +-------------+---------------+-------------+--------------+
19286
19287 By default, appendfile will not deliver if the path name for the file is that
19288 of a symbolic link. Setting this option relaxes that constraint, but there are
19289 security issues involved in the use of symbolic links. Be sure you know what
19290 you are doing if you set this. Details of exactly what this option affects are
19291 included in the discussion which follows this list of options.
19292
19293 +--------+---------------+-------------+--------------+
19294 |batch_id|Use: appendfile|Type: string*|Default: unset|
19295 +--------+---------------+-------------+--------------+
19296
19297 See the description of local delivery batching in chapter 25. However, batching
19298 is automatically disabled for appendfile deliveries that happen as a result of
19299 forwarding or aliasing or other redirection directly to a file.
19300
19301 +---------+---------------+-------------+----------+
19302 |batch_max|Use: appendfile|Type: integer|Default: 1|
19303 +---------+---------------+-------------+----------+
19304
19305 See the description of local delivery batching in chapter 25.
19306
19307 +-----------+---------------+-------------+--------------+
19308 |check_group|Use: appendfile|Type: boolean|Default: false|
19309 +-----------+---------------+-------------+--------------+
19310
19311 When this option is set, the group owner of the file defined by the file option
19312 is checked to see that it is the same as the group under which the delivery
19313 process is running. The default setting is false because the default file mode
19314 is 0600, which means that the group is irrelevant.
19315
19316 +-----------+---------------+-------------+-------------+
19317 |check_owner|Use: appendfile|Type: boolean|Default: true|
19318 +-----------+---------------+-------------+-------------+
19319
19320 When this option is set, the owner of the file defined by the file option is
19321 checked to ensure that it is the same as the user under which the delivery
19322 process is running.
19323
19324 +------------+---------------+------------+------------------+
19325 |check_string|Use: appendfile|Type: string|Default: see below|
19326 +------------+---------------+------------+------------------+
19327
19328 As appendfile writes the message, the start of each line is tested for matching
19329 check_string, and if it does, the initial matching characters are replaced by
19330 the contents of escape_string. The value of check_string is a literal string,
19331 not a regular expression, and the case of any letters it contains is
19332 significant.
19333
19334 If use_bsmtp is set the values of check_string and escape_string are forced to
19335 "." and ".." respectively, and any settings in the configuration are ignored.
19336 Otherwise, they default to "From " and ">From " when the file option is set,
19337 and unset when any of the directory, maildir, or mailstore options are set.
19338
19339 The default settings, along with message_prefix and message_suffix, are
19340 suitable for traditional "BSD" mailboxes, where a line beginning with "From "
19341 indicates the start of a new message. All four options need changing if another
19342 format is used. For example, to deliver to mailboxes in MMDF format:
19343
19344 check_string = "\1\1\1\1\n"
19345 escape_string = "\1\1\1\1 \n"
19346 message_prefix = "\1\1\1\1\n"
19347 message_suffix = "\1\1\1\1\n"
19348
19349 +----------------+---------------+-------------+-------------+
19350 |create_directory|Use: appendfile|Type: boolean|Default: true|
19351 +----------------+---------------+-------------+-------------+
19352
19353 When this option is true, Exim attempts to create any missing superior
19354 directories for the file that it is about to write. A created directory's mode
19355 is given by the directory_mode option.
19356
19357 The group ownership of a newly created directory is highly dependent on the
19358 operating system (and possibly the file system) that is being used. For
19359 example, in Solaris, if the parent directory has the setgid bit set, its group
19360 is propagated to the child; if not, the currently set group is used. However,
19361 in FreeBSD, the parent's group is always used.
19362
19363 +-----------+---------------+------------+-----------------+
19364 |create_file|Use: appendfile|Type: string|Default: anywhere|
19365 +-----------+---------------+------------+-----------------+
19366
19367 This option constrains the location of files and directories that are created
19368 by this transport. It applies to files defined by the file option and
19369 directories defined by the directory option. In the case of maildir delivery,
19370 it applies to the top level directory, not the maildir directories beneath.
19371
19372 The option must be set to one of the words "anywhere", "inhome", or
19373 "belowhome". In the second and third cases, a home directory must have been set
19374 for the transport. This option is not useful when an explicit file name is
19375 given for normal mailbox deliveries. It is intended for the case when file
19376 names are generated from users' .forward files. These are usually handled by an
19377 appendfile transport called address_file. See also file_must_exist.
19378
19379 +---------+---------------+-------------+--------------+
19380 |directory|Use: appendfile|Type: string*|Default: unset|
19381 +---------+---------------+-------------+--------------+
19382
19383 This option is mutually exclusive with the file option, but one of file or
19384 directory must be set, unless the delivery is the direct result of a
19385 redirection (see section 26.1).
19386
19387 When directory is set, the string is expanded, and the message is delivered
19388 into a new file or files in or below the given directory, instead of being
19389 appended to a single mailbox file. A number of different formats are provided
19390 (see maildir_format and mailstore_format), and see section 26.4 for further
19391 details of this form of delivery.
19392
19393 +--------------+---------------+-------------+------------------+
19394 |directory_file|Use: appendfile|Type: string*|Default: see below|
19395 +--------------+---------------+-------------+------------------+
19396
19397 When directory is set, but neither maildir_format nor mailstore_format is set,
19398 appendfile delivers each message into a file whose name is obtained by
19399 expanding this string. The default value is:
19400
19401 q${base62:$tod_epoch}-$inode
19402
19403 This generates a unique name from the current time, in base 62 form, and the
19404 inode of the file. The variable $inode is available only when expanding this
19405 option.
19406
19407 +--------------+---------------+-------------------+-------------+
19408 |directory_mode|Use: appendfile|Type: octal integer|Default: 0700|
19409 +--------------+---------------+-------------------+-------------+
19410
19411 If appendfile creates any directories as a result of the create_directory
19412 option, their mode is specified by this option.
19413
19414 +-------------+---------------+------------+------------------------+
19415 |escape_string|Use: appendfile|Type: string|Default: see description|
19416 +-------------+---------------+------------+------------------------+
19417
19418 See check_string above.
19419
19420 +----+---------------+-------------+--------------+
19421 |file|Use: appendfile|Type: string*|Default: unset|
19422 +----+---------------+-------------+--------------+
19423
19424 This option is mutually exclusive with the directory option, but one of file or
19425 directory must be set, unless the delivery is the direct result of a
19426 redirection (see section 26.1). The file option specifies a single file, to
19427 which the message is appended. One or more of use_fcntl_lock, use_flock_lock,
19428 or use_lockfile must be set with file.
19429
19430 If you are using more than one host to deliver over NFS into the same
19431 mailboxes, you should always use lock files.
19432
19433 The string value is expanded for each delivery, and must yield an absolute
19434 path. The most common settings of this option are variations on one of these
19435 examples:
19436
19437 file = /var/spool/mail/$local_part
19438 file = /home/$local_part/inbox
19439 file = $home/inbox
19440
19441 In the first example, all deliveries are done into the same directory. If Exim
19442 is configured to use lock files (see use_lockfile below) it must be able to
19443 create a file in the directory, so the "sticky" bit must be turned on for
19444 deliveries to be possible, or alternatively the group option can be used to run
19445 the delivery under a group id which has write access to the directory.
19446
19447 +-----------+---------------+------------+--------------+
19448 |file_format|Use: appendfile|Type: string|Default: unset|
19449 +-----------+---------------+------------+--------------+
19450
19451 This option requests the transport to check the format of an existing file
19452 before adding to it. The check consists of matching a specific string at the
19453 start of the file. The value of the option consists of an even number of
19454 colon-separated strings. The first of each pair is the test string, and the
19455 second is the name of a transport. If the transport associated with a matched
19456 string is not the current transport, control is passed over to the other
19457 transport. For example, suppose the standard local_delivery transport has this
19458 added to it:
19459
19460 file_format = "From : local_delivery :\
19461 \1\1\1\1\n : local_mmdf_delivery"
19462
19463 Mailboxes that begin with "From" are still handled by this transport, but if a
19464 mailbox begins with four binary ones followed by a newline, control is passed
19465 to a transport called local_mmdf_delivery, which presumably is configured to do
19466 the delivery in MMDF format. If a mailbox does not exist or is empty, it is
19467 assumed to match the current transport. If the start of a mailbox doesn't match
19468 any string, or if the transport named for a given string is not defined,
19469 delivery is deferred.
19470
19471 +---------------+---------------+-------------+--------------+
19472 |file_must_exist|Use: appendfile|Type: boolean|Default: false|
19473 +---------------+---------------+-------------+--------------+
19474
19475 If this option is true, the file specified by the file option must exist. A
19476 temporary error occurs if it does not, causing delivery to be deferred. If this
19477 option is false, the file is created if it does not exist.
19478
19479 +------------------+---------------+----------+-----------+
19480 |lock_fcntl_timeout|Use: appendfile|Type: time|Default: 0s|
19481 +------------------+---------------+----------+-----------+
19482
19483 By default, the appendfile transport uses non-blocking calls to fcntl() when
19484 locking an open mailbox file. If the call fails, the delivery process sleeps
19485 for lock_interval and tries again, up to lock_retries times. Non-blocking calls
19486 are used so that the file is not kept open during the wait for the lock; the
19487 reason for this is to make it as safe as possible for deliveries over NFS in
19488 the case when processes might be accessing an NFS mailbox without using a lock
19489 file. This should not be done, but misunderstandings and hence
19490 misconfigurations are not unknown.
19491
19492 On a busy system, however, the performance of a non-blocking lock approach is
19493 not as good as using a blocking lock with a timeout. In this case, the waiting
19494 is done inside the system call, and Exim's delivery process acquires the lock
19495 and can proceed as soon as the previous lock holder releases it.
19496
19497 If lock_fcntl_timeout is set to a non-zero time, blocking locks, with that
19498 timeout, are used. There may still be some retrying: the maximum number of
19499 retries is
19500
19501 (lock_retries * lock_interval) / lock_fcntl_timeout
19502
19503 rounded up to the next whole number. In other words, the total time during
19504 which appendfile is trying to get a lock is roughly the same, unless
19505 lock_fcntl_timeout is set very large.
19506
19507 You should consider setting this option if you are getting a lot of delayed
19508 local deliveries because of errors of the form
19509
19510 failed to lock mailbox /some/file (fcntl)
19511
19512 +------------------+---------------+----------+-----------+
19513 |lock_flock_timeout|Use: appendfile|Type: time|Default: 0s|
19514 +------------------+---------------+----------+-----------+
19515
19516 This timeout applies to file locking when using flock() (see use_flock); the
19517 timeout operates in a similar manner to lock_fcntl_timeout.
19518
19519 +-------------+---------------+----------+-----------+
19520 |lock_interval|Use: appendfile|Type: time|Default: 3s|
19521 +-------------+---------------+----------+-----------+
19522
19523 This specifies the time to wait between attempts to lock the file. See below
19524 for details of locking.
19525
19526 +------------+---------------+-------------+-----------+
19527 |lock_retries|Use: appendfile|Type: integer|Default: 10|
19528 +------------+---------------+-------------+-----------+
19529
19530 This specifies the maximum number of attempts to lock the file. A value of zero
19531 is treated as 1. See below for details of locking.
19532
19533 +-------------+---------------+-------------------+-------------+
19534 |lockfile_mode|Use: appendfile|Type: octal integer|Default: 0600|
19535 +-------------+---------------+-------------------+-------------+
19536
19537 This specifies the mode of the created lock file, when a lock file is being
19538 used (see use_lockfile and use_mbx_lock).
19539
19540 +----------------+---------------+----------+------------+
19541 |lockfile_timeout|Use: appendfile|Type: time|Default: 30m|
19542 +----------------+---------------+----------+------------+
19543
19544 When a lock file is being used (see use_lockfile), if a lock file already
19545 exists and is older than this value, it is assumed to have been left behind by
19546 accident, and Exim attempts to remove it.
19547
19548 +-----------------+---------------+-------------+--------------+
19549 |mailbox_filecount|Use: appendfile|Type: string*|Default: unset|
19550 +-----------------+---------------+-------------+--------------+
19551
19552 If this option is set, it is expanded, and the result is taken as the current
19553 number of files in the mailbox. It must be a decimal number, optionally
19554 followed by K or M. This provides a way of obtaining this information from an
19555 external source that maintains the data.
19556
19557 +------------+---------------+-------------+--------------+
19558 |mailbox_size|Use: appendfile|Type: string*|Default: unset|
19559 +------------+---------------+-------------+--------------+
19560
19561 If this option is set, it is expanded, and the result is taken as the current
19562 size the mailbox. It must be a decimal number, optionally followed by K or M.
19563 This provides a way of obtaining this information from an external source that
19564 maintains the data. This is likely to be helpful for maildir deliveries where
19565 it is computationally expensive to compute the size of a mailbox.
19566
19567 +--------------+---------------+-------------+--------------+
19568 |maildir_format|Use: appendfile|Type: boolean|Default: false|
19569 +--------------+---------------+-------------+--------------+
19570
19571 If this option is set with the directory option, the delivery is into a new
19572 file, in the "maildir" format that is used by other mail software. When the
19573 transport is activated directly from a redirect router (for example, the
19574 address_file transport in the default configuration), setting maildir_format
19575 causes the path received from the router to be treated as a directory, whether
19576 or not it ends with "/". This option is available only if SUPPORT_MAILDIR is
19577 present in Local/Makefile. See section 26.5 below for further details.
19578
19579 +-----------------------------+---------------+------------+------------------+
19580 |maildir_quota_directory_regex|Use: appendfile|Type: string|Default: See below|
19581 +-----------------------------+---------------+------------+------------------+
19582
19583 This option is relevant only when maildir_use_size_file is set. It defines a
19584 regular expression for specifying directories, relative to the quota directory
19585 (see quota_directory), that should be included in the quota calculation. The
19586 default value is:
19587
19588 maildir_quota_directory_regex = ^(?:cur|new|\..*)$
19589
19590 This includes the cur and new directories, and any maildir++ folders
19591 (directories whose names begin with a dot). If you want to exclude the Trash
19592 folder from the count (as some sites do), you need to change this setting to
19593
19594 maildir_quota_directory_regex = ^(?:cur|new|\.(?!Trash).*)$
19595
19596 This uses a negative lookahead in the regular expression to exclude the
19597 directory whose name is .Trash. When a directory is excluded from quota
19598 calculations, quota processing is bypassed for any messages that are delivered
19599 directly into that directory.
19600
19601 +---------------+---------------+-------------+-----------+
19602 |maildir_retries|Use: appendfile|Type: integer|Default: 10|
19603 +---------------+---------------+-------------+-----------+
19604
19605 This option specifies the number of times to retry when writing a file in
19606 "maildir" format. See section 26.5 below.
19607
19608 +-----------+---------------+-------------+--------------+
19609 |maildir_tag|Use: appendfile|Type: string*|Default: unset|
19610 +-----------+---------------+-------------+--------------+
19611
19612 This option applies only to deliveries in maildir format, and is described in
19613 section 26.5 below.
19614
19615 +---------------------+----------------+-------------+--------------+
19616 |maildir_use_size_file|Use: appendfile*|Type: boolean|Default: false|
19617 +---------------------+----------------+-------------+--------------+
19618
19619 The result of string expansion for this option must be a valid boolean value.
19620 If it is true, it enables support for maildirsize files. Exim creates a
19621 maildirsize file in a maildir if one does not exist, taking the quota from the
19622 quota option of the transport. If quota is unset, the value is zero. See
19623 maildir_quota_directory_regex above and section 26.5 below for further details.
19624
19625 +--------------------------+---------------+------------+--------------+
19626 |maildirfolder_create_regex|Use: appendfile|Type: string|Default: unset|
19627 +--------------------------+---------------+------------+--------------+
19628
19629 The value of this option is a regular expression. If it is unset, it has no
19630 effect. Otherwise, before a maildir delivery takes place, the pattern is
19631 matched against the name of the maildir directory, that is, the directory
19632 containing the new and tmp subdirectories that will be used for the delivery.
19633 If there is a match, Exim checks for the existence of a file called
19634 maildirfolder in the directory, and creates it if it does not exist. See
19635 section 26.5 for more details.
19636
19637 +----------------+---------------+-------------+--------------+
19638 |mailstore_format|Use: appendfile|Type: boolean|Default: false|
19639 +----------------+---------------+-------------+--------------+
19640
19641 If this option is set with the directory option, the delivery is into two new
19642 files in "mailstore" format. The option is available only if SUPPORT_MAILSTORE
19643 is present in Local/Makefile. See section 26.4 below for further details.
19644
19645 +----------------+---------------+-------------+--------------+
19646 |mailstore_prefix|Use: appendfile|Type: string*|Default: unset|
19647 +----------------+---------------+-------------+--------------+
19648
19649 This option applies only to deliveries in mailstore format, and is described in
19650 section 26.4 below.
19651
19652 +----------------+---------------+-------------+--------------+
19653 |mailstore_suffix|Use: appendfile|Type: string*|Default: unset|
19654 +----------------+---------------+-------------+--------------+
19655
19656 This option applies only to deliveries in mailstore format, and is described in
19657 section 26.4 below.
19658
19659 +----------+---------------+-------------+--------------+
19660 |mbx_format|Use: appendfile|Type: boolean|Default: false|
19661 +----------+---------------+-------------+--------------+
19662
19663 This option is available only if Exim has been compiled with SUPPORT_MBX set in
19664 Local/Makefile. If mbx_format is set with the file option, the message is
19665 appended to the mailbox file in MBX format instead of traditional Unix format.
19666 This format is supported by Pine4 and its associated IMAP and POP daemons, by
19667 means of the c-client library that they all use.
19668
19669 Note: The message_prefix and message_suffix options are not automatically
19670 changed by the use of mbx_format. They should normally be set empty when using
19671 MBX format, so this option almost always appears in this combination:
19672
19673 mbx_format = true
19674 message_prefix =
19675 message_suffix =
19676
19677 If none of the locking options are mentioned in the configuration, use_mbx_lock
19678 is assumed and the other locking options default to false. It is possible to
19679 specify the other kinds of locking with mbx_format, but use_fcntl_lock and
19680 use_mbx_lock are mutually exclusive. MBX locking interworks with c-client,
19681 providing for shared access to the mailbox. It should not be used if any
19682 program that does not use this form of locking is going to access the mailbox,
19683 nor should it be used if the mailbox file is NFS mounted, because it works only
19684 when the mailbox is accessed from a single host.
19685
19686 If you set use_fcntl_lock with an MBX-format mailbox, you cannot use the
19687 standard version of c-client, because as long as it has a mailbox open (this
19688 means for the whole of a Pine or IMAP session), Exim will not be able to append
19689 messages to it.
19690
19691 +--------------+---------------+-------------+------------------+
19692 |message_prefix|Use: appendfile|Type: string*|Default: see below|
19693 +--------------+---------------+-------------+------------------+
19694
19695 The string specified here is expanded and output at the start of every message.
19696 The default is unset unless file is specified and use_bsmtp is not set, in
19697 which case it is:
19698
19699 message_prefix = "From ${if def:return_path{$return_path}\
19700 {MAILER-DAEMON}} $tod_bsdinbox\n"
19701
19702 Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\
19703 n" in message_prefix.
19704
19705 +--------------+---------------+-------------+------------------+
19706 |message_suffix|Use: appendfile|Type: string*|Default: see below|
19707 +--------------+---------------+-------------+------------------+
19708
19709 The string specified here is expanded and output at the end of every message.
19710 The default is unset unless file is specified and use_bsmtp is not set, in
19711 which case it is a single newline character. The suffix can be suppressed by
19712 setting
19713
19714 message_suffix =
19715
19716 Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\
19717 n" in message_suffix.
19718
19719 +----+---------------+-------------------+-------------+
19720 |mode|Use: appendfile|Type: octal integer|Default: 0600|
19721 +----+---------------+-------------------+-------------+
19722
19723 If the output file is created, it is given this mode. If it already exists and
19724 has wider permissions, they are reduced to this mode. If it has narrower
19725 permissions, an error occurs unless mode_fail_narrower is false. However, if
19726 the delivery is the result of a save command in a filter file specifying a
19727 particular mode, the mode of the output file is always forced to take that
19728 value, and this option is ignored.
19729
19730 +------------------+---------------+-------------+-------------+
19731 |mode_fail_narrower|Use: appendfile|Type: boolean|Default: true|
19732 +------------------+---------------+-------------+-------------+
19733
19734 This option applies in the case when an existing mailbox file has a narrower
19735 mode than that specified by the mode option. If mode_fail_narrower is true, the
19736 delivery is deferred ("mailbox has the wrong mode"); otherwise Exim continues
19737 with the delivery attempt, using the existing mode of the file.
19738
19739 +-------------+---------------+-------------+--------------+
19740 |notify_comsat|Use: appendfile|Type: boolean|Default: false|
19741 +-------------+---------------+-------------+--------------+
19742
19743 If this option is true, the comsat daemon is notified after every successful
19744 delivery to a user mailbox. This is the daemon that notifies logged on users
19745 about incoming mail.
19746
19747 +-----+---------------+-------------+--------------+
19748 |quota|Use: appendfile|Type: string*|Default: unset|
19749 +-----+---------------+-------------+--------------+
19750
19751 This option imposes a limit on the size of the file to which Exim is appending,
19752 or to the total space used in the directory tree when the directory option is
19753 set. In the latter case, computation of the space used is expensive, because
19754 all the files in the directory (and any sub-directories) have to be
19755 individually inspected and their sizes summed. (See quota_size_regex and
19756 maildir_use_size_file for ways to avoid this in environments where users have
19757 no shell access to their mailboxes).
19758
19759 As there is no interlock against two simultaneous deliveries into a multi-file
19760 mailbox, it is possible for the quota to be overrun in this case. For
19761 single-file mailboxes, of course, an interlock is a necessity.
19762
19763 A file's size is taken as its used value. Because of blocking effects, this may
19764 be a lot less than the actual amount of disk space allocated to the file. If
19765 the sizes of a number of files are being added up, the rounding effect can
19766 become quite noticeable, especially on systems that have large block sizes.
19767 Nevertheless, it seems best to stick to the used figure, because this is the
19768 obvious value which users understand most easily.
19769
19770 The value of the option is expanded, and must then be a numerical value
19771 (decimal point allowed), optionally followed by one of the letters K, M, or G,
19772 for kilobytes, megabytes, or gigabytes. If Exim is running on a system with
19773 large file support (Linux and FreeBSD have this), mailboxes larger than 2G can
19774 be handled.
19775
19776 Note: A value of zero is interpreted as "no quota".
19777
19778 The expansion happens while Exim is running as root, before it changes uid for
19779 the delivery. This means that files that are inaccessible to the end user can
19780 be used to hold quota values that are looked up in the expansion. When delivery
19781 fails because this quota is exceeded, the handling of the error is as for
19782 system quota failures.
19783
19784 By default, Exim's quota checking mimics system quotas, and restricts the
19785 mailbox to the specified maximum size, though the value is not accurate to the
19786 last byte, owing to separator lines and additional headers that may get added
19787 during message delivery. When a mailbox is nearly full, large messages may get
19788 refused even though small ones are accepted, because the size of the current
19789 message is added to the quota when the check is made. This behaviour can be
19790 changed by setting quota_is_inclusive false. When this is done, the check for
19791 exceeding the quota does not include the current message. Thus, deliveries
19792 continue until the quota has been exceeded; thereafter, no further messages are
19793 delivered. See also quota_warn_threshold.
19794
19795 +---------------+---------------+-------------+--------------+
19796 |quota_directory|Use: appendfile|Type: string*|Default: unset|
19797 +---------------+---------------+-------------+--------------+
19798
19799 This option defines the directory to check for quota purposes when delivering
19800 into individual files. The default is the delivery directory, or, if a file
19801 called maildirfolder exists in a maildir directory, the parent of the delivery
19802 directory.
19803
19804 +---------------+---------------+-------------+----------+
19805 |quota_filecount|Use: appendfile|Type: string*|Default: 0|
19806 +---------------+---------------+-------------+----------+
19807
19808 This option applies when the directory option is set. It limits the total
19809 number of files in the directory (compare the inode limit in system quotas). It
19810 can only be used if quota is also set. The value is expanded; an expansion
19811 failure causes delivery to be deferred. A value of zero is interpreted as "no
19812 quota".
19813
19814 +------------------+---------------+-------------+-------------+
19815 |quota_is_inclusive|Use: appendfile|Type: boolean|Default: true|
19816 +------------------+---------------+-------------+-------------+
19817
19818 See quota above.
19819
19820 +----------------+---------------+------------+--------------+
19821 |quota_size_regex|Use: appendfile|Type: string|Default: unset|
19822 +----------------+---------------+------------+--------------+
19823
19824 This option applies when one of the delivery modes that writes a separate file
19825 for each message is being used. When Exim wants to find the size of one of
19826 these files in order to test the quota, it first checks quota_size_regex. If
19827 this is set to a regular expression that matches the file name, and it captures
19828 one string, that string is interpreted as a representation of the file's size.
19829 The value of quota_size_regex is not expanded.
19830
19831 This feature is useful only when users have no shell access to their mailboxes
19832 - otherwise they could defeat the quota simply by renaming the files. This
19833 facility can be used with maildir deliveries, by setting maildir_tag to add the
19834 file length to the file name. For example:
19835
19836 maildir_tag = ,S=$message_size
19837 quota_size_regex = ,S=(\d+)
19838
19839 An alternative to $message_size is $message_linecount, which contains the
19840 number of lines in the message.
19841
19842 The regular expression should not assume that the length is at the end of the
19843 file name (even though maildir_tag puts it there) because maildir MUAs
19844 sometimes add other information onto the ends of message file names.
19845
19846 Section 26.7 contains further information.
19847
19848 +------------------+---------------+-------------+------------------+
19849 |quota_warn_message|Use: appendfile|Type: string*|Default: see below|
19850 +------------------+---------------+-------------+------------------+
19851
19852 See below for the use of this option. If it is not set when
19853 quota_warn_threshold is set, it defaults to
19854
19855 quota_warn_message = "\
19856 To: $local_part@$domain\n\
19857 Subject: Your mailbox\n\n\
19858 This message is automatically created \
19859 by mail delivery software.\n\n\
19860 The size of your mailbox has exceeded \
19861 a warning threshold that is\n\
19862 set by the system administrator.\n"
19863
19864 +--------------------+---------------+-------------+----------+
19865 |quota_warn_threshold|Use: appendfile|Type: string*|Default: 0|
19866 +--------------------+---------------+-------------+----------+
19867
19868 This option is expanded in the same way as quota (see above). If the resulting
19869 value is greater than zero, and delivery of the message causes the size of the
19870 file or total space in the directory tree to cross the given threshold, a
19871 warning message is sent. If quota is also set, the threshold may be specified
19872 as a percentage of it by following the value with a percent sign. For example:
19873
19874 quota = 10M
19875 quota_warn_threshold = 75%
19876
19877 If quota is not set, a setting of quota_warn_threshold that ends with a percent
19878 sign is ignored.
19879
19880 The warning message itself is specified by the quota_warn_message option, and
19881 it must start with a To: header line containing the recipient(s) of the warning
19882 message. These do not necessarily have to include the recipient(s) of the
19883 original message. A Subject: line should also normally be supplied. You can
19884 include any other header lines that you want. If you do not include a From:
19885 line, the default is:
19886
19887 From: Mail Delivery System <mailer-daemon@$qualify_domain_sender>
19888
19889 If you supply a Reply-To: line, it overrides the global errors_reply_to option.
19890
19891 The quota option does not have to be set in order to use this option; they are
19892 independent of one another except when the threshold is specified as a
19893 percentage.
19894
19895 +---------+---------------+-------------+--------------+
19896 |use_bsmtp|Use: appendfile|Type: boolean|Default: false|
19897 +---------+---------------+-------------+--------------+
19898
19899 If this option is set true, appendfile writes messages in "batch SMTP" format,
19900 with the envelope sender and recipient(s) included as SMTP commands. If you
19901 want to include a leading HELO command with such messages, you can do so by
19902 setting the message_prefix option. See section 47.10 for details of batch SMTP.
19903
19904 +--------+---------------+-------------+--------------+
19905 |use_crlf|Use: appendfile|Type: boolean|Default: false|
19906 +--------+---------------+-------------+--------------+
19907
19908 This option causes lines to be terminated with the two-character CRLF sequence
19909 (carriage return, linefeed) instead of just a linefeed character. In the case
19910 of batched SMTP, the byte sequence written to the file is then an exact image
19911 of what would be sent down a real SMTP connection.
19912
19913 Note: The contents of the message_prefix and message_suffix options (which are
19914 used to supply the traditional "From " and blank line separators in
19915 Berkeley-style mailboxes) are written verbatim, so must contain their own
19916 carriage return characters if these are needed. In cases where these options
19917 have non-empty defaults, the values end with a single linefeed, so they must be
19918 changed to end with "\r\n" if use_crlf is set.
19919
19920 +--------------+---------------+-------------+------------------+
19921 |use_fcntl_lock|Use: appendfile|Type: boolean|Default: see below|
19922 +--------------+---------------+-------------+------------------+
19923
19924 This option controls the use of the fcntl() function to lock a file for
19925 exclusive use when a message is being appended. It is set by default unless
19926 use_flock_lock is set. Otherwise, it should be turned off only if you know that
19927 all your MUAs use lock file locking. When both use_fcntl_lock and
19928 use_flock_lock are unset, use_lockfile must be set.
19929
19930 +--------------+---------------+-------------+--------------+
19931 |use_flock_lock|Use: appendfile|Type: boolean|Default: false|
19932 +--------------+---------------+-------------+--------------+
19933
19934 This option is provided to support the use of flock() for file locking, for the
19935 few situations where it is needed. Most modern operating systems support fcntl
19936 () and lockf() locking, and these two functions interwork with each other. Exim
19937 uses fcntl() locking by default.
19938
19939 This option is required only if you are using an operating system where flock()
19940 is used by programs that access mailboxes (typically MUAs), and where flock()
19941 does not correctly interwork with fcntl(). You can use both fcntl() and flock()
19942 locking simultaneously if you want.
19943
19944 Not all operating systems provide flock(). Some versions of Solaris do not have
19945 it (and some, I think, provide a not quite right version built on top of lockf
19946 ()). If the OS does not have flock(), Exim will be built without the ability to
19947 use it, and any attempt to do so will cause a configuration error.
19948
19949 Warning: flock() locks do not work on NFS files (unless flock() is just being
19950 mapped onto fcntl() by the OS).
19951
19952 +------------+---------------+-------------+------------------+
19953 |use_lockfile|Use: appendfile|Type: boolean|Default: see below|
19954 +------------+---------------+-------------+------------------+
19955
19956 If this option is turned off, Exim does not attempt to create a lock file when
19957 appending to a mailbox file. In this situation, the only locking is by fcntl().
19958 You should only turn use_lockfile off if you are absolutely sure that every MUA
19959 that is ever going to look at your users' mailboxes uses fcntl() rather than a
19960 lock file, and even then only when you are not delivering over NFS from more
19961 than one host.
19962
19963 In order to append to an NFS file safely from more than one host, it is
19964 necessary to take out a lock before opening the file, and the lock file
19965 achieves this. Otherwise, even with fcntl() locking, there is a risk of file
19966 corruption.
19967
19968 The use_lockfile option is set by default unless use_mbx_lock is set. It is not
19969 possible to turn both use_lockfile and use_fcntl_lock off, except when
19970 mbx_format is set.
19971
19972 +------------+---------------+-------------+------------------+
19973 |use_mbx_lock|Use: appendfile|Type: boolean|Default: see below|
19974 +------------+---------------+-------------+------------------+
19975
19976 This option is available only if Exim has been compiled with SUPPORT_MBX set in
19977 Local/Makefile. Setting the option specifies that special MBX locking rules be
19978 used. It is set by default if mbx_format is set and none of the locking options
19979 are mentioned in the configuration. The locking rules are the same as are used
19980 by the c-client library that underlies Pine and the IMAP4 and POP daemons that
19981 come with it (see the discussion below). The rules allow for shared access to
19982 the mailbox. However, this kind of locking does not work when the mailbox is
19983 NFS mounted.
19984
19985 You can set use_mbx_lock with either (or both) of use_fcntl_lock and
19986 use_flock_lock to control what kind of locking is used in implementing the MBX
19987 locking rules. The default is to use fcntl() if use_mbx_lock is set without
19988 use_fcntl_lock or use_flock_lock.
19989
19990
19991 26.3 Operational details for appending
19992 --------------------------------------
19993
19994 Before appending to a file, the following preparations are made:
19995
19996 * If the name of the file is /dev/null, no action is taken, and a success
19997 return is given.
19998
19999 * If any directories on the file's path are missing, Exim creates them if the
20000 create_directory option is set. A created directory's mode is given by the
20001 directory_mode option.
20002
20003 * If file_format is set, the format of an existing file is checked. If this
20004 indicates that a different transport should be used, control is passed to
20005 that transport.
20006
20007 * If use_lockfile is set, a lock file is built in a way that will work
20008 reliably over NFS, as follows:
20009
20010 1. Create a "hitching post" file whose name is that of the lock file with
20011 the current time, primary host name, and process id added, by opening
20012 for writing as a new file. If this fails with an access error, delivery
20013 is deferred.
20014
20015 2. Close the hitching post file, and hard link it to the lock file name.
20016
20017 3. If the call to link() succeeds, creation of the lock file has
20018 succeeded. Unlink the hitching post name.
20019
20020 4. Otherwise, use stat() to get information about the hitching post file,
20021 and then unlink hitching post name. If the number of links is exactly
20022 two, creation of the lock file succeeded but something (for example, an
20023 NFS server crash and restart) caused this fact not to be communicated
20024 to the link() call.
20025
20026 5. If creation of the lock file failed, wait for lock_interval and try
20027 again, up to lock_retries times. However, since any program that writes
20028 to a mailbox should complete its task very quickly, it is reasonable to
20029 time out old lock files that are normally the result of user agent and
20030 system crashes. If an existing lock file is older than lockfile_timeout
20031 Exim attempts to unlink it before trying again.
20032
20033 * A call is made to lstat() to discover whether the main file exists, and if
20034 so, what its characteristics are. If lstat() fails for any reason other
20035 than non-existence, delivery is deferred.
20036
20037 * If the file does exist and is a symbolic link, delivery is deferred, unless
20038 the allow_symlink option is set, in which case the ownership of the link is
20039 checked, and then stat() is called to find out about the real file, which
20040 is then subjected to the checks below. The check on the top-level link
20041 ownership prevents one user creating a link for another's mailbox in a
20042 sticky directory, though allowing symbolic links in this case is definitely
20043 not a good idea. If there is a chain of symbolic links, the intermediate
20044 ones are not checked.
20045
20046 * If the file already exists but is not a regular file, or if the file's
20047 owner and group (if the group is being checked - see check_group above) are
20048 different from the user and group under which the delivery is running,
20049 delivery is deferred.
20050
20051 * If the file's permissions are more generous than specified, they are
20052 reduced. If they are insufficient, delivery is deferred, unless
20053 mode_fail_narrower is set false, in which case the delivery is tried using
20054 the existing permissions.
20055
20056 * The file's inode number is saved, and the file is then opened for
20057 appending. If this fails because the file has vanished, appendfile behaves
20058 as if it hadn't existed (see below). For any other failures, delivery is
20059 deferred.
20060
20061 * If the file is opened successfully, check that the inode number hasn't
20062 changed, that it is still a regular file, and that the owner and
20063 permissions have not changed. If anything is wrong, defer delivery and
20064 freeze the message.
20065
20066 * If the file did not exist originally, defer delivery if the file_must_exist
20067 option is set. Otherwise, check that the file is being created in a
20068 permitted directory if the create_file option is set (deferring on
20069 failure), and then open for writing as a new file, with the O_EXCL and
20070 O_CREAT options, except when dealing with a symbolic link (the
20071 allow_symlink option must be set). In this case, which can happen if the
20072 link points to a non-existent file, the file is opened for writing using
20073 O_CREAT but not O_EXCL, because that prevents link following.
20074
20075 * If opening fails because the file exists, obey the tests given above for
20076 existing files. However, to avoid looping in a situation where the file is
20077 being continuously created and destroyed, the exists/not-exists loop is
20078 broken after 10 repetitions, and the message is then frozen.
20079
20080 * If opening fails with any other error, defer delivery.
20081
20082 * Once the file is open, unless both use_fcntl_lock and use_flock_lock are
20083 false, it is locked using fcntl() or flock() or both. If use_mbx_lock is
20084 false, an exclusive lock is requested in each case. However, if
20085 use_mbx_lock is true, Exim takes out a shared lock on the open file, and an
20086 exclusive lock on the file whose name is
20087
20088 /tmp/.<device-number>.<inode-number>
20089
20090 using the device and inode numbers of the open mailbox file, in accordance
20091 with the MBX locking rules. This file is created with a mode that is
20092 specified by the lockfile_mode option.
20093
20094 If Exim fails to lock the file, there are two possible courses of action,
20095 depending on the value of the locking timeout. This is obtained from
20096 lock_fcntl_timeout or lock_flock_timeout, as appropriate.
20097
20098 If the timeout value is zero, the file is closed, Exim waits for
20099 lock_interval, and then goes back and re-opens the file as above and tries
20100 to lock it again. This happens up to lock_retries times, after which the
20101 delivery is deferred.
20102
20103 If the timeout has a value greater than zero, blocking calls to fcntl() or
20104 flock() are used (with the given timeout), so there has already been some
20105 waiting involved by the time locking fails. Nevertheless, Exim does not
20106 give up immediately. It retries up to
20107
20108 (lock_retries * lock_interval) / <timeout>
20109
20110 times (rounded up).
20111
20112 At the end of delivery, Exim closes the file (which releases the fcntl() and/or
20113 flock() locks) and then deletes the lock file if one was created.
20114
20115
20116 26.4 Operational details for delivery to a new file
20117 ---------------------------------------------------
20118
20119 When the directory option is set instead of file, each message is delivered
20120 into a newly-created file or set of files. When appendfile is activated
20121 directly from a redirect router, neither file nor directory is normally set,
20122 because the path for delivery is supplied by the router. (See for example, the
20123 address_file transport in the default configuration.) In this case, delivery is
20124 to a new file if either the path name ends in "/", or the maildir_format or
20125 mailstore_format option is set.
20126
20127 No locking is required while writing the message to a new file, so the various
20128 locking options of the transport are ignored. The "From" line that by default
20129 separates messages in a single file is not normally needed, nor is the escaping
20130 of message lines that start with "From", and there is no need to ensure a
20131 newline at the end of each message. Consequently, the default values for
20132 check_string, message_prefix, and message_suffix are all unset when any of
20133 directory, maildir_format, or mailstore_format is set.
20134
20135 If Exim is required to check a quota setting, it adds up the sizes of all the
20136 files in the delivery directory by default. However, you can specify a
20137 different directory by setting quota_directory. Also, for maildir deliveries
20138 (see below) the maildirfolder convention is honoured.
20139
20140 There are three different ways in which delivery to individual files can be
20141 done, controlled by the settings of the maildir_format and mailstore_format
20142 options. Note that code to support maildir or mailstore formats is not included
20143 in the binary unless SUPPORT_MAILDIR or SUPPORT_MAILSTORE, respectively, is set
20144 in Local/Makefile.
20145
20146 In all three cases an attempt is made to create the directory and any necessary
20147 sub-directories if they do not exist, provided that the create_directory option
20148 is set (the default). The location of a created directory can be constrained by
20149 setting create_file. A created directory's mode is given by the directory_mode
20150 option. If creation fails, or if the create_directory option is not set when
20151 creation is required, delivery is deferred.
20152
20153
20154 26.5 Maildir delivery
20155 ---------------------
20156
20157 If the maildir_format option is true, Exim delivers each message by writing it
20158 to a file whose name is tmp/<stime>.H<mtime>P<pid>.<host> in the directory that
20159 is defined by the directory option (the "delivery directory"). If the delivery
20160 is successful, the file is renamed into the new subdirectory.
20161
20162 In the file name, <stime> is the current time of day in seconds, and <mtime> is
20163 the microsecond fraction of the time. After a maildir delivery, Exim checks
20164 that the time-of-day clock has moved on by at least one microsecond before
20165 terminating the delivery process. This guarantees uniqueness for the file name.
20166 However, as a precaution, Exim calls stat() for the file before opening it. If
20167 any response other than ENOENT (does not exist) is given, Exim waits 2 seconds
20168 and tries again, up to maildir_retries times.
20169
20170 Before Exim carries out a maildir delivery, it ensures that subdirectories
20171 called new, cur, and tmp exist in the delivery directory. If they do not exist,
20172 Exim tries to create them and any superior directories in their path, subject
20173 to the create_directory and create_file options. If the
20174 maildirfolder_create_regex option is set, and the regular expression it
20175 contains matches the delivery directory, Exim also ensures that a file called
20176 maildirfolder exists in the delivery directory. If a missing directory or
20177 maildirfolder file cannot be created, delivery is deferred.
20178
20179 These features make it possible to use Exim to create all the necessary files
20180 and directories in a maildir mailbox, including subdirectories for maildir++
20181 folders. Consider this example:
20182
20183 maildir_format = true
20184 directory = /var/mail/$local_part\
20185 ${if eq{$local_part_suffix}{}{}\
20186 {/.${substr_1:$local_part_suffix}}}
20187 maildirfolder_create_regex = /\.[^/]+$
20188
20189 If $local_part_suffix is empty (there was no suffix for the local part),
20190 delivery is into a toplevel maildir with a name like /var/mail/pimbo (for the
20191 user called pimbo). The pattern in maildirfolder_create_regex does not match
20192 this name, so Exim will not look for or create the file /var/mail/pimbo/
20193 maildirfolder, though it will create /var/mail/pimbo/{cur,new,tmp} if
20194 necessary.
20195
20196 However, if $local_part_suffix contains "-eximusers" (for example), delivery is
20197 into the maildir++ folder /var/mail/pimbo/.eximusers, which does match
20198 maildirfolder_create_regex. In this case, Exim will create /var/mail/pimbo
20199 /.eximusers/maildirfolder as well as the three maildir directories /var/mail/
20200 pimbo/.eximusers/{cur,new,tmp}.
20201
20202 Warning: Take care when setting maildirfolder_create_regex that it does not
20203 inadvertently match the toplevel maildir directory, because a maildirfolder
20204 file at top level would completely break quota calculations.
20205
20206 If Exim is required to check a quota setting before a maildir delivery, and
20207 quota_directory is not set, it looks for a file called maildirfolder in the
20208 maildir directory (alongside new, cur, tmp). If this exists, Exim assumes the
20209 directory is a maildir++ folder directory, which is one level down from the
20210 user's top level mailbox directory. This causes it to start at the parent
20211 directory instead of the current directory when calculating the amount of space
20212 used.
20213
20214 One problem with delivering into a multi-file mailbox is that it is
20215 computationally expensive to compute the size of the mailbox for quota
20216 checking. Various approaches have been taken to reduce the amount of work
20217 needed. The next two sections describe two of them. A third alternative is to
20218 use some external process for maintaining the size data, and use the expansion
20219 of the mailbox_size option as a way of importing it into Exim.
20220
20221
20222 26.6 Using tags to record message sizes
20223 ---------------------------------------
20224
20225 If maildir_tag is set, the string is expanded for each delivery. When the
20226 maildir file is renamed into the new sub-directory, the tag is added to its
20227 name. However, if adding the tag takes the length of the name to the point
20228 where the test stat() call fails with ENAMETOOLONG, the tag is dropped and the
20229 maildir file is created with no tag.
20230
20231 Tags can be used to encode the size of files in their names; see
20232 quota_size_regex above for an example. The expansion of maildir_tag happens
20233 after the message has been written. The value of the $message_size variable is
20234 set to the number of bytes actually written. If the expansion is forced to
20235 fail, the tag is ignored, but a non-forced failure causes delivery to be
20236 deferred. The expanded tag may contain any printing characters except "/".
20237 Non-printing characters in the string are ignored; if the resulting string is
20238 empty, it is ignored. If it starts with an alphanumeric character, a leading
20239 colon is inserted; this default has not proven to be the path that popular
20240 maildir implementations have chosen (but changing it in Exim would break
20241 backwards compatibility).
20242
20243 For one common implementation, you might set:
20244
20245 maildir_tag = ,S=${message_size}
20246
20247 but you should check the documentation of the other software to be sure.
20248
20249 It is advisable to also set quota_size_regex when setting maildir_tag as this
20250 allows Exim to extract the size from your tag, instead of having to stat() each
20251 message file.
20252
20253
20254 26.7 Using a maildirsize file
20255 -----------------------------
20256
20257 If maildir_use_size_file is true, Exim implements the maildir++ rules for
20258 storing quota and message size information in a file called maildirsize within
20259 the toplevel maildir directory. If this file does not exist, Exim creates it,
20260 setting the quota from the quota option of the transport. If the maildir
20261 directory itself does not exist, it is created before any attempt to write a
20262 maildirsize file.
20263
20264 The maildirsize file is used to hold information about the sizes of messages in
20265 the maildir, thus speeding up quota calculations. The quota value in the file
20266 is just a cache; if the quota is changed in the transport, the new value
20267 overrides the cached value when the next message is delivered. The cache is
20268 maintained for the benefit of other programs that access the maildir and need
20269 to know the quota.
20270
20271 If the quota option in the transport is unset or zero, the maildirsize file is
20272 maintained (with a zero quota setting), but no quota is imposed.
20273
20274 A regular expression is available for controlling which directories in the
20275 maildir participate in quota calculations when a maildirsizefile is in use. See
20276 the description of the maildir_quota_directory_regex option above for details.
20277
20278
20279 26.8 Mailstore delivery
20280 -----------------------
20281
20282 If the mailstore_format option is true, each message is written as two files in
20283 the given directory. A unique base name is constructed from the message id and
20284 the current delivery process, and the files that are written use this base name
20285 plus the suffixes .env and .msg. The .env file contains the message's envelope,
20286 and the .msg file contains the message itself. The base name is placed in the
20287 variable $mailstore_basename.
20288
20289 During delivery, the envelope is first written to a file with the suffix .tmp.
20290 The .msg file is then written, and when it is complete, the .tmp file is
20291 renamed as the .env file. Programs that access messages in mailstore format
20292 should wait for the presence of both a .msg and a .env file before accessing
20293 either of them. An alternative approach is to wait for the absence of a .tmp
20294 file.
20295
20296 The envelope file starts with any text defined by the mailstore_prefix option,
20297 expanded and terminated by a newline if there isn't one. Then follows the
20298 sender address on one line, then all the recipient addresses, one per line.
20299 There can be more than one recipient only if the batch_max option is set
20300 greater than one. Finally, mailstore_suffix is expanded and the result appended
20301 to the file, followed by a newline if it does not end with one.
20302
20303 If expansion of mailstore_prefix or mailstore_suffix ends with a forced
20304 failure, it is ignored. Other expansion errors are treated as serious
20305 configuration errors, and delivery is deferred. The variable
20306 $mailstore_basename is available for use during these expansions.
20307
20308
20309 26.9 Non-special new file delivery
20310 ----------------------------------
20311
20312 If neither maildir_format nor mailstore_format is set, a single new file is
20313 created directly in the named directory. For example, when delivering messages
20314 into files in batched SMTP format for later delivery to some host (see section
20315 47.10), a setting such as
20316
20317 directory = /var/bsmtp/$host
20318
20319 might be used. A message is written to a file with a temporary name, which is
20320 then renamed when the delivery is complete. The final name is obtained by
20321 expanding the contents of the directory_file option.
20322
20323
20324
20325 ===============================================================================
20326 27. THE AUTOREPLY TRANSPORT
20327
20328 The autoreply transport is not a true transport in that it does not cause the
20329 message to be transmitted. Instead, it generates a new mail message as an
20330 automatic reply to the incoming message. References: and Auto-Submitted: header
20331 lines are included. These are constructed according to the rules in RFCs 2822
20332 and 3834, respectively.
20333
20334 If the router that passes the message to this transport does not have the
20335 unseen option set, the original message (for the current recipient) is not
20336 delivered anywhere. However, when the unseen option is set on the router that
20337 passes the message to this transport, routing of the address continues, so
20338 another router can set up a normal message delivery.
20339
20340 The autoreply transport is usually run as the result of mail filtering, a
20341 "vacation" message being the standard example. However, it can also be run
20342 directly from a router like any other transport. To reduce the possibility of
20343 message cascades, messages created by the autoreply transport always have empty
20344 envelope sender addresses, like bounce messages.
20345
20346 The parameters of the message to be sent can be specified in the configuration
20347 by options described below. However, these are used only when the address
20348 passed to the transport does not contain its own reply information. When the
20349 transport is run as a consequence of a mail or vacation command in a filter
20350 file, the parameters of the message are supplied by the filter, and passed with
20351 the address. The transport's options that define the message are then ignored
20352 (so they are not usually set in this case). The message is specified entirely
20353 by the filter or by the transport; it is never built from a mixture of options.
20354 However, the file_optional, mode, and return_message options apply in all
20355 cases.
20356
20357 Autoreply is implemented as a local transport. When used as a result of a
20358 command in a user's filter file, autoreply normally runs under the uid and gid
20359 of the user, and with appropriate current and home directories (see chapter 23
20360 ).
20361
20362 There is a subtle difference between routing a message to a pipe transport that
20363 generates some text to be returned to the sender, and routing it to an
20364 autoreply transport. This difference is noticeable only if more than one
20365 address from the same message is so handled. In the case of a pipe, the
20366 separate outputs from the different addresses are gathered up and returned to
20367 the sender in a single message, whereas if autoreply is used, a separate
20368 message is generated for each address that is passed to it.
20369
20370 Non-printing characters are not permitted in the header lines generated for the
20371 message that autoreply creates, with the exception of newlines that are
20372 immediately followed by white space. If any non-printing characters are found,
20373 the transport defers. Whether characters with the top bit set count as printing
20374 characters or not is controlled by the print_topbitchars global option.
20375
20376 If any of the generic options for manipulating headers (for example,
20377 headers_add) are set on an autoreply transport, they apply to the copy of the
20378 original message that is included in the generated message when return_message
20379 is set. They do not apply to the generated message itself.
20380
20381 If the autoreply transport receives return code 2 from Exim when it submits the
20382 message, indicating that there were no recipients, it does not treat this as an
20383 error. This means that autoreplies sent to $sender_address when this is empty
20384 (because the incoming message is a bounce message) do not cause problems. They
20385 are just discarded.
20386
20387
20388 27.1 Private options for autoreply
20389 ----------------------------------
20390
20391 +---+--------------+-------------+--------------+
20392 |bcc|Use: autoreply|Type: string*|Default: unset|
20393 +---+--------------+-------------+--------------+
20394
20395 This specifies the addresses that are to receive "blind carbon copies" of the
20396 message when the message is specified by the transport.
20397
20398 +--+--------------+-------------+--------------+
20399 |cc|Use: autoreply|Type: string*|Default: unset|
20400 +--+--------------+-------------+--------------+
20401
20402 This specifies recipients of the message and the contents of the Cc: header
20403 when the message is specified by the transport.
20404
20405 +----+--------------+-------------+--------------+
20406 |file|Use: autoreply|Type: string*|Default: unset|
20407 +----+--------------+-------------+--------------+
20408
20409 The contents of the file are sent as the body of the message when the message
20410 is specified by the transport. If both file and text are set, the text string
20411 comes first.
20412
20413 +-----------+--------------+-------------+--------------+
20414 |file_expand|Use: autoreply|Type: boolean|Default: false|
20415 +-----------+--------------+-------------+--------------+
20416
20417 If this is set, the contents of the file named by the file option are subjected
20418 to string expansion as they are added to the message.
20419
20420 +-------------+--------------+-------------+--------------+
20421 |file_optional|Use: autoreply|Type: boolean|Default: false|
20422 +-------------+--------------+-------------+--------------+
20423
20424 If this option is true, no error is generated if the file named by the file
20425 option or passed with the address does not exist or cannot be read.
20426
20427 +----+--------------+-------------+--------------+
20428 |from|Use: autoreply|Type: string*|Default: unset|
20429 +----+--------------+-------------+--------------+
20430
20431 This specifies the contents of the From: header when the message is specified
20432 by the transport.
20433
20434 +-------+--------------+-------------+--------------+
20435 |headers|Use: autoreply|Type: string*|Default: unset|
20436 +-------+--------------+-------------+--------------+
20437
20438 This specifies additional RFC 2822 headers that are to be added to the message
20439 when the message is specified by the transport. Several can be given by using "
20440 \n" to separate them. There is no check on the format.
20441
20442 +---+--------------+-------------+--------------+
20443 |log|Use: autoreply|Type: string*|Default: unset|
20444 +---+--------------+-------------+--------------+
20445
20446 This option names a file in which a record of every message sent is logged when
20447 the message is specified by the transport.
20448
20449 +----+--------------+-------------------+-------------+
20450 |mode|Use: autoreply|Type: octal integer|Default: 0600|
20451 +----+--------------+-------------------+-------------+
20452
20453 If either the log file or the "once" file has to be created, this mode is used.
20454
20455 +----------+--------------+-------------------+--------------+
20456 |never_mail|Use: autoreply|Type: address list*|Default: unset|
20457 +----------+--------------+-------------------+--------------+
20458
20459 If any run of the transport creates a message with a recipient that matches any
20460 item in the list, that recipient is quietly discarded. If all recipients are
20461 discarded, no message is created. This applies both when the recipients are
20462 generated by a filter and when they are specified in the transport.
20463
20464 +----+--------------+-------------+--------------+
20465 |once|Use: autoreply|Type: string*|Default: unset|
20466 +----+--------------+-------------+--------------+
20467
20468 This option names a file or DBM database in which a record of each To:
20469 recipient is kept when the message is specified by the transport. Note: This
20470 does not apply to Cc: or Bcc: recipients.
20471
20472 If once is unset, or is set to an empty string, the message is always sent. By
20473 default, if once is set to a non-empty file name, the message is not sent if a
20474 potential recipient is already listed in the database. However, if the
20475 once_repeat option specifies a time greater than zero, the message is sent if
20476 that much time has elapsed since a message was last sent to this recipient. A
20477 setting of zero time for once_repeat (the default) prevents a message from
20478 being sent a second time - in this case, zero means infinity.
20479
20480 If once_file_size is zero, a DBM database is used to remember recipients, and
20481 it is allowed to grow as large as necessary. If once_file_size is set greater
20482 than zero, it changes the way Exim implements the once option. Instead of using
20483 a DBM file to record every recipient it sends to, it uses a regular file, whose
20484 size will never get larger than the given value.
20485
20486 In the file, Exim keeps a linear list of recipient addresses and the times at
20487 which they were sent messages. If the file is full when a new address needs to
20488 be added, the oldest address is dropped. If once_repeat is not set, this means
20489 that a given recipient may receive multiple messages, but at unpredictable
20490 intervals that depend on the rate of turnover of addresses in the file. If
20491 once_repeat is set, it specifies a maximum time between repeats.
20492
20493 +--------------+--------------+-------------+----------+
20494 |once_file_size|Use: autoreply|Type: integer|Default: 0|
20495 +--------------+--------------+-------------+----------+
20496
20497 See once above.
20498
20499 +-----------+--------------+-----------+-----------+
20500 |once_repeat|Use: autoreply|Type: time*|Default: 0s|
20501 +-----------+--------------+-----------+-----------+
20502
20503 See once above. After expansion, the value of this option must be a valid time
20504 value.
20505
20506 +--------+--------------+-------------+--------------+
20507 |reply_to|Use: autoreply|Type: string*|Default: unset|
20508 +--------+--------------+-------------+--------------+
20509
20510 This specifies the contents of the Reply-To: header when the message is
20511 specified by the transport.
20512
20513 +--------------+--------------+-------------+--------------+
20514 |return_message|Use: autoreply|Type: boolean|Default: false|
20515 +--------------+--------------+-------------+--------------+
20516
20517 If this is set, a copy of the original message is returned with the new
20518 message, subject to the maximum size set in the return_size_limit global
20519 configuration option.
20520
20521 +-------+--------------+-------------+--------------+
20522 |subject|Use: autoreply|Type: string*|Default: unset|
20523 +-------+--------------+-------------+--------------+
20524
20525 This specifies the contents of the Subject: header when the message is
20526 specified by the transport. It is tempting to quote the original subject in
20527 automatic responses. For example:
20528
20529 subject = Re: $h_subject:
20530
20531 There is a danger in doing this, however. It may allow a third party to
20532 subscribe your users to an opt-in mailing list, provided that the list accepts
20533 bounce messages as subscription confirmations. Well-managed lists require a
20534 non-bounce message to confirm a subscription, so the danger is relatively
20535 small.
20536
20537 +----+--------------+-------------+--------------+
20538 |text|Use: autoreply|Type: string*|Default: unset|
20539 +----+--------------+-------------+--------------+
20540
20541 This specifies a single string to be used as the body of the message when the
20542 message is specified by the transport. If both text and file are set, the text
20543 comes first.
20544
20545 +--+--------------+-------------+--------------+
20546 |to|Use: autoreply|Type: string*|Default: unset|
20547 +--+--------------+-------------+--------------+
20548
20549 This specifies recipients of the message and the contents of the To: header
20550 when the message is specified by the transport.
20551
20552
20553
20554 ===============================================================================
20555 28. THE LMTP TRANSPORT
20556
20557 The lmtp transport runs the LMTP protocol (RFC 2033) over a pipe to a specified
20558 command or by interacting with a Unix domain socket. This transport is
20559 something of a cross between the pipe and smtp transports. Exim also has
20560 support for using LMTP over TCP/IP; this is implemented as an option for the
20561 smtp transport. Because LMTP is expected to be of minority interest, the
20562 default build-time configure in src/EDITME has it commented out. You need to
20563 ensure that
20564
20565 TRANSPORT_LMTP=yes
20566
20567 is present in your Local/Makefile in order to have the lmtp transport included
20568 in the Exim binary. The private options of the lmtp transport are as follows:
20569
20570 +--------+---------+-------------+--------------+
20571 |batch_id|Use: lmtp|Type: string*|Default: unset|
20572 +--------+---------+-------------+--------------+
20573
20574 See the description of local delivery batching in chapter 25.
20575
20576 +---------+---------+-------------+----------+
20577 |batch_max|Use: lmtp|Type: integer|Default: 1|
20578 +---------+---------+-------------+----------+
20579
20580 This limits the number of addresses that can be handled in a single delivery.
20581 Most LMTP servers can handle several addresses at once, so it is normally a
20582 good idea to increase this value. See the description of local delivery
20583 batching in chapter 25.
20584
20585 +-------+---------+-------------+--------------+
20586 |command|Use: lmtp|Type: string*|Default: unset|
20587 +-------+---------+-------------+--------------+
20588
20589 This option must be set if socket is not set. The string is a command which is
20590 run in a separate process. It is split up into a command name and list of
20591 arguments, each of which is separately expanded (so expansion cannot change the
20592 number of arguments). The command is run directly, not via a shell. The message
20593 is passed to the new process using the standard input and output to operate the
20594 LMTP protocol.
20595
20596 +------------+---------+-------------+--------------+
20597 |ignore_quota|Use: lmtp|Type: boolean|Default: false|
20598 +------------+---------+-------------+--------------+
20599
20600 If this option is set true, the string "IGNOREQUOTA" is added to RCPT commands,
20601 provided that the LMTP server has advertised support for IGNOREQUOTA in its
20602 response to the LHLO command.
20603
20604 +------+---------+-------------+--------------+
20605 |socket|Use: lmtp|Type: string*|Default: unset|
20606 +------+---------+-------------+--------------+
20607
20608 This option must be set if command is not set. The result of expansion must be
20609 the name of a Unix domain socket. The transport connects to the socket and
20610 delivers the message to it using the LMTP protocol.
20611
20612 +-------+---------+----------+-----------+
20613 |timeout|Use: lmtp|Type: time|Default: 5m|
20614 +-------+---------+----------+-----------+
20615
20616 The transport is aborted if the created process or Unix domain socket does not
20617 respond to LMTP commands or message input within this timeout. Delivery is
20618 deferred, and will be tried again later. Here is an example of a typical LMTP
20619 transport:
20620
20621 lmtp:
20622 driver = lmtp
20623 command = /some/local/lmtp/delivery/program
20624 batch_max = 20
20625 user = exim
20626
20627 This delivers up to 20 addresses at a time, in a mixture of domains if
20628 necessary, running as the user exim.
20629
20630
20631
20632 ===============================================================================
20633 29. THE PIPE TRANSPORT
20634
20635 The pipe transport is used to deliver messages via a pipe to a command running
20636 in another process. One example is the use of pipe as a pseudo-remote transport
20637 for passing messages to some other delivery mechanism (such as UUCP). Another
20638 is the use by individual users to automatically process their incoming
20639 messages. The pipe transport can be used in one of the following ways:
20640
20641 * A router routes one address to a transport in the normal way, and the
20642 transport is configured as a pipe transport. In this case, $local_part
20643 contains the local part of the address (as usual), and the command that is
20644 run is specified by the command option on the transport.
20645
20646 * If the batch_max option is set greater than 1 (the default is 1), the
20647 transport can handle more than one address in a single run. In this case,
20648 when more than one address is routed to the transport, $local_part is not
20649 set (because it is not unique). However, the pseudo-variable
20650 $pipe_addresses (described in section 29.3 below) contains all the
20651 addresses that are routed to the transport.
20652
20653 * A router redirects an address directly to a pipe command (for example, from
20654 an alias or forward file). In this case, $address_pipe contains the text of
20655 the pipe command, and the command option on the transport is ignored unless
20656 force_command is set. If only one address is being transported (batch_max
20657 is not greater than one, or only one address was redirected to this pipe
20658 command), $local_part contains the local part that was redirected.
20659
20660 The pipe transport is a non-interactive delivery method. Exim can also deliver
20661 messages over pipes using the LMTP interactive protocol. This is implemented by
20662 the lmtp transport.
20663
20664 In the case when pipe is run as a consequence of an entry in a local user's
20665 .forward file, the command runs under the uid and gid of that user. In other
20666 cases, the uid and gid have to be specified explicitly, either on the transport
20667 or on the router that handles the address. Current and "home" directories are
20668 also controllable. See chapter 23 for details of the local delivery environment
20669 and chapter 25 for a discussion of local delivery batching.
20670
20671
20672 29.1 Concurrent delivery
20673 ------------------------
20674
20675 If two messages arrive at almost the same time, and both are routed to a pipe
20676 delivery, the two pipe transports may be run concurrently. You must ensure that
20677 any pipe commands you set up are robust against this happening. If the commands
20678 write to a file, the exim_lock utility might be of use.
20679
20680
20681 29.2 Returned status and data
20682 -----------------------------
20683
20684 If the command exits with a non-zero return code, the delivery is deemed to
20685 have failed, unless either the ignore_status option is set (in which case the
20686 return code is treated as zero), or the return code is one of those listed in
20687 the temp_errors option, which are interpreted as meaning "try again later". In
20688 this case, delivery is deferred. Details of a permanent failure are logged, but
20689 are not included in the bounce message, which merely contains "local delivery
20690 failed".
20691
20692 If the command exits on a signal and the freeze_signal option is set then the
20693 message will be frozen in the queue. If that option is not set, a bounce will
20694 be sent as normal.
20695
20696 If the return code is greater than 128 and the command being run is a shell
20697 script, it normally means that the script was terminated by a signal whose
20698 value is the return code minus 128. The freeze_signal option does not apply in
20699 this case.
20700
20701 If Exim is unable to run the command (that is, if execve() fails), the return
20702 code is set to 127. This is the value that a shell returns if it is asked to
20703 run a non-existent command. The wording for the log line suggests that a
20704 non-existent command may be the problem.
20705
20706 The return_output option can affect the result of a pipe delivery. If it is set
20707 and the command produces any output on its standard output or standard error
20708 streams, the command is considered to have failed, even if it gave a zero
20709 return code or if ignore_status is set. The output from the command is included
20710 as part of the bounce message. The return_fail_output option is similar, except
20711 that output is returned only when the command exits with a failure return code,
20712 that is, a value other than zero or a code that matches temp_errors.
20713
20714
20715 29.3 How the command is run
20716 ---------------------------
20717
20718 The command line is (by default) broken down into a command name and arguments
20719 by the pipe transport itself. The allow_commands and restrict_to_path options
20720 can be used to restrict the commands that may be run.
20721
20722 Unquoted arguments are delimited by white space. If an argument appears in
20723 double quotes, backslash is interpreted as an escape character in the usual
20724 way. If an argument appears in single quotes, no escaping is done.
20725
20726 String expansion is applied to the command line except when it comes from a
20727 traditional .forward file (commands from a filter file are expanded). The
20728 expansion is applied to each argument in turn rather than to the whole line.
20729 For this reason, any string expansion item that contains white space must be
20730 quoted so as to be contained within a single argument. A setting such as
20731
20732 command = /some/path ${if eq{$local_part}{postmaster}{xx}{yy}}
20733
20734 will not work, because the expansion item gets split between several arguments.
20735 You have to write
20736
20737 command = /some/path "${if eq{$local_part}{postmaster}{xx}{yy}}"
20738
20739 to ensure that it is all in one argument. The expansion is done in this way,
20740 argument by argument, so that the number of arguments cannot be changed as a
20741 result of expansion, and quotes or backslashes in inserted variables do not
20742 interact with external quoting. However, this leads to problems if you want to
20743 generate multiple arguments (or the command name plus arguments) from a single
20744 expansion. In this situation, the simplest solution is to use a shell. For
20745 example:
20746
20747 command = /bin/sh -c ${lookup{$local_part}lsearch{/some/file}}
20748
20749 Special handling takes place when an argument consists of precisely the text
20750 "$pipe_addresses". This is not a general expansion variable; the only place
20751 this string is recognized is when it appears as an argument for a pipe or
20752 transport filter command. It causes each address that is being handled to be
20753 inserted in the argument list at that point as a separate argument. This avoids
20754 any problems with spaces or shell metacharacters, and is of use when a pipe
20755 transport is handling groups of addresses in a batch.
20756
20757 If force_command is enabled on the transport, Special handling takes place for
20758 an argument that consists of precisely the text "$address_pipe". It is handled
20759 similarly to $pipe_addresses above. It is expanded and each argument is
20760 inserted in the argument list at that point as a separate argument. The
20761 "$address_pipe" item does not need to be the only item in the argument; in
20762 fact, if it were then force_command should behave as a no-op. Rather, it should
20763 be used to adjust the command run while preserving the argument vector
20764 separation.
20765
20766 After splitting up into arguments and expansion, the resulting command is run
20767 in a subprocess directly from the transport, not under a shell. The message
20768 that is being delivered is supplied on the standard input, and the standard
20769 output and standard error are both connected to a single pipe that is read by
20770 Exim. The max_output option controls how much output the command may produce,
20771 and the return_output and return_fail_output options control what is done with
20772 it.
20773
20774 Not running the command under a shell (by default) lessens the security risks
20775 in cases when a command from a user's filter file is built out of data that was
20776 taken from an incoming message. If a shell is required, it can of course be
20777 explicitly specified as the command to be run. However, there are circumstances
20778 where existing commands (for example, in .forward files) expect to be run under
20779 a shell and cannot easily be modified. To allow for these cases, there is an
20780 option called use_shell, which changes the way the pipe transport works.
20781 Instead of breaking up the command line as just described, it expands it as a
20782 single string and passes the result to /bin/sh. The restrict_to_path option and
20783 the $pipe_addresses facility cannot be used with use_shell, and the whole
20784 mechanism is inherently less secure.
20785
20786
20787 29.4 Environment variables
20788 --------------------------
20789
20790 The environment variables listed below are set up when the command is invoked.
20791 This list is a compromise for maximum compatibility with other MTAs. Note that
20792 the environment option can be used to add additional variables to this
20793 environment.
20794
20795 DOMAIN the domain of the address
20796 HOME the home directory, if set
20797 HOST the host name when called from a router (see below)
20798 LOCAL_PART see below
20799 LOCAL_PART_PREFIX see below
20800 LOCAL_PART_SUFFIX see below
20801 LOGNAME see below
20802 MESSAGE_ID Exim's local ID for the message
20803 PATH as specified by the path option below
20804 QUALIFY_DOMAIN the sender qualification domain
20805 RECIPIENT the complete recipient address
20806 SENDER the sender of the message (empty if a bounce)
20807 SHELL /bin/sh
20808 TZ the value of the timezone option, if set
20809 USER see below
20810
20811 When a pipe transport is called directly from (for example) an accept router,
20812 LOCAL_PART is set to the local part of the address. When it is called as a
20813 result of a forward or alias expansion, LOCAL_PART is set to the local part of
20814 the address that was expanded. In both cases, any affixes are removed from the
20815 local part, and made available in LOCAL_PART_PREFIX and LOCAL_PART_SUFFIX,
20816 respectively. LOGNAME and USER are set to the same value as LOCAL_PART for
20817 compatibility with other MTAs.
20818
20819 HOST is set only when a pipe transport is called from a router that associates
20820 hosts with an address, typically when using pipe as a pseudo-remote transport.
20821 HOST is set to the first host name specified by the router.
20822
20823 If the transport's generic home_directory option is set, its value is used for
20824 the HOME environment variable. Otherwise, a home directory may be set by the
20825 router's transport_home_directory option, which defaults to the user's home
20826 directory if check_local_user is set.
20827
20828
20829 29.5 Private options for pipe
20830 -----------------------------
20831
20832 +--------------+---------+------------------+--------------+
20833 |allow_commands|Use: pipe|Type: string list*|Default: unset|
20834 +--------------+---------+------------------+--------------+
20835
20836 The string is expanded, and is then interpreted as a colon-separated list of
20837 permitted commands. If restrict_to_path is not set, the only commands permitted
20838 are those in the allow_commands list. They need not be absolute paths; the path
20839 option is still used for relative paths. If restrict_to_path is set with
20840 allow_commands, the command must either be in the allow_commands list, or a
20841 name without any slashes that is found on the path. In other words, if neither
20842 allow_commands nor restrict_to_path is set, there is no restriction on the
20843 command, but otherwise only commands that are permitted by one or the other are
20844 allowed. For example, if
20845
20846 allow_commands = /usr/bin/vacation
20847
20848 and restrict_to_path is not set, the only permitted command is /usr/bin/
20849 vacation. The allow_commands option may not be set if use_shell is set.
20850
20851 +--------+---------+-------------+--------------+
20852 |batch_id|Use: pipe|Type: string*|Default: unset|
20853 +--------+---------+-------------+--------------+
20854
20855 See the description of local delivery batching in chapter 25.
20856
20857 +---------+---------+-------------+----------+
20858 |batch_max|Use: pipe|Type: integer|Default: 1|
20859 +---------+---------+-------------+----------+
20860
20861 This limits the number of addresses that can be handled in a single delivery.
20862 See the description of local delivery batching in chapter 25.
20863
20864 +------------+---------+------------+--------------+
20865 |check_string|Use: pipe|Type: string|Default: unset|
20866 +------------+---------+------------+--------------+
20867
20868 As pipe writes the message, the start of each line is tested for matching
20869 check_string, and if it does, the initial matching characters are replaced by
20870 the contents of escape_string, provided both are set. The value of check_string
20871 is a literal string, not a regular expression, and the case of any letters it
20872 contains is significant. When use_bsmtp is set, the contents of check_string
20873 and escape_string are forced to values that implement the SMTP escaping
20874 protocol. Any settings made in the configuration file are ignored.
20875
20876 +-------+---------+-------------+--------------+
20877 |command|Use: pipe|Type: string*|Default: unset|
20878 +-------+---------+-------------+--------------+
20879
20880 This option need not be set when pipe is being used to deliver to pipes
20881 obtained directly from address redirections. In other cases, the option must be
20882 set, to provide a command to be run. It need not yield an absolute path (see
20883 the path option below). The command is split up into separate arguments by
20884 Exim, and each argument is separately expanded, as described in section 29.3
20885 above.
20886
20887 +-----------+---------+-------------+--------------+
20888 |environment|Use: pipe|Type: string*|Default: unset|
20889 +-----------+---------+-------------+--------------+
20890
20891 This option is used to add additional variables to the environment in which the
20892 command runs (see section 29.4 for the default list). Its value is a string
20893 which is expanded, and then interpreted as a colon-separated list of
20894 environment settings of the form <name>=<value>.
20895
20896 +-------------+---------+------------+--------------+
20897 |escape_string|Use: pipe|Type: string|Default: unset|
20898 +-------------+---------+------------+--------------+
20899
20900 See check_string above.
20901
20902 +----------------+---------+-------------+--------------+
20903 |freeze_exec_fail|Use: pipe|Type: boolean|Default: false|
20904 +----------------+---------+-------------+--------------+
20905
20906 Failure to exec the command in a pipe transport is by default treated like any
20907 other failure while running the command. However, if freeze_exec_fail is set,
20908 failure to exec is treated specially, and causes the message to be frozen,
20909 whatever the setting of ignore_status.
20910
20911 +-------------+---------+-------------+--------------+
20912 |freeze_signal|Use: pipe|Type: boolean|Default: false|
20913 +-------------+---------+-------------+--------------+
20914
20915 Normally if the process run by a command in a pipe transport exits on a signal,
20916 a bounce message is sent. If freeze_signal is set, the message will be frozen
20917 in Exim's queue instead.
20918
20919 +-------------+---------+-------------+--------------+
20920 |force_command|Use: pipe|Type: boolean|Default: false|
20921 +-------------+---------+-------------+--------------+
20922
20923 Normally when a router redirects an address directly to a pipe command the
20924 command option on the transport is ignored. If force_command is set, the
20925 command option will used. This is especially useful for forcing a wrapper or
20926 additional argument to be added to the command. For example:
20927
20928 command = /usr/bin/remote_exec myhost -- $address_pipe
20929 force_command
20930
20931 Note that $address_pipe is handled specially in command when force_command is
20932 set, expanding out to the original argument vector as separate items, similarly
20933 to a Unix shell ""$@"" construct.
20934
20935 +-------------+---------+-------------+--------------+
20936 |ignore_status|Use: pipe|Type: boolean|Default: false|
20937 +-------------+---------+-------------+--------------+
20938
20939 If this option is true, the status returned by the subprocess that is set up to
20940 run the command is ignored, and Exim behaves as if zero had been returned.
20941 Otherwise, a non-zero status or termination by signal causes an error return
20942 from the transport unless the status value is one of those listed in
20943 temp_errors; these cause the delivery to be deferred and tried again later.
20944
20945 Note: This option does not apply to timeouts, which do not return a status. See
20946 the timeout_defer option for how timeouts are handled.
20947
20948 +----------------+---------+-------------+--------------+
20949 |log_defer_output|Use: pipe|Type: boolean|Default: false|
20950 +----------------+---------+-------------+--------------+
20951
20952 If this option is set, and the status returned by the command is one of the
20953 codes listed in temp_errors (that is, delivery was deferred), and any output
20954 was produced, the first line of it is written to the main log.
20955
20956 +---------------+---------+-------------+--------------+
20957 |log_fail_output|Use: pipe|Type: boolean|Default: false|
20958 +---------------+---------+-------------+--------------+
20959
20960 If this option is set, and the command returns any output, and also ends with a
20961 return code that is neither zero nor one of the return codes listed in
20962 temp_errors (that is, the delivery failed), the first line of output is written
20963 to the main log. This option and log_output are mutually exclusive. Only one of
20964 them may be set.
20965
20966 +----------+---------+-------------+--------------+
20967 |log_output|Use: pipe|Type: boolean|Default: false|
20968 +----------+---------+-------------+--------------+
20969
20970 If this option is set and the command returns any output, the first line of
20971 output is written to the main log, whatever the return code. This option and
20972 log_fail_output are mutually exclusive. Only one of them may be set.
20973
20974 +----------+---------+-------------+------------+
20975 |max_output|Use: pipe|Type: integer|Default: 20K|
20976 +----------+---------+-------------+------------+
20977
20978 This specifies the maximum amount of output that the command may produce on its
20979 standard output and standard error file combined. If the limit is exceeded, the
20980 process running the command is killed. This is intended as a safety measure to
20981 catch runaway processes. The limit is applied independently of the settings of
20982 the options that control what is done with such output (for example,
20983 return_output). Because of buffering effects, the amount of output may exceed
20984 the limit by a small amount before Exim notices.
20985
20986 +--------------+---------+-------------+------------------+
20987 |message_prefix|Use: pipe|Type: string*|Default: see below|
20988 +--------------+---------+-------------+------------------+
20989
20990 The string specified here is expanded and output at the start of every message.
20991 The default is unset if use_bsmtp is set. Otherwise it is
20992
20993 message_prefix = \
20994 From ${if def:return_path{$return_path}{MAILER-DAEMON}}\
20995 ${tod_bsdinbox}\n
20996
20997 This is required by the commonly used /usr/bin/vacation program. However, it
20998 must not be present if delivery is to the Cyrus IMAP server, or to the tmail
20999 local delivery agent. The prefix can be suppressed by setting
21000
21001 message_prefix =
21002
21003 Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\
21004 n" in message_prefix.
21005
21006 +--------------+---------+-------------+------------------+
21007 |message_suffix|Use: pipe|Type: string*|Default: see below|
21008 +--------------+---------+-------------+------------------+
21009
21010 The string specified here is expanded and output at the end of every message.
21011 The default is unset if use_bsmtp is set. Otherwise it is a single newline. The
21012 suffix can be suppressed by setting
21013
21014 message_suffix =
21015
21016 Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\
21017 n" in message_suffix.
21018
21019 +----+---------+------------+------------------+
21020 |path|Use: pipe|Type: string|Default: see below|
21021 +----+---------+------------+------------------+
21022
21023 This option specifies the string that is set up in the PATH environment
21024 variable of the subprocess. The default is:
21025
21026 /bin:/usr/bin
21027
21028 If the command option does not yield an absolute path name, the command is
21029 sought in the PATH directories, in the usual way. Warning: This does not apply
21030 to a command specified as a transport filter.
21031
21032 +---------------+---------+-------------+--------------+
21033 |permit_coredump|Use: pipe|Type: boolean|Default: false|
21034 +---------------+---------+-------------+--------------+
21035
21036 Normally Exim inhibits core-dumps during delivery. If you have a need to get a
21037 core-dump of a pipe command, enable this command. This enables core-dumps
21038 during delivery and affects both the Exim binary and the pipe command run. It
21039 is recommended that this option remain off unless and until you have a need for
21040 it and that this only be enabled when needed, as the risk of excessive resource
21041 consumption can be quite high. Note also that Exim is typically installed as a
21042 setuid binary and most operating systems will inhibit coredumps of these by
21043 default, so further OS-specific action may be required.
21044
21045 +---------------+---------+-------------+--------------+
21046 |pipe_as_creator|Use: pipe|Type: boolean|Default: false|
21047 +---------------+---------+-------------+--------------+
21048
21049 If the generic user option is not set and this option is true, the delivery
21050 process is run under the uid that was in force when Exim was originally called
21051 to accept the message. If the group id is not otherwise set (via the generic
21052 group option), the gid that was in force when Exim was originally called to
21053 accept the message is used.
21054
21055 +----------------+---------+-------------+--------------+
21056 |restrict_to_path|Use: pipe|Type: boolean|Default: false|
21057 +----------------+---------+-------------+--------------+
21058
21059 When this option is set, any command name not listed in allow_commands must
21060 contain no slashes. The command is searched for only in the directories listed
21061 in the path option. This option is intended for use in the case when a pipe
21062 command has been generated from a user's .forward file. This is usually handled
21063 by a pipe transport called address_pipe.
21064
21065 +------------------+---------+-------------+--------------+
21066 |return_fail_output|Use: pipe|Type: boolean|Default: false|
21067 +------------------+---------+-------------+--------------+
21068
21069 If this option is true, and the command produced any output and ended with a
21070 return code other than zero or one of the codes listed in temp_errors (that is,
21071 the delivery failed), the output is returned in the bounce message. However, if
21072 the message has a null sender (that is, it is itself a bounce message), output
21073 from the command is discarded. This option and return_output are mutually
21074 exclusive. Only one of them may be set.
21075
21076 +-------------+---------+-------------+--------------+
21077 |return_output|Use: pipe|Type: boolean|Default: false|
21078 +-------------+---------+-------------+--------------+
21079
21080 If this option is true, and the command produced any output, the delivery is
21081 deemed to have failed whatever the return code from the command, and the output
21082 is returned in the bounce message. Otherwise, the output is just discarded.
21083 However, if the message has a null sender (that is, it is a bounce message),
21084 output from the command is always discarded, whatever the setting of this
21085 option. This option and return_fail_output are mutually exclusive. Only one of
21086 them may be set.
21087
21088 +-----------+---------+-----------------+------------------+
21089 |temp_errors|Use: pipe|Type: string list|Default: see below|
21090 +-----------+---------+-----------------+------------------+
21091
21092 This option contains either a colon-separated list of numbers, or a single
21093 asterisk. If ignore_status is false and return_output is not set, and the
21094 command exits with a non-zero return code, the failure is treated as temporary
21095 and the delivery is deferred if the return code matches one of the numbers, or
21096 if the setting is a single asterisk. Otherwise, non-zero return codes are
21097 treated as permanent errors. The default setting contains the codes defined by
21098 EX_TEMPFAIL and EX_CANTCREAT in sysexits.h. If Exim is compiled on a system
21099 that does not define these macros, it assumes values of 75 and 73,
21100 respectively.
21101
21102 +-------+---------+----------+-----------+
21103 |timeout|Use: pipe|Type: time|Default: 1h|
21104 +-------+---------+----------+-----------+
21105
21106 If the command fails to complete within this time, it is killed. This normally
21107 causes the delivery to fail (but see timeout_defer). A zero time interval
21108 specifies no timeout. In order to ensure that any subprocesses created by the
21109 command are also killed, Exim makes the initial process a process group leader,
21110 and kills the whole process group on a timeout. However, this can be defeated
21111 if one of the processes starts a new process group.
21112
21113 +-------------+---------+-------------+--------------+
21114 |timeout_defer|Use: pipe|Type: boolean|Default: false|
21115 +-------------+---------+-------------+--------------+
21116
21117 A timeout in a pipe transport, either in the command that the transport runs,
21118 or in a transport filter that is associated with it, is by default treated as a
21119 hard error, and the delivery fails. However, if timeout_defer is set true, both
21120 kinds of timeout become temporary errors, causing the delivery to be deferred.
21121
21122 +-----+---------+-------------------+------------+
21123 |umask|Use: pipe|Type: octal integer|Default: 022|
21124 +-----+---------+-------------------+------------+
21125
21126 This specifies the umask setting for the subprocess that runs the command.
21127
21128 +---------+---------+-------------+--------------+
21129 |use_bsmtp|Use: pipe|Type: boolean|Default: false|
21130 +---------+---------+-------------+--------------+
21131
21132 If this option is set true, the pipe transport writes messages in "batch SMTP"
21133 format, with the envelope sender and recipient(s) included as SMTP commands. If
21134 you want to include a leading HELO command with such messages, you can do so by
21135 setting the message_prefix option. See section 47.10 for details of batch SMTP.
21136
21137 +------------------+---------+-------------+--------------+
21138 |use_classresources|Use: pipe|Type: boolean|Default: false|
21139 +------------------+---------+-------------+--------------+
21140
21141 This option is available only when Exim is running on FreeBSD, NetBSD, or BSD/
21142 OS. If it is set true, the setclassresources() function is used to set resource
21143 limits when a pipe transport is run to perform a delivery. The limits for the
21144 uid under which the pipe is to run are obtained from the login class database.
21145
21146 +--------+---------+-------------+--------------+
21147 |use_crlf|Use: pipe|Type: boolean|Default: false|
21148 +--------+---------+-------------+--------------+
21149
21150 This option causes lines to be terminated with the two-character CRLF sequence
21151 (carriage return, linefeed) instead of just a linefeed character. In the case
21152 of batched SMTP, the byte sequence written to the pipe is then an exact image
21153 of what would be sent down a real SMTP connection.
21154
21155 The contents of the message_prefix and message_suffix options are written
21156 verbatim, so must contain their own carriage return characters if these are
21157 needed. When use_bsmtp is not set, the default values for both message_prefix
21158 and message_suffix end with a single linefeed, so their values must be changed
21159 to end with "\r\n" if use_crlf is set.
21160
21161 +---------+---------+-------------+--------------+
21162 |use_shell|Use: pipe|Type: boolean|Default: false|
21163 +---------+---------+-------------+--------------+
21164
21165 If this option is set, it causes the command to be passed to /bin/sh instead of
21166 being run directly from the transport, as described in section 29.3. This is
21167 less secure, but is needed in some situations where the command is expected to
21168 be run under a shell and cannot easily be modified. The allow_commands and
21169 restrict_to_path options, and the "$pipe_addresses" facility are incompatible
21170 with use_shell. The command is expanded as a single string, and handed to /bin/
21171 sh as data for its -c option.
21172
21173
21174 29.6 Using an external local delivery agent
21175 -------------------------------------------
21176
21177 The pipe transport can be used to pass all messages that require local delivery
21178 to a separate local delivery agent such as procmail. When doing this, care must
21179 be taken to ensure that the pipe is run under an appropriate uid and gid. In
21180 some configurations one wants this to be a uid that is trusted by the delivery
21181 agent to supply the correct sender of the message. It may be necessary to
21182 recompile or reconfigure the delivery agent so that it trusts an appropriate
21183 user. The following is an example transport and router configuration for
21184 procmail:
21185
21186 # transport
21187 procmail_pipe:
21188 driver = pipe
21189 command = /usr/local/bin/procmail -d $local_part
21190 return_path_add
21191 delivery_date_add
21192 envelope_to_add
21193 check_string = "From "
21194 escape_string = ">From "
21195 umask = 077
21196 user = $local_part
21197 group = mail
21198
21199 # router
21200 procmail:
21201 driver = accept
21202 check_local_user
21203 transport = procmail_pipe
21204
21205 In this example, the pipe is run as the local user, but with the group set to
21206 mail. An alternative is to run the pipe as a specific user such as mail or exim
21207 , but in this case you must arrange for procmail to trust that user to supply a
21208 correct sender address. If you do not specify either a group or a user option,
21209 the pipe command is run as the local user. The home directory is the user's
21210 home directory by default.
21211
21212 Note: The command that the pipe transport runs does not begin with
21213
21214 IFS=" "
21215
21216 as shown in some procmail documentation, because Exim does not by default use a
21217 shell to run pipe commands.
21218
21219 The next example shows a transport and a router for a system where local
21220 deliveries are handled by the Cyrus IMAP server.
21221
21222 # transport
21223 local_delivery_cyrus:
21224 driver = pipe
21225 command = /usr/cyrus/bin/deliver \
21226 -m ${substr_1:$local_part_suffix} -- $local_part
21227 user = cyrus
21228 group = mail
21229 return_output
21230 log_output
21231 message_prefix =
21232 message_suffix =
21233
21234 # router
21235 local_user_cyrus:
21236 driver = accept
21237 check_local_user
21238 local_part_suffix = .*
21239 transport = local_delivery_cyrus
21240
21241 Note the unsetting of message_prefix and message_suffix, and the use of
21242 return_output to cause any text written by Cyrus to be returned to the sender.
21243
21244
21245
21246 ===============================================================================
21247 30. THE SMTP TRANSPORT
21248
21249 The smtp transport delivers messages over TCP/IP connections using the SMTP or
21250 LMTP protocol. The list of hosts to try can either be taken from the address
21251 that is being processed (having been set up by the router), or specified
21252 explicitly for the transport. Timeout and retry processing (see chapter 32) is
21253 applied to each IP address independently.
21254
21255
21256 30.1 Multiple messages on a single connection
21257 ---------------------------------------------
21258
21259 The sending of multiple messages over a single TCP/IP connection can arise in
21260 two ways:
21261
21262 * If a message contains more than max_rcpt (see below) addresses that are
21263 routed to the same host, more than one copy of the message has to be sent
21264 to that host. In this situation, multiple copies may be sent in a single
21265 run of the smtp transport over a single TCP/IP connection. (What Exim
21266 actually does when it has too many addresses to send in one message also
21267 depends on the value of the global remote_max_parallel option. Details are
21268 given in section 47.1.)
21269
21270 * When a message has been successfully delivered over a TCP/IP connection,
21271 Exim looks in its hints database to see if there are any other messages
21272 awaiting a connection to the same host. If there are, a new delivery
21273 process is started for one of them, and the current TCP/IP connection is
21274 passed on to it. The new process may in turn send multiple copies and
21275 possibly create yet another process.
21276
21277 For each copy sent over the same TCP/IP connection, a sequence counter is
21278 incremented, and if it ever gets to the value of connection_max_messages, no
21279 further messages are sent over that connection.
21280
21281
21282 30.2 Use of the $host and $host_address variables
21283 -------------------------------------------------
21284
21285 At the start of a run of the smtp transport, the values of $host and
21286 $host_address are the name and IP address of the first host on the host list
21287 passed by the router. However, when the transport is about to connect to a
21288 specific host, and while it is connected to that host, $host and $host_address
21289 are set to the values for that host. These are the values that are in force
21290 when the helo_data, hosts_try_auth, interface, serialize_hosts, and the various
21291 TLS options are expanded.
21292
21293
21294 30.3 Use of $tls_cipher and $tls_peerdn
21295 ---------------------------------------
21296
21297 At the start of a run of the smtp transport, the values of $tls_bits,
21298 $tls_cipher, $tls_peerdn and $tls_sni are the values that were set when the
21299 message was received. These are the values that are used for options that are
21300 expanded before any SMTP connections are made. Just before each connection is
21301 made, these four variables are emptied. If TLS is subsequently started, they
21302 are set to the appropriate values for the outgoing connection, and these are
21303 the values that are in force when any authenticators are run and when the
21304 authenticated_sender option is expanded.
21305
21306 These variables are deprecated in favour of $tls_in_cipher et. al. and will be
21307 removed in a future release.
21308
21309
21310 30.4 Private options for smtp
21311 -----------------------------
21312
21313 The private options of the smtp transport are as follows:
21314
21315 +----------------------------+---------+-------------+-------------+
21316 |address_retry_include_sender|Use: smtp|Type: boolean|Default: true|
21317 +----------------------------+---------+-------------+-------------+
21318
21319 When an address is delayed because of a 4xx response to a RCPT command, it is
21320 the combination of sender and recipient that is delayed in subsequent queue
21321 runs until the retry time is reached. You can delay the recipient without
21322 reference to the sender (which is what earlier versions of Exim did), by
21323 setting address_retry_include_sender false. However, this can lead to problems
21324 with servers that regularly issue 4xx responses to RCPT commands.
21325
21326 +---------------+---------+-------------+--------------+
21327 |allow_localhost|Use: smtp|Type: boolean|Default: false|
21328 +---------------+---------+-------------+--------------+
21329
21330 When a host specified in hosts or fallback_hosts (see below) turns out to be
21331 the local host, or is listed in hosts_treat_as_local, delivery is deferred by
21332 default. However, if allow_localhost is set, Exim goes on to do the delivery
21333 anyway. This should be used only in special cases when the configuration
21334 ensures that no looping will result (for example, a differently configured Exim
21335 is listening on the port to which the message is sent).
21336
21337 +--------------------+---------+-------------+--------------+
21338 |authenticated_sender|Use: smtp|Type: string*|Default: unset|
21339 +--------------------+---------+-------------+--------------+
21340
21341 When Exim has authenticated as a client, or if authenticated_sender_force is
21342 true, this option sets a value for the AUTH= item on outgoing MAIL commands,
21343 overriding any existing authenticated sender value. If the string expansion is
21344 forced to fail, the option is ignored. Other expansion failures cause delivery
21345 to be deferred. If the result of expansion is an empty string, that is also
21346 ignored.
21347
21348 The expansion happens after the outgoing connection has been made and TLS
21349 started, if required. This means that the $host, $host_address, $tls_out_cipher
21350 , and $tls_out_peerdn variables are set according to the particular connection.
21351
21352 If the SMTP session is not authenticated, the expansion of authenticated_sender
21353 still happens (and can cause the delivery to be deferred if it fails), but no
21354 AUTH= item is added to MAIL commands unless authenticated_sender_force is true.
21355
21356 This option allows you to use the smtp transport in LMTP mode to deliver mail
21357 to Cyrus IMAP and provide the proper local part as the "authenticated sender",
21358 via a setting such as:
21359
21360 authenticated_sender = $local_part
21361
21362 This removes the need for IMAP subfolders to be assigned special ACLs to allow
21363 direct delivery to those subfolders.
21364
21365 Because of expected uses such as that just described for Cyrus (when no domain
21366 is involved), there is no checking on the syntax of the provided value.
21367
21368 +--------------------------+---------+-------------+--------------+
21369 |authenticated_sender_force|Use: smtp|Type: boolean|Default: false|
21370 +--------------------------+---------+-------------+--------------+
21371
21372 If this option is set true, the authenticated_sender option's value is used for
21373 the AUTH= item on outgoing MAIL commands, even if Exim has not authenticated as
21374 a client.
21375
21376 +---------------+---------+----------+-----------+
21377 |command_timeout|Use: smtp|Type: time|Default: 5m|
21378 +---------------+---------+----------+-----------+
21379
21380 This sets a timeout for receiving a response to an SMTP command that has been
21381 sent out. It is also used when waiting for the initial banner line from the
21382 remote host. Its value must not be zero.
21383
21384 +---------------+---------+----------+-----------+
21385 |connect_timeout|Use: smtp|Type: time|Default: 5m|
21386 +---------------+---------+----------+-----------+
21387
21388 This sets a timeout for the connect() function, which sets up a TCP/IP call to
21389 a remote host. A setting of zero allows the system timeout (typically several
21390 minutes) to act. To have any effect, the value of this option must be less than
21391 the system timeout. However, it has been observed that on some systems there is
21392 no system timeout, which is why the default value for this option is 5 minutes,
21393 a value recommended by RFC 1123.
21394
21395 +-----------------------+---------+-------------+------------+
21396 |connection_max_messages|Use: smtp|Type: integer|Default: 500|
21397 +-----------------------+---------+-------------+------------+
21398
21399 This controls the maximum number of separate message deliveries that are sent
21400 over a single TCP/IP connection. If the value is zero, there is no limit. For
21401 testing purposes, this value can be overridden by the -oB command line option.
21402
21403 +------------+---------+----------+-----------+
21404 |data_timeout|Use: smtp|Type: time|Default: 5m|
21405 +------------+---------+----------+-----------+
21406
21407 This sets a timeout for the transmission of each block in the data portion of
21408 the message. As a result, the overall timeout for a message depends on the size
21409 of the message. Its value must not be zero. See also final_timeout.
21410
21411 +------------------+---------+-------------+-------------+
21412 |delay_after_cutoff|Use: smtp|Type: boolean|Default: true|
21413 +------------------+---------+-------------+-------------+
21414
21415 This option controls what happens when all remote IP addresses for a given
21416 domain have been inaccessible for so long that they have passed their retry
21417 cutoff times.
21418
21419 In the default state, if the next retry time has not been reached for any of
21420 them, the address is bounced without trying any deliveries. In other words,
21421 Exim delays retrying an IP address after the final cutoff time until a new
21422 retry time is reached, and can therefore bounce an address without ever trying
21423 a delivery, when machines have been down for a long time. Some people are
21424 unhappy at this prospect, so...
21425
21426 If delay_after_cutoff is set false, Exim behaves differently. If all IP
21427 addresses are past their final cutoff time, Exim tries to deliver to those IP
21428 addresses that have not been tried since the message arrived. If there are
21429 none, of if they all fail, the address is bounced. In other words, it does not
21430 delay when a new message arrives, but immediately tries those expired IP
21431 addresses that haven't been tried since the message arrived. If there is a
21432 continuous stream of messages for the dead hosts, unsetting delay_after_cutoff
21433 means that there will be many more attempts to deliver to them.
21434
21435 +------------------+---------+-------------+-------------+
21436 |dns_qualify_single|Use: smtp|Type: boolean|Default: true|
21437 +------------------+---------+-------------+-------------+
21438
21439 If the hosts or fallback_hosts option is being used, and the gethostbyname
21440 option is false, the RES_DEFNAMES resolver option is set. See the
21441 qualify_single option in chapter 17 for more details.
21442
21443 +------------------+---------+-------------+--------------+
21444 |dns_search_parents|Use: smtp|Type: boolean|Default: false|
21445 +------------------+---------+-------------+--------------+
21446
21447 If the hosts or fallback_hosts option is being used, and the gethostbyname
21448 option is false, the RES_DNSRCH resolver option is set. See the search_parents
21449 option in chapter 17 for more details.
21450
21451 +----------------------+---------+------------------+--------------+
21452 |dnssec_request_domains|Use: smtp|Type: domain list*|Default: unset|
21453 +----------------------+---------+------------------+--------------+
21454
21455 DNS lookups for domains matching dnssec_request_domains will be done with the
21456 dnssec request bit set. This applies to all of the SRV, MX A6, AAAA, A lookup
21457 sequence.
21458
21459 +----------------------+---------+------------------+--------------+
21460 |dnssec_require_domains|Use: smtp|Type: domain list*|Default: unset|
21461 +----------------------+---------+------------------+--------------+
21462
21463 DNS lookups for domains matching dnssec_request_domains will be done with the
21464 dnssec request bit set. Any returns not having the Authenticated Data bit (AD
21465 bit) set wil be ignored and logged as a host-lookup failure. This applies to
21466 all of the SRV, MX A6, AAAA, A lookup sequence.
21467
21468 +----+---------+-------------+--------------+
21469 |dscp|Use: smtp|Type: string*|Default: unset|
21470 +----+---------+-------------+--------------+
21471
21472 This option causes the DSCP value associated with a socket to be set to one of
21473 a number of fixed strings or to numeric value. The -bI:dscp option may be used
21474 to ask Exim which names it knows of. Common values include "throughput",
21475 "mincost", and on newer systems "ef", "af41", etc. Numeric values may be in the
21476 range 0 to 0x3F.
21477
21478 The outbound packets from Exim will be marked with this value in the header
21479 (for IPv4, the TOS field; for IPv6, the TCLASS field); there is no guarantee
21480 that these values will have any effect, not be stripped by networking
21481 equipment, or do much of anything without cooperation with your Network
21482 Engineer and those of all network operators between the source and destination.
21483
21484 +--------------+---------+-----------------+--------------+
21485 |fallback_hosts|Use: smtp|Type: string list|Default: unset|
21486 +--------------+---------+-----------------+--------------+
21487
21488 String expansion is not applied to this option. The argument must be a
21489 colon-separated list of host names or IP addresses, optionally also including
21490 port numbers, though the separator can be changed, as described in section 6.19
21491 . Each individual item in the list is the same as an item in a route_list
21492 setting for the manualroute router, as described in section 20.5.
21493
21494 Fallback hosts can also be specified on routers, which associate them with the
21495 addresses they process. As for the hosts option without hosts_override,
21496 fallback_hosts specified on the transport is used only if the address does not
21497 have its own associated fallback host list. Unlike hosts, a setting of
21498 fallback_hosts on an address is not overridden by hosts_override. However,
21499 hosts_randomize does apply to fallback host lists.
21500
21501 If Exim is unable to deliver to any of the hosts for a particular address, and
21502 the errors are not permanent rejections, the address is put on a separate
21503 transport queue with its host list replaced by the fallback hosts, unless the
21504 address was routed via MX records and the current host was in the original MX
21505 list. In that situation, the fallback host list is not used.
21506
21507 Once normal deliveries are complete, the fallback queue is delivered by
21508 re-running the same transports with the new host lists. If several failing
21509 addresses have the same fallback hosts (and max_rcpt permits it), a single copy
21510 of the message is sent.
21511
21512 The resolution of the host names on the fallback list is controlled by the
21513 gethostbyname option, as for the hosts option. Fallback hosts apply both to
21514 cases when the host list comes with the address and when it is taken from hosts
21515 . This option provides a "use a smart host only if delivery fails" facility.
21516
21517 +-------------+---------+----------+------------+
21518 |final_timeout|Use: smtp|Type: time|Default: 10m|
21519 +-------------+---------+----------+------------+
21520
21521 This is the timeout that applies while waiting for the response to the final
21522 line containing just "." that terminates a message. Its value must not be zero.
21523
21524 +-------------+---------+-------------+--------------+
21525 |gethostbyname|Use: smtp|Type: boolean|Default: false|
21526 +-------------+---------+-------------+--------------+
21527
21528 If this option is true when the hosts and/or fallback_hosts options are being
21529 used, names are looked up using gethostbyname() (or getipnodebyname() when
21530 available) instead of using the DNS. Of course, that function may in fact use
21531 the DNS, but it may also consult other sources of information such as /etc/
21532 hosts.
21533
21534 +------------------+---------+-------------+--------------+
21535 |gnutls_compat_mode|Use: smtp|Type: boolean|Default: unset|
21536 +------------------+---------+-------------+--------------+
21537
21538 This option controls whether GnuTLS is used in compatibility mode in an Exim
21539 server. This reduces security slightly, but improves interworking with older
21540 implementations of TLS.
21541
21542 +---------+---------+-------------+------------------+
21543 |helo_data|Use: smtp|Type: string*|Default: see below|
21544 +---------+---------+-------------+------------------+
21545
21546 The value of this option is expanded after a connection to a another host has
21547 been set up. The result is used as the argument for the EHLO, HELO, or LHLO
21548 command that starts the outgoing SMTP or LMTP session. The default value of the
21549 option is:
21550
21551 $primary_hostname
21552
21553 During the expansion, the variables $host and $host_address are set to the
21554 identity of the remote host, and the variables $sending_ip_address and
21555 $sending_port are set to the local IP address and port number that are being
21556 used. These variables can be used to generate different values for different
21557 servers or different local IP addresses. For example, if you want the string
21558 that is used for helo_data to be obtained by a DNS lookup of the outgoing
21559 interface address, you could use this:
21560
21561 helo_data = ${lookup dnsdb{ptr=$sending_ip_address}{$value}\
21562 {$primary_hostname}}
21563
21564 The use of helo_data applies both to sending messages and when doing callouts.
21565
21566 +-----+---------+------------------+--------------+
21567 |hosts|Use: smtp|Type: string list*|Default: unset|
21568 +-----+---------+------------------+--------------+
21569
21570 Hosts are associated with an address by a router such as dnslookup, which finds
21571 the hosts by looking up the address domain in the DNS, or by manualroute, which
21572 has lists of hosts in its configuration. However, email addresses can be passed
21573 to the smtp transport by any router, and not all of them can provide an
21574 associated list of hosts.
21575
21576 The hosts option specifies a list of hosts to be used if the address being
21577 processed does not have any hosts associated with it. The hosts specified by
21578 hosts are also used, whether or not the address has its own hosts, if
21579 hosts_override is set.
21580
21581 The string is first expanded, before being interpreted as a colon-separated
21582 list of host names or IP addresses, possibly including port numbers. The
21583 separator may be changed to something other than colon, as described in section
21584 6.19. Each individual item in the list is the same as an item in a route_list
21585 setting for the manualroute router, as described in section 20.5. However, note
21586 that the "/MX" facility of the manualroute router is not available here.
21587
21588 If the expansion fails, delivery is deferred. Unless the failure was caused by
21589 the inability to complete a lookup, the error is logged to the panic log as
21590 well as the main log. Host names are looked up either by searching directly for
21591 address records in the DNS or by calling gethostbyname() (or getipnodebyname()
21592 when available), depending on the setting of the gethostbyname option. When
21593 Exim is compiled with IPv6 support, if a host that is looked up in the DNS has
21594 both IPv4 and IPv6 addresses, both types of address are used.
21595
21596 During delivery, the hosts are tried in order, subject to their retry status,
21597 unless hosts_randomize is set.
21598
21599 +-----------------+---------+----------------+--------------+
21600 |hosts_avoid_esmtp|Use: smtp|Type: host list*|Default: unset|
21601 +-----------------+---------+----------------+--------------+
21602
21603 This option is for use with broken hosts that announce ESMTP facilities (for
21604 example, PIPELINING) and then fail to implement them properly. When a host
21605 matches hosts_avoid_esmtp, Exim sends HELO rather than EHLO at the start of the
21606 SMTP session. This means that it cannot use any of the ESMTP facilities such as
21607 AUTH, PIPELINING, SIZE, and STARTTLS.
21608
21609 +----------------------+---------+----------------+--------------+
21610 |hosts_avoid_pipelining|Use: smtp|Type: host list*|Default: unset|
21611 +----------------------+---------+----------------+--------------+
21612
21613 Exim will not use the SMTP PIPELINING extension when delivering to any host
21614 that matches this list, even if the server host advertises PIPELINING support.
21615
21616 +---------------+---------+----------------+--------------+
21617 |hosts_avoid_tls|Use: smtp|Type: host list*|Default: unset|
21618 +---------------+---------+----------------+--------------+
21619
21620 Exim will not try to start a TLS session when delivering to any host that
21621 matches this list. See chapter 41 for details of TLS.
21622
21623 +----------------------+---------+----------------+----------+
21624 |hosts_verify_avoid_tls|Use: smtp|Type: host list*|Default: *|
21625 +----------------------+---------+----------------+----------+
21626
21627 Exim will not try to start a TLS session for a verify callout, or when
21628 delivering in cutthrough mode, to any host that matches this list. Note that
21629 the default is to not use TLS.
21630
21631 +-------------+---------+-------------+----------+
21632 |hosts_max_try|Use: smtp|Type: integer|Default: 5|
21633 +-------------+---------+-------------+----------+
21634
21635 This option limits the number of IP addresses that are tried for any one
21636 delivery in cases where there are temporary delivery errors. Section 30.5
21637 describes in detail how the value of this option is used.
21638
21639 +-----------------------+---------+-------------+-----------+
21640 |hosts_max_try_hardlimit|Use: smtp|Type: integer|Default: 50|
21641 +-----------------------+---------+-------------+-----------+
21642
21643 This is an additional check on the maximum number of IP addresses that Exim
21644 tries for any one delivery. Section 30.5 describes its use and why it exists.
21645
21646 +----------------+---------+----------------+--------------+
21647 |hosts_nopass_tls|Use: smtp|Type: host list*|Default: unset|
21648 +----------------+---------+----------------+--------------+
21649
21650 For any host that matches this list, a connection on which a TLS session has
21651 been started will not be passed to a new delivery process for sending another
21652 message on the same connection. See section 41.11 for an explanation of when
21653 this might be needed.
21654
21655 +--------------+---------+-------------+--------------+
21656 |hosts_override|Use: smtp|Type: boolean|Default: false|
21657 +--------------+---------+-------------+--------------+
21658
21659 If this option is set and the hosts option is also set, any hosts that are
21660 attached to the address are ignored, and instead the hosts specified by the
21661 hosts option are always used. This option does not apply to fallback_hosts.
21662
21663 +---------------+---------+-------------+--------------+
21664 |hosts_randomize|Use: smtp|Type: boolean|Default: false|
21665 +---------------+---------+-------------+--------------+
21666
21667 If this option is set, and either the list of hosts is taken from the hosts or
21668 the fallback_hosts option, or the hosts supplied by the router were not
21669 obtained from MX records (this includes fallback hosts from the router), and
21670 were not randomized by the router, the order of trying the hosts is randomized
21671 each time the transport runs. Randomizing the order of a host list can be used
21672 to do crude load sharing.
21673
21674 When hosts_randomize is true, a host list may be split into groups whose order
21675 is separately randomized. This makes it possible to set up MX-like behaviour.
21676 The boundaries between groups are indicated by an item that is just "+" in the
21677 host list. For example:
21678
21679 hosts = host1:host2:host3:+:host4:host5
21680
21681 The order of the first three hosts and the order of the last two hosts is
21682 randomized for each use, but the first three always end up before the last two.
21683 If hosts_randomize is not set, a "+" item in the list is ignored.
21684
21685 +------------------+---------+----------------+--------------+
21686 |hosts_require_auth|Use: smtp|Type: host list*|Default: unset|
21687 +------------------+---------+----------------+--------------+
21688
21689 This option provides a list of servers for which authentication must succeed
21690 before Exim will try to transfer a message. If authentication fails for servers
21691 which are not in this list, Exim tries to send unauthenticated. If
21692 authentication fails for one of these servers, delivery is deferred. This
21693 temporary error is detectable in the retry rules, so it can be turned into a
21694 hard failure if required. See also hosts_try_auth, and chapter 33 for details
21695 of authentication.
21696
21697 +------------------+---------+----------------+----------+
21698 |hosts_request_ocsp|Use: smtp|Type: host list*|Default: *|
21699 +------------------+---------+----------------+----------+
21700
21701 Exim will request a Certificate Status on a TLS session for any host that
21702 matches this list. tls_verify_certificates should also be set for the
21703 transport.
21704
21705 +------------------+---------+----------------+--------------+
21706 |hosts_require_ocsp|Use: smtp|Type: host list*|Default: unset|
21707 +------------------+---------+----------------+--------------+
21708
21709 Exim will request, and check for a valid Certificate Status being given, on a
21710 TLS session for any host that matches this list. tls_verify_certificates should
21711 also be set for the transport.
21712
21713 +-----------------+---------+----------------+--------------+
21714 |hosts_require_tls|Use: smtp|Type: host list*|Default: unset|
21715 +-----------------+---------+----------------+--------------+
21716
21717 Exim will insist on using a TLS session when delivering to any host that
21718 matches this list. See chapter 41 for details of TLS. Note: This option affects
21719 outgoing mail only. To insist on TLS for incoming messages, use an appropriate
21720 ACL.
21721
21722 +--------------+---------+----------------+--------------+
21723 |hosts_try_auth|Use: smtp|Type: host list*|Default: unset|
21724 +--------------+---------+----------------+--------------+
21725
21726 This option provides a list of servers to which, provided they announce
21727 authentication support, Exim will attempt to authenticate as a client when it
21728 connects. If authentication fails, Exim will try to transfer the message
21729 unauthenticated. See also hosts_require_auth, and chapter 33 for details of
21730 authentication.
21731
21732 +--------------+---------+----------------+--------------+
21733 |hosts_try_prdr|Use: smtp|Type: host list*|Default: unset|
21734 +--------------+---------+----------------+--------------+
21735
21736 This option provides a list of servers to which, provided they announce PRDR
21737 support, Exim will attempt to negotiate PRDR for multi-recipient messages.
21738
21739 +---------+---------+------------------+--------------+
21740 |interface|Use: smtp|Type: string list*|Default: unset|
21741 +---------+---------+------------------+--------------+
21742
21743 This option specifies which interface to bind to when making an outgoing SMTP
21744 call. The value is an IP address, not an interface name such as "eth0". Do not
21745 confuse this with the interface address that was used when a message was
21746 received, which is in $received_ip_address, formerly known as
21747 $interface_address. The name was changed to minimize confusion with the
21748 outgoing interface address. There is no variable that contains an outgoing
21749 interface address because, unless it is set by this option, its value is
21750 unknown.
21751
21752 During the expansion of the interface option the variables $host and
21753 $host_address refer to the host to which a connection is about to be made
21754 during the expansion of the string. Forced expansion failure, or an empty
21755 string result causes the option to be ignored. Otherwise, after expansion, the
21756 string must be a list of IP addresses, colon-separated by default, but the
21757 separator can be changed in the usual way. For example:
21758
21759 interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061
21760
21761 The first interface of the correct type (IPv4 or IPv6) is used for the outgoing
21762 connection. If none of them are the correct type, the option is ignored. If
21763 interface is not set, or is ignored, the system's IP functions choose which
21764 interface to use if the host has more than one.
21765
21766 +---------+---------+-------------+-------------+
21767 |keepalive|Use: smtp|Type: boolean|Default: true|
21768 +---------+---------+-------------+-------------+
21769
21770 This option controls the setting of SO_KEEPALIVE on outgoing TCP/IP socket
21771 connections. When set, it causes the kernel to probe idle connections
21772 periodically, by sending packets with "old" sequence numbers. The other end of
21773 the connection should send a acknowledgment if the connection is still okay or
21774 a reset if the connection has been aborted. The reason for doing this is that
21775 it has the beneficial effect of freeing up certain types of connection that can
21776 get stuck when the remote host is disconnected without tidying up the TCP/IP
21777 call properly. The keepalive mechanism takes several hours to detect
21778 unreachable hosts.
21779
21780 +-----------------+---------+-------------+--------------+
21781 |lmtp_ignore_quota|Use: smtp|Type: boolean|Default: false|
21782 +-----------------+---------+-------------+--------------+
21783
21784 If this option is set true when the protocol option is set to "lmtp", the
21785 string "IGNOREQUOTA" is added to RCPT commands, provided that the LMTP server
21786 has advertised support for IGNOREQUOTA in its response to the LHLO command.
21787
21788 +--------+---------+-------------+------------+
21789 |max_rcpt|Use: smtp|Type: integer|Default: 100|
21790 +--------+---------+-------------+------------+
21791
21792 This option limits the number of RCPT commands that are sent in a single SMTP
21793 message transaction. Each set of addresses is treated independently, and so can
21794 cause parallel connections to the same host if remote_max_parallel permits
21795 this.
21796
21797 +------------+---------+-------------+-------------+
21798 |multi_domain|Use: smtp|Type: boolean|Default: true|
21799 +------------+---------+-------------+-------------+
21800
21801 When this option is set, the smtp transport can handle a number of addresses
21802 containing a mixture of different domains provided they all resolve to the same
21803 list of hosts. Turning the option off restricts the transport to handling only
21804 one domain at a time. This is useful if you want to use $domain in an expansion
21805 for the transport, because it is set only when there is a single domain
21806 involved in a remote delivery.
21807
21808 +----+---------+-------------+------------------+
21809 |port|Use: smtp|Type: string*|Default: see below|
21810 +----+---------+-------------+------------------+
21811
21812 This option specifies the TCP/IP port on the server to which Exim connects.
21813 Note: Do not confuse this with the port that was used when a message was
21814 received, which is in $received_port, formerly known as $interface_port. The
21815 name was changed to minimize confusion with the outgoing port. There is no
21816 variable that contains an outgoing port.
21817
21818 If the value of this option begins with a digit it is taken as a port number;
21819 otherwise it is looked up using getservbyname(). The default value is normally
21820 "smtp", but if protocol is set to "lmtp", the default is "lmtp". If the
21821 expansion fails, or if a port number cannot be found, delivery is deferred.
21822
21823 +--------+---------+------------+-------------+
21824 |protocol|Use: smtp|Type: string|Default: smtp|
21825 +--------+---------+------------+-------------+
21826
21827 If this option is set to "lmtp" instead of "smtp", the default value for the
21828 port option changes to "lmtp", and the transport operates the LMTP protocol
21829 (RFC 2033) instead of SMTP. This protocol is sometimes used for local
21830 deliveries into closed message stores. Exim also has support for running LMTP
21831 over a pipe to a local process - see chapter 28.
21832
21833 If this option is set to "smtps", the default vaule for the port option changes
21834 to "smtps", and the transport initiates TLS immediately after connecting, as an
21835 outbound SSL-on-connect, instead of using STARTTLS to upgrade. The Internet
21836 standards bodies strongly discourage use of this mode.
21837
21838 +------------------------+---------+-------------+-------------+
21839 |retry_include_ip_address|Use: smtp|Type: boolean|Default: true|
21840 +------------------------+---------+-------------+-------------+
21841
21842 Exim normally includes both the host name and the IP address in the key it
21843 constructs for indexing retry data after a temporary delivery failure. This
21844 means that when one of several IP addresses for a host is failing, it gets
21845 tried periodically (controlled by the retry rules), but use of the other IP
21846 addresses is not affected.
21847
21848 However, in some dialup environments hosts are assigned a different IP address
21849 each time they connect. In this situation the use of the IP address as part of
21850 the retry key leads to undesirable behaviour. Setting this option false causes
21851 Exim to use only the host name. This should normally be done on a separate
21852 instance of the smtp transport, set up specially to handle the dialup hosts.
21853
21854 +---------------+---------+----------------+--------------+
21855 |serialize_hosts|Use: smtp|Type: host list*|Default: unset|
21856 +---------------+---------+----------------+--------------+
21857
21858 Because Exim operates in a distributed manner, if several messages for the same
21859 host arrive at around the same time, more than one simultaneous connection to
21860 the remote host can occur. This is not usually a problem except when there is a
21861 slow link between the hosts. In that situation it may be helpful to restrict
21862 Exim to one connection at a time. This can be done by setting serialize_hosts
21863 to match the relevant hosts.
21864
21865 Exim implements serialization by means of a hints database in which a record is
21866 written whenever a process connects to one of the restricted hosts. The record
21867 is deleted when the connection is completed. Obviously there is scope for
21868 records to get left lying around if there is a system or program crash. To
21869 guard against this, Exim ignores any records that are more than six hours old.
21870
21871 If you set up this kind of serialization, you should also arrange to delete the
21872 relevant hints database whenever your system reboots. The names of the files
21873 start with misc and they are kept in the spool/db directory. There may be one
21874 or two files, depending on the type of DBM in use. The same files are used for
21875 ETRN serialization.
21876
21877 +-------------+---------+-------------+-------------+
21878 |size_addition|Use: smtp|Type: integer|Default: 1024|
21879 +-------------+---------+-------------+-------------+
21880
21881 If a remote SMTP server indicates that it supports the SIZE option of the MAIL
21882 command, Exim uses this to pass over the message size at the start of an SMTP
21883 transaction. It adds the value of size_addition to the value it sends, to allow
21884 for headers and other text that may be added during delivery by configuration
21885 options or in a transport filter. It may be necessary to increase this if a lot
21886 of text is added to messages.
21887
21888 Alternatively, if the value of size_addition is set negative, it disables the
21889 use of the SIZE option altogether.
21890
21891 +---------------+---------+-------------+--------------+
21892 |tls_certificate|Use: smtp|Type: string*|Default: unset|
21893 +---------------+---------+-------------+--------------+
21894
21895 The value of this option must be the absolute path to a file which contains the
21896 client's certificate, for possible use when sending a message over an encrypted
21897 connection. The values of $host and $host_address are set to the name and
21898 address of the server during the expansion. See chapter 41 for details of TLS.
21899
21900 Note: This option must be set if you want Exim to be able to use a TLS
21901 certificate when sending messages as a client. The global option of the same
21902 name specifies the certificate for Exim as a server; it is not automatically
21903 assumed that the same certificate should be used when Exim is operating as a
21904 client.
21905
21906 +-------+---------+-------------+--------------+
21907 |tls_crl|Use: smtp|Type: string*|Default: unset|
21908 +-------+---------+-------------+--------------+
21909
21910 This option specifies a certificate revocation list. The expanded value must be
21911 the name of a file that contains a CRL in PEM format.
21912
21913 +---------------+---------+-------------+-------------+
21914 |tls_dh_min_bits|Use: smtp|Type: integer|Default: 1024|
21915 +---------------+---------+-------------+-------------+
21916
21917 When establishing a TLS session, if a ciphersuite which uses Diffie-Hellman key
21918 agreement is negotiated, the server will provide a large prime number for use.
21919 This option establishes the minimum acceptable size of that number. If the
21920 parameter offered by the server is too small, then the TLS handshake will fail.
21921
21922 Only supported when using GnuTLS.
21923
21924 +--------------+---------+-------------+--------------+
21925 |tls_privatekey|Use: smtp|Type: string*|Default: unset|
21926 +--------------+---------+-------------+--------------+
21927
21928 The value of this option must be the absolute path to a file which contains the
21929 client's private key. This is used when sending a message over an encrypted
21930 connection using a client certificate. The values of $host and $host_address
21931 are set to the name and address of the server during the expansion. If this
21932 option is unset, or the expansion is forced to fail, or the result is an empty
21933 string, the private key is assumed to be in the same file as the certificate.
21934 See chapter 41 for details of TLS.
21935
21936 +-------------------+---------+-------------+--------------+
21937 |tls_require_ciphers|Use: smtp|Type: string*|Default: unset|
21938 +-------------------+---------+-------------+--------------+
21939
21940 The value of this option must be a list of permitted cipher suites, for use
21941 when setting up an outgoing encrypted connection. (There is a global option of
21942 the same name for controlling incoming connections.) The values of $host and
21943 $host_address are set to the name and address of the server during the
21944 expansion. See chapter 41 for details of TLS; note that this option is used in
21945 different ways by OpenSSL and GnuTLS (see sections 41.4 and 41.5). For GnuTLS,
21946 the order of the ciphers is a preference order.
21947
21948 +-------+---------+-------------+--------------+
21949 |tls_sni|Use: smtp|Type: string*|Default: unset|
21950 +-------+---------+-------------+--------------+
21951
21952 If this option is set then it sets the $tls_out_sni variable and causes any TLS
21953 session to pass this value as the Server Name Indication extension to the
21954 remote side, which can be used by the remote side to select an appropriate
21955 certificate and private key for the session.
21956
21957 See 41.10 for more information.
21958
21959 Note that for OpenSSL, this feature requires a build of OpenSSL that supports
21960 TLS extensions.
21961
21962 +---------------------+---------+-------------+-------------+
21963 |tls_tempfail_tryclear|Use: smtp|Type: boolean|Default: true|
21964 +---------------------+---------+-------------+-------------+
21965
21966 When the server host is not in hosts_require_tls, and there is a problem in
21967 setting up a TLS session, this option determines whether or not Exim should try
21968 to deliver the message unencrypted. If it is set false, delivery to the current
21969 host is deferred; if there are other hosts, they are tried. If this option is
21970 set true, Exim attempts to deliver unencrypted after a 4xx response to
21971 STARTTLS. Also, if STARTTLS is accepted, but the subsequent TLS negotiation
21972 fails, Exim closes the current connection (because it is in an unknown state),
21973 opens a new one to the same host, and then tries the delivery in clear.
21974
21975 +--------------------+---------+----------------------+--------+
21976 |tls_try_verify_hosts|Use: smtp|Type: host list* unset|Default:|
21977 +--------------------+---------+----------------------+--------+
21978
21979 This option gives a list of hosts for which, on encrypted connections,
21980 certificate verification will be tried but need not succeed. The
21981 tls_verify_certificates option must also be set. Note that unless the host is
21982 in this list TLS connections will be denied to hosts using self-signed
21983 certificates when tls_verify_certificates is set. The
21984 $tls_out_certificate_verified variable is set when certificate verification
21985 succeeds.
21986
21987 +-----------------------+---------+-------------+--------------+
21988 |tls_verify_certificates|Use: smtp|Type: string*|Default: unset|
21989 +-----------------------+---------+-------------+--------------+
21990
21991 The value of this option must be the absolute path to a file containing
21992 permitted server certificates, for use when setting up an encrypted connection.
21993 Alternatively, if you are using OpenSSL, you can set tls_verify_certificates to
21994 the name of a directory containing certificate files. This does not work with
21995 GnuTLS; the option must be set to the name of a single file if you are using
21996 GnuTLS. The values of $host and $host_address are set to the name and address
21997 of the server during the expansion of this option. See chapter 41 for details
21998 of TLS.
21999
22000 For back-compatability, if neither tls_verify_hosts nor tls_try_verify_hosts
22001 are set and certificate verification fails the TLS connection is closed.
22002
22003 +----------------+---------+----------------------+--------+
22004 |tls_verify_hosts|Use: smtp|Type: host list* unset|Default:|
22005 +----------------+---------+----------------------+--------+
22006
22007 This option gives a list of hosts for which. on encrypted connections,
22008 certificate verification must succeed. The tls_verify_certificates option must
22009 also be set. If both this option and tls_try_verify_hosts are unset operation
22010 is as if this option selected all hosts.
22011
22012
22013 30.5 How the limits for the number of hosts to try are used
22014 -----------------------------------------------------------
22015
22016 There are two options that are concerned with the number of hosts that are
22017 tried when an SMTP delivery takes place. They are hosts_max_try and
22018 hosts_max_try_hardlimit.
22019
22020 The hosts_max_try option limits the number of hosts that are tried for a single
22021 delivery. However, despite the term "host" in its name, the option actually
22022 applies to each IP address independently. In other words, a multihomed host is
22023 treated as several independent hosts, just as it is for retrying.
22024
22025 Many of the larger ISPs have multiple MX records which often point to
22026 multihomed hosts. As a result, a list of a dozen or more IP addresses may be
22027 created as a result of routing one of these domains.
22028
22029 Trying every single IP address on such a long list does not seem sensible; if
22030 several at the top of the list fail, it is reasonable to assume there is some
22031 problem that is likely to affect all of them. Roughly speaking, the value of
22032 hosts_max_try is the maximum number that are tried before deferring the
22033 delivery. However, the logic cannot be quite that simple.
22034
22035 Firstly, IP addresses that are skipped because their retry times have not
22036 arrived do not count, and in addition, addresses that are past their retry
22037 limits are also not counted, even when they are tried. This means that when
22038 some IP addresses are past their retry limits, more than the value of
22039 hosts_max_retry may be tried. The reason for this behaviour is to ensure that
22040 all IP addresses are considered before timing out an email address (but see
22041 below for an exception).
22042
22043 Secondly, when the hosts_max_try limit is reached, Exim looks down the host
22044 list to see if there is a subsequent host with a different (higher valued) MX.
22045 If there is, that host is considered next, and the current IP address is used
22046 but not counted. This behaviour helps in the case of a domain with a retry rule
22047 that hardly ever delays any hosts, as is now explained:
22048
22049 Consider the case of a long list of hosts with one MX value, and a few with a
22050 higher MX value. If hosts_max_try is small (the default is 5) only a few hosts
22051 at the top of the list are tried at first. With the default retry rule, which
22052 specifies increasing retry times, the higher MX hosts are eventually tried when
22053 those at the top of the list are skipped because they have not reached their
22054 retry times.
22055
22056 However, it is common practice to put a fixed short retry time on domains for
22057 large ISPs, on the grounds that their servers are rarely down for very long.
22058 Unfortunately, these are exactly the domains that tend to resolve to long lists
22059 of hosts. The short retry time means that the lowest MX hosts are tried every
22060 time. The attempts may be in a different order because of random sorting, but
22061 without the special MX check, the higher MX hosts would never be tried until
22062 all the lower MX hosts had timed out (which might be several days), because
22063 there are always some lower MX hosts that have reached their retry times. With
22064 the special check, Exim considers at least one IP address from each MX value at
22065 every delivery attempt, even if the hosts_max_try limit has already been
22066 reached.
22067
22068 The above logic means that hosts_max_try is not a hard limit, and in
22069 particular, Exim normally eventually tries all the IP addresses before timing
22070 out an email address. When hosts_max_try was implemented, this seemed a
22071 reasonable thing to do. Recently, however, some lunatic DNS configurations have
22072 been set up with hundreds of IP addresses for some domains. It can take a very
22073 long time indeed for an address to time out in these cases.
22074
22075 The hosts_max_try_hardlimit option was added to help with this problem. Exim
22076 never tries more than this number of IP addresses; if it hits this limit and
22077 they are all timed out, the email address is bounced, even though not all
22078 possible IP addresses have been tried.
22079
22080
22081
22082 ===============================================================================
22083 31. ADDRESS REWRITING
22084
22085 There are some circumstances in which Exim automatically rewrites domains in
22086 addresses. The two most common are when an address is given without a domain
22087 (referred to as an "unqualified address") or when an address contains an
22088 abbreviated domain that is expanded by DNS lookup.
22089
22090 Unqualified envelope addresses are accepted only for locally submitted
22091 messages, or for messages that are received from hosts matching
22092 sender_unqualified_hosts or recipient_unqualified_hosts, as appropriate.
22093 Unqualified addresses in header lines are qualified if they are in locally
22094 submitted messages, or messages from hosts that are permitted to send
22095 unqualified envelope addresses. Otherwise, unqualified addresses in header
22096 lines are neither qualified nor rewritten.
22097
22098 One situation in which Exim does not automatically rewrite a domain is when it
22099 is the name of a CNAME record in the DNS. The older RFCs suggest that such a
22100 domain should be rewritten using the "canonical" name, and some MTAs do this.
22101 The new RFCs do not contain this suggestion.
22102
22103
22104 31.1 Explicitly configured address rewriting
22105 --------------------------------------------
22106
22107 This chapter describes the rewriting rules that can be used in the main rewrite
22108 section of the configuration file, and also in the generic headers_rewrite
22109 option that can be set on any transport.
22110
22111 Some people believe that configured address rewriting is a Mortal Sin. Others
22112 believe that life is not possible without it. Exim provides the facility; you
22113 do not have to use it.
22114
22115 The main rewriting rules that appear in the "rewrite" section of the
22116 configuration file are applied to addresses in incoming messages, both envelope
22117 addresses and addresses in header lines. Each rule specifies the types of
22118 address to which it applies.
22119
22120 Whether or not addresses in header lines are rewritten depends on the origin of
22121 the headers and the type of rewriting. Global rewriting, that is, rewriting
22122 rules from the rewrite section of the configuration file, is applied only to
22123 those headers that were received with the message. Header lines that are added
22124 by ACLs or by a system filter or by individual routers or transports (which are
22125 specific to individual recipient addresses) are not rewritten by the global
22126 rules.
22127
22128 Rewriting at transport time, by means of the headers_rewrite option, applies
22129 all headers except those added by routers and transports. That is, as well as
22130 the headers that were received with the message, it also applies to headers
22131 that were added by an ACL or a system filter.
22132
22133 In general, rewriting addresses from your own system or domain has some
22134 legitimacy. Rewriting other addresses should be done only with great care and
22135 in special circumstances. The author of Exim believes that rewriting should be
22136 used sparingly, and mainly for "regularizing" addresses in your own domains.
22137 Although it can sometimes be used as a routing tool, this is very strongly
22138 discouraged.
22139
22140 There are two commonly encountered circumstances where rewriting is used, as
22141 illustrated by these examples:
22142
22143 * The company whose domain is hitch.fict.example has a number of hosts that
22144 exchange mail with each other behind a firewall, but there is only a single
22145 gateway to the outer world. The gateway rewrites *.hitch.fict.example as
22146 hitch.fict.example when sending mail off-site.
22147
22148 * A host rewrites the local parts of its own users so that, for example,
22149 fp42@hitch.fict.example becomes Ford.Prefect@hitch.fict.example.
22150
22151
22152 31.2 When does rewriting happen?
22153 --------------------------------
22154
22155 Configured address rewriting can take place at several different stages of a
22156 message's processing.
22157
22158 At the start of an ACL for MAIL, the sender address may have been rewritten by
22159 a special SMTP-time rewrite rule (see section 31.9), but no ordinary rewrite
22160 rules have yet been applied. If, however, the sender address is verified in the
22161 ACL, it is rewritten before verification, and remains rewritten thereafter. The
22162 subsequent value of $sender_address is the rewritten address. This also applies
22163 if sender verification happens in a RCPT ACL. Otherwise, when the sender
22164 address is not verified, it is rewritten as soon as a message's header lines
22165 have been received.
22166
22167 Similarly, at the start of an ACL for RCPT, the current recipient's address may
22168 have been rewritten by a special SMTP-time rewrite rule, but no ordinary
22169 rewrite rules have yet been applied to it. However, the behaviour is different
22170 from the sender address when a recipient is verified. The address is rewritten
22171 for the verification, but the rewriting is not remembered at this stage. The
22172 value of $local_part and $domain after verification are always the same as they
22173 were before (that is, they contain the unrewritten - except for SMTP-time
22174 rewriting - address).
22175
22176 As soon as a message's header lines have been received, all the envelope
22177 recipient addresses are permanently rewritten, and rewriting is also applied to
22178 the addresses in the header lines (if configured). This happens before adding
22179 any header lines that were specified in MAIL or RCPT ACLs, and before the DATA
22180 ACL and local_scan() functions are run.
22181
22182 When an address is being routed, either for delivery or for verification,
22183 rewriting is applied immediately to child addresses that are generated by
22184 redirection, unless no_rewrite is set on the router.
22185
22186 At transport time, additional rewriting of addresses in header lines can be
22187 specified by setting the generic headers_rewrite option on a transport. This
22188 option contains rules that are identical in form to those in the rewrite
22189 section of the configuration file. They are applied to the original message
22190 header lines and any that were added by ACLs or a system filter. They are not
22191 applied to header lines that are added by routers or the transport.
22192
22193 The outgoing envelope sender can be rewritten by means of the return_path
22194 transport option. However, it is not possible to rewrite envelope recipients at
22195 transport time.
22196
22197
22198 31.3 Testing the rewriting rules that apply on input
22199 ----------------------------------------------------
22200
22201 Exim's input rewriting configuration appears in a part of the run time
22202 configuration file headed by "begin rewrite". It can be tested by the -brw
22203 command line option. This takes an address (which can be a full RFC 2822
22204 address) as its argument. The output is a list of how the address would be
22205 transformed by the rewriting rules for each of the different places it might
22206 appear in an incoming message, that is, for each different header and for the
22207 envelope sender and recipient fields. For example,
22208
22209 exim -brw ph10@exim.workshop.example
22210
22211 might produce the output
22212
22213 sender: Philip.Hazel@exim.workshop.example
22214 from: Philip.Hazel@exim.workshop.example
22215 to: ph10@exim.workshop.example
22216 cc: ph10@exim.workshop.example
22217 bcc: ph10@exim.workshop.example
22218 reply-to: Philip.Hazel@exim.workshop.example
22219 env-from: Philip.Hazel@exim.workshop.example
22220 env-to: ph10@exim.workshop.example
22221
22222 which shows that rewriting has been set up for that address when used in any of
22223 the source fields, but not when it appears as a recipient address. At the
22224 present time, there is no equivalent way of testing rewriting rules that are
22225 set for a particular transport.
22226
22227
22228 31.4 Rewriting rules
22229 --------------------
22230
22231 The rewrite section of the configuration file consists of lines of rewriting
22232 rules in the form
22233
22234 <source pattern> <replacement> <flags>
22235
22236 Rewriting rules that are specified for the headers_rewrite generic transport
22237 option are given as a colon-separated list. Each item in the list takes the
22238 same form as a line in the main rewriting configuration (except that any colons
22239 must be doubled, of course).
22240
22241 The formats of source patterns and replacement strings are described below.
22242 Each is terminated by white space, unless enclosed in double quotes, in which
22243 case normal quoting conventions apply inside the quotes. The flags are single
22244 characters which may appear in any order. Spaces and tabs between them are
22245 ignored.
22246
22247 For each address that could potentially be rewritten, the rules are scanned in
22248 order, and replacements for the address from earlier rules can themselves be
22249 replaced by later rules (but see the "q" and "R" flags).
22250
22251 The order in which addresses are rewritten is undefined, may change between
22252 releases, and must not be relied on, with one exception: when a message is
22253 received, the envelope sender is always rewritten first, before any header
22254 lines are rewritten. For example, the replacement string for a rewrite of an
22255 address in To: must not assume that the message's address in From: has (or has
22256 not) already been rewritten. However, a rewrite of From: may assume that the
22257 envelope sender has already been rewritten.
22258
22259 The variables $local_part and $domain can be used in the replacement string to
22260 refer to the address that is being rewritten. Note that lookup-driven rewriting
22261 can be done by a rule of the form
22262
22263 *@* ${lookup ...
22264
22265 where the lookup key uses $1 and $2 or $local_part and $domain to refer to the
22266 address that is being rewritten.
22267
22268
22269 31.5 Rewriting patterns
22270 -----------------------
22271
22272 The source pattern in a rewriting rule is any item which may appear in an
22273 address list (see section 10.19). It is in fact processed as a single-item
22274 address list, which means that it is expanded before being tested against the
22275 address. As always, if you use a regular expression as a pattern, you must take
22276 care to escape dollar and backslash characters, or use the "\N" facility to
22277 suppress string expansion within the regular expression.
22278
22279 Domains in patterns should be given in lower case. Local parts in patterns are
22280 case-sensitive. If you want to do case-insensitive matching of local parts, you
22281 can use a regular expression that starts with "^(?i)".
22282
22283 After matching, the numerical variables $1, $2, etc. may be set, depending on
22284 the type of match which occurred. These can be used in the replacement string
22285 to insert portions of the incoming address. $0 always refers to the complete
22286 incoming address. When a regular expression is used, the numerical variables
22287 are set from its capturing subexpressions. For other types of pattern they are
22288 set as follows:
22289
22290 * If a local part or domain starts with an asterisk, the numerical variables
22291 refer to the character strings matched by asterisks, with $1 associated
22292 with the first asterisk, and $2 with the second, if present. For example,
22293 if the pattern
22294
22295 *queen@*.fict.example
22296
22297 is matched against the address hearts-queen@wonderland.fict.example then
22298
22299 $0 = hearts-queen@wonderland.fict.example
22300 $1 = hearts-
22301 $2 = wonderland
22302
22303 Note that if the local part does not start with an asterisk, but the domain
22304 does, it is $1 that contains the wild part of the domain.
22305
22306 * If the domain part of the pattern is a partial lookup, the wild and fixed
22307 parts of the domain are placed in the next available numerical variables.
22308 Suppose, for example, that the address foo@bar.baz.example is processed by
22309 a rewriting rule of the form
22310
22311 *@partial-dbm;/some/dbm/file <replacement string>
22312
22313 and the key in the file that matches the domain is "*.baz.example". Then
22314
22315 $1 = foo
22316 $2 = bar
22317 $3 = baz.example
22318
22319 If the address foo@baz.example is looked up, this matches the same wildcard
22320 file entry, and in this case $2 is set to the empty string, but $3 is still
22321 set to baz.example. If a non-wild key is matched in a partial lookup, $2 is
22322 again set to the empty string and $3 is set to the whole domain. For
22323 non-partial domain lookups, no numerical variables are set.
22324
22325
22326 31.6 Rewriting replacements
22327 ---------------------------
22328
22329 If the replacement string for a rule is a single asterisk, addresses that match
22330 the pattern and the flags are not rewritten, and no subsequent rewriting rules
22331 are scanned. For example,
22332
22333 hatta@lookingglass.fict.example * f
22334
22335 specifies that hatta@lookingglass.fict.example is never to be rewritten in
22336 From: headers.
22337
22338 If the replacement string is not a single asterisk, it is expanded, and must
22339 yield a fully qualified address. Within the expansion, the variables
22340 $local_part and $domain refer to the address that is being rewritten. Any
22341 letters they contain retain their original case - they are not lower cased. The
22342 numerical variables are set up according to the type of pattern that matched
22343 the address, as described above. If the expansion is forced to fail by the
22344 presence of "fail" in a conditional or lookup item, rewriting by the current
22345 rule is abandoned, but subsequent rules may take effect. Any other expansion
22346 failure causes the entire rewriting operation to be abandoned, and an entry
22347 written to the panic log.
22348
22349
22350 31.7 Rewriting flags
22351 --------------------
22352
22353 There are three different kinds of flag that may appear on rewriting rules:
22354
22355 * Flags that specify which headers and envelope addresses to rewrite: E, F,
22356 T, b, c, f, h, r, s, t.
22357
22358 * A flag that specifies rewriting at SMTP time: S.
22359
22360 * Flags that control the rewriting process: Q, q, R, w.
22361
22362 For rules that are part of the headers_rewrite generic transport option, E, F,
22363 T, and S are not permitted.
22364
22365
22366 31.8 Flags specifying which headers and envelope addresses to rewrite
22367 ---------------------------------------------------------------------
22368
22369 If none of the following flag letters, nor the "S" flag (see section 31.9) are
22370 present, a main rewriting rule applies to all headers and to both the sender
22371 and recipient fields of the envelope, whereas a transport-time rewriting rule
22372 just applies to all headers. Otherwise, the rewriting rule is skipped unless
22373 the relevant addresses are being processed.
22374
22375 E rewrite all envelope fields
22376 F rewrite the envelope From field
22377 T rewrite the envelope To field
22378 b rewrite the Bcc: header
22379 c rewrite the Cc: header
22380 f rewrite the From: header
22381 h rewrite all headers
22382 r rewrite the Reply-To: header
22383 s rewrite the Sender: header
22384 t rewrite the To: header
22385
22386 "All headers" means all of the headers listed above that can be selected
22387 individually, plus their Resent- versions. It does not include other headers
22388 such as Subject: etc.
22389
22390 You should be particularly careful about rewriting Sender: headers, and
22391 restrict this to special known cases in your own domains.
22392
22393
22394 31.9 The SMTP-time rewriting flag
22395 ---------------------------------
22396
22397 The rewrite flag "S" specifies a rewrite of incoming envelope addresses at SMTP
22398 time, as soon as an address is received in a MAIL or RCPT command, and before
22399 any other processing; even before syntax checking. The pattern is required to
22400 be a regular expression, and it is matched against the whole of the data for
22401 the command, including any surrounding angle brackets.
22402
22403 This form of rewrite rule allows for the handling of addresses that are not
22404 compliant with RFCs 2821 and 2822 (for example, "bang paths" in batched SMTP
22405 input). Because the input is not required to be a syntactically valid address,
22406 the variables $local_part and $domain are not available during the expansion of
22407 the replacement string. The result of rewriting replaces the original address
22408 in the MAIL or RCPT command.
22409
22410
22411 31.10 Flags controlling the rewriting process
22412 ---------------------------------------------
22413
22414 There are four flags which control the way the rewriting process works. These
22415 take effect only when a rule is invoked, that is, when the address is of the
22416 correct type (matches the flags) and matches the pattern:
22417
22418 * If the "Q" flag is set on a rule, the rewritten address is permitted to be
22419 an unqualified local part. It is qualified with qualify_recipient. In the
22420 absence of "Q" the rewritten address must always include a domain.
22421
22422 * If the "q" flag is set on a rule, no further rewriting rules are
22423 considered, even if no rewriting actually takes place because of a "fail"
22424 in the expansion. The "q" flag is not effective if the address is of the
22425 wrong type (does not match the flags) or does not match the pattern.
22426
22427 * The "R" flag causes a successful rewriting rule to be re-applied to the new
22428 address, up to ten times. It can be combined with the "q" flag, to stop
22429 rewriting once it fails to match (after at least one successful rewrite).
22430
22431 * When an address in a header is rewritten, the rewriting normally applies
22432 only to the working part of the address, with any comments and RFC 2822
22433 "phrase" left unchanged. For example, rewriting might change
22434
22435 From: Ford Prefect <fp42@restaurant.hitch.fict.example>
22436
22437 into
22438
22439 From: Ford Prefect <prefectf@hitch.fict.example>
22440
22441 Sometimes there is a need to replace the whole address item, and this can
22442 be done by adding the flag letter "w" to a rule. If this is set on a rule
22443 that causes an address in a header line to be rewritten, the entire address
22444 is replaced, not just the working part. The replacement must be a complete
22445 RFC 2822 address, including the angle brackets if necessary. If text
22446 outside angle brackets contains a character whose value is greater than 126
22447 or less than 32 (except for tab), the text is encoded according to RFC
22448 2047. The character set is taken from headers_charset, which defaults to
22449 ISO-8859-1.
22450
22451 When the "w" flag is set on a rule that causes an envelope address to be
22452 rewritten, all but the working part of the replacement address is
22453 discarded.
22454
22455
22456 31.11 Rewriting examples
22457 ------------------------
22458
22459 Here is an example of the two common rewriting paradigms:
22460
22461 *@*.hitch.fict.example $1@hitch.fict.example
22462 *@hitch.fict.example ${lookup{$1}dbm{/etc/realnames}\
22463 {$value}fail}@hitch.fict.example bctfrF
22464
22465 Note the use of "fail" in the lookup expansion in the second rule, forcing the
22466 string expansion to fail if the lookup does not succeed. In this context it has
22467 the effect of leaving the original address unchanged, but Exim goes on to
22468 consider subsequent rewriting rules, if any, because the "q" flag is not
22469 present in that rule. An alternative to "fail" would be to supply $1
22470 explicitly, which would cause the rewritten address to be the same as before,
22471 at the cost of a small bit of processing. Not supplying either of these is an
22472 error, since the rewritten address would then contain no local part.
22473
22474 The first example above replaces the domain with a superior, more general
22475 domain. This may not be desirable for certain local parts. If the rule
22476
22477 root@*.hitch.fict.example *
22478
22479 were inserted before the first rule, rewriting would be suppressed for the
22480 local part root at any domain ending in hitch.fict.example.
22481
22482 Rewriting can be made conditional on a number of tests, by making use of ${if
22483 in the expansion item. For example, to apply a rewriting rule only to messages
22484 that originate outside the local host:
22485
22486 *@*.hitch.fict.example "${if !eq {$sender_host_address}{}\
22487 {$1@hitch.fict.example}fail}"
22488
22489 The replacement string is quoted in this example because it contains white
22490 space.
22491
22492 Exim does not handle addresses in the form of "bang paths". If it sees such an
22493 address it treats it as an unqualified local part which it qualifies with the
22494 local qualification domain (if the source of the message is local or if the
22495 remote host is permitted to send unqualified addresses). Rewriting can
22496 sometimes be used to handle simple bang paths with a fixed number of
22497 components. For example, the rule
22498
22499 \N^([^!]+)!(.*)@your.domain.example$\N $2@$1
22500
22501 rewrites a two-component bang path host.name!user as the domain address
22502 user@host.name. However, there is a security implication in using this as a
22503 global rewriting rule for envelope addresses. It can provide a backdoor method
22504 for using your system as a relay, because the incoming addresses appear to be
22505 local. If the bang path addresses are received via SMTP, it is safer to use the
22506 "S" flag to rewrite them as they are received, so that relay checking can be
22507 done on the rewritten addresses.
22508
22509
22510
22511 ===============================================================================
22512 32. RETRY CONFIGURATION
22513
22514 The "retry" section of the runtime configuration file contains a list of retry
22515 rules that control how often Exim tries to deliver messages that cannot be
22516 delivered at the first attempt. If there are no retry rules (the section is
22517 empty or not present), there are no retries. In this situation, temporary
22518 errors are treated as permanent. The default configuration contains a single,
22519 general-purpose retry rule (see section 7.5). The -brt command line option can
22520 be used to test which retry rule will be used for a given address, domain and
22521 error.
22522
22523 The most common cause of retries is temporary failure to deliver to a remote
22524 host because the host is down, or inaccessible because of a network problem.
22525 Exim's retry processing in this case is applied on a per-host (strictly, per IP
22526 address) basis, not on a per-message basis. Thus, if one message has recently
22527 been delayed, delivery of a new message to the same host is not immediately
22528 tried, but waits for the host's retry time to arrive. If the retry_defer log
22529 selector is set, the message "retry time not reached" is written to the main
22530 log whenever a delivery is skipped for this reason. Section 47.2 contains more
22531 details of the handling of errors during remote deliveries.
22532
22533 Retry processing applies to routing as well as to delivering, except as covered
22534 in the next paragraph. The retry rules do not distinguish between these
22535 actions. It is not possible, for example, to specify different behaviour for
22536 failures to route the domain snark.fict.example and failures to deliver to the
22537 host snark.fict.example. I didn't think anyone would ever need this added
22538 complication, so did not implement it. However, although they share the same
22539 retry rule, the actual retry times for routing and transporting a given domain
22540 are maintained independently.
22541
22542 When a delivery is not part of a queue run (typically an immediate delivery on
22543 receipt of a message), the routers are always run, and local deliveries are
22544 always attempted, even if retry times are set for them. This makes for better
22545 behaviour if one particular message is causing problems (for example, causing
22546 quota overflow, or provoking an error in a filter file). If such a delivery
22547 suffers a temporary failure, the retry data is updated as normal, and
22548 subsequent delivery attempts from queue runs occur only when the retry time for
22549 the local address is reached.
22550
22551
22552 32.1 Changing retry rules
22553 -------------------------
22554
22555 If you change the retry rules in your configuration, you should consider
22556 whether or not to delete the retry data that is stored in Exim's spool area in
22557 files with names like db/retry. Deleting any of Exim's hints files is always
22558 safe; that is why they are called "hints".
22559
22560 The hints retry data contains suggested retry times based on the previous
22561 rules. In the case of a long-running problem with a remote host, it might
22562 record the fact that the host has timed out. If your new rules increase the
22563 timeout time for such a host, you should definitely remove the old retry data
22564 and let Exim recreate it, based on the new rules. Otherwise Exim might bounce
22565 messages that it should now be retaining.
22566
22567
22568 32.2 Format of retry rules
22569 --------------------------
22570
22571 Each retry rule occupies one line and consists of three or four parts,
22572 separated by white space: a pattern, an error name, an optional list of sender
22573 addresses, and a list of retry parameters. The pattern and sender lists must be
22574 enclosed in double quotes if they contain white space. The rules are searched
22575 in order until one is found where the pattern, error name, and sender list (if
22576 present) match the failing host or address, the error that occurred, and the
22577 message's sender, respectively.
22578
22579 The pattern is any single item that may appear in an address list (see section
22580 10.19). It is in fact processed as a one-item address list, which means that it
22581 is expanded before being tested against the address that has been delayed. A
22582 negated address list item is permitted. Address list processing treats a plain
22583 domain name as if it were preceded by "*@", which makes it possible for many
22584 retry rules to start with just a domain. For example,
22585
22586 lookingglass.fict.example * F,24h,30m;
22587
22588 provides a rule for any address in the lookingglass.fict.example domain,
22589 whereas
22590
22591 alice@lookingglass.fict.example * F,24h,30m;
22592
22593 applies only to temporary failures involving the local part alice. In practice,
22594 almost all rules start with a domain name pattern without a local part.
22595
22596 Warning: If you use a regular expression in a retry rule pattern, it must match
22597 a complete address, not just a domain, because that is how regular expressions
22598 work in address lists.
22599
22600 ^\Nxyz\d+\.abc\.example$\N * G,1h,10m,2 Wrong
22601 ^\N[^@]+@xyz\d+\.abc\.example$\N * G,1h,10m,2 Right
22602
22603
22604 32.3 Choosing which retry rule to use for address errors
22605 --------------------------------------------------------
22606
22607 When Exim is looking for a retry rule after a routing attempt has failed (for
22608 example, after a DNS timeout), each line in the retry configuration is tested
22609 against the complete address only if retry_use_local_part is set for the
22610 router. Otherwise, only the domain is used, except when matching against a
22611 regular expression, when the local part of the address is replaced with "*". A
22612 domain on its own can match a domain pattern, or a pattern that starts with
22613 "*@". By default, retry_use_local_part is true for routers where
22614 check_local_user is true, and false for other routers.
22615
22616 Similarly, when Exim is looking for a retry rule after a local delivery has
22617 failed (for example, after a mailbox full error), each line in the retry
22618 configuration is tested against the complete address only if
22619 retry_use_local_part is set for the transport (it defaults true for all local
22620 transports).
22621
22622 However, when Exim is looking for a retry rule after a remote delivery attempt
22623 suffers an address error (a 4xx SMTP response for a recipient address), the
22624 whole address is always used as the key when searching the retry rules. The
22625 rule that is found is used to create a retry time for the combination of the
22626 failing address and the message's sender. It is the combination of sender and
22627 recipient that is delayed in subsequent queue runs until its retry time is
22628 reached. You can delay the recipient without regard to the sender by setting
22629 address_retry_include_sender false in the smtp transport but this can lead to
22630 problems with servers that regularly issue 4xx responses to RCPT commands.
22631
22632
22633 32.4 Choosing which retry rule to use for host and message errors
22634 -----------------------------------------------------------------
22635
22636 For a temporary error that is not related to an individual address (for
22637 example, a connection timeout), each line in the retry configuration is checked
22638 twice. First, the name of the remote host is used as a domain name (preceded by
22639 "*@" when matching a regular expression). If this does not match the line, the
22640 domain from the email address is tried in a similar fashion. For example,
22641 suppose the MX records for a.b.c.example are
22642
22643 a.b.c.example MX 5 x.y.z.example
22644 MX 6 p.q.r.example
22645 MX 7 m.n.o.example
22646
22647 and the retry rules are
22648
22649 p.q.r.example * F,24h,30m;
22650 a.b.c.example * F,4d,45m;
22651
22652 and a delivery to the host x.y.z.example suffers a connection failure. The
22653 first rule matches neither the host nor the domain, so Exim looks at the second
22654 rule. This does not match the host, but it does match the domain, so it is used
22655 to calculate the retry time for the host x.y.z.example. Meanwhile, Exim tries
22656 to deliver to p.q.r.example. If this also suffers a host error, the first retry
22657 rule is used, because it matches the host.
22658
22659 In other words, temporary failures to deliver to host p.q.r.example use the
22660 first rule to determine retry times, but for all the other hosts for the domain
22661 a.b.c.example, the second rule is used. The second rule is also used if routing
22662 to a.b.c.example suffers a temporary failure.
22663
22664 Note: The host name is used when matching the patterns, not its IP address.
22665 However, if a message is routed directly to an IP address without the use of a
22666 host name, for example, if a manualroute router contains a setting such as:
22667
22668 route_list = *.a.example 192.168.34.23
22669
22670 then the "host name" that is used when searching for a retry rule is the
22671 textual form of the IP address.
22672
22673
22674 32.5 Retry rules for specific errors
22675 ------------------------------------
22676
22677 The second field in a retry rule is the name of a particular error, or an
22678 asterisk, which matches any error. The errors that can be tested for are:
22679
22680 auth_failed
22681
22682 Authentication failed when trying to send to a host in the
22683 hosts_require_auth list in an smtp transport.
22684
22685 data_4xx
22686
22687 A 4xx error was received for an outgoing DATA command, either immediately
22688 after the command, or after sending the message's data.
22689
22690 mail_4xx
22691
22692 A 4xx error was received for an outgoing MAIL command.
22693
22694 rcpt_4xx
22695
22696 A 4xx error was received for an outgoing RCPT command.
22697
22698 For the three 4xx errors, either the first or both of the x's can be given as
22699 specific digits, for example: "mail_45x" or "rcpt_436". For example, to
22700 recognize 452 errors given to RCPT commands for addresses in a certain domain,
22701 and have retries every ten minutes with a one-hour timeout, you could set up a
22702 retry rule of this form:
22703
22704 the.domain.name rcpt_452 F,1h,10m
22705
22706 These errors apply to both outgoing SMTP (the smtp transport) and outgoing LMTP
22707 (either the lmtp transport, or the smtp transport in LMTP mode).
22708
22709 lost_connection
22710
22711 A server unexpectedly closed the SMTP connection. There may, of course,
22712 legitimate reasons for this (host died, network died), but if it repeats a
22713 lot for the same host, it indicates something odd.
22714
22715 refused_MX
22716
22717 A connection to a host obtained from an MX record was refused.
22718
22719 refused_A
22720
22721 A connection to a host not obtained from an MX record was refused.
22722
22723 refused
22724
22725 A connection was refused.
22726
22727 timeout_connect_MX
22728
22729 A connection attempt to a host obtained from an MX record timed out.
22730
22731 timeout_connect_A
22732
22733 A connection attempt to a host not obtained from an MX record timed out.
22734
22735 timeout_connect
22736
22737 A connection attempt timed out.
22738
22739 timeout_MX
22740
22741 There was a timeout while connecting or during an SMTP session with a host
22742 obtained from an MX record.
22743
22744 timeout_A
22745
22746 There was a timeout while connecting or during an SMTP session with a host
22747 not obtained from an MX record.
22748
22749 timeout
22750
22751 There was a timeout while connecting or during an SMTP session.
22752
22753 tls_required
22754
22755 The server was required to use TLS (it matched hosts_require_tls in the
22756 smtp transport), but either did not offer TLS, or it responded with 4xx to
22757 STARTTLS, or there was a problem setting up the TLS connection.
22758
22759 quota
22760
22761 A mailbox quota was exceeded in a local delivery by the appendfile
22762 transport.
22763
22764 quota_<time>
22765
22766 A mailbox quota was exceeded in a local delivery by the appendfile
22767 transport, and the mailbox has not been accessed for <time>. For example,
22768 quota_4d applies to a quota error when the mailbox has not been accessed
22769 for four days.
22770
22771 The idea of quota_<time> is to make it possible to have shorter timeouts when
22772 the mailbox is full and is not being read by its owner. Ideally, it should be
22773 based on the last time that the user accessed the mailbox. However, it is not
22774 always possible to determine this. Exim uses the following heuristic rules:
22775
22776 * If the mailbox is a single file, the time of last access (the "atime") is
22777 used. As no new messages are being delivered (because the mailbox is over
22778 quota), Exim does not access the file, so this is the time of last user
22779 access.
22780
22781 * For a maildir delivery, the time of last modification of the new
22782 subdirectory is used. As the mailbox is over quota, no new files are
22783 created in the new subdirectory, because no new messages are being
22784 delivered. Any change to the new subdirectory is therefore assumed to be
22785 the result of an MUA moving a new message to the cur directory when it is
22786 first read. The time that is used is therefore the last time that the user
22787 read a new message.
22788
22789 * For other kinds of multi-file mailbox, the time of last access cannot be
22790 obtained, so a retry rule that uses this type of error field is never
22791 matched.
22792
22793 The quota errors apply both to system-enforced quotas and to Exim's own quota
22794 mechanism in the appendfile transport. The quota error also applies when a
22795 local delivery is deferred because a partition is full (the ENOSPC error).
22796
22797
22798 32.6 Retry rules for specified senders
22799 --------------------------------------
22800
22801 You can specify retry rules that apply only when the failing message has a
22802 specific sender. In particular, this can be used to define retry rules that
22803 apply only to bounce messages. The third item in a retry rule can be of this
22804 form:
22805
22806 senders=<address list>
22807
22808 The retry timings themselves are then the fourth item. For example:
22809
22810 * rcpt_4xx senders=: F,1h,30m
22811
22812 matches recipient 4xx errors for bounce messages sent to any address at any
22813 host. If the address list contains white space, it must be enclosed in quotes.
22814 For example:
22815
22816 a.domain rcpt_452 senders="xb.dom : yc.dom" G,8h,10m,1.5
22817
22818 Warning: This facility can be unhelpful if it is used for host errors (which do
22819 not depend on the recipient). The reason is that the sender is used only to
22820 match the retry rule. Once the rule has been found for a host error, its
22821 contents are used to set a retry time for the host, and this will apply to all
22822 messages, not just those with specific senders.
22823
22824 When testing retry rules using -brt, you can supply a sender using the -f
22825 command line option, like this:
22826
22827 exim -f "" -brt user@dom.ain
22828
22829 If you do not set -f with -brt, a retry rule that contains a senders list is
22830 never matched.
22831
22832
22833 32.7 Retry parameters
22834 ---------------------
22835
22836 The third (or fourth, if a senders list is present) field in a retry rule is a
22837 sequence of retry parameter sets, separated by semicolons. Each set consists of
22838
22839 <letter>,<cutoff time>,<arguments>
22840
22841 The letter identifies the algorithm for computing a new retry time; the cutoff
22842 time is the time beyond which this algorithm no longer applies, and the
22843 arguments vary the algorithm's action. The cutoff time is measured from the
22844 time that the first failure for the domain (combined with the local part if
22845 relevant) was detected, not from the time the message was received.
22846
22847 The available algorithms are:
22848
22849 * F: retry at fixed intervals. There is a single time parameter specifying
22850 the interval.
22851
22852 * G: retry at geometrically increasing intervals. The first argument
22853 specifies a starting value for the interval, and the second a multiplier,
22854 which is used to increase the size of the interval at each retry.
22855
22856 * H: retry at randomized intervals. The arguments are as for G. For each
22857 retry, the previous interval is multiplied by the factor in order to get a
22858 maximum for the next interval. The minimum interval is the first argument
22859 of the parameter, and an actual interval is chosen randomly between them.
22860 Such a rule has been found to be helpful in cluster configurations when all
22861 the members of the cluster restart at once, and may therefore synchronize
22862 their queue processing times.
22863
22864 When computing the next retry time, the algorithm definitions are scanned in
22865 order until one whose cutoff time has not yet passed is reached. This is then
22866 used to compute a new retry time that is later than the current time. In the
22867 case of fixed interval retries, this simply means adding the interval to the
22868 current time. For geometrically increasing intervals, retry intervals are
22869 computed from the rule's parameters until one that is greater than the previous
22870 interval is found. The main configuration variable retry_interval_max limits
22871 the maximum interval between retries. It cannot be set greater than "24h",
22872 which is its default value.
22873
22874 A single remote domain may have a number of hosts associated with it, and each
22875 host may have more than one IP address. Retry algorithms are selected on the
22876 basis of the domain name, but are applied to each IP address independently. If,
22877 for example, a host has two IP addresses and one is unusable, Exim will
22878 generate retry times for it and will not try to use it until its next retry
22879 time comes. Thus the good IP address is likely to be tried first most of the
22880 time.
22881
22882 Retry times are hints rather than promises. Exim does not make any attempt to
22883 run deliveries exactly at the computed times. Instead, a queue runner process
22884 starts delivery processes for delayed messages periodically, and these attempt
22885 new deliveries only for those addresses that have passed their next retry time.
22886 If a new message arrives for a deferred address, an immediate delivery attempt
22887 occurs only if the address has passed its retry time. In the absence of new
22888 messages, the minimum time between retries is the interval between queue runner
22889 processes. There is not much point in setting retry times of five minutes if
22890 your queue runners happen only once an hour, unless there are a significant
22891 number of incoming messages (which might be the case on a system that is
22892 sending everything to a smart host, for example).
22893
22894 The data in the retry hints database can be inspected by using the exim_dumpdb
22895 or exim_fixdb utility programs (see chapter 52). The latter utility can also be
22896 used to change the data. The exinext utility script can be used to find out
22897 what the next retry times are for the hosts associated with a particular mail
22898 domain, and also for local deliveries that have been deferred.
22899
22900
22901 32.8 Retry rule examples
22902 ------------------------
22903
22904 Here are some example retry rules:
22905
22906 alice@wonderland.fict.example quota_5d F,7d,3h
22907 wonderland.fict.example quota_5d
22908 wonderland.fict.example * F,1h,15m; G,2d,1h,2;
22909 lookingglass.fict.example * F,24h,30m;
22910 * refused_A F,2h,20m;
22911 * * F,2h,15m; G,16h,1h,1.5; F,5d,8h
22912
22913 The first rule sets up special handling for mail to
22914 alice@wonderland.fict.example when there is an over-quota error and the mailbox
22915 has not been read for at least 5 days. Retries continue every three hours for 7
22916 days. The second rule handles over-quota errors for all other local parts at
22917 wonderland.fict.example; the absence of a local part has the same effect as
22918 supplying "*@". As no retry algorithms are supplied, messages that fail are
22919 bounced immediately if the mailbox has not been read for at least 5 days.
22920
22921 The third rule handles all other errors at wonderland.fict.example; retries
22922 happen every 15 minutes for an hour, then with geometrically increasing
22923 intervals until two days have passed since a delivery first failed. After the
22924 first hour there is a delay of one hour, then two hours, then four hours, and
22925 so on (this is a rather extreme example).
22926
22927 The fourth rule controls retries for the domain lookingglass.fict.example. They
22928 happen every 30 minutes for 24 hours only. The remaining two rules handle all
22929 other domains, with special action for connection refusal from hosts that were
22930 not obtained from an MX record.
22931
22932 The final rule in a retry configuration should always have asterisks in the
22933 first two fields so as to provide a general catch-all for any addresses that do
22934 not have their own special handling. This example tries every 15 minutes for 2
22935 hours, then with intervals starting at one hour and increasing by a factor of
22936 1.5 up to 16 hours, then every 8 hours up to 5 days.
22937
22938
22939 32.9 Timeout of retry data
22940 --------------------------
22941
22942 Exim timestamps the data that it writes to its retry hints database. When it
22943 consults the data during a delivery it ignores any that is older than the value
22944 set in retry_data_expire (default 7 days). If, for example, a host hasn't been
22945 tried for 7 days, Exim will try to deliver to it immediately a message arrives,
22946 and if that fails, it will calculate a retry time as if it were failing for the
22947 first time.
22948
22949 This improves the behaviour for messages routed to rarely-used hosts such as MX
22950 backups. If such a host was down at one time, and happens to be down again when
22951 Exim tries a month later, using the old retry data would imply that it had been
22952 down all the time, which is not a justified assumption.
22953
22954 If a host really is permanently dead, this behaviour causes a burst of retries
22955 every now and again, but only if messages routed to it are rare. If there is a
22956 message at least once every 7 days the retry data never expires.
22957
22958
22959 32.10 Long-term failures
22960 ------------------------
22961
22962 Special processing happens when an email address has been failing for so long
22963 that the cutoff time for the last algorithm is reached. For example, using the
22964 default retry rule:
22965
22966 * * F,2h,15m; G,16h,1h,1.5; F,4d,6h
22967
22968 the cutoff time is four days. Reaching the retry cutoff is independent of how
22969 long any specific message has been failing; it is the length of continuous
22970 failure for the recipient address that counts.
22971
22972 When the cutoff time is reached for a local delivery, or for all the IP
22973 addresses associated with a remote delivery, a subsequent delivery failure
22974 causes Exim to give up on the address, and a bounce message is generated. In
22975 order to cater for new messages that use the failing address, a next retry time
22976 is still computed from the final algorithm, and is used as follows:
22977
22978 For local deliveries, one delivery attempt is always made for any subsequent
22979 messages. If this delivery fails, the address fails immediately. The
22980 post-cutoff retry time is not used.
22981
22982 If the delivery is remote, there are two possibilities, controlled by the
22983 delay_after_cutoff option of the smtp transport. The option is true by default.
22984 Until the post-cutoff retry time for one of the IP addresses is reached, the
22985 failing email address is bounced immediately, without a delivery attempt taking
22986 place. After that time, one new delivery attempt is made to those IP addresses
22987 that are past their retry times, and if that still fails, the address is
22988 bounced and new retry times are computed.
22989
22990 In other words, when all the hosts for a given email address have been failing
22991 for a long time, Exim bounces rather then defers until one of the hosts' retry
22992 times is reached. Then it tries once, and bounces if that attempt fails. This
22993 behaviour ensures that few resources are wasted in repeatedly trying to deliver
22994 to a broken destination, but if the host does recover, Exim will eventually
22995 notice.
22996
22997 If delay_after_cutoff is set false, Exim behaves differently. If all IP
22998 addresses are past their final cutoff time, Exim tries to deliver to those IP
22999 addresses that have not been tried since the message arrived. If there are no
23000 suitable IP addresses, or if they all fail, the address is bounced. In other
23001 words, it does not delay when a new message arrives, but tries the expired
23002 addresses immediately, unless they have been tried since the message arrived.
23003 If there is a continuous stream of messages for the failing domains, setting
23004 delay_after_cutoff false means that there will be many more attempts to deliver
23005 to permanently failing IP addresses than when delay_after_cutoff is true.
23006
23007
23008 32.11 Deliveries that work intermittently
23009 -----------------------------------------
23010
23011 Some additional logic is needed to cope with cases where a host is
23012 intermittently available, or when a message has some attribute that prevents
23013 its delivery when others to the same address get through. In this situation,
23014 because some messages are successfully delivered, the "retry clock" for the
23015 host or address keeps getting reset by the successful deliveries, and so
23016 failing messages remain on the queue for ever because the cutoff time is never
23017 reached.
23018
23019 Two exceptional actions are applied to prevent this happening. The first
23020 applies to errors that are related to a message rather than a remote host.
23021 Section 47.2 has a discussion of the different kinds of error; examples of
23022 message-related errors are 4xx responses to MAIL or DATA commands, and quota
23023 failures. For this type of error, if a message's arrival time is earlier than
23024 the "first failed" time for the error, the earlier time is used when scanning
23025 the retry rules to decide when to try next and when to time out the address.
23026
23027 The exceptional second action applies in all cases. If a message has been on
23028 the queue for longer than the cutoff time of any applicable retry rule for a
23029 given address, a delivery is attempted for that address, even if it is not yet
23030 time, and if this delivery fails, the address is timed out. A new retry time is
23031 not computed in this case, so that other messages for the same address are
23032 considered immediately.
23033
23034
23035
23036 ===============================================================================
23037 33. SMTP AUTHENTICATION
23038
23039 The "authenticators" section of Exim's run time configuration is concerned with
23040 SMTP authentication. This facility is an extension to the SMTP protocol,
23041 described in RFC 2554, which allows a client SMTP host to authenticate itself
23042 to a server. This is a common way for a server to recognize clients that are
23043 permitted to use it as a relay. SMTP authentication is not of relevance to the
23044 transfer of mail between servers that have no managerial connection with each
23045 other.
23046
23047 Very briefly, the way SMTP authentication works is as follows:
23048
23049 * The server advertises a number of authentication mechanisms in response to
23050 the client's EHLO command.
23051
23052 * The client issues an AUTH command, naming a specific mechanism. The command
23053 may, optionally, contain some authentication data.
23054
23055 * The server may issue one or more challenges, to which the client must send
23056 appropriate responses. In simple authentication mechanisms, the challenges
23057 are just prompts for user names and passwords. The server does not have to
23058 issue any challenges - in some mechanisms the relevant data may all be
23059 transmitted with the AUTH command.
23060
23061 * The server either accepts or denies authentication.
23062
23063 * If authentication succeeds, the client may optionally make use of the AUTH
23064 option on the MAIL command to pass an authenticated sender in subsequent
23065 mail transactions. Authentication lasts for the remainder of the SMTP
23066 connection.
23067
23068 * If authentication fails, the client may give up, or it may try a different
23069 authentication mechanism, or it may try transferring mail over the
23070 unauthenticated connection.
23071
23072 If you are setting up a client, and want to know which authentication
23073 mechanisms the server supports, you can use Telnet to connect to port 25 (the
23074 SMTP port) on the server, and issue an EHLO command. The response to this
23075 includes the list of supported mechanisms. For example:
23076
23077 $ telnet server.example 25
23078 Trying 192.168.34.25...
23079 Connected to server.example.
23080 Escape character is '^]'.
23081 220 server.example ESMTP Exim 4.20 ...
23082 ehlo client.example
23083 250-server.example Hello client.example [10.8.4.5]
23084 250-SIZE 52428800
23085 250-PIPELINING
23086 250-AUTH PLAIN
23087 250 HELP
23088
23089 The second-last line of this example output shows that the server supports
23090 authentication using the PLAIN mechanism. In Exim, the different authentication
23091 mechanisms are configured by specifying authenticator drivers. Like the routers
23092 and transports, which authenticators are included in the binary is controlled
23093 by build-time definitions. The following are currently available, included by
23094 setting
23095
23096 AUTH_CRAM_MD5=yes
23097 AUTH_CYRUS_SASL=yes
23098 AUTH_DOVECOT=yes
23099 AUTH_GSASL=yes
23100 AUTH_HEIMDAL_GSSAPI=yes
23101 AUTH_PLAINTEXT=yes
23102 AUTH_SPA=yes
23103
23104 in Local/Makefile, respectively. The first of these supports the CRAM-MD5
23105 authentication mechanism (RFC 2195), and the second provides an interface to
23106 the Cyrus SASL authentication library. The third is an interface to Dovecot's
23107 authentication system, delegating the work via a socket interface. The fourth
23108 provides an interface to the GNU SASL authentication library, which provides
23109 mechanisms but typically not data sources. The fifth provides direct access to
23110 Heimdal GSSAPI, geared for Kerberos, but supporting setting a server keytab.
23111 The sixth can be configured to support the PLAIN authentication mechanism (RFC
23112 2595) or the LOGIN mechanism, which is not formally documented, but used by
23113 several MUAs. The seventh authenticator supports Microsoft's Secure Password
23114 Authentication mechanism.
23115
23116 The authenticators are configured using the same syntax as other drivers (see
23117 section 6.22). If no authenticators are required, no authentication section
23118 need be present in the configuration file. Each authenticator can in principle
23119 have both server and client functions. When Exim is receiving SMTP mail, it is
23120 acting as a server; when it is sending out messages over SMTP, it is acting as
23121 a client. Authenticator configuration options are provided for use in both
23122 these circumstances.
23123
23124 To make it clear which options apply to which situation, the prefixes server_
23125 and client_ are used on option names that are specific to either the server or
23126 the client function, respectively. Server and client functions are disabled if
23127 none of their options are set. If an authenticator is to be used for both
23128 server and client functions, a single definition, using both sets of options,
23129 is required. For example:
23130
23131 cram:
23132 driver = cram_md5
23133 public_name = CRAM-MD5
23134 server_secret = ${if eq{$auth1}{ph10}{secret1}fail}
23135 client_name = ph10
23136 client_secret = secret2
23137
23138 The server_ option is used when Exim is acting as a server, and the client_
23139 options when it is acting as a client.
23140
23141 Descriptions of the individual authenticators are given in subsequent chapters.
23142 The remainder of this chapter covers the generic options for the
23143 authenticators, followed by general discussion of the way authentication works
23144 in Exim.
23145
23146 Beware: the meaning of $auth1, $auth2, ... varies on a per-driver and
23147 per-mechanism basis. Please read carefully to determine which variables hold
23148 account labels such as usercodes and which hold passwords or other
23149 authenticating data.
23150
23151 Note that some mechanisms support two different identifiers for accounts: the
23152 authentication id and the authorization id. The contractions authn and authz
23153 are commonly encountered. The American spelling is standard here. Conceptually,
23154 authentication data such as passwords are tied to the identifier used to
23155 authenticate; servers may have rules to permit one user to act as a second
23156 user, so that after login the session is treated as though that second user had
23157 logged in. That second user is the authorization id. A robust configuration
23158 might confirm that the authz field is empty or matches the authn field. Often
23159 this is just ignored. The authn can be considered as verified data, the authz
23160 as an unverified request which the server might choose to honour.
23161
23162 A realm is a text string, typically a domain name, presented by a server to a
23163 client to help it select an account and credentials to use. In some mechanisms,
23164 the client and server provably agree on the realm, but clients typically can
23165 not treat the realm as secure data to be blindly trusted.
23166
23167
23168 33.1 Generic options for authenticators
23169 ---------------------------------------
23170
23171 +----------------+-------------------+-------------+--------------+
23172 |client_condition|Use: authenticators|Type: string*|Default: unset|
23173 +----------------+-------------------+-------------+--------------+
23174
23175 When Exim is authenticating as a client, it skips any authenticator whose
23176 client_condition expansion yields "0", "no", or "false". This can be used, for
23177 example, to skip plain text authenticators when the connection is not encrypted
23178 by a setting such as:
23179
23180 client_condition = ${if !eq{$tls_out_cipher}{}}
23181
23182 +-------------+-------------------+-------------+--------------+
23183 |client_set_id|Use: authenticators|Type: string*|Default: unset|
23184 +-------------+-------------------+-------------+--------------+
23185
23186 When client authentication succeeds, this condition is expanded; the result is
23187 used in the log lines for outbound messasges. Typically it will be the user
23188 name used for authentication.
23189
23190 +------+-------------------+------------+--------------+
23191 |driver|Use: authenticators|Type: string|Default: unset|
23192 +------+-------------------+------------+--------------+
23193
23194 This option must always be set. It specifies which of the available
23195 authenticators is to be used.
23196
23197 +-----------+-------------------+------------+--------------+
23198 |public_name|Use: authenticators|Type: string|Default: unset|
23199 +-----------+-------------------+------------+--------------+
23200
23201 This option specifies the name of the authentication mechanism that the driver
23202 implements, and by which it is known to the outside world. These names should
23203 contain only upper case letters, digits, underscores, and hyphens (RFC 2222),
23204 but Exim in fact matches them caselessly. If public_name is not set, it
23205 defaults to the driver's instance name.
23206
23207 +--------------------------+-------------------+-------------+--------------+
23208 |server_advertise_condition|Use: authenticators|Type: string*|Default: unset|
23209 +--------------------------+-------------------+-------------+--------------+
23210
23211 When a server is about to advertise an authentication mechanism, the condition
23212 is expanded. If it yields the empty string, "0", "no", or "false", the
23213 mechanism is not advertised. If the expansion fails, the mechanism is not
23214 advertised. If the failure was not forced, and was not caused by a lookup
23215 defer, the incident is logged. See section 33.3 below for further discussion.
23216
23217 +----------------+-------------------+-------------+--------------+
23218 |server_condition|Use: authenticators|Type: string*|Default: unset|
23219 +----------------+-------------------+-------------+--------------+
23220
23221 This option must be set for a plaintext server authenticator, where it is used
23222 directly to control authentication. See section 34.2 for details.
23223
23224 For the gsasl authenticator, this option is required for various mechanisms;
23225 see chapter 38 for details.
23226
23227 For the other authenticators, server_condition can be used as an additional
23228 authentication or authorization mechanism that is applied after the other
23229 authenticator conditions succeed. If it is set, it is expanded when the
23230 authenticator would otherwise return a success code. If the expansion is forced
23231 to fail, authentication fails. Any other expansion failure causes a temporary
23232 error code to be returned. If the result of a successful expansion is an empty
23233 string, "0", "no", or "false", authentication fails. If the result of the
23234 expansion is "1", "yes", or "true", authentication succeeds. For any other
23235 result, a temporary error code is returned, with the expanded string as the
23236 error text.
23237
23238 +------------------+-------------------+-------------+--------------+
23239 |server_debug_print|Use: authenticators|Type: string*|Default: unset|
23240 +------------------+-------------------+-------------+--------------+
23241
23242 If this option is set and authentication debugging is enabled (see the -d
23243 command line option), the string is expanded and included in the debugging
23244 output when the authenticator is run as a server. This can help with checking
23245 out the values of variables. If expansion of the string fails, the error
23246 message is written to the debugging output, and Exim carries on processing.
23247
23248 +-------------+-------------------+-------------+--------------+
23249 |server_set_id|Use: authenticators|Type: string*|Default: unset|
23250 +-------------+-------------------+-------------+--------------+
23251
23252 When an Exim server successfully authenticates a client, this string is
23253 expanded using data from the authentication, and preserved for any incoming
23254 messages in the variable $authenticated_id. It is also included in the log
23255 lines for incoming messages. For example, a user/password authenticator
23256 configuration might preserve the user name that was used to authenticate, and
23257 refer to it subsequently during delivery of the message. If expansion fails,
23258 the option is ignored.
23259
23260 +--------------------------+-------------------+-------------+--------------+
23261 |server_mail_auth_condition|Use: authenticators|Type: string*|Default: unset|
23262 +--------------------------+-------------------+-------------+--------------+
23263
23264 This option allows a server to discard authenticated sender addresses supplied
23265 as part of MAIL commands in SMTP connections that are authenticated by the
23266 driver on which server_mail_auth_condition is set. The option is not used as
23267 part of the authentication process; instead its (unexpanded) value is
23268 remembered for later use. How it is used is described in the following section.
23269
23270
23271 33.2 The AUTH parameter on MAIL commands
23272 ----------------------------------------
23273
23274 When a client supplied an AUTH= item on a MAIL command, Exim applies the
23275 following checks before accepting it as the authenticated sender of the
23276 message:
23277
23278 * If the connection is not using extended SMTP (that is, HELO was used rather
23279 than EHLO), the use of AUTH= is a syntax error.
23280
23281 * If the value of the AUTH= parameter is "<>", it is ignored.
23282
23283 * If acl_smtp_mailauth is defined, the ACL it specifies is run. While it is
23284 running, the value of $authenticated_sender is set to the value obtained
23285 from the AUTH= parameter. If the ACL does not yield "accept", the value of
23286 $authenticated_sender is deleted. The acl_smtp_mailauth ACL may not return
23287 "drop" or "discard". If it defers, a temporary error code (451) is given
23288 for the MAIL command.
23289
23290 * If acl_smtp_mailauth is not defined, the value of the AUTH= parameter is
23291 accepted and placed in $authenticated_sender only if the client has
23292 authenticated.
23293
23294 * If the AUTH= value was accepted by either of the two previous rules, and
23295 the client has authenticated, and the authenticator has a setting for the
23296 server_mail_auth_condition, the condition is checked at this point. The
23297 valued that was saved from the authenticator is expanded. If the expansion
23298 fails, or yields an empty string, "0", "no", or "false", the value of
23299 $authenticated_sender is deleted. If the expansion yields any other value,
23300 the value of $authenticated_sender is retained and passed on with the
23301 message.
23302
23303 When $authenticated_sender is set for a message, it is passed on to other hosts
23304 to which Exim authenticates as a client. Do not confuse this value with
23305 $authenticated_id, which is a string obtained from the authentication process,
23306 and which is not usually a complete email address.
23307
23308 Whenever an AUTH= value is ignored, the incident is logged. The ACL for MAIL,
23309 if defined, is run after AUTH= is accepted or ignored. It can therefore make
23310 use of $authenticated_sender. The converse is not true: the value of
23311 $sender_address is not yet set up when the acl_smtp_mailauth ACL is run.
23312
23313
23314 33.3 Authentication on an Exim server
23315 -------------------------------------
23316
23317 When Exim receives an EHLO command, it advertises the public names of those
23318 authenticators that are configured as servers, subject to the following
23319 conditions:
23320
23321 * The client host must match auth_advertise_hosts (default *).
23322
23323 * It the server_advertise_condition option is set, its expansion must not
23324 yield the empty string, "0", "no", or "false".
23325
23326 The order in which the authenticators are defined controls the order in which
23327 the mechanisms are advertised.
23328
23329 Some mail clients (for example, some versions of Netscape) require the user to
23330 provide a name and password for authentication whenever AUTH is advertised,
23331 even though authentication may not in fact be needed (for example, Exim may be
23332 set up to allow unconditional relaying from the client by an IP address check).
23333 You can make such clients more friendly by not advertising AUTH to them. For
23334 example, if clients on the 10.9.8.0/24 network are permitted (by the ACL that
23335 runs for RCPT) to relay without authentication, you should set
23336
23337 auth_advertise_hosts = ! 10.9.8.0/24
23338
23339 so that no authentication mechanisms are advertised to them.
23340
23341 The server_advertise_condition controls the advertisement of individual
23342 authentication mechanisms. For example, it can be used to restrict the
23343 advertisement of a particular mechanism to encrypted connections, by a setting
23344 such as:
23345
23346 server_advertise_condition = ${if eq{$tls_in_cipher}{}{no}{yes}}
23347
23348 If the session is encrypted, $tls_in_cipher is not empty, and so the expansion
23349 yields "yes", which allows the advertisement to happen.
23350
23351 When an Exim server receives an AUTH command from a client, it rejects it
23352 immediately if AUTH was not advertised in response to an earlier EHLO command.
23353 This is the case if
23354
23355 * The client host does not match auth_advertise_hosts; or
23356
23357 * No authenticators are configured with server options; or
23358
23359 * Expansion of server_advertise_condition blocked the advertising of all the
23360 server authenticators.
23361
23362 Otherwise, Exim runs the ACL specified by acl_smtp_auth in order to decide
23363 whether to accept the command. If acl_smtp_auth is not set, AUTH is accepted
23364 from any client host.
23365
23366 If AUTH is not rejected by the ACL, Exim searches its configuration for a
23367 server authentication mechanism that was advertised in response to EHLO and
23368 that matches the one named in the AUTH command. If it finds one, it runs the
23369 appropriate authentication protocol, and authentication either succeeds or
23370 fails. If there is no matching advertised mechanism, the AUTH command is
23371 rejected with a 504 error.
23372
23373 When a message is received from an authenticated host, the value of
23374 $received_protocol is set to "esmtpa" or "esmtpsa" instead of "esmtp" or
23375 "esmtps", and $sender_host_authenticated contains the name (not the public
23376 name) of the authenticator driver that successfully authenticated the client
23377 from which the message was received. This variable is empty if there was no
23378 successful authentication.
23379
23380
23381 33.4 Testing server authentication
23382 ----------------------------------
23383
23384 Exim's -bh option can be useful for testing server authentication
23385 configurations. The data for the AUTH command has to be sent using base64
23386 encoding. A quick way to produce such data for testing is the following Perl
23387 script:
23388
23389 use MIME::Base64;
23390 printf ("%s", encode_base64(eval "\"$ARGV[0]\""));
23391
23392 This interprets its argument as a Perl string, and then encodes it. The
23393 interpretation as a Perl string allows binary zeros, which are required for
23394 some kinds of authentication, to be included in the data. For example, a
23395 command line to run this script on such data might be
23396
23397 encode '\0user\0password'
23398
23399 Note the use of single quotes to prevent the shell interpreting the
23400 backslashes, so that they can be interpreted by Perl to specify characters
23401 whose code value is zero.
23402
23403 Warning 1: If either of the user or password strings starts with an octal
23404 digit, you must use three zeros instead of one after the leading backslash. If
23405 you do not, the octal digit that starts your string will be incorrectly
23406 interpreted as part of the code for the first character.
23407
23408 Warning 2: If there are characters in the strings that Perl interprets
23409 specially, you must use a Perl escape to prevent them being misinterpreted. For
23410 example, a command such as
23411
23412 encode '\0user@domain.com\0pas$$word'
23413
23414 gives an incorrect answer because of the unescaped "@" and "$" characters.
23415
23416 If you have the mimencode command installed, another way to do produce
23417 base64-encoded strings is to run the command
23418
23419 echo -e -n `\0user\0password' | mimencode
23420
23421 The -e option of echo enables the interpretation of backslash escapes in the
23422 argument, and the -n option specifies no newline at the end of its output.
23423 However, not all versions of echo recognize these options, so you should check
23424 your version before relying on this suggestion.
23425
23426
23427 33.5 Authentication by an Exim client
23428 -------------------------------------
23429
23430 The smtp transport has two options called hosts_require_auth and hosts_try_auth
23431 . When the smtp transport connects to a server that announces support for
23432 authentication, and the host matches an entry in either of these options, Exim
23433 (as a client) tries to authenticate as follows:
23434
23435 * For each authenticator that is configured as a client, in the order in
23436 which they are defined in the configuration, it searches the authentication
23437 mechanisms announced by the server for one whose name matches the public
23438 name of the authenticator.
23439
23440 * When it finds one that matches, it runs the authenticator's client code.
23441 The variables $host and $host_address are available for any string
23442 expansions that the client might do. They are set to the server's name and
23443 IP address. If any expansion is forced to fail, the authentication attempt
23444 is abandoned, and Exim moves on to the next authenticator. Otherwise an
23445 expansion failure causes delivery to be deferred.
23446
23447 * If the result of the authentication attempt is a temporary error or a
23448 timeout, Exim abandons trying to send the message to the host for the
23449 moment. It will try again later. If there are any backup hosts available,
23450 they are tried in the usual way.
23451
23452 * If the response to authentication is a permanent error (5xx code), Exim
23453 carries on searching the list of authenticators and tries another one if
23454 possible. If all authentication attempts give permanent errors, or if there
23455 are no attempts because no mechanisms match (or option expansions force
23456 failure), what happens depends on whether the host matches
23457 hosts_require_auth or hosts_try_auth. In the first case, a temporary error
23458 is generated, and delivery is deferred. The error can be detected in the
23459 retry rules, and thereby turned into a permanent error if you wish. In the
23460 second case, Exim tries to deliver the message unauthenticated.
23461
23462 When Exim has authenticated itself to a remote server, it adds the AUTH
23463 parameter to the MAIL commands it sends, if it has an authenticated sender for
23464 the message. If the message came from a remote host, the authenticated sender
23465 is the one that was receiving on an incoming MAIL command, provided that the
23466 incoming connection was authenticated and the server_mail_auth condition
23467 allowed the authenticated sender to be retained. If a local process calls Exim
23468 to send a message, the sender address that is built from the login name and
23469 qualify_domain is treated as authenticated. However, if the
23470 authenticated_sender option is set on the smtp transport, it overrides the
23471 authenticated sender that was received with the message.
23472
23473
23474
23475 ===============================================================================
23476 34. THE PLAINTEXT AUTHENTICATOR
23477
23478 The plaintext authenticator can be configured to support the PLAIN and LOGIN
23479 authentication mechanisms, both of which transfer authentication data as plain
23480 (unencrypted) text (though base64 encoded). The use of plain text is a security
23481 risk; you are strongly advised to insist on the use of SMTP encryption (see
23482 chapter 41) if you use the PLAIN or LOGIN mechanisms. If you do use unencrypted
23483 plain text, you should not use the same passwords for SMTP connections as you
23484 do for login accounts.
23485
23486
23487 34.1 Plaintext options
23488 ----------------------
23489
23490 When configured as a server, plaintext uses the following options:
23491
23492 +----------------+-------------------+-------------+--------------+
23493 |server_condition|Use: authenticators|Type: string*|Default: unset|
23494 +----------------+-------------------+-------------+--------------+
23495
23496 This is actually a global authentication option, but it must be set in order to
23497 configure the plaintext driver as a server. Its use is described below.
23498
23499 +--------------+--------------+-------------+--------------+
23500 |server_prompts|Use: plaintext|Type: string*|Default: unset|
23501 +--------------+--------------+-------------+--------------+
23502
23503 The contents of this option, after expansion, must be a colon-separated list of
23504 prompt strings. If expansion fails, a temporary authentication rejection is
23505 given.
23506
23507
23508 34.2 Using plaintext in a server
23509 --------------------------------
23510
23511 When running as a server, plaintext performs the authentication test by
23512 expanding a string. The data sent by the client with the AUTH command, or in
23513 response to subsequent prompts, is base64 encoded, and so may contain any byte
23514 values when decoded. If any data is supplied with the command, it is treated as
23515 a list of strings, separated by NULs (binary zeros), the first three of which
23516 are placed in the expansion variables $auth1, $auth2, and $auth3 (neither LOGIN
23517 nor PLAIN uses more than three strings).
23518
23519 For compatibility with previous releases of Exim, the values are also placed in
23520 the expansion variables $1, $2, and $3. However, the use of these variables for
23521 this purpose is now deprecated, as it can lead to confusion in string
23522 expansions that also use them for other things.
23523
23524 If there are more strings in server_prompts than the number of strings supplied
23525 with the AUTH command, the remaining prompts are used to obtain more data. Each
23526 response from the client may be a list of NUL-separated strings.
23527
23528 Once a sufficient number of data strings have been received, server_condition
23529 is expanded. If the expansion is forced to fail, authentication fails. Any
23530 other expansion failure causes a temporary error code to be returned. If the
23531 result of a successful expansion is an empty string, "0", "no", or "false",
23532 authentication fails. If the result of the expansion is "1", "yes", or "true",
23533 authentication succeeds and the generic server_set_id option is expanded and
23534 saved in $authenticated_id. For any other result, a temporary error code is
23535 returned, with the expanded string as the error text
23536
23537 Warning: If you use a lookup in the expansion to find the user's password, be
23538 sure to make the authentication fail if the user is unknown. There are good and
23539 bad examples at the end of the next section.
23540
23541
23542 34.3 The PLAIN authentication mechanism
23543 ---------------------------------------
23544
23545 The PLAIN authentication mechanism (RFC 2595) specifies that three strings be
23546 sent as one item of data (that is, one combined string containing two NUL
23547 separators). The data is sent either as part of the AUTH command, or
23548 subsequently in response to an empty prompt from the server.
23549
23550 The second and third strings are a user name and a corresponding password.
23551 Using a single fixed user name and password as an example, this could be
23552 configured as follows:
23553
23554 fixed_plain:
23555 driver = plaintext
23556 public_name = PLAIN
23557 server_prompts = :
23558 server_condition = \
23559 ${if and {{eq{$auth2}{username}}{eq{$auth3}{mysecret}}}}
23560 server_set_id = $auth2
23561
23562 Note that the default result strings from if ("true" or an empty string) are
23563 exactly what we want here, so they need not be specified. Obviously, if the
23564 password contains expansion-significant characters such as dollar, backslash,
23565 or closing brace, they have to be escaped.
23566
23567 The server_prompts setting specifies a single, empty prompt (empty items at the
23568 end of a string list are ignored). If all the data comes as part of the AUTH
23569 command, as is commonly the case, the prompt is not used. This authenticator is
23570 advertised in the response to EHLO as
23571
23572 250-AUTH PLAIN
23573
23574 and a client host can authenticate itself by sending the command
23575
23576 AUTH PLAIN AHVzZXJuYW1lAG15c2VjcmV0
23577
23578 As this contains three strings (more than the number of prompts), no further
23579 data is required from the client. Alternatively, the client may just send
23580
23581 AUTH PLAIN
23582
23583 to initiate authentication, in which case the server replies with an empty
23584 prompt. The client must respond with the combined data string.
23585
23586 The data string is base64 encoded, as required by the RFC. This example, when
23587 decoded, is <NUL>"username"<NUL>"mysecret", where <NUL> represents a zero byte.
23588 This is split up into three strings, the first of which is empty. The
23589 server_condition option in the authenticator checks that the second two are
23590 "username" and "mysecret" respectively.
23591
23592 Having just one fixed user name and password, as in this example, is not very
23593 realistic, though for a small organization with only a handful of
23594 authenticating clients it could make sense.
23595
23596 A more sophisticated instance of this authenticator could use the user name in
23597 $auth2 to look up a password in a file or database, and maybe do an encrypted
23598 comparison (see crypteq in chapter 11). Here is a example of this approach,
23599 where the passwords are looked up in a DBM file. Warning: This is an incorrect
23600 example:
23601
23602 server_condition = \
23603 ${if eq{$auth3}{${lookup{$auth2}dbm{/etc/authpwd}}}}
23604
23605 The expansion uses the user name ($auth2) as the key to look up a password,
23606 which it then compares to the supplied password ($auth3). Why is this example
23607 incorrect? It works fine for existing users, but consider what happens if a
23608 non-existent user name is given. The lookup fails, but as no success/failure
23609 strings are given for the lookup, it yields an empty string. Thus, to defeat
23610 the authentication, all a client has to do is to supply a non-existent user
23611 name and an empty password. The correct way of writing this test is:
23612
23613 server_condition = ${lookup{$auth2}dbm{/etc/authpwd}\
23614 {${if eq{$value}{$auth3}}} {false}}
23615
23616 In this case, if the lookup succeeds, the result is checked; if the lookup
23617 fails, "false" is returned and authentication fails. If crypteq is being used
23618 instead of eq, the first example is in fact safe, because crypteq always fails
23619 if its second argument is empty. However, the second way of writing the test
23620 makes the logic clearer.
23621
23622
23623 34.4 The LOGIN authentication mechanism
23624 ---------------------------------------
23625
23626 The LOGIN authentication mechanism is not documented in any RFC, but is in use
23627 in a number of programs. No data is sent with the AUTH command. Instead, a user
23628 name and password are supplied separately, in response to prompts. The
23629 plaintext authenticator can be configured to support this as in this example:
23630
23631 fixed_login:
23632 driver = plaintext
23633 public_name = LOGIN
23634 server_prompts = User Name : Password
23635 server_condition = \
23636 ${if and {{eq{$auth1}{username}}{eq{$auth2}{mysecret}}}}
23637 server_set_id = $auth1
23638
23639 Because of the way plaintext operates, this authenticator accepts data supplied
23640 with the AUTH command (in contravention of the specification of LOGIN), but if
23641 the client does not supply it (as is the case for LOGIN clients), the prompt
23642 strings are used to obtain two data items.
23643
23644 Some clients are very particular about the precise text of the prompts. For
23645 example, Outlook Express is reported to recognize only "Username:" and
23646 "Password:". Here is an example of a LOGIN authenticator that uses those
23647 strings. It uses the ldapauth expansion condition to check the user name and
23648 password by binding to an LDAP server:
23649
23650 login:
23651 driver = plaintext
23652 public_name = LOGIN
23653 server_prompts = Username:: : Password::
23654 server_condition = ${if and{{ \
23655 !eq{}{$auth1} }{ \
23656 ldapauth{\
23657 user="uid=${quote_ldap_dn:$auth1},ou=people,o=example.org" \
23658 pass=${quote:$auth2} \
23659 ldap://ldap.example.org/} }} }
23660 server_set_id = uid=$auth1,ou=people,o=example.org
23661
23662 We have to check that the username is not empty before using it, because LDAP
23663 does not permit empty DN components. We must also use the quote_ldap_dn
23664 operator to correctly quote the DN for authentication. However, the basic quote
23665 operator, rather than any of the LDAP quoting operators, is the correct one to
23666 use for the password, because quoting is needed only to make the password
23667 conform to the Exim syntax. At the LDAP level, the password is an uninterpreted
23668 string.
23669
23670
23671 34.5 Support for different kinds of authentication
23672 --------------------------------------------------
23673
23674 A number of string expansion features are provided for the purpose of
23675 interfacing to different ways of user authentication. These include checking
23676 traditionally encrypted passwords from /etc/passwd (or equivalent), PAM,
23677 Radius, ldapauth, pwcheck, and saslauthd. For details see section 11.7.
23678
23679
23680 34.6 Using plaintext in a client
23681 --------------------------------
23682
23683 The plaintext authenticator has two client options:
23684
23685 +----------------------------+--------------+-------------+--------------+
23686 |client_ignore_invalid_base64|Use: plaintext|Type: boolean|Default: false|
23687 +----------------------------+--------------+-------------+--------------+
23688
23689 If the client receives a server prompt that is not a valid base64 string,
23690 authentication is abandoned by default. However, if this option is set true,
23691 the error in the challenge is ignored and the client sends the response as
23692 usual.
23693
23694 +-----------+--------------+-------------+--------------+
23695 |client_send|Use: plaintext|Type: string*|Default: unset|
23696 +-----------+--------------+-------------+--------------+
23697
23698 The string is a colon-separated list of authentication data strings. Each
23699 string is independently expanded before being sent to the server. The first
23700 string is sent with the AUTH command; any more strings are sent in response to
23701 prompts from the server. Before each string is expanded, the value of the most
23702 recent prompt is placed in the next $auth<n> variable, starting with $auth1 for
23703 the first prompt. Up to three prompts are stored in this way. Thus, the prompt
23704 that is received in response to sending the first string (with the AUTH
23705 command) can be used in the expansion of the second string, and so on. If an
23706 invalid base64 string is received when client_ignore_invalid_base64 is set, an
23707 empty string is put in the $auth<n> variable.
23708
23709 Note: You cannot use expansion to create multiple strings, because splitting
23710 takes priority and happens first.
23711
23712 Because the PLAIN authentication mechanism requires NUL (binary zero) bytes in
23713 the data, further processing is applied to each string before it is sent. If
23714 there are any single circumflex characters in the string, they are converted to
23715 NULs. Should an actual circumflex be required as data, it must be doubled in
23716 the string.
23717
23718 This is an example of a client configuration that implements the PLAIN
23719 authentication mechanism with a fixed user name and password:
23720
23721 fixed_plain:
23722 driver = plaintext
23723 public_name = PLAIN
23724 client_send = ^username^mysecret
23725
23726 The lack of colons means that the entire text is sent with the AUTH command,
23727 with the circumflex characters converted to NULs. A similar example that uses
23728 the LOGIN mechanism is:
23729
23730 fixed_login:
23731 driver = plaintext
23732 public_name = LOGIN
23733 client_send = : username : mysecret
23734
23735 The initial colon means that the first string is empty, so no data is sent with
23736 the AUTH command itself. The remaining strings are sent in response to prompts.
23737
23738
23739
23740 ===============================================================================
23741 35. THE CRAM_MD5 AUTHENTICATOR
23742
23743 The CRAM-MD5 authentication mechanism is described in RFC 2195. The server
23744 sends a challenge string to the client, and the response consists of a user
23745 name and the CRAM-MD5 digest of the challenge string combined with a secret
23746 string (password) which is known to both server and client. Thus, the secret is
23747 not sent over the network as plain text, which makes this authenticator more
23748 secure than plaintext. However, the downside is that the secret has to be
23749 available in plain text at either end.
23750
23751
23752 35.1 Using cram_md5 as a server
23753 -------------------------------
23754
23755 This authenticator has one server option, which must be set to configure the
23756 authenticator as a server:
23757
23758 +-------------+-------------+-------------+--------------+
23759 |server_secret|Use: cram_md5|Type: string*|Default: unset|
23760 +-------------+-------------+-------------+--------------+
23761
23762 When the server receives the client's response, the user name is placed in the
23763 expansion variable $auth1, and server_secret is expanded to obtain the password
23764 for that user. The server then computes the CRAM-MD5 digest that the client
23765 should have sent, and checks that it received the correct string. If the
23766 expansion of server_secret is forced to fail, authentication fails. If the
23767 expansion fails for some other reason, a temporary error code is returned to
23768 the client.
23769
23770 For compatibility with previous releases of Exim, the user name is also placed
23771 in $1. However, the use of this variables for this purpose is now deprecated,
23772 as it can lead to confusion in string expansions that also use numeric
23773 variables for other things.
23774
23775 For example, the following authenticator checks that the user name given by the
23776 client is "ph10", and if so, uses "secret" as the password. For any other user
23777 name, authentication fails.
23778
23779 fixed_cram:
23780 driver = cram_md5
23781 public_name = CRAM-MD5
23782 server_secret = ${if eq{$auth1}{ph10}{secret}fail}
23783 server_set_id = $auth1
23784
23785 If authentication succeeds, the setting of server_set_id preserves the user
23786 name in $authenticated_id. A more typical configuration might look up the
23787 secret string in a file, using the user name as the key. For example:
23788
23789 lookup_cram:
23790 driver = cram_md5
23791 public_name = CRAM-MD5
23792 server_secret = ${lookup{$auth1}lsearch{/etc/authpwd}\
23793 {$value}fail}
23794 server_set_id = $auth1
23795
23796 Note that this expansion explicitly forces failure if the lookup fails because
23797 $auth1 contains an unknown user name.
23798
23799 As another example, if you wish to re-use a Cyrus SASL sasldb2 file without
23800 using the relevant libraries, you need to know the realm to specify in the
23801 lookup and then ask for the "userPassword" attribute for that user in that
23802 realm, with:
23803
23804 cyrusless_crammd5:
23805 driver = cram_md5
23806 public_name = CRAM-MD5
23807 server_secret = ${lookup{$auth1:mail.example.org:userPassword}\
23808 dbmjz{/etc/sasldb2}}
23809 server_set_id = $auth1
23810
23811
23812 35.2 Using cram_md5 as a client
23813 -------------------------------
23814
23815 When used as a client, the cram_md5 authenticator has two options:
23816
23817 +-----------+-------------+-------------+------------------------------+
23818 |client_name|Use: cram_md5|Type: string*|Default: the primary host name|
23819 +-----------+-------------+-------------+------------------------------+
23820
23821 This string is expanded, and the result used as the user name data when
23822 computing the response to the server's challenge.
23823
23824 +-------------+-------------+-------------+--------------+
23825 |client_secret|Use: cram_md5|Type: string*|Default: unset|
23826 +-------------+-------------+-------------+--------------+
23827
23828 This option must be set for the authenticator to work as a client. Its value is
23829 expanded and the result used as the secret string when computing the response.
23830
23831 Different user names and secrets can be used for different servers by referring
23832 to $host or $host_address in the options. Forced failure of either expansion
23833 string is treated as an indication that this authenticator is not prepared to
23834 handle this case. Exim moves on to the next configured client authenticator.
23835 Any other expansion failure causes Exim to give up trying to send the message
23836 to the current server.
23837
23838 A simple example configuration of a cram_md5 authenticator, using fixed
23839 strings, is:
23840
23841 fixed_cram:
23842 driver = cram_md5
23843 public_name = CRAM-MD5
23844 client_name = ph10
23845 client_secret = secret
23846
23847
23848
23849 ===============================================================================
23850 36. THE CYRUS_SASL AUTHENTICATOR
23851
23852 The code for this authenticator was provided by Matthew Byng-Maddick of A L
23853 Digital Ltd (http://www.aldigital.co.uk).
23854
23855 The cyrus_sasl authenticator provides server support for the Cyrus SASL library
23856 implementation of the RFC 2222 ("Simple Authentication and Security Layer").
23857 This library supports a number of authentication mechanisms, including PLAIN
23858 and LOGIN, but also several others that Exim does not support directly. In
23859 particular, there is support for Kerberos authentication.
23860
23861 The cyrus_sasl authenticator provides a gatewaying mechanism directly to the
23862 Cyrus interface, so if your Cyrus library can do, for example, CRAM-MD5, then
23863 so can the cyrus_sasl authenticator. By default it uses the public name of the
23864 driver to determine which mechanism to support.
23865
23866 Where access to some kind of secret file is required, for example in GSSAPI or
23867 CRAM-MD5, it is worth noting that the authenticator runs as the Exim user, and
23868 that the Cyrus SASL library has no way of escalating privileges by default. You
23869 may also find you need to set environment variables, depending on the driver
23870 you are using.
23871
23872 The application name provided by Exim is "exim", so various SASL options may be
23873 set in exim.conf in your SASL directory. If you are using GSSAPI for Kerberos,
23874 note that because of limitations in the GSSAPI interface, changing the server
23875 keytab might need to be communicated down to the Kerberos layer independently.
23876 The mechanism for doing so is dependent upon the Kerberos implementation.
23877
23878 For example, for older releases of Heimdal, the environment variable
23879 KRB5_KTNAME may be set to point to an alternative keytab file. Exim will pass
23880 this variable through from its own inherited environment when started as root
23881 or the Exim user. The keytab file needs to be readable by the Exim user. With
23882 newer releases of Heimdal, a setuid Exim may cause Heimdal to discard the
23883 environment variable. In practice, for those releases, the Cyrus authenticator
23884 is not a suitable interface for GSSAPI (Kerberos) support. Instead, consider
23885 the heimdal_gssapi authenticator, described in chapter 39
23886
23887
23888 36.1 Using cyrus_sasl as a server
23889 ---------------------------------
23890
23891 The cyrus_sasl authenticator has four private options. It puts the username (on
23892 a successful authentication) into $auth1. For compatibility with previous
23893 releases of Exim, the username is also placed in $1. However, the use of this
23894 variable for this purpose is now deprecated, as it can lead to confusion in
23895 string expansions that also use numeric variables for other things.
23896
23897 +---------------+---------------+-------------+------------------+
23898 |server_hostname|Use: cyrus_sasl|Type: string*|Default: see below|
23899 +---------------+---------------+-------------+------------------+
23900
23901 This option selects the hostname that is used when communicating with the
23902 library. The default value is "$primary_hostname". It is up to the underlying
23903 SASL plug-in what it does with this data.
23904
23905 +-----------+---------------+------------+------------------+
23906 |server_mech|Use: cyrus_sasl|Type: string|Default: see below|
23907 +-----------+---------------+------------+------------------+
23908
23909 This option selects the authentication mechanism this driver should use. The
23910 default is the value of the generic public_name option. This option allows you
23911 to use a different underlying mechanism from the advertised name. For example:
23912
23913 sasl:
23914 driver = cyrus_sasl
23915 public_name = X-ANYTHING
23916 server_mech = CRAM-MD5
23917 server_set_id = $auth1
23918
23919 +------------+---------------+-------------+--------------+
23920 |server_realm|Use: cyrus_sasl|Type: string*|Default: unset|
23921 +------------+---------------+-------------+--------------+
23922
23923 This specifies the SASL realm that the server claims to be in.
23924
23925 +--------------+---------------+------------+---------------+
23926 |server_service|Use: cyrus_sasl|Type: string|Default: "smtp"|
23927 +--------------+---------------+------------+---------------+
23928
23929 This is the SASL service that the server claims to implement.
23930
23931 For straightforward cases, you do not need to set any of the authenticator's
23932 private options. All you need to do is to specify an appropriate mechanism as
23933 the public name. Thus, if you have a SASL library that supports CRAM-MD5 and
23934 PLAIN, you could have two authenticators as follows:
23935
23936 sasl_cram_md5:
23937 driver = cyrus_sasl
23938 public_name = CRAM-MD5
23939 server_set_id = $auth1
23940
23941 sasl_plain:
23942 driver = cyrus_sasl
23943 public_name = PLAIN
23944 server_set_id = $auth2
23945
23946 Cyrus SASL does implement the LOGIN authentication method, even though it is
23947 not a standard method. It is disabled by default in the source distribution,
23948 but it is present in many binary distributions.
23949
23950
23951
23952 ===============================================================================
23953 37. THE DOVECOT AUTHENTICATOR
23954
23955 This authenticator is an interface to the authentication facility of the
23956 Dovecot POP/IMAP server, which can support a number of authentication methods.
23957
23958 Note that Dovecot must be configured to use auth-client not auth-userdb.
23959
23960 If you are using Dovecot to authenticate POP/IMAP clients, it might be helpful
23961 to use the same mechanisms for SMTP authentication. This is a server
23962 authenticator only. There is only one option:
23963
23964 +-------------+------------+------------+--------------+
23965 |server_socket|Use: dovecot|Type: string|Default: unset|
23966 +-------------+------------+------------+--------------+
23967
23968 This option must specify the socket that is the interface to Dovecot
23969 authentication. The public_name option must specify an authentication mechanism
23970 that Dovecot is configured to support. You can have several authenticators for
23971 different mechanisms. For example:
23972
23973 dovecot_plain:
23974 driver = dovecot
23975 public_name = PLAIN
23976 server_socket = /var/run/dovecot/auth-client
23977 server_set_id = $auth1
23978
23979 dovecot_ntlm:
23980 driver = dovecot
23981 public_name = NTLM
23982 server_socket = /var/run/dovecot/auth-client
23983 server_set_id = $auth1
23984
23985 If the SMTP connection is encrypted, or if $sender_host_address is equal to
23986 $received_ip_address (that is, the connection is local), the "secured" option
23987 is passed in the Dovecot authentication command. If, for a TLS connection, a
23988 client certificate has been verified, the "valid-client-cert" option is passed.
23989 When authentication succeeds, the identity of the user who authenticated is
23990 placed in $auth1.
23991
23992
23993
23994 ===============================================================================
23995 38. THE GSASL AUTHENTICATOR
23996
23997 The gsasl authenticator provides server integration for the GNU SASL library
23998 and the mechanisms it provides. This is new as of the 4.80 release and there
23999 are a few areas where the library does not let Exim smoothly scale to handle
24000 future authentication mechanisms, so no guarantee can be made that any
24001 particular new authentication mechanism will be supported without code changes
24002 in Exim.
24003
24004 +---------------------+----------+-------------+--------------+
24005 |server_channelbinding|Use: gsasl|Type: boolean|Default: false|
24006 +---------------------+----------+-------------+--------------+
24007
24008 Some authentication mechanisms are able to use external context at both ends of
24009 the session to bind the authentication to that context, and fail the
24010 authentication process if that context differs. Specifically, some TLS
24011 ciphersuites can provide identifying information about the cryptographic
24012 context.
24013
24014 This means that certificate identity and verification becomes a non-issue, as a
24015 man-in-the-middle attack will cause the correct client and server to see
24016 different identifiers and authentication will fail.
24017
24018 This is currently only supported when using the GnuTLS library. This is only
24019 usable by mechanisms which support "channel binding"; at time of writing,
24020 that's the SCRAM family.
24021
24022 This defaults off to ensure smooth upgrade across Exim releases, in case this
24023 option causes some clients to start failing. Some future release of Exim may
24024 switch the default to be true.
24025
24026 +---------------+----------+-------------+------------------+
24027 |server_hostname|Use: gsasl|Type: string*|Default: see below|
24028 +---------------+----------+-------------+------------------+
24029
24030 This option selects the hostname that is used when communicating with the
24031 library. The default value is "$primary_hostname". Some mechanisms will use
24032 this data.
24033
24034 +-----------+----------+------------+------------------+
24035 |server_mech|Use: gsasl|Type: string|Default: see below|
24036 +-----------+----------+------------+------------------+
24037
24038 This option selects the authentication mechanism this driver should use. The
24039 default is the value of the generic public_name option. This option allows you
24040 to use a different underlying mechanism from the advertised name. For example:
24041
24042 sasl:
24043 driver = gsasl
24044 public_name = X-ANYTHING
24045 server_mech = CRAM-MD5
24046 server_set_id = $auth1
24047
24048 +---------------+----------+-------------+--------------+
24049 |server_password|Use: gsasl|Type: string*|Default: unset|
24050 +---------------+----------+-------------+--------------+
24051
24052 Various mechanisms need access to the cleartext password on the server, so that
24053 proof-of-possession can be demonstrated on the wire, without sending the
24054 password itself.
24055
24056 The data available for lookup varies per mechanism. In all cases, $auth1 is set
24057 to the authentication id. The $auth2 variable will always be the authorization
24058 id (authz) if available, else the empty string. The $auth3 variable will always
24059 be the realm if available, else the empty string.
24060
24061 A forced failure will cause authentication to defer.
24062
24063 If using this option, it may make sense to set the server_condition option to
24064 be simply "true".
24065
24066 +------------+----------+-------------+--------------+
24067 |server_realm|Use: gsasl|Type: string*|Default: unset|
24068 +------------+----------+-------------+--------------+
24069
24070 This specifies the SASL realm that the server claims to be in. Some mechanisms
24071 will use this data.
24072
24073 +-----------------+----------+-------------+--------------+
24074 |server_scram_iter|Use: gsasl|Type: string*|Default: unset|
24075 +-----------------+----------+-------------+--------------+
24076
24077 This option provides data for the SCRAM family of mechanisms. $auth1 is not
24078 available at evaluation time. (This may change, as we receive feedback on use)
24079
24080 +-----------------+----------+-------------+--------------+
24081 |server_scram_salt|Use: gsasl|Type: string*|Default: unset|
24082 +-----------------+----------+-------------+--------------+
24083
24084 This option provides data for the SCRAM family of mechanisms. $auth1 is not
24085 available at evaluation time. (This may change, as we receive feedback on use)
24086
24087 +--------------+----------+------------+---------------+
24088 |server_service|Use: gsasl|Type: string|Default: "smtp"|
24089 +--------------+----------+------------+---------------+
24090
24091 This is the SASL service that the server claims to implement. Some mechanisms
24092 will use this data.
24093
24094
24095 38.1 gsasl auth variables
24096 -------------------------
24097
24098 These may be set when evaluating specific options, as detailed above. They will
24099 also be set when evaluating server_condition.
24100
24101 Unless otherwise stated below, the gsasl integration will use the following
24102 meanings for these variables:
24103
24104 * $auth1: the authentication id
24105
24106 * $auth2: the authorization id
24107
24108 * $auth3: the realm
24109
24110 On a per-mechanism basis:
24111
24112 * EXTERNAL: only $auth1 is set, to the possibly empty authorization id; the
24113 server_condition option must be present.
24114
24115 * ANONYMOUS: only $auth1 is set, to the possibly empty anonymous token; the
24116 server_condition option must be present.
24117
24118 * GSSAPI: $auth1 will be set to the GSSAPI Display Name; $auth2 will be set
24119 to the authorization id, the server_condition option must be present.
24120
24121 An anonymous token is something passed along as an unauthenticated identifier;
24122 this is analogous to FTP anonymous authentication passing an email address, or
24123 software-identifier@, as the "password".
24124
24125 An example showing the password having the realm specified in the callback and
24126 demonstrating a Cyrus SASL to GSASL migration approach is:
24127
24128 gsasl_cyrusless_crammd5:
24129 driver = gsasl
24130 public_name = CRAM-MD5
24131 server_realm = imap.example.org
24132 server_password = ${lookup{$auth1:$auth3:userPassword}\
24133 dbmjz{/etc/sasldb2}{$value}fail}
24134 server_set_id = ${quote:$auth1}
24135 server_condition = yes
24136
24137
24138
24139 ===============================================================================
24140 39. THE HEIMDAL_GSSAPI AUTHENTICATOR
24141
24142 The heimdal_gssapi authenticator provides server integration for the Heimdal
24143 GSSAPI/Kerberos library, permitting Exim to set a keytab pathname reliably.
24144
24145 +---------------+-------------------+-------------+------------------+
24146 |server_hostname|Use: heimdal_gssapi|Type: string*|Default: see below|
24147 +---------------+-------------------+-------------+------------------+
24148
24149 This option selects the hostname that is used, with server_service, for
24150 constructing the GSS server name, as a GSS_C_NT_HOSTBASED_SERVICE identifier.
24151 The default value is "$primary_hostname".
24152
24153 +-------------+-------------------+-------------+--------------+
24154 |server_keytab|Use: heimdal_gssapi|Type: string*|Default: unset|
24155 +-------------+-------------------+-------------+--------------+
24156
24157 If set, then Heimdal will not use the system default keytab (typically /etc/
24158 krb5.keytab) but instead the pathname given in this option. The value should be
24159 a pathname, with no "file:" prefix.
24160
24161 +--------------+-------------------+-------------+-------------+
24162 |server_service|Use: heimdal_gssapi|Type: string*|Default: smtp|
24163 +--------------+-------------------+-------------+-------------+
24164
24165 This option specifies the service identifier used, in conjunction with
24166 server_hostname, for building the identifer for finding credentials from the
24167 keytab.
24168
24169
24170 39.1 heimdal_gssapi auth variables
24171 ----------------------------------
24172
24173 Beware that these variables will typically include a realm, thus will appear to
24174 be roughly like an email address already. The authzid in $auth2 is not
24175 verified, so a malicious client can set it to anything.
24176
24177 The $auth1 field should be safely trustable as a value from the Key
24178 Distribution Center. Note that these are not quite email addresses. Each
24179 identifier is for a role, and so the left-hand-side may include a role suffix.
24180 For instance, "joe/admin@EXAMPLE.ORG".
24181
24182 * $auth1: the authentication id, set to the GSS Display Name.
24183
24184 * $auth2: the authorization id, sent within SASL encapsulation after
24185 authentication. If that was empty, this will also be set to the GSS Display
24186 Name.
24187
24188
24189
24190 ===============================================================================
24191 40. THE SPA AUTHENTICATOR
24192
24193 The spa authenticator provides client support for Microsoft's Secure Password
24194 Authentication mechanism, which is also sometimes known as NTLM (NT LanMan).
24195 The code for client side of this authenticator was contributed by Marc
24196 Prud'hommeaux, and much of it is taken from the Samba project (http://
24197 www.samba.org). The code for the server side was subsequently contributed by
24198 Tom Kistner. The mechanism works as follows:
24199
24200 * After the AUTH command has been accepted, the client sends an SPA
24201 authentication request based on the user name and optional domain.
24202
24203 * The server sends back a challenge.
24204
24205 * The client builds a challenge response which makes use of the user's
24206 password and sends it to the server, which then accepts or rejects it.
24207
24208 Encryption is used to protect the password in transit.
24209
24210
24211 40.1 Using spa as a server
24212 --------------------------
24213
24214 The spa authenticator has just one server option:
24215
24216 +---------------+--------+-------------+--------------+
24217 |server_password|Use: spa|Type: string*|Default: unset|
24218 +---------------+--------+-------------+--------------+
24219
24220 This option is expanded, and the result must be the cleartext password for the
24221 authenticating user, whose name is at this point in $auth1. For compatibility
24222 with previous releases of Exim, the user name is also placed in $1. However,
24223 the use of this variable for this purpose is now deprecated, as it can lead to
24224 confusion in string expansions that also use numeric variables for other
24225 things. For example:
24226
24227 spa:
24228 driver = spa
24229 public_name = NTLM
24230 server_password = \
24231 ${lookup{$auth1}lsearch{/etc/exim/spa_clearpass}{$value}fail}
24232
24233 If the expansion is forced to fail, authentication fails. Any other expansion
24234 failure causes a temporary error code to be returned.
24235
24236
24237 40.2 Using spa as a client
24238 --------------------------
24239
24240 The spa authenticator has the following client options:
24241
24242 +-------------+--------+-------------+--------------+
24243 |client_domain|Use: spa|Type: string*|Default: unset|
24244 +-------------+--------+-------------+--------------+
24245
24246 This option specifies an optional domain for the authentication.
24247
24248 +---------------+--------+-------------+--------------+
24249 |client_password|Use: spa|Type: string*|Default: unset|
24250 +---------------+--------+-------------+--------------+
24251
24252 This option specifies the user's password, and must be set.
24253
24254 +---------------+--------+-------------+--------------+
24255 |client_username|Use: spa|Type: string*|Default: unset|
24256 +---------------+--------+-------------+--------------+
24257
24258 This option specifies the user name, and must be set. Here is an example of a
24259 configuration of this authenticator for use with the mail servers at msn.com:
24260
24261 msn:
24262 driver = spa
24263 public_name = MSN
24264 client_username = msn/msn_username
24265 client_password = msn_plaintext_password
24266 client_domain = DOMAIN_OR_UNSET
24267
24268
24269
24270 ===============================================================================
24271 41. ENCRYPTED SMTP CONNECTIONS USING TLS/SSL
24272
24273 Support for TLS (Transport Layer Security), formerly known as SSL (Secure
24274 Sockets Layer), is implemented by making use of the OpenSSL library or the
24275 GnuTLS library (Exim requires GnuTLS release 1.0 or later). There is no
24276 cryptographic code in the Exim distribution itself for implementing TLS. In
24277 order to use this feature you must install OpenSSL or GnuTLS, and then build a
24278 version of Exim that includes TLS support (see section 4.7). You also need to
24279 understand the basic concepts of encryption at a managerial level, and in
24280 particular, the way that public keys, private keys, and certificates are used.
24281
24282 RFC 3207 defines how SMTP connections can make use of encryption. Once a
24283 connection is established, the client issues a STARTTLS command. If the server
24284 accepts this, the client and the server negotiate an encryption mechanism. If
24285 the negotiation succeeds, the data that subsequently passes between them is
24286 encrypted.
24287
24288 Exim's ACLs can detect whether the current SMTP session is encrypted or not,
24289 and if so, what cipher suite is in use, whether the client supplied a
24290 certificate, and whether or not that certificate was verified. This makes it
24291 possible for an Exim server to deny or accept certain commands based on the
24292 encryption state.
24293
24294 Warning: Certain types of firewall and certain anti-virus products can disrupt
24295 TLS connections. You need to turn off SMTP scanning for these products in order
24296 to get TLS to work.
24297
24298
24299 41.1 Support for the legacy "ssmtp" (aka "smtps") protocol
24300 ----------------------------------------------------------
24301
24302 Early implementations of encrypted SMTP used a different TCP port from normal
24303 SMTP, and expected an encryption negotiation to start immediately, instead of
24304 waiting for a STARTTLS command from the client using the standard SMTP port.
24305 The protocol was called "ssmtp" or "smtps", and port 465 was allocated for this
24306 purpose.
24307
24308 This approach was abandoned when encrypted SMTP was standardized, but there are
24309 still some legacy clients that use it. Exim supports these clients by means of
24310 the tls_on_connect_ports global option. Its value must be a list of port
24311 numbers; the most common use is expected to be:
24312
24313 tls_on_connect_ports = 465
24314
24315 The port numbers specified by this option apply to all SMTP connections, both
24316 via the daemon and via inetd. You still need to specify all the ports that the
24317 daemon uses (by setting daemon_smtp_ports or local_interfaces or the -oX
24318 command line option) because tls_on_connect_ports does not add an extra port -
24319 rather, it specifies different behaviour on a port that is defined elsewhere.
24320
24321 There is also a -tls-on-connect command line option. This overrides
24322 tls_on_connect_ports; it forces the legacy behaviour for all ports.
24323
24324
24325 41.2 OpenSSL vs GnuTLS
24326 ----------------------
24327
24328 The first TLS support in Exim was implemented using OpenSSL. Support for GnuTLS
24329 followed later, when the first versions of GnuTLS were released. To build Exim
24330 to use GnuTLS, you need to set
24331
24332 USE_GNUTLS=yes
24333
24334 in Local/Makefile, in addition to
24335
24336 SUPPORT_TLS=yes
24337
24338 You must also set TLS_LIBS and TLS_INCLUDE appropriately, so that the include
24339 files and libraries for GnuTLS can be found.
24340
24341 There are some differences in usage when using GnuTLS instead of OpenSSL:
24342
24343 * The tls_verify_certificates option must contain the name of a file, not the
24344 name of a directory (for OpenSSL it can be either).
24345
24346 * The default value for tls_dhparam differs for historical reasons.
24347
24348 * Distinguished Name (DN) strings reported by the OpenSSL library use a slash
24349 for separating fields; GnuTLS uses commas, in accordance with RFC 2253.
24350 This affects the value of the $tls_in_peerdn and $tls_out_peerdn variables.
24351
24352 * OpenSSL identifies cipher suites using hyphens as separators, for example:
24353 DES-CBC3-SHA. GnuTLS historically used underscores, for example:
24354 RSA_ARCFOUR_SHA. What is more, OpenSSL complains if underscores are present
24355 in a cipher list. To make life simpler, Exim changes underscores to hyphens
24356 for OpenSSL and passes the string unchanged to GnuTLS (expecting the
24357 library to handle its own older variants) when processing lists of cipher
24358 suites in the tls_require_ciphers options (the global option and the smtp
24359 transport option).
24360
24361 * The tls_require_ciphers options operate differently, as described in the
24362 sections 41.4 and 41.5.
24363
24364 * The tls_dh_min_bits SMTP transport option is only honoured by GnuTLS. When
24365 using OpenSSL, this option is ignored. (If an API is found to let OpenSSL
24366 be configured in this way, let the Exim Maintainers know and we'll likely
24367 use it).
24368
24369 * Some other recently added features may only be available in one or the
24370 other. This should be documented with the feature. If the documentation
24371 does not explicitly state that the feature is infeasible in the other TLS
24372 implementation, then patches are welcome.
24373
24374
24375 41.3 GnuTLS parameter computation
24376 ---------------------------------
24377
24378 This section only applies if tls_dhparam is set to "historic" or to an explicit
24379 path; if the latter, then the text about generation still applies, but not the
24380 chosen filename. By default, as of Exim 4.80 a hard-coded D-H prime is used.
24381 See the documentation of tls_dhparam for more information.
24382
24383 GnuTLS uses D-H parameters that may take a substantial amount of time to
24384 compute. It is unreasonable to re-compute them for every TLS session.
24385 Therefore, Exim keeps this data in a file in its spool directory, called
24386 gnutls-params-NNNN for some value of NNNN, corresponding to the number of bits
24387 requested. The file is owned by the Exim user and is readable only by its
24388 owner. Every Exim process that start up GnuTLS reads the D-H parameters from
24389 this file. If the file does not exist, the first Exim process that needs it
24390 computes the data and writes it to a temporary file which is renamed once it is
24391 complete. It does not matter if several Exim processes do this simultaneously
24392 (apart from wasting a few resources). Once a file is in place, new Exim
24393 processes immediately start using it.
24394
24395 For maximum security, the parameters that are stored in this file should be
24396 recalculated periodically, the frequency depending on your paranoia level. If
24397 you are avoiding using the fixed D-H primes published in RFCs, then you are
24398 concerned about some advanced attacks and will wish to do this; if you do not
24399 regenerate then you might as well stick to the standard primes.
24400
24401 Arranging this is easy in principle; just delete the file when you want new
24402 values to be computed. However, there may be a problem. The calculation of new
24403 parameters needs random numbers, and these are obtained from /dev/random. If
24404 the system is not very active, /dev/random may delay returning data until
24405 enough randomness (entropy) is available. This may cause Exim to hang for a
24406 substantial amount of time, causing timeouts on incoming connections.
24407
24408 The solution is to generate the parameters externally to Exim. They are stored
24409 in gnutls-params-N in PEM format, which means that they can be generated
24410 externally using the certtool command that is part of GnuTLS.
24411
24412 To replace the parameters with new ones, instead of deleting the file and
24413 letting Exim re-create it, you can generate new parameters using certtool and,
24414 when this has been done, replace Exim's cache file by renaming. The relevant
24415 commands are something like this:
24416
24417 # ls
24418 [ look for file; assume gnutls-params-2236 is the most recent ]
24419 # rm -f new-params
24420 # touch new-params
24421 # chown exim:exim new-params
24422 # chmod 0600 new-params
24423 # certtool --generate-dh-params --bits 2236 >>new-params
24424 # openssl dhparam -noout -text -in new-params | head
24425 [ check the first line, make sure it's not more than 2236;
24426 if it is, then go back to the start ("rm") and repeat
24427 until the size generated is at most the size requested ]
24428 # chmod 0400 new-params
24429 # mv new-params gnutls-params-2236
24430
24431 If Exim never has to generate the parameters itself, the possibility of
24432 stalling is removed.
24433
24434 The filename changed in Exim 4.80, to gain the -bits suffix. The value which
24435 Exim will choose depends upon the version of GnuTLS in use. For older GnuTLS,
24436 the value remains hard-coded in Exim as 1024. As of GnuTLS 2.12.x, there is a
24437 way for Exim to ask for the "normal" number of bits for D-H public-key usage,
24438 and Exim does so. This attempt to remove Exim from TLS policy decisions failed,
24439 as GnuTLS 2.12 returns a value higher than the current hard-coded limit of the
24440 NSS library. Thus Exim gains the tls_dh_max_bits global option, which applies
24441 to all D-H usage, client or server. If the value returned by GnuTLS is greater
24442 than tls_dh_max_bits then the value will be clamped down to tls_dh_max_bits.
24443 The default value has been set at the current NSS limit, which is still much
24444 higher than Exim historically used.
24445
24446 The filename and bits used will change as the GnuTLS maintainers change the
24447 value for their parameter "GNUTLS_SEC_PARAM_NORMAL", as clamped by
24448 tls_dh_max_bits. At the time of writing (mid 2012), GnuTLS 2.12 recommends 2432
24449 bits, while NSS is limited to 2236 bits.
24450
24451 In fact, the requested value will be *lower* than tls_dh_max_bits, to increase
24452 the chance of the generated prime actually being within acceptable bounds, as
24453 GnuTLS has been observed to overshoot. Note the check step in the procedure
24454 above. There is no sane procedure available to Exim to double-check the size of
24455 the generated prime, so it might still be too large.
24456
24457
24458 41.4 Requiring specific ciphers in OpenSSL
24459 ------------------------------------------
24460
24461 There is a function in the OpenSSL library that can be passed a list of cipher
24462 suites before the cipher negotiation takes place. This specifies which ciphers
24463 are acceptable. The list is colon separated and may contain names like
24464 DES-CBC3-SHA. Exim passes the expanded value of tls_require_ciphers directly to
24465 this function call. Many systems will install the OpenSSL manual-pages, so you
24466 may have ciphers(1) available to you. The following quotation from the OpenSSL
24467 documentation specifies what forms of item are allowed in the cipher string:
24468
24469 * It can consist of a single cipher suite such as RC4-SHA.
24470
24471 * It can represent a list of cipher suites containing a certain algorithm, or
24472 cipher suites of a certain type. For example SHA1 represents all ciphers
24473 suites using the digest algorithm SHA1 and SSLv3 represents all SSL v3
24474 algorithms.
24475
24476 * Lists of cipher suites can be combined in a single cipher string using the
24477 + character. This is used as a logical and operation. For example SHA1+DES
24478 represents all cipher suites containing the SHA1 and the DES algorithms.
24479
24480 Each cipher string can be optionally preceded by one of the characters "!", "-"
24481 or "+".
24482
24483 * If "!" is used, the ciphers are permanently deleted from the list. The
24484 ciphers deleted can never reappear in the list even if they are explicitly
24485 stated.
24486
24487 * If "-" is used, the ciphers are deleted from the list, but some or all of
24488 the ciphers can be added again by later options.
24489
24490 * If "+" is used, the ciphers are moved to the end of the list. This option
24491 does not add any new ciphers; it just moves matching existing ones.
24492
24493 If none of these characters is present, the string is interpreted as a list of
24494 ciphers to be appended to the current preference list. If the list includes any
24495 ciphers already present they will be ignored: that is, they will not be moved
24496 to the end of the list.
24497
24498 The OpenSSL ciphers(1) command may be used to test the results of a given
24499 string:
24500
24501 # note single-quotes to get ! past any shell history expansion
24502 $ openssl ciphers 'HIGH:!MD5:!SHA1'
24503
24504 This example will let the library defaults be permitted on the MX port, where
24505 there's probably no identity verification anyway, but ups the ante on the
24506 submission ports where the administrator might have some influence on the
24507 choice of clients used:
24508
24509 # OpenSSL variant; see man ciphers(1)
24510 tls_require_ciphers = ${if =={$received_port}{25}\
24511 {DEFAULT}\
24512 {HIGH:!MD5:!SHA1}}
24513
24514
24515 41.5 Requiring specific ciphers or other parameters in GnuTLS
24516 -------------------------------------------------------------
24517
24518 The GnuTLS library allows the caller to provide a "priority string", documented
24519 as part of the gnutls_priority_init function. This is very similar to the
24520 ciphersuite specification in OpenSSL.
24521
24522 The tls_require_ciphers option is treated as the GnuTLS priority string.
24523
24524 The tls_require_ciphers option is available both as an global option,
24525 controlling how Exim behaves as a server, and also as an option of the smtp
24526 transport, controlling how Exim behaves as a client. In both cases the value is
24527 string expanded. The resulting string is not an Exim list and the string is
24528 given to the GnuTLS library, so that Exim does not need to be aware of future
24529 feature enhancements of GnuTLS.
24530
24531 Documentation of the strings accepted may be found in the GnuTLS manual, under
24532 "Priority strings". This is online as http://www.gnutls.org/manual/html_node/
24533 Priority-Strings.html, but beware that this relates to GnuTLS 3, which may be
24534 newer than the version installed on your system. If you are using GnuTLS 3,
24535 then the example code on that site can be used to test a given string.
24536
24537 Prior to Exim 4.80, an older API of GnuTLS was used, and Exim supported three
24538 additional options, "gnutls_require_kx", "gnutls_require_mac" and "
24539 gnutls_require_protocols". tls_require_ciphers was an Exim list.
24540
24541 This example will let the library defaults be permitted on the MX port, where
24542 there's probably no identity verification anyway, and lowers security further
24543 by increasing compatibility; but this ups the ante on the submission ports
24544 where the administrator might have some influence on the choice of clients
24545 used:
24546
24547 # GnuTLS variant
24548 tls_require_ciphers = ${if =={$received_port}{25}\
24549 {NORMAL:%COMPAT}\
24550 {SECURE128}}
24551
24552
24553 41.6 Configuring an Exim server to use TLS
24554 ------------------------------------------
24555
24556 When Exim has been built with TLS support, it advertises the availability of
24557 the STARTTLS command to client hosts that match tls_advertise_hosts, but not to
24558 any others. The default value of this option is unset, which means that
24559 STARTTLS is not advertised at all. This default is chosen because you need to
24560 set some other options in order to make TLS available, and also it is sensible
24561 for systems that want to use TLS only as a client.
24562
24563 If a client issues a STARTTLS command and there is some configuration problem
24564 in the server, the command is rejected with a 454 error. If the client persists
24565 in trying to issue SMTP commands, all except QUIT are rejected with the error
24566
24567 554 Security failure
24568
24569 If a STARTTLS command is issued within an existing TLS session, it is rejected
24570 with a 554 error code.
24571
24572 To enable TLS operations on a server, you must set tls_advertise_hosts to match
24573 some hosts. You can, of course, set it to * to match all hosts. However, this
24574 is not all you need to do. TLS sessions to a server won't work without some
24575 further configuration at the server end.
24576
24577 It is rumoured that all existing clients that support TLS/SSL use RSA
24578 encryption. To make this work you need to set, in the server,
24579
24580 tls_certificate = /some/file/name
24581 tls_privatekey = /some/file/name
24582
24583 These options are, in fact, expanded strings, so you can make them depend on
24584 the identity of the client that is connected if you wish. The first file
24585 contains the server's X509 certificate, and the second contains the private key
24586 that goes with it. These files need to be readable by the Exim user, and must
24587 always be given as full path names. They can be the same file if both the
24588 certificate and the key are contained within it. If tls_privatekey is not set,
24589 or if its expansion is forced to fail or results in an empty string, this is
24590 assumed to be the case. The certificate file may also contain intermediate
24591 certificates that need to be sent to the client to enable it to authenticate
24592 the server's certificate.
24593
24594 If you do not understand about certificates and keys, please try to find a
24595 source of this background information, which is not Exim-specific. (There are a
24596 few comments below in section 41.12.)
24597
24598 Note: These options do not apply when Exim is operating as a client - they
24599 apply only in the case of a server. If you need to use a certificate in an Exim
24600 client, you must set the options of the same names in an smtp transport.
24601
24602 With just these options, an Exim server will be able to use TLS. It does not
24603 require the client to have a certificate (but see below for how to insist on
24604 this). There is one other option that may be needed in other situations. If
24605
24606 tls_dhparam = /some/file/name
24607
24608 is set, the SSL library is initialized for the use of Diffie-Hellman ciphers
24609 with the parameters contained in the file. Set this to "none" to disable use of
24610 DH entirely, by making no prime available:
24611
24612 tls_dhparam = none
24613
24614 This may also be set to a string identifying a standard prime to be used for
24615 DH; if it is set to "default" or, for OpenSSL, is unset, then the prime used is
24616 "ike23". There are a few standard primes available, see the documentation for
24617 tls_dhparam for the complete list.
24618
24619 See the command
24620
24621 openssl dhparam
24622
24623 for a way of generating file data.
24624
24625 The strings supplied for these three options are expanded every time a client
24626 host connects. It is therefore possible to use different certificates and keys
24627 for different hosts, if you so wish, by making use of the client's IP address
24628 in $sender_host_address to control the expansion. If a string expansion is
24629 forced to fail, Exim behaves as if the option is not set.
24630
24631 The variable $tls_in_cipher is set to the cipher suite that was negotiated for
24632 an incoming TLS connection. It is included in the Received: header of an
24633 incoming message (by default - you can, of course, change this), and it is also
24634 included in the log line that records a message's arrival, keyed by "X=",
24635 unless the tls_cipher log selector is turned off. The encrypted condition can
24636 be used to test for specific cipher suites in ACLs.
24637
24638 Once TLS has been established, the ACLs that run for subsequent SMTP commands
24639 can check the name of the cipher suite and vary their actions accordingly. The
24640 cipher suite names vary, depending on which TLS library is being used. For
24641 example, OpenSSL uses the name DES-CBC3-SHA for the cipher suite which in other
24642 contexts is known as TLS_RSA_WITH_3DES_EDE_CBC_SHA. Check the OpenSSL or GnuTLS
24643 documentation for more details.
24644
24645 For outgoing SMTP deliveries, $tls_out_cipher is used and logged (again
24646 depending on the tls_cipher log selector).
24647
24648
24649 41.7 Requesting and verifying client certificates
24650 -------------------------------------------------
24651
24652 If you want an Exim server to request a certificate when negotiating a TLS
24653 session with a client, you must set either tls_verify_hosts or
24654 tls_try_verify_hosts. You can, of course, set either of them to * to apply to
24655 all TLS connections. For any host that matches one of these options, Exim
24656 requests a certificate as part of the setup of the TLS session. The contents of
24657 the certificate are verified by comparing it with a list of expected
24658 certificates. These must be available in a file or, for OpenSSL only (not
24659 GnuTLS), a directory, identified by tls_verify_certificates.
24660
24661 A file can contain multiple certificates, concatenated end to end. If a
24662 directory is used (OpenSSL only), each certificate must be in a separate file,
24663 with a name (or a symbolic link) of the form <hash>.0, where <hash> is a hash
24664 value constructed from the certificate. You can compute the relevant hash by
24665 running the command
24666
24667 openssl x509 -hash -noout -in /cert/file
24668
24669 where /cert/file contains a single certificate.
24670
24671 The difference between tls_verify_hosts and tls_try_verify_hosts is what
24672 happens if the client does not supply a certificate, or if the certificate does
24673 not match any of the certificates in the collection named by
24674 tls_verify_certificates. If the client matches tls_verify_hosts, the attempt to
24675 set up a TLS session is aborted, and the incoming connection is dropped. If the
24676 client matches tls_try_verify_hosts, the (encrypted) SMTP session continues.
24677 ACLs that run for subsequent SMTP commands can detect the fact that no
24678 certificate was verified, and vary their actions accordingly. For example, you
24679 can insist on a certificate before accepting a message for relaying, but not
24680 when the message is destined for local delivery.
24681
24682 When a client supplies a certificate (whether it verifies or not), the value of
24683 the Distinguished Name of the certificate is made available in the variable
24684 $tls_in_peerdn during subsequent processing of the message.
24685
24686 Because it is often a long text string, it is not included in the log line or
24687 Received: header by default. You can arrange for it to be logged, keyed by "DN=
24688 ", by setting the tls_peerdn log selector, and you can use received_header_text
24689 to change the Received: header. When no certificate is supplied, $tls_in_peerdn
24690 is empty.
24691
24692
24693 41.8 Revoked certificates
24694 -------------------------
24695
24696 Certificate issuing authorities issue Certificate Revocation Lists (CRLs) when
24697 certificates are revoked. If you have such a list, you can pass it to an Exim
24698 server using the global option called tls_crl and to an Exim client using an
24699 identically named option for the smtp transport. In each case, the value of the
24700 option is expanded and must then be the name of a file that contains a CRL in
24701 PEM format. The downside is that clients have to periodically re-download a
24702 potentially huge file from every certificate authority the know of.
24703
24704 The way with most moving parts at query time is Online Certificate Status
24705 Protocol (OCSP), where the client verifies the certificate against an OCSP
24706 server run by the CA. This lets the CA track all usage of the certs. It
24707 requires running software with access to the private key of the CA, to sign the
24708 responses to the OCSP queries. OCSP is based on HTTP and can be proxied
24709 accordingly.
24710
24711 The only widespread OCSP server implementation (known to this writer) comes as
24712 part of OpenSSL and aborts on an invalid request, such as connecting to the
24713 port and then disconnecting. This requires re-entering the passphrase each time
24714 some random client does this.
24715
24716 The third way is OCSP Stapling; in this, the server using a certificate issued
24717 by the CA periodically requests an OCSP proof of validity from the OCSP server,
24718 then serves it up inline as part of the TLS negotiation. This approach adds no
24719 extra round trips, does not let the CA track users, scales well with number of
24720 certs issued by the CA and is resilient to temporary OCSP server failures, as
24721 long as the server starts retrying to fetch an OCSP proof some time before its
24722 current proof expires. The downside is that it requires server support.
24723
24724 Unless Exim is built with the support disabled, or with GnuTLS earlier than
24725 version 3.1.3, support for OCSP stapling is included.
24726
24727 There is a global option called tls_ocsp_file. The file specified therein is
24728 expected to be in DER format, and contain an OCSP proof. Exim will serve it as
24729 part of the TLS handshake. This option will be re-expanded for SNI, if the
24730 tls_certificate option contains "tls_in_sni", as per other TLS options.
24731
24732 Exim does not at this time implement any support for fetching a new OCSP proof.
24733 The burden is on the administrator to handle this, outside of Exim. The file
24734 specified should be replaced atomically, so that the contents are always valid.
24735 Exim will expand the tls_ocsp_file option on each connection, so a new file
24736 will be handled transparently on the next connection.
24737
24738 When built with OpenSSL Exim will check for a valid next update timestamp in
24739 the OCSP proof; if not present, or if the proof has expired, it will be
24740 ignored.
24741
24742 For the client to be able to verify the stapled OCSP the server must also
24743 supply, in its stapled information, any intermediate certificates for the chain
24744 leading to the OCSP proof from the signer of the server certificate. There may
24745 be zero or one such. These intermediate certificates should be added to the
24746 server OCSP stapling file named by tls_ocsp_file.
24747
24748 Note that the proof only covers the terminal server certificate, not any of the
24749 chain from CA to it.
24750
24751 There is no current way to staple a proof for a client certificate.
24752
24753 A helper script "ocsp_fetch.pl" for fetching a proof from a CA
24754 OCSP server is supplied. The server URL may be included in the
24755 server certificate, if the CA is helpful.
24756
24757 One failure mode seen was the OCSP Signer cert expiring before the end
24758 of validity of the OCSP proof. The checking done by Exim/OpenSSL
24759 noted this as invalid overall, but the re-fetch script did not.
24760
24761
24762 41.9 Configuring an Exim client to use TLS
24763 ------------------------------------------
24764
24765 The tls_cipher and tls_peerdn log selectors apply to outgoing SMTP deliveries
24766 as well as to incoming, the latter one causing logging of the server
24767 certificate's DN. The remaining client configuration for TLS is all within the
24768 smtp transport.
24769
24770 It is not necessary to set any options to have TLS work in the smtp transport.
24771 If Exim is built with TLS support, and TLS is advertised by a server, the smtp
24772 transport always tries to start a TLS session. However, this can be prevented
24773 by setting hosts_avoid_tls (an option of the transport) to a list of server
24774 hosts for which TLS should not be used.
24775
24776 If you do not want Exim to attempt to send messages unencrypted when an attempt
24777 to set up an encrypted connection fails in any way, you can set
24778 hosts_require_tls to a list of hosts for which encryption is mandatory. For
24779 those hosts, delivery is always deferred if an encrypted connection cannot be
24780 set up. If there are any other hosts for the address, they are tried in the
24781 usual way.
24782
24783 When the server host is not in hosts_require_tls, Exim may try to deliver the
24784 message unencrypted. It always does this if the response to STARTTLS is a 5xx
24785 code. For a temporary error code, or for a failure to negotiate a TLS session
24786 after a success response code, what happens is controlled by the
24787 tls_tempfail_tryclear option of the smtp transport. If it is false, delivery to
24788 this host is deferred, and other hosts (if available) are tried. If it is true,
24789 Exim attempts to deliver unencrypted after a 4xx response to STARTTLS, and if
24790 STARTTLS is accepted, but the subsequent TLS negotiation fails, Exim closes the
24791 current connection (because it is in an unknown state), opens a new one to the
24792 same host, and then tries the delivery unencrypted.
24793
24794 The tls_certificate and tls_privatekey options of the smtp transport provide
24795 the client with a certificate, which is passed to the server if it requests it.
24796 If the server is Exim, it will request a certificate only if tls_verify_hosts
24797 or tls_try_verify_hosts matches the client.
24798
24799 If the tls_verify_certificates option is set on the smtp transport, it must
24800 name a file or, for OpenSSL only (not GnuTLS), a directory, that contains a
24801 collection of expected server certificates. The client verifies the server's
24802 certificate against this collection, taking into account any revoked
24803 certificates that are in the list defined by tls_crl. Failure to verify fails
24804 the TLS connection unless either of the tls_verify_hosts or
24805 tls_try_verify_hosts options are set.
24806
24807 The tls_verify_hosts and tls_try_verify_hosts options restrict certificate
24808 verification to the listed servers. Verification either must or need not
24809 succeed respectively.
24810
24811 The smtp transport has two OCSP-related options: hosts_require_ocsp; a
24812 host-list for which a Certificate Status is requested and required for the
24813 connection to proceed. The default value is empty. hosts_request_ocsp; a
24814 host-list for which (additionally) a Certificate Status is requested (but not
24815 necessarily verified). The default value is "*" meaning that requests are made
24816 unless configured otherwise.
24817
24818 The host(s) should also be in hosts_require_tls, and tls_verify_certificates
24819 configured for the transport, for OCSP to be relevant.
24820
24821 If tls_require_ciphers is set on the smtp transport, it must contain a list of
24822 permitted cipher suites. If either of these checks fails, delivery to the
24823 current host is abandoned, and the smtp transport tries to deliver to
24824 alternative hosts, if any.
24825
24826 Note: These options must be set in the smtp transport for Exim to use TLS when
24827 it is operating as a client. Exim does not assume that a server certificate
24828 (set by the global options of the same name) should also be used when operating
24829 as a client.
24830
24831 All the TLS options in the smtp transport are expanded before use, with $host
24832 and $host_address containing the name and address of the server to which the
24833 client is connected. Forced failure of an expansion causes Exim to behave as if
24834 the relevant option were unset.
24835
24836 Before an SMTP connection is established, the $tls_out_bits, $tls_out_cipher,
24837 $tls_out_peerdn and $tls_out_sni variables are emptied. (Until the first
24838 connection, they contain the values that were set when the message was
24839 received.) If STARTTLS is subsequently successfully obeyed, these variables are
24840 set to the relevant values for the outgoing connection.
24841
24842
24843 41.10 Use of TLS Server Name Indication
24844 ---------------------------------------
24845
24846 With TLS1.0 or above, there is an extension mechanism by which extra
24847 information can be included at various points in the protocol. One of these
24848 extensions, documented in RFC 6066 (and before that RFC 4366) is "Server Name
24849 Indication", commonly "SNI". This extension is sent by the client in the
24850 initial handshake, so that the server can examine the servername within and
24851 possibly choose to use different certificates and keys (and more) for this
24852 session.
24853
24854 This is analagous to HTTP's "Host:" header, and is the main mechanism by which
24855 HTTPS-enabled web-sites can be virtual-hosted, many sites to one IP address.
24856
24857 With SMTP to MX, there are the same problems here as in choosing the identity
24858 against which to validate a certificate: you can't rely on insecure DNS to
24859 provide the identity which you then cryptographically verify. So this will be
24860 of limited use in that environment.
24861
24862 With SMTP to Submission, there is a well-defined hostname which clients are
24863 connecting to and can validate certificates against. Thus clients can choose to
24864 include this information in the TLS negotiation. If this becomes wide-spread,
24865 then hosters can choose to present different certificates to different clients.
24866 Or even negotiate different cipher suites.
24867
24868 The tls_sni option on an SMTP transport is an expanded string; the result, if
24869 not empty, will be sent on a TLS session as part of the handshake. There's
24870 nothing more to it. Choosing a sensible value not derived insecurely is the
24871 only point of caution. The $tls_out_sni variable will be set to this string for
24872 the lifetime of the client connection (including during authentication).
24873
24874 Except during SMTP client sessions, if $tls_in_sni is set then it is a string
24875 received from a client. It can be logged with the log_selector item "+tls_sni".
24876
24877 If the string "tls_in_sni" appears in the main section's tls_certificate option
24878 (prior to expansion) then the following options will be re-expanded during TLS
24879 session handshake, to permit alternative values to be chosen:
24880
24881 * tls_certificate
24882
24883 * tls_crl
24884
24885 * tls_privatekey
24886
24887 * tls_verify_certificates
24888
24889 * tls_verify_certificates
24890
24891 Great care should be taken to deal with matters of case, various injection
24892 attacks in the string ("../" or SQL), and ensuring that a valid filename can
24893 always be referenced; it is important to remember that $tls_sni is arbitrary
24894 unverified data provided prior to authentication.
24895
24896 The Exim developers are proceeding cautiously and so far no other TLS options
24897 are re-expanded.
24898
24899 When Exim is built againt OpenSSL, OpenSSL must have been built with support
24900 for TLS Extensions. This holds true for OpenSSL 1.0.0+ and 0.9.8+ with
24901 enable-tlsext in EXTRACONFIGURE. If you invoke openssl s_client -h and see
24902 "-servername" in the output, then OpenSSL has support.
24903
24904 When Exim is built against GnuTLS, SNI support is available as of GnuTLS
24905 0.5.10. (Its presence predates the current API which Exim uses, so if Exim
24906 built, then you have SNI support).
24907
24908
24909 41.11 Multiple messages on the same encrypted TCP/IP connection
24910 ---------------------------------------------------------------
24911
24912 Exim sends multiple messages down the same TCP/IP connection by starting up an
24913 entirely new delivery process for each message, passing the socket from one
24914 process to the next. This implementation does not fit well with the use of TLS,
24915 because there is quite a lot of state information associated with a TLS
24916 connection, not just a socket identification. Passing all the state information
24917 to a new process is not feasible. Consequently, Exim shuts down an existing TLS
24918 session before passing the socket to a new process. The new process may then
24919 try to start a new TLS session, and if successful, may try to re-authenticate
24920 if AUTH is in use, before sending the next message.
24921
24922 The RFC is not clear as to whether or not an SMTP session continues in clear
24923 after TLS has been shut down, or whether TLS may be restarted again later, as
24924 just described. However, if the server is Exim, this shutdown and
24925 reinitialization works. It is not known which (if any) other servers operate
24926 successfully if the client closes a TLS session and continues with unencrypted
24927 SMTP, but there are certainly some that do not work. For such servers, Exim
24928 should not pass the socket to another process, because the failure of the
24929 subsequent attempt to use it would cause Exim to record a temporary host error,
24930 and delay other deliveries to that host.
24931
24932 To test for this case, Exim sends an EHLO command to the server after closing
24933 down the TLS session. If this fails in any way, the connection is closed
24934 instead of being passed to a new delivery process, but no retry information is
24935 recorded.
24936
24937 There is also a manual override; you can set hosts_nopass_tls on the smtp
24938 transport to match those hosts for which Exim should not pass connections to
24939 new processes if TLS has been used.
24940
24941
24942 41.12 Certificates and all that
24943 -------------------------------
24944
24945 In order to understand fully how TLS works, you need to know about
24946 certificates, certificate signing, and certificate authorities. This is not the
24947 place to give a tutorial, especially as I do not know very much about it
24948 myself. Some helpful introduction can be found in the FAQ for the SSL addition
24949 to Apache, currently at
24950
24951 http://www.modssl.org/docs/2.7/ssl_faq.html#ToC24
24952
24953 Other parts of the modssl documentation are also helpful, and have links to
24954 further files. Eric Rescorla's book, SSL and TLS, published by Addison-Wesley
24955 (ISBN 0-201-61598-3), contains both introductory and more in-depth
24956 descriptions. Some sample programs taken from the book are available from
24957
24958 http://www.rtfm.com/openssl-examples/
24959
24960
24961 41.13 Certificate chains
24962 ------------------------
24963
24964 The file named by tls_certificate may contain more than one certificate. This
24965 is useful in the case where the certificate that is being sent is validated by
24966 an intermediate certificate which the other end does not have. Multiple
24967 certificates must be in the correct order in the file. First the host's
24968 certificate itself, then the first intermediate certificate to validate the
24969 issuer of the host certificate, then the next intermediate certificate to
24970 validate the issuer of the first intermediate certificate, and so on, until
24971 finally (optionally) the root certificate. The root certificate must already be
24972 trusted by the recipient for validation to succeed, of course, but if it's not
24973 preinstalled, sending the root certificate along with the rest makes it
24974 available for the user to install if the receiving end is a client MUA that can
24975 interact with a user.
24976
24977 Note that certificates using MD5 are unlikely to work on today's Internet; even
24978 if your libraries allow loading them for use in Exim when acting as a server,
24979 increasingly clients will not accept such certificates. The error diagnostics
24980 in such a case can be frustratingly vague.
24981
24982
24983 41.14 Self-signed certificates
24984 ------------------------------
24985
24986 You can create a self-signed certificate using the req command provided with
24987 OpenSSL, like this:
24988
24989 openssl req -x509 -newkey rsa:1024 -keyout file1 -out file2 \
24990 -days 9999 -nodes
24991
24992 file1 and file2 can be the same file; the key and the certificate are delimited
24993 and so can be identified independently. The -days option specifies a period for
24994 which the certificate is valid. The -nodes option is important: if you do not
24995 set it, the key is encrypted with a passphrase that you are prompted for, and
24996 any use that is made of the key causes more prompting for the passphrase. This
24997 is not helpful if you are going to use this certificate and key in an MTA,
24998 where prompting is not possible.
24999
25000 NB: we are now past the point where 9999 days takes us past the 32-bit Unix
25001 epoch. If your system uses unsigned time_t (most do) and is 32-bit, then the
25002 above command might produce a date in the past. Think carefully about the
25003 lifetime of the systems you're deploying, and either reduce the duration of the
25004 certificate or reconsider your platform deployment. (At time of writing,
25005 reducing the duration is the most likely choice, but the inexorable progression
25006 of time takes us steadily towards an era where this will not be a sensible
25007 resolution).
25008
25009 A self-signed certificate made in this way is sufficient for testing, and may
25010 be adequate for all your requirements if you are mainly interested in
25011 encrypting transfers, and not in secure identification.
25012
25013 However, many clients require that the certificate presented by the server be a
25014 user (also called "leaf" or "site") certificate, and not a self-signed
25015 certificate. In this situation, the self-signed certificate described above
25016 must be installed on the client host as a trusted root certification authority
25017 (CA), and the certificate used by Exim must be a user certificate signed with
25018 that self-signed certificate.
25019
25020 For information on creating self-signed CA certificates and using them to sign
25021 user certificates, see the General implementation overview chapter of the
25022 Open-source PKI book, available online at http://ospkibook.sourceforge.net/.
25023
25024
25025
25026 ===============================================================================
25027 42. ACCESS CONTROL LISTS
25028
25029 Access Control Lists (ACLs) are defined in a separate section of the run time
25030 configuration file, headed by "begin acl". Each ACL definition starts with a
25031 name, terminated by a colon. Here is a complete ACL section that contains just
25032 one very small ACL:
25033
25034 begin acl
25035 small_acl:
25036 accept hosts = one.host.only
25037
25038 You can have as many lists as you like in the ACL section, and the order in
25039 which they appear does not matter. The lists are self-terminating.
25040
25041 The majority of ACLs are used to control Exim's behaviour when it receives
25042 certain SMTP commands. This applies both to incoming TCP/IP connections, and
25043 when a local process submits a message using SMTP by specifying the -bs option.
25044 The most common use is for controlling which recipients are accepted in
25045 incoming messages. In addition, you can define an ACL that is used to check
25046 local non-SMTP messages. The default configuration file contains an example of
25047 a realistic ACL for checking RCPT commands. This is discussed in chapter 7.
25048
25049
25050 42.1 Testing ACLs
25051 -----------------
25052
25053 The -bh command line option provides a way of testing your ACL configuration
25054 locally by running a fake SMTP session with which you interact. The host
25055 relay-test.mail-abuse.org provides a service for checking your relaying
25056 configuration (see section 42.53 for more details).
25057
25058
25059 42.2 Specifying when ACLs are used
25060 ----------------------------------
25061
25062 In order to cause an ACL to be used, you have to name it in one of the relevant
25063 options in the main part of the configuration. These options are:
25064
25065 acl_not_smtp ACL for non-SMTP messages
25066 acl_not_smtp_mime ACL for non-SMTP MIME parts
25067 acl_not_smtp_start ACL at start of non-SMTP message
25068 acl_smtp_auth ACL for AUTH
25069 acl_smtp_connect ACL for start of SMTP connection
25070 acl_smtp_data ACL after DATA is complete
25071 acl_smtp_data_prdr ACL for each recipient, after DATA is complete
25072 acl_smtp_etrn ACL for ETRN
25073 acl_smtp_expn ACL for EXPN
25074 acl_smtp_helo ACL for HELO or EHLO
25075 acl_smtp_mail ACL for MAIL
25076 acl_smtp_mailauth ACL for the AUTH parameter of MAIL
25077 acl_smtp_mime ACL for content-scanning MIME parts
25078 acl_smtp_notquit ACL for non-QUIT terminations
25079 acl_smtp_predata ACL at start of DATA command
25080 acl_smtp_quit ACL for QUIT
25081 acl_smtp_rcpt ACL for RCPT
25082 acl_smtp_starttls ACL for STARTTLS
25083 acl_smtp_vrfy ACL for VRFY
25084
25085 For example, if you set
25086
25087 acl_smtp_rcpt = small_acl
25088
25089 the little ACL defined above is used whenever Exim receives a RCPT command in
25090 an SMTP dialogue. The majority of policy tests on incoming messages can be done
25091 when RCPT commands arrive. A rejection of RCPT should cause the sending MTA to
25092 give up on the recipient address contained in the RCPT command, whereas
25093 rejection at other times may cause the client MTA to keep on trying to deliver
25094 the message. It is therefore recommended that you do as much testing as
25095 possible at RCPT time.
25096
25097
25098 42.3 The non-SMTP ACLs
25099 ----------------------
25100
25101 The non-SMTP ACLs apply to all non-interactive incoming messages, that is, they
25102 apply to batched SMTP as well as to non-SMTP messages. (Batched SMTP is not
25103 really SMTP.) Many of the ACL conditions (for example, host tests, and tests on
25104 the state of the SMTP connection such as encryption and authentication) are not
25105 relevant and are forbidden in these ACLs. However, the sender and recipients
25106 are known, so the senders and sender_domains conditions and the $sender_address
25107 and $recipients variables can be used. Variables such as $authenticated_sender
25108 are also available. You can specify added header lines in any of these ACLs.
25109
25110 The acl_not_smtp_start ACL is run right at the start of receiving a non-SMTP
25111 message, before any of the message has been read. (This is the analogue of the
25112 acl_smtp_predata ACL for SMTP input.) In the case of batched SMTP input, it
25113 runs after the DATA command has been reached. The result of this ACL is
25114 ignored; it cannot be used to reject a message. If you really need to, you
25115 could set a value in an ACL variable here and reject based on that in the
25116 acl_not_smtp ACL. However, this ACL can be used to set controls, and in
25117 particular, it can be used to set
25118
25119 control = suppress_local_fixups
25120
25121 This cannot be used in the other non-SMTP ACLs because by the time they are
25122 run, it is too late.
25123
25124 The acl_not_smtp_mime ACL is available only when Exim is compiled with the
25125 content-scanning extension. For details, see chapter 43.
25126
25127 The acl_not_smtp ACL is run just before the local_scan() function. Any kind of
25128 rejection is treated as permanent, because there is no way of sending a
25129 temporary error for these kinds of message.
25130
25131
25132 42.4 The SMTP connect ACL
25133 -------------------------
25134
25135 The ACL test specified by acl_smtp_connect happens at the start of an SMTP
25136 session, after the test specified by host_reject_connection (which is now an
25137 anomaly) and any TCP Wrappers testing (if configured). If the connection is
25138 accepted by an accept verb that has a message modifier, the contents of the
25139 message override the banner message that is otherwise specified by the
25140 smtp_banner option.
25141
25142
25143 42.5 The EHLO/HELO ACL
25144 ----------------------
25145
25146 The ACL test specified by acl_smtp_helo happens when the client issues an EHLO
25147 or HELO command, after the tests specified by helo_accept_junk_hosts,
25148 helo_allow_chars, helo_verify_hosts, and helo_try_verify_hosts. Note that a
25149 client may issue more than one EHLO or HELO command in an SMTP session, and
25150 indeed is required to issue a new EHLO or HELO after successfully setting up
25151 encryption following a STARTTLS command.
25152
25153 If the command is accepted by an accept verb that has a message modifier, the
25154 message may not contain more than one line (it will be truncated at the first
25155 newline and a panic logged if it does). Such a message cannot affect the EHLO
25156 options that are listed on the second and subsequent lines of an EHLO response.
25157
25158
25159 42.6 The DATA ACLs
25160 ------------------
25161
25162 Two ACLs are associated with the DATA command, because it is two-stage command,
25163 with two responses being sent to the client. When the DATA command is received,
25164 the ACL defined by acl_smtp_predata is obeyed. This gives you control after all
25165 the RCPT commands, but before the message itself is received. It offers the
25166 opportunity to give a negative response to the DATA command before the data is
25167 transmitted. Header lines added by MAIL or RCPT ACLs are not visible at this
25168 time, but any that are defined here are visible when the acl_smtp_data ACL is
25169 run.
25170
25171 You cannot test the contents of the message, for example, to verify addresses
25172 in the headers, at RCPT time or when the DATA command is received. Such tests
25173 have to appear in the ACL that is run after the message itself has been
25174 received, before the final response to the DATA command is sent. This is the
25175 ACL specified by acl_smtp_data, which is the second ACL that is associated with
25176 the DATA command.
25177
25178 For both of these ACLs, it is not possible to reject individual recipients. An
25179 error response rejects the entire message. Unfortunately, it is known that some
25180 MTAs do not treat hard (5xx) responses to the DATA command (either before or
25181 after the data) correctly - they keep the message on their queues and try again
25182 later, but that is their problem, though it does waste some of your resources.
25183
25184 The acl_smtp_data ACL is run after the acl_smtp_data_prdr, the acl_smtp_dkim
25185 and the acl_smtp_mime ACLs.
25186
25187
25188 42.7 The SMTP DKIM ACL
25189 ----------------------
25190
25191 The acl_smtp_dkim ACL is available only when Exim is compiled with DKIM support
25192 enabled (which is the default).
25193
25194 The ACL test specified by acl_smtp_dkim happens after a message has been
25195 received, and is executed for each DKIM signature found in a message. If not
25196 otherwise specified, the default action is to accept.
25197
25198 This ACL is evaluated before acl_smtp_mime and acl_smtp_data.
25199
25200 For details on the operation of DKIM, see chapter 56.
25201
25202
25203 42.8 The SMTP MIME ACL
25204 ----------------------
25205
25206 The acl_smtp_mime option is available only when Exim is compiled with the
25207 content-scanning extension. For details, see chapter 43.
25208
25209 This ACL is evaluated after acl_smtp_dkim but before acl_smtp_data.
25210
25211
25212 42.9 The SMTP PRDR ACL
25213 ----------------------
25214
25215 The acl_smtp_data_prdr ACL is available only when Exim is compiled with PRDR
25216 support enabled (which is the default). It becomes active only when the PRDR
25217 feature is negotiated between client and server for a message, and more than
25218 one recipient has been accepted.
25219
25220 The ACL test specfied by acl_smtp_data_prdr happens after a message has been
25221 recieved, and is executed for each recipient of the message. The test may
25222 accept or deny for inividual recipients. The acl_smtp_data will still be called
25223 after this ACL and can reject the message overall, even if this ACL has
25224 accepted it for some or all recipients.
25225
25226 PRDR may be used to support per-user content filtering. Without it one must
25227 defer any recipient after the first that has a different content-filter
25228 configuration. With PRDR, the RCPT-time check for this can be disabled when the
25229 MAIL-time $smtp_command included "PRDR". Any required difference in behaviour
25230 of the main DATA-time ACL should however depend on the PRDR-time ACL having
25231 run, as Exim will avoid doing so in some situations (eg. single-recipient
25232 mails).
25233
25234 See also the prdr_enable global option and the hosts_try_prdr smtp transport
25235 option.
25236
25237 This ACL is evaluated after acl_smtp_dkim but before acl_smtp_data. If the ACL
25238 is not defined, processing completes as if the feature was not requested by the
25239 client.
25240
25241
25242 42.10 The QUIT ACL
25243 ------------------
25244
25245 The ACL for the SMTP QUIT command is anomalous, in that the outcome of the ACL
25246 does not affect the response code to QUIT, which is always 221. Thus, the ACL
25247 does not in fact control any access. For this reason, the only verbs that are
25248 permitted are accept and warn.
25249
25250 This ACL can be used for tasks such as custom logging at the end of an SMTP
25251 session. For example, you can use ACL variables in other ACLs to count
25252 messages, recipients, etc., and log the totals at QUIT time using one or more
25253 logwrite modifiers on a warn verb.
25254
25255 Warning: Only the $acl_cx variables can be used for this, because the $acl_mx
25256 variables are reset at the end of each incoming message.
25257
25258 You do not need to have a final accept, but if you do, you can use a message
25259 modifier to specify custom text that is sent as part of the 221 response to
25260 QUIT.
25261
25262 This ACL is run only for a "normal" QUIT. For certain kinds of disastrous
25263 failure (for example, failure to open a log file, or when Exim is bombing out
25264 because it has detected an unrecoverable error), all SMTP commands from the
25265 client are given temporary error responses until QUIT is received or the
25266 connection is closed. In these special cases, the QUIT ACL does not run.
25267
25268
25269 42.11 The not-QUIT ACL
25270 ----------------------
25271
25272 The not-QUIT ACL, specified by acl_smtp_notquit, is run in most cases when an
25273 SMTP session ends without sending QUIT. However, when Exim itself is in bad
25274 trouble, such as being unable to write to its log files, this ACL is not run,
25275 because it might try to do things (such as write to log files) that make the
25276 situation even worse.
25277
25278 Like the QUIT ACL, this ACL is provided to make it possible to do customized
25279 logging or to gather statistics, and its outcome is ignored. The delay modifier
25280 is forbidden in this ACL, and the only permitted verbs are accept and warn.
25281
25282 When the not-QUIT ACL is running, the variable $smtp_notquit_reason is set to a
25283 string that indicates the reason for the termination of the SMTP connection.
25284 The possible values are:
25285
25286 "acl-drop" Another ACL issued a drop command
25287 "bad-commands" Too many unknown or non-mail commands
25288 "command-timeout" Timeout while reading SMTP commands
25289 "connection-lost" The SMTP connection has been lost
25290 "data-timeout" Timeout while reading message data
25291 "local-scan-error" The local_scan() function crashed
25292 "local-scan-timeout" The local_scan() function timed out
25293 "signal-exit" SIGTERM or SIGINT
25294 "synchronization-error" SMTP synchronization error
25295 "tls-failed" TLS failed to start
25296
25297 In most cases when an SMTP connection is closed without having received QUIT,
25298 Exim sends an SMTP response message before actually closing the connection.
25299 With the exception of the "acl-drop" case, the default message can be
25300 overridden by the message modifier in the not-QUIT ACL. In the case of a drop
25301 verb in another ACL, it is the message from the other ACL that is used.
25302
25303
25304 42.12 Finding an ACL to use
25305 ---------------------------
25306
25307 The value of an acl_smtp_xxx option is expanded before use, so you can use
25308 different ACLs in different circumstances. For example,
25309
25310 acl_smtp_rcpt = ${if ={25}{$interface_port} \
25311 {acl_check_rcpt} {acl_check_rcpt_submit} }
25312
25313 In the default configuration file there are some example settings for providing
25314 an RFC 4409 message submission service on port 587 and a non-standard "smtps"
25315 service on port 465. You can use a string expansion like this to choose an ACL
25316 for MUAs on these ports which is more appropriate for this purpose than the
25317 default ACL on port 25.
25318
25319 The expanded string does not have to be the name of an ACL in the configuration
25320 file; there are other possibilities. Having expanded the string, Exim searches
25321 for an ACL as follows:
25322
25323 * If the string begins with a slash, Exim uses it as a file name, and reads
25324 its contents as an ACL. The lines are processed in the same way as lines in
25325 the Exim configuration file. In particular, continuation lines are
25326 supported, blank lines are ignored, as are lines whose first non-whitespace
25327 character is "#". If the file does not exist or cannot be read, an error
25328 occurs (typically causing a temporary failure of whatever caused the ACL to
25329 be run). For example:
25330
25331 acl_smtp_data = /etc/acls/\
25332 ${lookup{$sender_host_address}lsearch\
25333 {/etc/acllist}{$value}{default}}
25334
25335 This looks up an ACL file to use on the basis of the host's IP address,
25336 falling back to a default if the lookup fails. If an ACL is successfully
25337 read from a file, it is retained in memory for the duration of the Exim
25338 process, so that it can be re-used without having to re-read the file.
25339
25340 * If the string does not start with a slash, and does not contain any spaces,
25341 Exim searches the ACL section of the configuration for an ACL whose name
25342 matches the string.
25343
25344 * If no named ACL is found, or if the string contains spaces, Exim parses the
25345 string as an inline ACL. This can save typing in cases where you just want
25346 to have something like
25347
25348 acl_smtp_vrfy = accept
25349
25350 in order to allow free use of the VRFY command. Such a string may contain
25351 newlines; it is processed in the same way as an ACL that is read from a
25352 file.
25353
25354
25355 42.13 ACL return codes
25356 ----------------------
25357
25358 Except for the QUIT ACL, which does not affect the SMTP return code (see
25359 section 42.10 above), the result of running an ACL is either "accept" or
25360 "deny", or, if some test cannot be completed (for example, if a database is
25361 down), "defer". These results cause 2xx, 5xx, and 4xx return codes,
25362 respectively, to be used in the SMTP dialogue. A fourth return, "error", occurs
25363 when there is an error such as invalid syntax in the ACL. This also causes a 4
25364 xx return code.
25365
25366 For the non-SMTP ACL, "defer" and "error" are treated in the same way as
25367 "deny", because there is no mechanism for passing temporary errors to the
25368 submitters of non-SMTP messages.
25369
25370 ACLs that are relevant to message reception may also return "discard". This has
25371 the effect of "accept", but causes either the entire message or an individual
25372 recipient address to be discarded. In other words, it is a blackholing
25373 facility. Use it with care.
25374
25375 If the ACL for MAIL returns "discard", all recipients are discarded, and no ACL
25376 is run for subsequent RCPT commands. The effect of "discard" in a RCPT ACL is
25377 to discard just the one recipient address. If there are no recipients left when
25378 the message's data is received, the DATA ACL is not run. A "discard" return
25379 from the DATA or the non-SMTP ACL discards all the remaining recipients. The
25380 "discard" return is not permitted for the acl_smtp_predata ACL.
25381
25382 The local_scan() function is always run, even if there are no remaining
25383 recipients; it may create new recipients.
25384
25385
25386 42.14 Unset ACL options
25387 -----------------------
25388
25389 The default actions when any of the acl_xxx options are unset are not all the
25390 same. Note: These defaults apply only when the relevant ACL is not defined at
25391 all. For any defined ACL, the default action when control reaches the end of
25392 the ACL statements is "deny".
25393
25394 For acl_smtp_quit and acl_not_smtp_start there is no default because these two
25395 are ACLs that are used only for their side effects. They cannot be used to
25396 accept or reject anything.
25397
25398 For acl_not_smtp, acl_smtp_auth, acl_smtp_connect, acl_smtp_data, acl_smtp_helo
25399 , acl_smtp_mail, acl_smtp_mailauth, acl_smtp_mime, acl_smtp_predata, and
25400 acl_smtp_starttls, the action when the ACL is not defined is "accept".
25401
25402 For the others (acl_smtp_etrn, acl_smtp_expn, acl_smtp_rcpt, and acl_smtp_vrfy
25403 ), the action when the ACL is not defined is "deny". This means that
25404 acl_smtp_rcpt must be defined in order to receive any messages over an SMTP
25405 connection. For an example, see the ACL in the default configuration file.
25406
25407
25408 42.15 Data for message ACLs
25409 ---------------------------
25410
25411 When a MAIL or RCPT ACL, or either of the DATA ACLs, is running, the variables
25412 that contain information about the host and the message's sender (for example,
25413 $sender_host_address and $sender_address) are set, and can be used in ACL
25414 statements. In the case of RCPT (but not MAIL or DATA), $domain and $local_part
25415 are set from the argument address. The entire SMTP command is available in
25416 $smtp_command.
25417
25418 When an ACL for the AUTH parameter of MAIL is running, the variables that
25419 contain information about the host are set, but $sender_address is not yet set.
25420 Section 33.2 contains a discussion of this parameter and how it is used.
25421
25422 The $message_size variable is set to the value of the SIZE parameter on the
25423 MAIL command at MAIL, RCPT and pre-data time, or to -1 if that parameter is not
25424 given. The value is updated to the true message size by the time the final DATA
25425 ACL is run (after the message data has been received).
25426
25427 The $rcpt_count variable increases by one for each RCPT command received. The
25428 $recipients_count variable increases by one each time a RCPT command is
25429 accepted, so while an ACL for RCPT is being processed, it contains the number
25430 of previously accepted recipients. At DATA time (for both the DATA ACLs),
25431 $rcpt_count contains the total number of RCPT commands, and $recipients_count
25432 contains the total number of accepted recipients.
25433
25434
25435 42.16 Data for non-message ACLs
25436 -------------------------------
25437
25438 When an ACL is being run for AUTH, EHLO, ETRN, EXPN, HELO, STARTTLS, or VRFY,
25439 the remainder of the SMTP command line is placed in $smtp_command_argument, and
25440 the entire SMTP command is available in $smtp_command. These variables can be
25441 tested using a condition condition. For example, here is an ACL for use with
25442 AUTH, which insists that either the session is encrypted, or the CRAM-MD5
25443 authentication method is used. In other words, it does not permit
25444 authentication methods that use cleartext passwords on unencrypted connections.
25445
25446 acl_check_auth:
25447 accept encrypted = *
25448 accept condition = ${if eq{${uc:$smtp_command_argument}}\
25449 {CRAM-MD5}}
25450 deny message = TLS encryption or CRAM-MD5 required
25451
25452 (Another way of applying this restriction is to arrange for the authenticators
25453 that use cleartext passwords not to be advertised when the connection is not
25454 encrypted. You can use the generic server_advertise_condition authenticator
25455 option to do this.)
25456
25457
25458 42.17 Format of an ACL
25459 ----------------------
25460
25461 An individual ACL consists of a number of statements. Each statement starts
25462 with a verb, optionally followed by a number of conditions and "modifiers".
25463 Modifiers can change the way the verb operates, define error and log messages,
25464 set variables, insert delays, and vary the processing of accepted messages.
25465
25466 If all the conditions are met, the verb is obeyed. The same condition may be
25467 used (with different arguments) more than once in the same statement. This
25468 provides a means of specifying an "and" conjunction between conditions. For
25469 example:
25470
25471 deny dnslists = list1.example
25472 dnslists = list2.example
25473
25474 If there are no conditions, the verb is always obeyed. Exim stops evaluating
25475 the conditions and modifiers when it reaches a condition that fails. What
25476 happens then depends on the verb (and in one case, on a special modifier). Not
25477 all the conditions make sense at every testing point. For example, you cannot
25478 test a sender address in the ACL that is run for a VRFY command.
25479
25480
25481 42.18 ACL verbs
25482 ---------------
25483
25484 The ACL verbs are as follows:
25485
25486 * accept: If all the conditions are met, the ACL returns "accept". If any of
25487 the conditions are not met, what happens depends on whether endpass appears
25488 among the conditions (for syntax see below). If the failing condition is
25489 before endpass, control is passed to the next ACL statement; if it is after
25490 endpass, the ACL returns "deny". Consider this statement, used to check a
25491 RCPT command:
25492
25493 accept domains = +local_domains
25494 endpass
25495 verify = recipient
25496
25497 If the recipient domain does not match the domains condition, control
25498 passes to the next statement. If it does match, the recipient is verified,
25499 and the command is accepted if verification succeeds. However, if
25500 verification fails, the ACL yields "deny", because the failing condition is
25501 after endpass.
25502
25503 The endpass feature has turned out to be confusing to many people, so its
25504 use is not recommended nowadays. It is always possible to rewrite an ACL so
25505 that endpass is not needed, and it is no longer used in the default
25506 configuration.
25507
25508 If a message modifier appears on an accept statement, its action depends on
25509 whether or not endpass is present. In the absence of endpass (when an
25510 accept verb either accepts or passes control to the next statement),
25511 message can be used to vary the message that is sent when an SMTP command
25512 is accepted. For example, in a RCPT ACL you could have:
25513
25514 accept <some conditions>
25515 message = OK, I will allow you through today
25516
25517 You can specify an SMTP response code, optionally followed by an "extended
25518 response code" at the start of the message, but the first digit must be the
25519 same as would be sent by default, which is 2 for an accept verb.
25520
25521 If endpass is present in an accept statement, message specifies an error
25522 message that is used when access is denied. This behaviour is retained for
25523 backward compatibility, but current "best practice" is to avoid the use of
25524 endpass.
25525
25526 * defer: If all the conditions are true, the ACL returns "defer" which, in an
25527 SMTP session, causes a 4xx response to be given. For a non-SMTP ACL, defer
25528 is the same as deny, because there is no way of sending a temporary error.
25529 For a RCPT command, defer is much the same as using a redirect router and
25530 ":defer:" while verifying, but the defer verb can be used in any ACL, and
25531 even for a recipient it might be a simpler approach.
25532
25533 * deny: If all the conditions are met, the ACL returns "deny". If any of the
25534 conditions are not met, control is passed to the next ACL statement. For
25535 example,
25536
25537 deny dnslists = blackholes.mail-abuse.org
25538
25539 rejects commands from hosts that are on a DNS black list.
25540
25541 * discard: This verb behaves like accept, except that it returns "discard"
25542 from the ACL instead of "accept". It is permitted only on ACLs that are
25543 concerned with receiving messages. When all the conditions are true, the
25544 sending entity receives a "success" response. However, discard causes
25545 recipients to be discarded. If it is used in an ACL for RCPT, just the one
25546 recipient is discarded; if used for MAIL, DATA or in the non-SMTP ACL, all
25547 the message's recipients are discarded. Recipients that are discarded
25548 before DATA do not appear in the log line when the received_recipients log
25549 selector is set.
25550
25551 If the log_message modifier is set when discard operates, its contents are
25552 added to the line that is automatically written to the log. The message
25553 modifier operates exactly as it does for accept.
25554
25555 * drop: This verb behaves like deny, except that an SMTP connection is
25556 forcibly closed after the 5xx error message has been sent. For example:
25557
25558 drop message = I don't take more than 20 RCPTs
25559 condition = ${if > {$rcpt_count}{20}}
25560
25561 There is no difference between deny and drop for the connect-time ACL. The
25562 connection is always dropped after sending a 550 response.
25563
25564 * require: If all the conditions are met, control is passed to the next ACL
25565 statement. If any of the conditions are not met, the ACL returns "deny".
25566 For example, when checking a RCPT command,
25567
25568 require message = Sender did not verify
25569 verify = sender
25570
25571 passes control to subsequent statements only if the message's sender can be
25572 verified. Otherwise, it rejects the command. Note the positioning of the
25573 message modifier, before the verify condition. The reason for this is
25574 discussed in section 42.20.
25575
25576 * warn: If all the conditions are true, a line specified by the log_message
25577 modifier is written to Exim's main log. Control always passes to the next
25578 ACL statement. If any condition is false, the log line is not written. If
25579 an identical log line is requested several times in the same message, only
25580 one copy is actually written to the log. If you want to force duplicates to
25581 be written, use the logwrite modifier instead.
25582
25583 If log_message is not present, a warn verb just checks its conditions and
25584 obeys any "immediate" modifiers (such as control, set, logwrite, add_header
25585 , and remove_header) that appear before the first failing condition. There
25586 is more about adding header lines in section 42.24.
25587
25588 If any condition on a warn statement cannot be completed (that is, there is
25589 some sort of defer), the log line specified by log_message is not written.
25590 This does not include the case of a forced failure from a lookup, which is
25591 considered to be a successful completion. After a defer, no further
25592 conditions or modifiers in the warn statement are processed. The incident
25593 is logged, and the ACL continues to be processed, from the next statement
25594 onwards.
25595
25596 When one of the warn conditions is an address verification that fails, the
25597 text of the verification failure message is in $acl_verify_message. If you
25598 want this logged, you must set it up explicitly. For example:
25599
25600 warn !verify = sender
25601 log_message = sender verify failed: $acl_verify_message
25602
25603 At the end of each ACL there is an implicit unconditional deny.
25604
25605 As you can see from the examples above, the conditions and modifiers are
25606 written one to a line, with the first one on the same line as the verb, and
25607 subsequent ones on following lines. If you have a very long condition, you can
25608 continue it onto several physical lines by the usual backslash continuation
25609 mechanism. It is conventional to align the conditions vertically.
25610
25611
25612 42.19 ACL variables
25613 -------------------
25614
25615 There are some special variables that can be set during ACL processing. They
25616 can be used to pass information between different ACLs, different invocations
25617 of the same ACL in the same SMTP connection, and between ACLs and the routers,
25618 transports, and filters that are used to deliver a message. The names of these
25619 variables must begin with $acl_c or $acl_m, followed either by a digit or an
25620 underscore, but the remainder of the name can be any sequence of alphanumeric
25621 characters and underscores that you choose. There is no limit on the number of
25622 ACL variables. The two sets act as follows:
25623
25624 * The values of those variables whose names begin with $acl_c persist
25625 throughout an SMTP connection. They are never reset. Thus, a value that is
25626 set while receiving one message is still available when receiving the next
25627 message on the same SMTP connection.
25628
25629 * The values of those variables whose names begin with $acl_m persist only
25630 while a message is being received. They are reset afterwards. They are also
25631 reset by MAIL, RSET, EHLO, HELO, and after starting up a TLS session.
25632
25633 When a message is accepted, the current values of all the ACL variables are
25634 preserved with the message and are subsequently made available at delivery
25635 time. The ACL variables are set by a modifier called set. For example:
25636
25637 accept hosts = whatever
25638 set acl_m4 = some value
25639 accept authenticated = *
25640 set acl_c_auth = yes
25641
25642 Note: A leading dollar sign is not used when naming a variable that is to be
25643 set. If you want to set a variable without taking any action, you can use a
25644 warn verb without any other modifiers or conditions.
25645
25646 What happens if a syntactically valid but undefined ACL variable is referenced
25647 depends on the setting of the strict_acl_vars option. If it is false (the
25648 default), an empty string is substituted; if it is true, an error is generated.
25649
25650 Versions of Exim before 4.64 have a limited set of numbered variables, but
25651 their names are compatible, so there is no problem with upgrading.
25652
25653
25654 42.20 Condition and modifier processing
25655 ---------------------------------------
25656
25657 An exclamation mark preceding a condition negates its result. For example:
25658
25659 deny domains = *.dom.example
25660 !verify = recipient
25661
25662 causes the ACL to return "deny" if the recipient domain ends in dom.example and
25663 the recipient address cannot be verified. Sometimes negation can be used on the
25664 right-hand side of a condition. For example, these two statements are
25665 equivalent:
25666
25667 deny hosts = !192.168.3.4
25668 deny !hosts = 192.168.3.4
25669
25670 However, for many conditions (verify being a good example), only left-hand side
25671 negation of the whole condition is possible.
25672
25673 The arguments of conditions and modifiers are expanded. A forced failure of an
25674 expansion causes a condition to be ignored, that is, it behaves as if the
25675 condition is true. Consider these two statements:
25676
25677 accept senders = ${lookup{$host_name}lsearch\
25678 {/some/file}{$value}fail}
25679 accept senders = ${lookup{$host_name}lsearch\
25680 {/some/file}{$value}{}}
25681
25682 Each attempts to look up a list of acceptable senders. If the lookup succeeds,
25683 the returned list is searched, but if the lookup fails the behaviour is
25684 different in the two cases. The fail in the first statement causes the
25685 condition to be ignored, leaving no further conditions. The accept verb
25686 therefore succeeds. The second statement, however, generates an empty list when
25687 the lookup fails. No sender can match an empty list, so the condition fails,
25688 and therefore the accept also fails.
25689
25690 ACL modifiers appear mixed in with conditions in ACL statements. Some of them
25691 specify actions that are taken as the conditions for a statement are checked;
25692 others specify text for messages that are used when access is denied or a
25693 warning is generated. The control modifier affects the way an incoming message
25694 is handled.
25695
25696 The positioning of the modifiers in an ACL statement is important, because the
25697 processing of a verb ceases as soon as its outcome is known. Only those
25698 modifiers that have already been encountered will take effect. For example,
25699 consider this use of the message modifier:
25700
25701 require message = Can't verify sender
25702 verify = sender
25703 message = Can't verify recipient
25704 verify = recipient
25705 message = This message cannot be used
25706
25707 If sender verification fails, Exim knows that the result of the statement is
25708 "deny", so it goes no further. The first message modifier has been seen, so its
25709 text is used as the error message. If sender verification succeeds, but
25710 recipient verification fails, the second message is used. If recipient
25711 verification succeeds, the third message becomes "current", but is never used
25712 because there are no more conditions to cause failure.
25713
25714 For the deny verb, on the other hand, it is always the last message modifier
25715 that is used, because all the conditions must be true for rejection to happen.
25716 Specifying more than one message modifier does not make sense, and the message
25717 can even be specified after all the conditions. For example:
25718
25719 deny hosts = ...
25720 !senders = *@my.domain.example
25721 message = Invalid sender from client host
25722
25723 The "deny" result does not happen until the end of the statement is reached, by
25724 which time Exim has set up the message.
25725
25726
25727 42.21 ACL modifiers
25728 -------------------
25729
25730 The ACL modifiers are as follows:
25731
25732 add_header = <text>
25733
25734 This modifier specifies one or more header lines that are to be added to an
25735 incoming message, assuming, of course, that the message is ultimately
25736 accepted. For details, see section 42.24.
25737
25738 continue = <text>
25739
25740 This modifier does nothing of itself, and processing of the ACL always
25741 continues with the next condition or modifier. The value of continue is in
25742 the side effects of expanding its argument. Typically this could be used to
25743 update a database. It is really just a syntactic tidiness, to avoid having
25744 to write rather ugly lines like this:
25745
25746 condition = ${if eq{0}{<some expansion>}{true}{true}}
25747
25748 Instead, all you need is
25749
25750 continue = <some expansion>
25751
25752 control = <text>
25753
25754 This modifier affects the subsequent processing of the SMTP connection or
25755 of an incoming message that is accepted. The effect of the first type of
25756 control lasts for the duration of the connection, whereas the effect of the
25757 second type lasts only until the current message has been received. The
25758 message-specific controls always apply to the whole message, not to
25759 individual recipients, even if the control modifier appears in a RCPT ACL.
25760
25761 As there are now quite a few controls that can be applied, they are
25762 described separately in section 42.22. The control modifier can be used in
25763 several different ways. For example:
25764
25765 * It can be at the end of an accept statement:
25766
25767 accept ...some conditions
25768 control = queue_only
25769
25770 In this case, the control is applied when this statement yields
25771 "accept", in other words, when the conditions are all true.
25772
25773 * It can be in the middle of an accept statement:
25774
25775 accept ...some conditions...
25776 control = queue_only
25777 ...some more conditions...
25778
25779 If the first set of conditions are true, the control is applied, even
25780 if the statement does not accept because one of the second set of
25781 conditions is false. In this case, some subsequent statement must yield
25782 "accept" for the control to be relevant.
25783
25784 * It can be used with warn to apply the control, leaving the decision
25785 about accepting or denying to a subsequent verb. For example:
25786
25787 warn ...some conditions...
25788 control = freeze
25789 accept ...
25790
25791 This example of warn does not contain message, log_message, or logwrite
25792 , so it does not add anything to the message and does not write a log
25793 entry.
25794
25795 * If you want to apply a control unconditionally, you can use it with a
25796 require verb. For example:
25797
25798 require control = no_multiline_responses
25799
25800 delay = <time>
25801
25802 This modifier may appear in any ACL except notquit. It causes Exim to wait
25803 for the time interval before proceeding. However, when testing Exim using
25804 the -bh option, the delay is not actually imposed (an appropriate message
25805 is output instead). The time is given in the usual Exim notation, and the
25806 delay happens as soon as the modifier is processed. In an SMTP session,
25807 pending output is flushed before the delay is imposed.
25808
25809 Like control, delay can be used with accept or deny, for example:
25810
25811 deny ...some conditions...
25812 delay = 30s
25813
25814 The delay happens if all the conditions are true, before the statement
25815 returns "deny". Compare this with:
25816
25817 deny delay = 30s
25818 ...some conditions...
25819
25820 which waits for 30s before processing the conditions. The delay modifier
25821 can also be used with warn and together with control:
25822
25823 warn ...some conditions...
25824 delay = 2m
25825 control = freeze
25826 accept ...
25827
25828 If delay is encountered when the SMTP PIPELINING extension is in use,
25829 responses to several commands are no longer buffered and sent in one packet
25830 (as they would normally be) because all output is flushed before imposing
25831 the delay. This optimization is disabled so that a number of small delays
25832 do not appear to the client as one large aggregated delay that might
25833 provoke an unwanted timeout. You can, however, disable output flushing for
25834 delay by using a control modifier to set no_delay_flush.
25835
25836 endpass
25837
25838 This modifier, which has no argument, is recognized only in accept and
25839 discard statements. It marks the boundary between the conditions whose
25840 failure causes control to pass to the next statement, and the conditions
25841 whose failure causes the ACL to return "deny". This concept has proved to
25842 be confusing to some people, so the use of endpass is no longer recommended
25843 as "best practice". See the description of accept above for more details.
25844
25845 log_message = <text>
25846
25847 This modifier sets up a message that is used as part of the log message if
25848 the ACL denies access or a warn statement's conditions are true. For
25849 example:
25850
25851 require log_message = wrong cipher suite $tls_in_cipher
25852 encrypted = DES-CBC3-SHA
25853
25854 log_message is also used when recipients are discarded by discard. For
25855 example:
25856
25857 discard <some conditions>
25858 log_message = Discarded $local_part@$domain because...
25859
25860 When access is denied, log_message adds to any underlying error message
25861 that may exist because of a condition failure. For example, while verifying
25862 a recipient address, a :fail: redirection might have already set up a
25863 message.
25864
25865 The message may be defined before the conditions to which it applies,
25866 because the string expansion does not happen until Exim decides that access
25867 is to be denied. This means that any variables that are set by the
25868 condition are available for inclusion in the message. For example, the
25869 $dnslist_<xxx> variables are set after a DNS black list lookup succeeds. If
25870 the expansion of log_message fails, or if the result is an empty string,
25871 the modifier is ignored.
25872
25873 If you want to use a warn statement to log the result of an address
25874 verification, you can use $acl_verify_message to include the verification
25875 error message.
25876
25877 If log_message is used with a warn statement, "Warning:" is added to the
25878 start of the logged message. If the same warning log message is requested
25879 more than once while receiving a single email message, only one copy is
25880 actually logged. If you want to log multiple copies, use logwrite instead
25881 of log_message. In the absence of log_message and logwrite, nothing is
25882 logged for a successful warn statement.
25883
25884 If log_message is not present and there is no underlying error message (for
25885 example, from the failure of address verification), but message is present,
25886 the message text is used for logging rejections. However, if any text for
25887 logging contains newlines, only the first line is logged. In the absence of
25888 both log_message and message, a default built-in message is used for
25889 logging rejections.
25890
25891 log_reject_target = <log name list>
25892
25893 This modifier makes it possible to specify which logs are used for messages
25894 about ACL rejections. Its argument is a colon-separated list of words that
25895 can be "main", "reject", or "panic". The default is "main:reject". The list
25896 may be empty, in which case a rejection is not logged at all. For example,
25897 this ACL fragment writes no logging information when access is denied:
25898
25899 deny <some conditions>
25900 log_reject_target =
25901
25902 This modifier can be used in SMTP and non-SMTP ACLs. It applies to both
25903 permanent and temporary rejections. Its effect lasts for the rest of the
25904 current ACL.
25905
25906 logwrite = <text>
25907
25908 This modifier writes a message to a log file as soon as it is encountered
25909 when processing an ACL. (Compare log_message, which, except in the case of
25910 warn and discard, is used only if the ACL statement denies access.) The
25911 logwrite modifier can be used to log special incidents in ACLs. For
25912 example:
25913
25914 accept <some special conditions>
25915 control = freeze
25916 logwrite = froze message because ...
25917
25918 By default, the message is written to the main log. However, it may begin
25919 with a colon, followed by a comma-separated list of log names, and then
25920 another colon, to specify exactly which logs are to be written. For
25921 example:
25922
25923 logwrite = :main,reject: text for main and reject logs
25924 logwrite = :panic: text for panic log only
25925
25926 message = <text>
25927
25928 This modifier sets up a text string that is expanded and used as a response
25929 message when an ACL statement terminates the ACL with an "accept", "deny",
25930 or "defer" response. (In the case of the accept and discard verbs, there is
25931 some complication if endpass is involved; see the description of accept for
25932 details.)
25933
25934 The expansion of the message happens at the time Exim decides that the ACL
25935 is to end, not at the time it processes message. If the expansion fails, or
25936 generates an empty string, the modifier is ignored. Here is an example
25937 where message must be specified first, because the ACL ends with a
25938 rejection if the hosts condition fails:
25939
25940 require message = Host not recognized
25941 hosts = 10.0.0.0/8
25942
25943 (Once a condition has failed, no further conditions or modifiers are
25944 processed.)
25945
25946 For ACLs that are triggered by SMTP commands, the message is returned as
25947 part of the SMTP response. The use of message with accept (or discard) is
25948 meaningful only for SMTP, as no message is returned when a non-SMTP message
25949 is accepted. In the case of the connect ACL, accepting with a message
25950 modifier overrides the value of smtp_banner. For the EHLO/HELO ACL, a
25951 customized accept message may not contain more than one line (otherwise it
25952 will be truncated at the first newline and a panic logged), and it cannot
25953 affect the EHLO options.
25954
25955 When SMTP is involved, the message may begin with an overriding response
25956 code, consisting of three digits optionally followed by an "extended
25957 response code" of the form n.n.n, each code being followed by a space. For
25958 example:
25959
25960 deny message = 599 1.2.3 Host not welcome
25961 hosts = 192.168.34.0/24
25962
25963 The first digit of the supplied response code must be the same as would be
25964 sent by default. A panic occurs if it is not. Exim uses a 550 code when it
25965 denies access, but for the predata ACL, note that the default success code
25966 is 354, not 2xx.
25967
25968 Notwithstanding the previous paragraph, for the QUIT ACL, unlike the
25969 others, the message modifier cannot override the 221 response code.
25970
25971 The text in a message modifier is literal; any quotes are taken as
25972 literals, but because the string is expanded, backslash escapes are
25973 processed anyway. If the message contains newlines, this gives rise to a
25974 multi-line SMTP response.
25975
25976 If message is used on a statement that verifies an address, the message
25977 specified overrides any message that is generated by the verification
25978 process. However, the original message is available in the variable
25979 $acl_verify_message, so you can incorporate it into your message if you
25980 wish. In particular, if you want the text from :fail: items in redirect
25981 routers to be passed back as part of the SMTP response, you should either
25982 not use a message modifier, or make use of $acl_verify_message.
25983
25984 For compatibility with previous releases of Exim, a message modifier that
25985 is used with a warn verb behaves in a similar way to the add_header
25986 modifier, but this usage is now deprecated. However, message acts only when
25987 all the conditions are true, wherever it appears in an ACL command, whereas
25988 add_header acts as soon as it is encountered. If message is used with warn
25989 in an ACL that is not concerned with receiving a message, it has no effect.
25990
25991 remove_header = <text>
25992
25993 This modifier specifies one or more header names in a colon-separated list
25994 that are to be removed from an incoming message, assuming, of course, that
25995 the message is ultimately accepted. For details, see section 42.25.
25996
25997 set <acl_name> = <value>
25998
25999 This modifier puts a value into one of the ACL variables (see section 42.19
26000 ).
26001
26002 udpsend = <parameters>
26003
26004 This modifier sends a UDP packet, for purposes such as statistics
26005 collection or behaviour monitoring. The parameters are expanded, and the
26006 result of the expansion must be a colon-separated list consisting of a
26007 destination server, port number, and the packet contents. The server can be
26008 specified as a host name or IPv4 or IPv6 address. The separator can be
26009 changed with the usual angle bracket syntax. For example, you might want to
26010 collect information on which hosts connect when:
26011
26012 udpsend = <; 2001:dB8::dead:beef ; 1234 ;\
26013 $tod_zulu $sender_host_address
26014
26015
26016 42.22 Use of the control modifier
26017 ---------------------------------
26018
26019 The control modifier supports the following settings:
26020
26021 control = allow_auth_unadvertised
26022
26023 This modifier allows a client host to use the SMTP AUTH command even when
26024 it has not been advertised in response to EHLO. Furthermore, because there
26025 are apparently some really broken clients that do this, Exim will accept
26026 AUTH after HELO (rather than EHLO) when this control is set. It should be
26027 used only if you really need it, and you should limit its use to those
26028 broken clients that do not work without it. For example:
26029
26030 warn hosts = 192.168.34.25
26031 control = allow_auth_unadvertised
26032
26033 Normally, when an Exim server receives an AUTH command, it checks the name
26034 of the authentication mechanism that is given in the command to ensure that
26035 it matches an advertised mechanism. When this control is set, the check
26036 that a mechanism has been advertised is bypassed. Any configured mechanism
26037 can be used by the client. This control is permitted only in the connection
26038 and HELO ACLs.
26039
26040 control = caseful_local_part, control = caselower_local_part
26041
26042 These two controls are permitted only in the ACL specified by acl_smtp_rcpt
26043 (that is, during RCPT processing). By default, the contents of $local_part
26044 are lower cased before ACL processing. If "caseful_local_part" is
26045 specified, any uppercase letters in the original local part are restored in
26046 $local_part for the rest of the ACL, or until a control that sets
26047 "caselower_local_part" is encountered.
26048
26049 These controls affect only the current recipient. Moreover, they apply only
26050 to local part handling that takes place directly in the ACL (for example,
26051 as a key in lookups). If a test to verify the recipient is obeyed, the
26052 case-related handling of the local part during the verification is
26053 controlled by the router configuration (see the caseful_local_part generic
26054 router option).
26055
26056 This facility could be used, for example, to add a spam score to local
26057 parts containing upper case letters. For example, using $acl_m4 to
26058 accumulate the spam score:
26059
26060 warn control = caseful_local_part
26061 set acl_m4 = ${eval:\
26062 $acl_m4 + \
26063 ${if match{$local_part}{[A-Z]}{1}{0}}\
26064 }
26065 control = caselower_local_part
26066
26067 Notice that we put back the lower cased version afterwards, assuming that
26068 is what is wanted for subsequent tests.
26069
26070 control = cutthrough_delivery
26071
26072 This option requests delivery be attempted while the item is being
26073 received. It is usable in the RCPT ACL and valid only for single-recipient
26074 mails forwarded from one SMTP connection to another. If a recipient-verify
26075 callout connection is requested in the same ACL it is held open and used
26076 for the data, otherwise one is made after the ACL completes.
26077
26078 Note that routers are used in verify mode, and cannot depend on content of
26079 received headers. Note also that headers cannot be modified by any of the
26080 post-data ACLs (DATA, MIME and DKIM). Headers may be modified by routers
26081 (subject to the above) and transports.
26082
26083 Cutthrough delivery is not supported via transport-filters or when DKIM
26084 signing of outgoing messages is done, because it sends data to the ultimate
26085 destination before the entire message has been received from the source.
26086
26087 Should the ultimate destination system positively accept or reject the
26088 mail, a corresponding indication is given to the source system and nothing
26089 is queued. If there is a temporary error the item is queued for later
26090 delivery in the usual fashion. If the item is successfully delivered in
26091 cutthrough mode the log line is tagged with ">>" rather than "=>" and
26092 appears before the acceptance "<=" line.
26093
26094 Delivery in this mode avoids the generation of a bounce mail to a (possibly
26095 faked) sender when the destination system is doing content-scan based
26096 rejection.
26097
26098 control = debug/<options>
26099
26100 This control turns on debug logging, almost as though Exim had been invoked
26101 with "-d", with the output going to a new logfile, by default called
26102 debuglog. The filename can be adjusted with the tag option, which may
26103 access any variables already defined. The logging may be adjusted with the
26104 opts option, which takes the same values as the "-d" command-line option.
26105 Some examples (which depend on variables that don't exist in all contexts):
26106
26107 control = debug
26108 control = debug/tag=.$sender_host_address
26109 control = debug/opts=+expand+acl
26110 control = debug/tag=.$message_exim_id/opts=+expand
26111
26112 control = dkim_disable_verify
26113
26114 This control turns off DKIM verification processing entirely. For details
26115 on the operation and configuration of DKIM, see chapter 56.
26116
26117 control = dscp/<value>
26118
26119 This option causes the DSCP value associated with the socket for the
26120 inbound connection to be adjusted to a given value, given as one of a
26121 number of fixed strings or to numeric value. The -bI:dscp option may be
26122 used to ask Exim which names it knows of. Common values include
26123 "throughput", "mincost", and on newer systems "ef", "af41", etc. Numeric
26124 values may be in the range 0 to 0x3F.
26125
26126 The outbound packets from Exim will be marked with this value in the header
26127 (for IPv4, the TOS field; for IPv6, the TCLASS field); there is no
26128 guarantee that these values will have any effect, not be stripped by
26129 networking equipment, or do much of anything without cooperation with your
26130 Network Engineer and those of all network operators between the source and
26131 destination.
26132
26133 control = enforce_sync, control = no_enforce_sync
26134
26135 These controls make it possible to be selective about when SMTP
26136 synchronization is enforced. The global option smtp_enforce_sync specifies
26137 the initial state of the switch (it is true by default). See the
26138 description of this option in chapter 14 for details of SMTP
26139 synchronization checking.
26140
26141 The effect of these two controls lasts for the remainder of the SMTP
26142 connection. They can appear in any ACL except the one for the non-SMTP
26143 messages. The most straightforward place to put them is in the ACL defined
26144 by acl_smtp_connect, which is run at the start of an incoming SMTP
26145 connection, before the first synchronization check. The expected use is to
26146 turn off the synchronization checks for badly-behaved hosts that you
26147 nevertheless need to work with.
26148
26149 control = fakedefer/<message>
26150
26151 This control works in exactly the same way as fakereject (described below)
26152 except that it causes an SMTP 450 response after the message data instead
26153 of a 550 response. You must take care when using fakedefer because it
26154 causes the messages to be duplicated when the sender retries. Therefore,
26155 you should not use fakedefer if the message is to be delivered normally.
26156
26157 control = fakereject/<message>
26158
26159 This control is permitted only for the MAIL, RCPT, and DATA ACLs, in other
26160 words, only when an SMTP message is being received. If Exim accepts the
26161 message, instead the final 250 response, a 550 rejection message is sent.
26162 However, Exim proceeds to deliver the message as normal. The control
26163 applies only to the current message, not to any subsequent ones that may be
26164 received in the same SMTP connection.
26165
26166 The text for the 550 response is taken from the control modifier. If no
26167 message is supplied, the following is used:
26168
26169 550-Your message has been rejected but is being
26170 550-kept for evaluation.
26171 550-If it was a legitimate message, it may still be
26172 550 delivered to the target recipient(s).
26173
26174 This facility should be used with extreme caution.
26175
26176 control = freeze
26177
26178 This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs,
26179 in other words, only when a message is being received. If the message is
26180 accepted, it is placed on Exim's queue and frozen. The control applies only
26181 to the current message, not to any subsequent ones that may be received in
26182 the same SMTP connection.
26183
26184 This modifier can optionally be followed by "/no_tell". If the global
26185 option freeze_tell is set, it is ignored for the current message (that is,
26186 nobody is told about the freezing), provided all the control=freeze
26187 modifiers that are obeyed for the current message have the "/no_tell"
26188 option.
26189
26190 control = no_delay_flush
26191
26192 Exim normally flushes SMTP output before implementing a delay in an ACL, to
26193 avoid unexpected timeouts in clients when the SMTP PIPELINING extension is
26194 in use. This control, as long as it is encountered before the delay
26195 modifier, disables such output flushing.
26196
26197 control = no_callout_flush
26198
26199 Exim normally flushes SMTP output before performing a callout in an ACL, to
26200 avoid unexpected timeouts in clients when the SMTP PIPELINING extension is
26201 in use. This control, as long as it is encountered before the verify
26202 condition that causes the callout, disables such output flushing.
26203
26204 control = no_mbox_unspool
26205
26206 This control is available when Exim is compiled with the content scanning
26207 extension. Content scanning may require a copy of the current message, or
26208 parts of it, to be written in "mbox format" to a spool file, for passing to
26209 a virus or spam scanner. Normally, such copies are deleted when they are no
26210 longer needed. If this control is set, the copies are not deleted. The
26211 control applies only to the current message, not to any subsequent ones
26212 that may be received in the same SMTP connection. It is provided for
26213 debugging purposes and is unlikely to be useful in production.
26214
26215 control = no_multiline_responses
26216
26217 This control is permitted for any ACL except the one for non-SMTP messages.
26218 It seems that there are broken clients in use that cannot handle multiline
26219 SMTP responses, despite the fact that RFC 821 defined them over 20 years
26220 ago.
26221
26222 If this control is set, multiline SMTP responses from ACL rejections are
26223 suppressed. One way of doing this would have been to put out these
26224 responses as one long line. However, RFC 2821 specifies a maximum of 512
26225 bytes per response ("use multiline responses for more" it says - ha!), and
26226 some of the responses might get close to that. So this facility, which is
26227 after all only a sop to broken clients, is implemented by doing two very
26228 easy things:
26229
26230 * Extra information that is normally output as part of a rejection caused
26231 by sender verification failure is omitted. Only the final line
26232 (typically "sender verification failed") is sent.
26233
26234 * If a message modifier supplies a multiline response, only the first
26235 line is output.
26236
26237 The setting of the switch can, of course, be made conditional on the
26238 calling host. Its effect lasts until the end of the SMTP connection.
26239
26240 control = no_pipelining
26241
26242 This control turns off the advertising of the PIPELINING extension to SMTP
26243 in the current session. To be useful, it must be obeyed before Exim sends
26244 its response to an EHLO command. Therefore, it should normally appear in an
26245 ACL controlled by acl_smtp_connect or acl_smtp_helo. See also
26246 pipelining_advertise_hosts.
26247
26248 control = queue_only
26249
26250 This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs,
26251 in other words, only when a message is being received. If the message is
26252 accepted, it is placed on Exim's queue and left there for delivery by a
26253 subsequent queue runner. No immediate delivery process is started. In other
26254 words, it has the effect as the queue_only global option. However, the
26255 control applies only to the current message, not to any subsequent ones
26256 that may be received in the same SMTP connection.
26257
26258 control = submission/<options>
26259
26260 This control is permitted only for the MAIL, RCPT, and start of data ACLs
26261 (the latter is the one defined by acl_smtp_predata). Setting it tells Exim
26262 that the current message is a submission from a local MUA. In this case,
26263 Exim operates in "submission mode", and applies certain fixups to the
26264 message if necessary. For example, it adds a Date: header line if one is
26265 not present. This control is not permitted in the acl_smtp_data ACL,
26266 because that is too late (the message has already been created).
26267
26268 Chapter 46 describes the processing that Exim applies to messages. Section
26269 46.1 covers the processing that happens in submission mode; the available
26270 options for this control are described there. The control applies only to
26271 the current message, not to any subsequent ones that may be received in the
26272 same SMTP connection.
26273
26274 control = suppress_local_fixups
26275
26276 This control applies to locally submitted (non TCP/IP) messages, and is the
26277 complement of "control = submission". It disables the fixups that are
26278 normally applied to locally-submitted messages. Specifically:
26279
26280 * Any Sender: header line is left alone (in this respect, it is a dynamic
26281 version of local_sender_retain).
26282
26283 * No Message-ID:, From:, or Date: header lines are added.
26284
26285 * There is no check that From: corresponds to the actual sender.
26286
26287 This control may be useful when a remotely-originated message is accepted,
26288 passed to some scanning program, and then re-submitted for delivery. It can
26289 be used only in the acl_smtp_mail, acl_smtp_rcpt, acl_smtp_predata, and
26290 acl_not_smtp_start ACLs, because it has to be set before the message's data
26291 is read.
26292
26293 Note: This control applies only to the current message, not to any others
26294 that are being submitted at the same time using -bs or -bS.
26295
26296
26297 42.23 Summary of message fixup control
26298 --------------------------------------
26299
26300 All four possibilities for message fixups can be specified:
26301
26302 * Locally submitted, fixups applied: the default.
26303
26304 * Locally submitted, no fixups applied: use "control =
26305 suppress_local_fixups".
26306
26307 * Remotely submitted, no fixups applied: the default.
26308
26309 * Remotely submitted, fixups applied: use "control = submission".
26310
26311
26312 42.24 Adding header lines in ACLs
26313 ---------------------------------
26314
26315 The add_header modifier can be used to add one or more extra header lines to an
26316 incoming message, as in this example:
26317
26318 warn dnslists = sbl.spamhaus.org : \
26319 dialup.mail-abuse.org
26320 add_header = X-blacklisted-at: $dnslist_domain
26321
26322 The add_header modifier is permitted in the MAIL, RCPT, PREDATA, DATA, MIME,
26323 DKIM, and non-SMTP ACLs (in other words, those that are concerned with
26324 receiving a message). The message must ultimately be accepted for add_header to
26325 have any significant effect. You can use add_header with any ACL verb,
26326 including deny (though this is potentially useful only in a RCPT ACL).
26327
26328 Headers will not be added to the message if the modifier is used in DATA, MIME
26329 or DKIM ACLs for messages delivered by cutthrough routing.
26330
26331 Leading and trailing newlines are removed from the data for the add_header
26332 modifier; if it then contains one or more newlines that are not followed by a
26333 space or a tab, it is assumed to contain multiple header lines. Each one is
26334 checked for valid syntax; "X-ACL-Warn:" is added to the front of any line that
26335 is not a valid header line.
26336
26337 Added header lines are accumulated during the MAIL, RCPT, and predata ACLs.
26338 They are added to the message before processing the DATA and MIME ACLs.
26339 However, if an identical header line is requested more than once, only one copy
26340 is actually added to the message. Further header lines may be accumulated
26341 during the DATA and MIME ACLs, after which they are added to the message, again
26342 with duplicates suppressed. Thus, it is possible to add two identical header
26343 lines to an SMTP message, but only if one is added before DATA and one after.
26344 In the case of non-SMTP messages, new headers are accumulated during the
26345 non-SMTP ACLs, and are added to the message after all the ACLs have run. If a
26346 message is rejected after DATA or by the non-SMTP ACL, all added header lines
26347 are included in the entry that is written to the reject log.
26348
26349 Header lines are not visible in string expansions of message headers until they
26350 are added to the message. It follows that header lines defined in the MAIL,
26351 RCPT, and predata ACLs are not visible until the DATA ACL and MIME ACLs are
26352 run. Similarly, header lines that are added by the DATA or MIME ACLs are not
26353 visible in those ACLs. Because of this restriction, you cannot use header lines
26354 as a way of passing data between (for example) the MAIL and RCPT ACLs. If you
26355 want to do this, you can use ACL variables, as described in section 42.19.
26356
26357 The list of headers yet to be added is given by the $headers_added variable.
26358
26359 The add_header modifier acts immediately as it is encountered during the
26360 processing of an ACL. Notice the difference between these two cases:
26361
26362 accept add_header = ADDED: some text
26363 <some condition>
26364
26365 accept <some condition>
26366 add_header = ADDED: some text
26367
26368 In the first case, the header line is always added, whether or not the
26369 condition is true. In the second case, the header line is added only if the
26370 condition is true. Multiple occurrences of add_header may occur in the same ACL
26371 statement. All those that are encountered before a condition fails are
26372 honoured.
26373
26374 For compatibility with previous versions of Exim, a message modifier for a warn
26375 verb acts in the same way as add_header, except that it takes effect only if
26376 all the conditions are true, even if it appears before some of them.
26377 Furthermore, only the last occurrence of message is honoured. This usage of
26378 message is now deprecated. If both add_header and message are present on a warn
26379 verb, both are processed according to their specifications.
26380
26381 By default, new header lines are added to a message at the end of the existing
26382 header lines. However, you can specify that any particular header line should
26383 be added right at the start (before all the Received: lines), immediately after
26384 the first block of Received: lines, or immediately before any line that is not
26385 a Received: or Resent-something: header.
26386
26387 This is done by specifying ":at_start:", ":after_received:", or
26388 ":at_start_rfc:" (or, for completeness, ":at_end:") before the text of the
26389 header line, respectively. (Header text cannot start with a colon, as there has
26390 to be a header name first.) For example:
26391
26392 warn add_header = \
26393 :after_received:X-My-Header: something or other...
26394
26395 If more than one header line is supplied in a single add_header modifier, each
26396 one is treated independently and can therefore be placed differently. If you
26397 add more than one line at the start, or after the Received: block, they end up
26398 in reverse order.
26399
26400 Warning: This facility currently applies only to header lines that are added in
26401 an ACL. It does NOT work for header lines that are added in a system filter or
26402 in a router or transport.
26403
26404
26405 42.25 Removing header lines in ACLs
26406 -----------------------------------
26407
26408 The remove_header modifier can be used to remove one or more header lines from
26409 an incoming message, as in this example:
26410
26411 warn message = Remove internal headers
26412 remove_header = x-route-mail1 : x-route-mail2
26413
26414 The remove_header modifier is permitted in the MAIL, RCPT, PREDATA, DATA, MIME,
26415 DKIM, and non-SMTP ACLs (in other words, those that are concerned with
26416 receiving a message). The message must ultimately be accepted for remove_header
26417 to have any significant effect. You can use remove_header with any ACL verb,
26418 including deny, though this is really not useful for any verb that doesn't
26419 result in a delivered message.
26420
26421 Headers will not be removed to the message if the modifier is used in DATA,
26422 MIME or DKIM ACLs for messages delivered by cutthrough routing.
26423
26424 More than one header can be removed at the same time by using a colon separated
26425 list of header names. The header matching is case insensitive. Wildcards are
26426 not permitted, nor is list expansion performed, so you cannot use hostlists to
26427 create a list of headers, however both connection and message variable
26428 expansion are performed ($acl_c_* and $acl_m_*), illustrated in this example:
26429
26430 warn hosts = +internal_hosts
26431 set acl_c_ihdrs = x-route-mail1 : x-route-mail2
26432 warn message = Remove internal headers
26433 remove_header = $acl_c_ihdrs
26434
26435 Removed header lines are accumulated during the MAIL, RCPT, and predata ACLs.
26436 They are removed from the message before processing the DATA and MIME ACLs.
26437 There is no harm in attempting to remove the same header twice nor is removing
26438 a non-existent header. Further header lines to be removed may be accumulated
26439 during the DATA and MIME ACLs, after which they are removed from the message,
26440 if present. In the case of non-SMTP messages, headers to be removed are
26441 accumulated during the non-SMTP ACLs, and are removed from the message after
26442 all the ACLs have run. If a message is rejected after DATA or by the non-SMTP
26443 ACL, there really is no effect because there is no logging of what headers
26444 would have been removed.
26445
26446 Header lines are not visible in string expansions until the DATA phase when it
26447 is received. Any header lines removed in the MAIL, RCPT, and predata ACLs are
26448 not visible in the DATA ACL and MIME ACLs. Similarly, header lines that are
26449 removed by the DATA or MIME ACLs are still visible in those ACLs. Because of
26450 this restriction, you cannot use header lines as a way of controlling data
26451 passed between (for example) the MAIL and RCPT ACLs. If you want to do this,
26452 you should instead use ACL variables, as described in section 42.19.
26453
26454 The remove_header modifier acts immediately as it is encountered during the
26455 processing of an ACL. Notice the difference between these two cases:
26456
26457 accept remove_header = X-Internal
26458 <some condition>
26459
26460 accept <some condition>
26461 remove_header = X-Internal
26462
26463 In the first case, the header line is always removed, whether or not the
26464 condition is true. In the second case, the header line is removed only if the
26465 condition is true. Multiple occurrences of remove_header may occur in the same
26466 ACL statement. All those that are encountered before a condition fails are
26467 honoured.
26468
26469 Warning: This facility currently applies only to header lines that are present
26470 during ACL processing. It does NOT remove header lines that are added in a
26471 system filter or in a router or transport.
26472
26473
26474 42.26 ACL conditions
26475 --------------------
26476
26477 Some of the conditions listed in this section are available only when Exim is
26478 compiled with the content-scanning extension. They are included here briefly
26479 for completeness. More detailed descriptions can be found in the discussion on
26480 content scanning in chapter 43.
26481
26482 Not all conditions are relevant in all circumstances. For example, testing
26483 senders and recipients does not make sense in an ACL that is being run as the
26484 result of the arrival of an ETRN command, and checks on message headers can be
26485 done only in the ACLs specified by acl_smtp_data and acl_not_smtp. You can use
26486 the same condition (with different parameters) more than once in the same ACL
26487 statement. This provides a way of specifying an "and" conjunction. The
26488 conditions are as follows:
26489
26490 acl = <name of acl or ACL string or file name >
26491
26492 The possible values of the argument are the same as for the acl_smtp_xxx
26493 options. The named or inline ACL is run. If it returns "accept" the
26494 condition is true; if it returns "deny" the condition is false. If it
26495 returns "defer", the current ACL returns "defer" unless the condition is on
26496 a warn verb. In that case, a "defer" return makes the condition false. This
26497 means that further processing of the warn verb ceases, but processing of
26498 the ACL continues.
26499
26500 If the argument is a named ACL, up to nine space-separated optional values
26501 can be appended; they appear within the called ACL in $acl_arg1 to
26502 $acl_arg9, and $acl_narg is set to the count of values. Previous values of
26503 these variables are restored after the call returns. The name and values
26504 are expanded separately.
26505
26506 If the nested acl returns "drop" and the outer condition denies access, the
26507 connection is dropped. If it returns "discard", the verb must be accept or
26508 discard, and the action is taken immediately - no further conditions are
26509 tested.
26510
26511 ACLs may be nested up to 20 deep; the limit exists purely to catch runaway
26512 loops. This condition allows you to use different ACLs in different
26513 circumstances. For example, different ACLs can be used to handle RCPT
26514 commands for different local users or different local domains.
26515
26516 authenticated = <string list>
26517
26518 If the SMTP connection is not authenticated, the condition is false.
26519 Otherwise, the name of the authenticator is tested against the list. To
26520 test for authentication by any authenticator, you can set
26521
26522 authenticated = *
26523
26524 condition = <string>
26525
26526 This feature allows you to make up custom conditions. If the result of
26527 expanding the string is an empty string, the number zero, or one of the
26528 strings "no" or "false", the condition is false. If the result is any
26529 non-zero number, or one of the strings "yes" or "true", the condition is
26530 true. For any other value, some error is assumed to have occurred, and the
26531 ACL returns "defer". However, if the expansion is forced to fail, the
26532 condition is ignored. The effect is to treat it as true, whether it is
26533 positive or negative.
26534
26535 decode = <location>
26536
26537 This condition is available only when Exim is compiled with the
26538 content-scanning extension, and it is allowed only in the ACL defined by
26539 acl_smtp_mime. It causes the current MIME part to be decoded into a file.
26540 If all goes well, the condition is true. It is false only if there are
26541 problems such as a syntax error or a memory shortage. For more details, see
26542 chapter 43.
26543
26544 demime = <extension list>
26545
26546 This condition is available only when Exim is compiled with the
26547 content-scanning extension. Its use is described in section 43.6.
26548
26549 dnslists = <list of domain names and other data>
26550
26551 This condition checks for entries in DNS black lists. These are also known
26552 as "RBL lists", after the original Realtime Blackhole List, but note that
26553 the use of the lists at mail-abuse.org now carries a charge. There are too
26554 many different variants of this condition to describe briefly here. See
26555 sections 42.27-42.37 for details.
26556
26557 domains = <domain list>
26558
26559 This condition is relevant only after a RCPT command. It checks that the
26560 domain of the recipient address is in the domain list. If percent-hack
26561 processing is enabled, it is done before this test is done. If the check
26562 succeeds with a lookup, the result of the lookup is placed in $domain_data
26563 until the next domains test.
26564
26565 Note carefully (because many people seem to fall foul of this): you cannot
26566 use domains in a DATA ACL.
26567
26568 encrypted = <string list>
26569
26570 If the SMTP connection is not encrypted, the condition is false. Otherwise,
26571 the name of the cipher suite in use is tested against the list. To test for
26572 encryption without testing for any specific cipher suite(s), set
26573
26574 encrypted = *
26575
26576 hosts = <host list>
26577
26578 This condition tests that the calling host matches the host list. If you
26579 have name lookups or wildcarded host names and IP addresses in the same
26580 host list, you should normally put the IP addresses first. For example, you
26581 could have:
26582
26583 accept hosts = 10.9.8.7 : dbm;/etc/friendly/hosts
26584
26585 The lookup in this example uses the host name for its key. This is implied
26586 by the lookup type "dbm". (For a host address lookup you would use
26587 "net-dbm" and it wouldn't matter which way round you had these two items.)
26588
26589 The reason for the problem with host names lies in the left-to-right way
26590 that Exim processes lists. It can test IP addresses without doing any DNS
26591 lookups, but when it reaches an item that requires a host name, it fails if
26592 it cannot find a host name to compare with the pattern. If the above list
26593 is given in the opposite order, the accept statement fails for a host whose
26594 name cannot be found, even if its IP address is 10.9.8.7.
26595
26596 If you really do want to do the name check first, and still recognize the
26597 IP address even if the name lookup fails, you can rewrite the ACL like
26598 this:
26599
26600 accept hosts = dbm;/etc/friendly/hosts
26601 accept hosts = 10.9.8.7
26602
26603 The default action on failing to find the host name is to assume that the
26604 host is not in the list, so the first accept statement fails. The second
26605 statement can then check the IP address.
26606
26607 If a hosts condition is satisfied by means of a lookup, the result of the
26608 lookup is made available in the $host_data variable. This allows you, for
26609 example, to set up a statement like this:
26610
26611 deny hosts = net-lsearch;/some/file
26612 message = $host_data
26613
26614 which gives a custom error message for each denied host.
26615
26616 local_parts = <local part list>
26617
26618 This condition is relevant only after a RCPT command. It checks that the
26619 local part of the recipient address is in the list. If percent-hack
26620 processing is enabled, it is done before this test. If the check succeeds
26621 with a lookup, the result of the lookup is placed in $local_part_data,
26622 which remains set until the next local_parts test.
26623
26624 malware = <option>
26625
26626 This condition is available only when Exim is compiled with the
26627 content-scanning extension. It causes the incoming message to be scanned
26628 for viruses. For details, see chapter 43.
26629
26630 mime_regex = <list of regular expressions>
26631
26632 This condition is available only when Exim is compiled with the
26633 content-scanning extension, and it is allowed only in the ACL defined by
26634 acl_smtp_mime. It causes the current MIME part to be scanned for a match
26635 with any of the regular expressions. For details, see chapter 43.
26636
26637 ratelimit = <parameters>
26638
26639 This condition can be used to limit the rate at which a user or host
26640 submits messages. Details are given in section 42.38.
26641
26642 recipients = <address list>
26643
26644 This condition is relevant only after a RCPT command. It checks the entire
26645 recipient address against a list of recipients.
26646
26647 regex = <list of regular expressions>
26648
26649 This condition is available only when Exim is compiled with the
26650 content-scanning extension, and is available only in the DATA, MIME, and
26651 non-SMTP ACLs. It causes the incoming message to be scanned for a match
26652 with any of the regular expressions. For details, see chapter 43.
26653
26654 sender_domains = <domain list>
26655
26656 This condition tests the domain of the sender of the message against the
26657 given domain list. Note: The domain of the sender address is in
26658 $sender_address_domain. It is not put in $domain during the testing of this
26659 condition. This is an exception to the general rule for testing domain
26660 lists. It is done this way so that, if this condition is used in an ACL for
26661 a RCPT command, the recipient's domain (which is in $domain) can be used to
26662 influence the sender checking.
26663
26664 Warning: It is a bad idea to use this condition on its own as a control on
26665 relaying, because sender addresses are easily, and commonly, forged.
26666
26667 senders = <address list>
26668
26669 This condition tests the sender of the message against the given list. To
26670 test for a bounce message, which has an empty sender, set
26671
26672 senders = :
26673
26674 Warning: It is a bad idea to use this condition on its own as a control on
26675 relaying, because sender addresses are easily, and commonly, forged.
26676
26677 spam = <username>
26678
26679 This condition is available only when Exim is compiled with the
26680 content-scanning extension. It causes the incoming message to be scanned by
26681 SpamAssassin. For details, see chapter 43.
26682
26683 verify = certificate
26684
26685 This condition is true in an SMTP session if the session is encrypted, and
26686 a certificate was received from the client, and the certificate was
26687 verified. The server requests a certificate only if the client matches
26688 tls_verify_hosts or tls_try_verify_hosts (see chapter 41).
26689
26690 verify = csa
26691
26692 This condition checks whether the sending host (the client) is authorized
26693 to send email. Details of how this works are given in section 42.50.
26694
26695 verify = header_names_ascii
26696
26697 This condition is relevant only in an ACL that is run after a message has
26698 been received, that is, in an ACL specified by acl_smtp_data or
26699 acl_not_smtp. It checks all header names (not the content) to make sure
26700 there are no non-ASCII characters, also excluding control characters. The
26701 allowable characters are decimal ASCII values 33 through 126.
26702
26703 Exim itself will handle headers with non-ASCII characters, but it can cause
26704 problems for downstream applications, so this option will allow their
26705 detection and rejection in the DATA ACL's.
26706
26707 verify = header_sender/<options>
26708
26709 This condition is relevant only in an ACL that is run after a message has
26710 been received, that is, in an ACL specified by acl_smtp_data or
26711 acl_not_smtp. It checks that there is a verifiable address in at least one
26712 of the Sender:, Reply-To:, or From: header lines. Such an address is
26713 loosely thought of as a "sender" address (hence the name of the test).
26714 However, an address that appears in one of these headers need not be an
26715 address that accepts bounce messages; only sender addresses in envelopes
26716 are required to accept bounces. Therefore, if you use the callout option on
26717 this check, you might want to arrange for a non-empty address in the MAIL
26718 command.
26719
26720 Details of address verification and the options are given later, starting
26721 at section 42.44 (callouts are described in section 42.45). You can combine
26722 this condition with the senders condition to restrict it to bounce messages
26723 only:
26724
26725 deny senders = :
26726 message = A valid sender header is required for bounces
26727 !verify = header_sender
26728
26729 verify = header_syntax
26730
26731 This condition is relevant only in an ACL that is run after a message has
26732 been received, that is, in an ACL specified by acl_smtp_data or
26733 acl_not_smtp. It checks the syntax of all header lines that can contain
26734 lists of addresses (Sender:, From:, Reply-To:, To:, Cc:, and Bcc:).
26735 Unqualified addresses (local parts without domains) are permitted only in
26736 locally generated messages and from hosts that match
26737 sender_unqualified_hosts or recipient_unqualified_hosts, as appropriate.
26738
26739 Note that this condition is a syntax check only. However, a common spamming
26740 ploy used to be to send syntactically invalid headers such as
26741
26742 To: @
26743
26744 and this condition can be used to reject such messages, though they are not
26745 as common as they used to be.
26746
26747 verify = helo
26748
26749 This condition is true if a HELO or EHLO command has been received from the
26750 client host, and its contents have been verified. If there has been no
26751 previous attempt to verify the HELO/EHLO contents, it is carried out when
26752 this condition is encountered. See the description of the helo_verify_hosts
26753 and helo_try_verify_hosts options for details of how to request
26754 verification independently of this condition.
26755
26756 For SMTP input that does not come over TCP/IP (the -bs command line
26757 option), this condition is always true.
26758
26759 verify = not_blind
26760
26761 This condition checks that there are no blind (bcc) recipients in the
26762 message. Every envelope recipient must appear either in a To: header line
26763 or in a Cc: header line for this condition to be true. Local parts are
26764 checked case-sensitively; domains are checked case-insensitively. If
26765 Resent-To: or Resent-Cc: header lines exist, they are also checked. This
26766 condition can be used only in a DATA or non-SMTP ACL.
26767
26768 There are, of course, many legitimate messages that make use of blind (bcc)
26769 recipients. This check should not be used on its own for blocking messages.
26770
26771 verify = recipient/<options>
26772
26773 This condition is relevant only after a RCPT command. It verifies the
26774 current recipient. Details of address verification are given later,
26775 starting at section 42.44. After a recipient has been verified, the value
26776 of $address_data is the last value that was set while routing the address.
26777 This applies even if the verification fails. When an address that is being
26778 verified is redirected to a single address, verification continues with the
26779 new address, and in that case, the subsequent value of $address_data is the
26780 value for the child address.
26781
26782 verify = reverse_host_lookup
26783
26784 This condition ensures that a verified host name has been looked up from
26785 the IP address of the client host. (This may have happened already if the
26786 host name was needed for checking a host list, or if the host matched
26787 host_lookup.) Verification ensures that the host name obtained from a
26788 reverse DNS lookup, or one of its aliases, does, when it is itself looked
26789 up in the DNS, yield the original IP address.
26790
26791 If this condition is used for a locally generated message (that is, when
26792 there is no client host involved), it always succeeds.
26793
26794 verify = sender/<options>
26795
26796 This condition is relevant only after a MAIL or RCPT command, or after a
26797 message has been received (the acl_smtp_data or acl_not_smtp ACLs). If the
26798 message's sender is empty (that is, this is a bounce message), the
26799 condition is true. Otherwise, the sender address is verified.
26800
26801 If there is data in the $address_data variable at the end of routing, its
26802 value is placed in $sender_address_data at the end of verification. This
26803 value can be used in subsequent conditions and modifiers in the same ACL
26804 statement. It does not persist after the end of the current statement. If
26805 you want to preserve the value for longer, you can save it in an ACL
26806 variable.
26807
26808 Details of verification are given later, starting at section 42.44. Exim
26809 caches the result of sender verification, to avoid doing it more than once
26810 per message.
26811
26812 verify = sender=<address>/<options>
26813
26814 This is a variation of the previous option, in which a modified address is
26815 verified as a sender.
26816
26817
26818 42.27 Using DNS lists
26819 ---------------------
26820
26821 In its simplest form, the dnslists condition tests whether the calling host is
26822 on at least one of a number of DNS lists by looking up the inverted IP address
26823 in one or more DNS domains. (Note that DNS list domains are not mail domains,
26824 so the "+" syntax for named lists doesn't work - it is used for special options
26825 instead.) For example, if the calling host's IP address is 192.168.62.43, and
26826 the ACL statement is
26827
26828 deny dnslists = blackholes.mail-abuse.org : \
26829 dialups.mail-abuse.org
26830
26831 the following records are looked up:
26832
26833 43.62.168.192.blackholes.mail-abuse.org
26834 43.62.168.192.dialups.mail-abuse.org
26835
26836 As soon as Exim finds an existing DNS record, processing of the list stops.
26837 Thus, multiple entries on the list provide an "or" conjunction. If you want to
26838 test that a host is on more than one list (an "and" conjunction), you can use
26839 two separate conditions:
26840
26841 deny dnslists = blackholes.mail-abuse.org
26842 dnslists = dialups.mail-abuse.org
26843
26844 If a DNS lookup times out or otherwise fails to give a decisive answer, Exim
26845 behaves as if the host does not match the list item, that is, as if the DNS
26846 record does not exist. If there are further items in the DNS list, they are
26847 processed.
26848
26849 This is usually the required action when dnslists is used with deny (which is
26850 the most common usage), because it prevents a DNS failure from blocking mail.
26851 However, you can change this behaviour by putting one of the following special
26852 items in the list:
26853
26854 +include_unknown behave as if the item is on the list
26855 +exclude_unknown behave as if the item is not on the list (default)
26856 +defer_unknown give a temporary error
26857
26858 Each of these applies to any subsequent items on the list. For example:
26859
26860 deny dnslists = +defer_unknown : foo.bar.example
26861
26862 Testing the list of domains stops as soon as a match is found. If you want to
26863 warn for one list and block for another, you can use two different statements:
26864
26865 deny dnslists = blackholes.mail-abuse.org
26866 warn message = X-Warn: sending host is on dialups list
26867 dnslists = dialups.mail-abuse.org
26868
26869 DNS list lookups are cached by Exim for the duration of the SMTP session, so a
26870 lookup based on the IP address is done at most once for any incoming
26871 connection. Exim does not share information between multiple incoming
26872 connections (but your local name server cache should be active).
26873
26874
26875 42.28 Specifying the IP address for a DNS list lookup
26876 -----------------------------------------------------
26877
26878 By default, the IP address that is used in a DNS list lookup is the IP address
26879 of the calling host. However, you can specify another IP address by listing it
26880 after the domain name, introduced by a slash. For example:
26881
26882 deny dnslists = black.list.tld/192.168.1.2
26883
26884 This feature is not very helpful with explicit IP addresses; it is intended for
26885 use with IP addresses that are looked up, for example, the IP addresses of the
26886 MX hosts or nameservers of an email sender address. For an example, see section
26887 42.30 below.
26888
26889
26890 42.29 DNS lists keyed on domain names
26891 -------------------------------------
26892
26893 There are some lists that are keyed on domain names rather than inverted IP
26894 addresses (see for example the domain based zones link at http://
26895 www.rfc-ignorant.org/). No reversing of components is used with these lists.
26896 You can change the name that is looked up in a DNS list by listing it after the
26897 domain name, introduced by a slash. For example,
26898
26899 deny message = Sender's domain is listed at $dnslist_domain
26900 dnslists = dsn.rfc-ignorant.org/$sender_address_domain
26901
26902 This particular example is useful only in ACLs that are obeyed after the RCPT
26903 or DATA commands, when a sender address is available. If (for example) the
26904 message's sender is user@tld.example the name that is looked up by this example
26905 is
26906
26907 tld.example.dsn.rfc-ignorant.org
26908
26909 A single dnslists condition can contain entries for both names and IP
26910 addresses. For example:
26911
26912 deny dnslists = sbl.spamhaus.org : \
26913 dsn.rfc-ignorant.org/$sender_address_domain
26914
26915 The first item checks the sending host's IP address; the second checks a domain
26916 name. The whole condition is true if either of the DNS lookups succeeds.
26917
26918
26919 42.30 Multiple explicit keys for a DNS list
26920 -------------------------------------------
26921
26922 The syntax described above for looking up explicitly-defined values (either
26923 names or IP addresses) in a DNS blacklist is a simplification. After the domain
26924 name for the DNS list, what follows the slash can in fact be a list of items.
26925 As with all lists in Exim, the default separator is a colon. However, because
26926 this is a sublist within the list of DNS blacklist domains, it is necessary
26927 either to double the separators like this:
26928
26929 dnslists = black.list.tld/name.1::name.2
26930
26931 or to change the separator character, like this:
26932
26933 dnslists = black.list.tld/<;name.1;name.2
26934
26935 If an item in the list is an IP address, it is inverted before the DNS
26936 blacklist domain is appended. If it is not an IP address, no inversion occurs.
26937 Consider this condition:
26938
26939 dnslists = black.list.tld/<;192.168.1.2;a.domain
26940
26941 The DNS lookups that occur are:
26942
26943 2.1.168.192.black.list.tld
26944 a.domain.black.list.tld
26945
26946 Once a DNS record has been found (that matches a specific IP return address, if
26947 specified - see section 42.33), no further lookups are done. If there is a
26948 temporary DNS error, the rest of the sublist of domains or IP addresses is
26949 tried. A temporary error for the whole dnslists item occurs only if no other
26950 DNS lookup in this sublist succeeds. In other words, a successful lookup for
26951 any of the items in the sublist overrides a temporary error for a previous
26952 item.
26953
26954 The ability to supply a list of items after the slash is in some sense just a
26955 syntactic convenience. These two examples have the same effect:
26956
26957 dnslists = black.list.tld/a.domain : black.list.tld/b.domain
26958 dnslists = black.list.tld/a.domain::b.domain
26959
26960 However, when the data for the list is obtained from a lookup, the second form
26961 is usually much more convenient. Consider this example:
26962
26963 deny message = The mail servers for the domain \
26964 $sender_address_domain \
26965 are listed at $dnslist_domain ($dnslist_value); \
26966 see $dnslist_text.
26967 dnslists = sbl.spamhaus.org/<|${lookup dnsdb {>|a=<|\
26968 ${lookup dnsdb {>|mxh=\
26969 $sender_address_domain} }} }
26970
26971 Note the use of ">|" in the dnsdb lookup to specify the separator for multiple
26972 DNS records. The inner dnsdb lookup produces a list of MX hosts and the outer
26973 dnsdb lookup finds the IP addresses for these hosts. The result of expanding
26974 the condition might be something like this:
26975
26976 dnslists = sbl.spahmaus.org/<|192.168.2.3|192.168.5.6|...
26977
26978 Thus, this example checks whether or not the IP addresses of the sender
26979 domain's mail servers are on the Spamhaus black list.
26980
26981 The key that was used for a successful DNS list lookup is put into the variable
26982 $dnslist_matched (see section 42.32).
26983
26984
26985 42.31 Data returned by DNS lists
26986 --------------------------------
26987
26988 DNS lists are constructed using address records in the DNS. The original RBL
26989 just used the address 127.0.0.1 on the right hand side of each record, but the
26990 RBL+ list and some other lists use a number of values with different meanings.
26991 The values used on the RBL+ list are:
26992
26993 127.1.0.1 RBL
26994 127.1.0.2 DUL
26995 127.1.0.3 DUL and RBL
26996 127.1.0.4 RSS
26997 127.1.0.5 RSS and RBL
26998 127.1.0.6 RSS and DUL
26999 127.1.0.7 RSS and DUL and RBL
27000
27001 Section 42.33 below describes how you can distinguish between different values.
27002 Some DNS lists may return more than one address record; see section 42.35 for
27003 details of how they are checked.
27004
27005
27006 42.32 Variables set from DNS lists
27007 ----------------------------------
27008
27009 When an entry is found in a DNS list, the variable $dnslist_domain contains the
27010 name of the overall domain that matched (for example, "spamhaus.example"),
27011 $dnslist_matched contains the key within that domain (for example,
27012 "192.168.5.3"), and $dnslist_value contains the data from the DNS record. When
27013 the key is an IP address, it is not reversed in $dnslist_matched (though it is,
27014 of course, in the actual lookup). In simple cases, for example:
27015
27016 deny dnslists = spamhaus.example
27017
27018 the key is also available in another variable (in this case,
27019 $sender_host_address). In more complicated cases, however, this is not true.
27020 For example, using a data lookup (as described in section 42.30) might generate
27021 a dnslists lookup like this:
27022
27023 deny dnslists = spamhaus.example/<|192.168.1.2|192.168.6.7|...
27024
27025 If this condition succeeds, the value in $dnslist_matched might be
27026 "192.168.6.7" (for example).
27027
27028 If more than one address record is returned by the DNS lookup, all the IP
27029 addresses are included in $dnslist_value, separated by commas and spaces. The
27030 variable $dnslist_text contains the contents of any associated TXT record. For
27031 lists such as RBL+ the TXT record for a merged entry is often not very
27032 meaningful. See section 42.36 for a way of obtaining more information.
27033
27034 You can use the DNS list variables in message or log_message modifiers -
27035 although these appear before the condition in the ACL, they are not expanded
27036 until after it has failed. For example:
27037
27038 deny hosts = !+local_networks
27039 message = $sender_host_address is listed \
27040 at $dnslist_domain
27041 dnslists = rbl-plus.mail-abuse.example
27042
27043
27044 42.33 Additional matching conditions for DNS lists
27045 --------------------------------------------------
27046
27047 You can add an equals sign and an IP address after a dnslists domain name in
27048 order to restrict its action to DNS records with a matching right hand side.
27049 For example,
27050
27051 deny dnslists = rblplus.mail-abuse.org=127.0.0.2
27052
27053 rejects only those hosts that yield 127.0.0.2. Without this additional data,
27054 any address record is considered to be a match. For the moment, we assume that
27055 the DNS lookup returns just one record. Section 42.35 describes how multiple
27056 records are handled.
27057
27058 More than one IP address may be given for checking, using a comma as a
27059 separator. These are alternatives - if any one of them matches, the dnslists
27060 condition is true. For example:
27061
27062 deny dnslists = a.b.c=127.0.0.2,127.0.0.3
27063
27064 If you want to specify a constraining address list and also specify names or IP
27065 addresses to be looked up, the constraining address list must be specified
27066 first. For example:
27067
27068 deny dnslists = dsn.rfc-ignorant.org\
27069 =127.0.0.2/$sender_address_domain
27070
27071 If the character "&" is used instead of "=", the comparison for each listed IP
27072 address is done by a bitwise "and" instead of by an equality test. In other
27073 words, the listed addresses are used as bit masks. The comparison is true if
27074 all the bits in the mask are present in the address that is being tested. For
27075 example:
27076
27077 dnslists = a.b.c&0.0.0.3
27078
27079 matches if the address is x.x.x.3, x.x.x.7, x.x.x.11, etc. If you want to test
27080 whether one bit or another bit is present (as opposed to both being present),
27081 you must use multiple values. For example:
27082
27083 dnslists = a.b.c&0.0.0.1,0.0.0.2
27084
27085 matches if the final component of the address is an odd number or two times an
27086 odd number.
27087
27088
27089 42.34 Negated DNS matching conditions
27090 -------------------------------------
27091
27092 You can supply a negative list of IP addresses as part of a dnslists condition.
27093 Whereas
27094
27095 deny dnslists = a.b.c=127.0.0.2,127.0.0.3
27096
27097 means "deny if the host is in the black list at the domain a.b.c and the IP
27098 address yielded by the list is either 127.0.0.2 or 127.0.0.3",
27099
27100 deny dnslists = a.b.c!=127.0.0.2,127.0.0.3
27101
27102 means "deny if the host is in the black list at the domain a.b.c and the IP
27103 address yielded by the list is not 127.0.0.2 and not 127.0.0.3". In other
27104 words, the result of the test is inverted if an exclamation mark appears before
27105 the "=" (or the "&") sign.
27106
27107 Note: This kind of negation is not the same as negation in a domain, host, or
27108 address list (which is why the syntax is different).
27109
27110 If you are using just one list, the negation syntax does not gain you much. The
27111 previous example is precisely equivalent to
27112
27113 deny dnslists = a.b.c
27114 !dnslists = a.b.c=127.0.0.2,127.0.0.3
27115
27116 However, if you are using multiple lists, the negation syntax is clearer.
27117 Consider this example:
27118
27119 deny dnslists = sbl.spamhaus.org : \
27120 list.dsbl.org : \
27121 dnsbl.njabl.org!=127.0.0.3 : \
27122 relays.ordb.org
27123
27124 Using only positive lists, this would have to be:
27125
27126 deny dnslists = sbl.spamhaus.org : \
27127 list.dsbl.org
27128 deny dnslists = dnsbl.njabl.org
27129 !dnslists = dnsbl.njabl.org=127.0.0.3
27130 deny dnslists = relays.ordb.org
27131
27132 which is less clear, and harder to maintain.
27133
27134
27135 42.35 Handling multiple DNS records from a DNS list
27136 ---------------------------------------------------
27137
27138 A DNS lookup for a dnslists condition may return more than one DNS record,
27139 thereby providing more than one IP address. When an item in a dnslists list is
27140 followed by "=" or "&" and a list of IP addresses, in order to restrict the
27141 match to specific results from the DNS lookup, there are two ways in which the
27142 checking can be handled. For example, consider the condition:
27143
27144 dnslists = a.b.c=127.0.0.1
27145
27146 What happens if the DNS lookup for the incoming IP address yields both
27147 127.0.0.1 and 127.0.0.2 by means of two separate DNS records? Is the condition
27148 true because at least one given value was found, or is it false because at
27149 least one of the found values was not listed? And how does this affect negated
27150 conditions? Both possibilities are provided for with the help of additional
27151 separators "==" and "=&".
27152
27153 * If "=" or "&" is used, the condition is true if any one of the looked up IP
27154 addresses matches one of the listed addresses. For the example above, the
27155 condition is true because 127.0.0.1 matches.
27156
27157 * If "==" or "=&" is used, the condition is true only if every one of the
27158 looked up IP addresses matches one of the listed addresses. If the
27159 condition is changed to:
27160
27161 dnslists = a.b.c==127.0.0.1
27162
27163 and the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is
27164 false because 127.0.0.2 is not listed. You would need to have:
27165
27166 dnslists = a.b.c==127.0.0.1,127.0.0.2
27167
27168 for the condition to be true.
27169
27170 When "!" is used to negate IP address matching, it inverts the result, giving
27171 the precise opposite of the behaviour above. Thus:
27172
27173 * If "!=" or "!&" is used, the condition is true if none of the looked up IP
27174 addresses matches one of the listed addresses. Consider:
27175
27176 dnslists = a.b.c!&0.0.0.1
27177
27178 If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is
27179 false because 127.0.0.1 matches.
27180
27181 * If "!==" or "!=&" is used, the condition is true if there is at least one
27182 looked up IP address that does not match. Consider:
27183
27184 dnslists = a.b.c!=&0.0.0.1
27185
27186 If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is
27187 true, because 127.0.0.2 does not match. You would need to have:
27188
27189 dnslists = a.b.c!=&0.0.0.1,0.0.0.2
27190
27191 for the condition to be false.
27192
27193 When the DNS lookup yields only a single IP address, there is no difference
27194 between "=" and "==" and between "&" and "=&".
27195
27196
27197 42.36 Detailed information from merged DNS lists
27198 ------------------------------------------------
27199
27200 When the facility for restricting the matching IP values in a DNS list is used,
27201 the text from the TXT record that is set in $dnslist_text may not reflect the
27202 true reason for rejection. This happens when lists are merged and the IP
27203 address in the A record is used to distinguish them; unfortunately there is
27204 only one TXT record. One way round this is not to use merged lists, but that
27205 can be inefficient because it requires multiple DNS lookups where one would do
27206 in the vast majority of cases when the host of interest is not on any of the
27207 lists.
27208
27209 A less inefficient way of solving this problem is available. If two domain
27210 names, comma-separated, are given, the second is used first to do an initial
27211 check, making use of any IP value restrictions that are set. If there is a
27212 match, the first domain is used, without any IP value restrictions, to get the
27213 TXT record. As a byproduct of this, there is also a check that the IP being
27214 tested is indeed on the first list. The first domain is the one that is put in
27215 $dnslist_domain. For example:
27216
27217 reject message = \
27218 rejected because $sender_host_address is blacklisted \
27219 at $dnslist_domain\n$dnslist_text
27220 dnslists = \
27221 sbl.spamhaus.org,sbl-xbl.spamhaus.org=127.0.0.2 : \
27222 dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10
27223
27224 For the first blacklist item, this starts by doing a lookup in
27225 sbl-xbl.spamhaus.org and testing for a 127.0.0.2 return. If there is a match,
27226 it then looks in sbl.spamhaus.org, without checking the return value, and as
27227 long as something is found, it looks for the corresponding TXT record. If there
27228 is no match in sbl-xbl.spamhaus.org, nothing more is done. The second blacklist
27229 item is processed similarly.
27230
27231 If you are interested in more than one merged list, the same list must be given
27232 several times, but because the results of the DNS lookups are cached, the DNS
27233 calls themselves are not repeated. For example:
27234
27235 reject dnslists = \
27236 http.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.2 : \
27237 socks.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.3 : \
27238 misc.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.4 : \
27239 dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10
27240
27241 In this case there is one lookup in dnsbl.sorbs.net, and if none of the IP
27242 values matches (or if no record is found), this is the only lookup that is
27243 done. Only if there is a match is one of the more specific lists consulted.
27244
27245
27246 42.37 DNS lists and IPv6
27247 ------------------------
27248
27249 If Exim is asked to do a dnslist lookup for an IPv6 address, it inverts it
27250 nibble by nibble. For example, if the calling host's IP address is
27251 3ffe:ffff:836f:0a00:000a:0800:200a:c031, Exim might look up
27252
27253 1.3.0.c.a.0.0.2.0.0.8.0.a.0.0.0.0.0.a.0.f.6.3.8.
27254 f.f.f.f.e.f.f.3.blackholes.mail-abuse.org
27255
27256 (split over two lines here to fit on the page). Unfortunately, some of the DNS
27257 lists contain wildcard records, intended for IPv4, that interact badly with
27258 IPv6. For example, the DNS entry
27259
27260 *.3.some.list.example. A 127.0.0.1
27261
27262 is probably intended to put the entire 3.0.0.0/8 IPv4 network on the list.
27263 Unfortunately, it also matches the entire 3::/4 IPv6 network.
27264
27265 You can exclude IPv6 addresses from DNS lookups by making use of a suitable
27266 condition condition, as in this example:
27267
27268 deny condition = ${if isip4{$sender_host_address}}
27269 dnslists = some.list.example
27270
27271 If an explicit key is being used for a DNS lookup and it may be an IPv6 address
27272 you should specify alternate list separators for both the outer (DNS list name)
27273 list and inner (lookup keys) list:
27274
27275 dnslists = <; dnsbl.example.com/<|$acl_m_addrslist
27276
27277
27278 42.38 Rate limiting incoming messages
27279 -------------------------------------
27280
27281 The ratelimit ACL condition can be used to measure and control the rate at
27282 which clients can send email. This is more powerful than the smtp_ratelimit_*
27283 options, because those options control the rate of commands in a single SMTP
27284 session only, whereas the ratelimit condition works across all connections
27285 (concurrent and sequential) from the same client host. The syntax of the
27286 ratelimit condition is:
27287
27288 ratelimit = <m> / <p> / <options> / <key>
27289
27290 If the average client sending rate is less than m messages per time period p
27291 then the condition is false; otherwise it is true.
27292
27293 As a side-effect, the ratelimit condition sets the expansion variable
27294 $sender_rate to the client's computed rate, $sender_rate_limit to the
27295 configured value of m, and $sender_rate_period to the configured value of p.
27296
27297 The parameter p is the smoothing time constant, in the form of an Exim time
27298 interval, for example, "8h" for eight hours. A larger time constant means that
27299 it takes Exim longer to forget a client's past behaviour. The parameter m is
27300 the maximum number of messages that a client is permitted to send in each time
27301 interval. It also specifies the number of messages permitted in a fast burst.
27302 By increasing both m and p but keeping m/p constant, you can allow a client to
27303 send more messages in a burst without changing its long-term sending rate
27304 limit. Conversely, if m and p are both small, messages must be sent at an even
27305 rate.
27306
27307 There is a script in util/ratelimit.pl which extracts sending rates from log
27308 files, to assist with choosing appropriate settings for m and p when deploying
27309 the ratelimit ACL condition. The script prints usage instructions when it is
27310 run with no arguments.
27311
27312 The key is used to look up the data for calculating the client's average
27313 sending rate. This data is stored in Exim's spool directory, alongside the
27314 retry and other hints databases. The default key is $sender_host_address, which
27315 means Exim computes the sending rate of each client host IP address. By
27316 changing the key you can change how Exim identifies clients for the purpose of
27317 ratelimiting. For example, to limit the sending rate of each authenticated
27318 user, independent of the computer they are sending from, set the key to
27319 $authenticated_id. You must ensure that the lookup key is meaningful; for
27320 example, $authenticated_id is only meaningful if the client has authenticated
27321 (which you can check with the authenticated ACL condition).
27322
27323 The lookup key does not have to identify clients: If you want to limit the rate
27324 at which a recipient receives messages, you can use the key
27325 "$local_part@$domain" with the per_rcpt option (see below) in a RCPT ACL.
27326
27327 Each ratelimit condition can have up to four options. A per_* option specifies
27328 what Exim measures the rate of, for example messages or recipients or bytes.
27329 You can adjust the measurement using the unique= and/or count= options. You can
27330 also control when Exim updates the recorded rate using a strict, leaky, or
27331 readonly option. The options are separated by a slash, like the other
27332 parameters. They may appear in any order.
27333
27334 Internally, Exim appends the smoothing constant p onto the lookup key with any
27335 options that alter the meaning of the stored data. The limit m is not stored,
27336 so you can alter the configured maximum rate and Exim will still remember
27337 clients' past behaviour. If you change the per_* mode or add or remove the
27338 unique= option, the lookup key changes so Exim will forget past behaviour. The
27339 lookup key is not affected by changes to the update mode and the count= option.
27340
27341
27342 42.39 Ratelimit options for what is being measured
27343 --------------------------------------------------
27344
27345 The per_conn option limits the client's connection rate. It is not normally
27346 used in the acl_not_smtp, acl_not_smtp_mime, or acl_not_smtp_start ACLs.
27347
27348 The per_mail option limits the client's rate of sending messages. This is the
27349 default if none of the per_* options is specified. It can be used in
27350 acl_smtp_mail, acl_smtp_rcpt, acl_smtp_predata, acl_smtp_mime, acl_smtp_data,
27351 or acl_not_smtp.
27352
27353 The per_byte option limits the sender's email bandwidth. It can be used in the
27354 same ACLs as the per_mail option, though it is best to use this option in the
27355 acl_smtp_mime, acl_smtp_data or acl_not_smtp ACLs; if it is used in an earlier
27356 ACL, Exim relies on the SIZE parameter given by the client in its MAIL command,
27357 which may be inaccurate or completely missing. You can follow the limit m in
27358 the configuration with K, M, or G to specify limits in kilobytes, megabytes, or
27359 gigabytes, respectively.
27360
27361 The per_rcpt option causes Exim to limit the rate at which recipients are
27362 accepted. It can be used in the acl_smtp_rcpt, acl_smtp_predata, acl_smtp_mime,
27363 acl_smtp_data, or acl_smtp_rcpt ACLs. In acl_smtp_rcpt the rate is updated one
27364 recipient at a time; in the other ACLs the rate is updated with the total
27365 recipient count in one go. Note that in either case the rate limiting engine
27366 will see a message with many recipients as a large high-speed burst.
27367
27368 The per_addr option is like the per_rcpt option, except it counts the number of
27369 different recipients that the client has sent messages to in the last time
27370 period. That is, if the client repeatedly sends messages to the same recipient,
27371 its measured rate is not increased. This option can only be used in
27372 acl_smtp_rcpt.
27373
27374 The per_cmd option causes Exim to recompute the rate every time the condition
27375 is processed. This can be used to limit the rate of any SMTP command. If it is
27376 used in multiple ACLs it can limit the aggregate rate of multiple different
27377 commands.
27378
27379 The count= option can be used to alter how much Exim adds to the client's
27380 measured rate. For example, the per_byte option is equivalent to "per_mail/
27381 count=$message_size". If there is no count= option, Exim increases the measured
27382 rate by one (except for the per_rcpt option in ACLs other than acl_smtp_rcpt).
27383 The count does not have to be an integer.
27384
27385 The unique= option is described in section 42.42 below.
27386
27387
27388 42.40 Ratelimit update modes
27389 ----------------------------
27390
27391 You can specify one of three options with the ratelimit condition to control
27392 when its database is updated. This section describes the readonly mode, and the
27393 next section describes the strict and leaky modes.
27394
27395 If the ratelimit condition is used in readonly mode, Exim looks up a
27396 previously-computed rate to check against the limit.
27397
27398 For example, you can test the client's sending rate and deny it access (when it
27399 is too fast) in the connect ACL. If the client passes this check then it can go
27400 on to send a message, in which case its recorded rate will be updated in the
27401 MAIL ACL. Subsequent connections from the same client will check this new rate.
27402
27403 acl_check_connect:
27404 deny ratelimit = 100 / 5m / readonly
27405 log_message = RATE CHECK: $sender_rate/$sender_rate_period \
27406 (max $sender_rate_limit)
27407 # ...
27408 acl_check_mail:
27409 warn ratelimit = 100 / 5m / strict
27410 log_message = RATE UPDATE: $sender_rate/$sender_rate_period \
27411 (max $sender_rate_limit)
27412
27413 If Exim encounters multiple ratelimit conditions with the same key when
27414 processing a message then it may increase the client's measured rate more than
27415 it should. For example, this will happen if you check the per_rcpt option in
27416 both acl_smtp_rcpt and acl_smtp_data. However it's OK to check the same
27417 ratelimit condition multiple times in the same ACL. You can avoid any multiple
27418 update problems by using the readonly option on later ratelimit checks.
27419
27420 The per_* options described above do not make sense in some ACLs. If you use a
27421 per_* option in an ACL where it is not normally permitted then the update mode
27422 defaults to readonly and you cannot specify the strict or leaky modes. In other
27423 ACLs the default update mode is leaky (see the next section) so you must
27424 specify the readonly option explicitly.
27425
27426
27427 42.41 Ratelimit options for handling fast clients
27428 -------------------------------------------------
27429
27430 If a client's average rate is greater than the maximum, the rate limiting
27431 engine can react in two possible ways, depending on the presence of the strict
27432 or leaky update modes. This is independent of the other counter-measures (such
27433 as rejecting the message) that may be specified by the rest of the ACL.
27434
27435 The leaky (default) option means that the client's recorded rate is not updated
27436 if it is above the limit. The effect of this is that Exim measures the client's
27437 average rate of successfully sent email, which cannot be greater than the
27438 maximum allowed. If the client is over the limit it may suffer some
27439 counter-measures (as specified in the ACL), but it will still be able to send
27440 email at the configured maximum rate, whatever the rate of its attempts. This
27441 is generally the better choice if you have clients that retry automatically.
27442 For example, it does not prevent a sender with an over-aggressive retry rate
27443 from getting any email through.
27444
27445 The strict option means that the client's recorded rate is always updated. The
27446 effect of this is that Exim measures the client's average rate of attempts to
27447 send email, which can be much higher than the maximum it is actually allowed.
27448 If the client is over the limit it may be subjected to counter-measures by the
27449 ACL. It must slow down and allow sufficient time to pass that its computed rate
27450 falls below the maximum before it can send email again. The time (the number of
27451 smoothing periods) it must wait and not attempt to send mail can be calculated
27452 with this formula:
27453
27454 ln(peakrate/maxrate)
27455
27456
27457 42.42 Limiting the rate of different events
27458 -------------------------------------------
27459
27460 The ratelimit unique= option controls a mechanism for counting the rate of
27461 different events. For example, the per_addr option uses this mechanism to count
27462 the number of different recipients that the client has sent messages to in the
27463 last time period; it is equivalent to "per_rcpt/unique=$local_part@$domain".
27464 You could use this feature to measure the rate that a client uses different
27465 sender addresses with the options "per_mail/unique=$sender_address".
27466
27467 For each ratelimit key Exim stores the set of unique= values that it has seen
27468 for that key. The whole set is thrown away when it is older than the rate
27469 smoothing period p, so each different event is counted at most once per period.
27470 In the leaky update mode, an event that causes the client to go over the limit
27471 is not added to the set, in the same way that the client's recorded rate is not
27472 updated in the same situation.
27473
27474 When you combine the unique= and readonly options, the specific unique= value
27475 is ignored, and Exim just retrieves the client's stored rate.
27476
27477 The unique= mechanism needs more space in the ratelimit database than the other
27478 ratelimit options in order to store the event set. The number of unique values
27479 is potentially as large as the rate limit, so the extra space required
27480 increases with larger limits.
27481
27482 The uniqueification is not perfect: there is a small probability that Exim will
27483 think a new event has happened before. If the sender's rate is less than the
27484 limit, Exim should be more than 99.9% correct. However in strict mode the
27485 measured rate can go above the limit, in which case Exim may under-count events
27486 by a significant margin. Fortunately, if the rate is high enough (2.7 times the
27487 limit) that the false positive rate goes above 9%, then Exim will throw away
27488 the over-full event set before the measured rate falls below the limit.
27489 Therefore the only harm should be that exceptionally high sending rates are
27490 logged incorrectly; any countermeasures you configure will be as effective as
27491 intended.
27492
27493
27494 42.43 Using rate limiting
27495 -------------------------
27496
27497 Exim's other ACL facilities are used to define what counter-measures are taken
27498 when the rate limit is exceeded. This might be anything from logging a warning
27499 (for example, while measuring existing sending rates in order to define
27500 policy), through time delays to slow down fast senders, up to rejecting the
27501 message. For example:
27502
27503 # Log all senders' rates
27504 warn ratelimit = 0 / 1h / strict
27505 log_message = Sender rate $sender_rate / $sender_rate_period
27506
27507 # Slow down fast senders; note the need to truncate $sender_rate
27508 # at the decimal point.
27509 warn ratelimit = 100 / 1h / per_rcpt / strict
27510 delay = ${eval: ${sg{$sender_rate}{[.].*}{}} - \
27511 $sender_rate_limit }s
27512
27513 # Keep authenticated users under control
27514 deny authenticated = *
27515 ratelimit = 100 / 1d / strict / $authenticated_id
27516
27517 # System-wide rate limit
27518 defer message = Sorry, too busy. Try again later.
27519 ratelimit = 10 / 1s / $primary_hostname
27520
27521 # Restrict incoming rate from each host, with a default
27522 # set using a macro and special cases looked up in a table.
27523 defer message = Sender rate exceeds $sender_rate_limit \
27524 messages per $sender_rate_period
27525 ratelimit = ${lookup {$sender_host_address} \
27526 cdb {DB/ratelimits.cdb} \
27527 {$value} {RATELIMIT} }
27528
27529 Warning: If you have a busy server with a lot of ratelimit tests, especially
27530 with the per_rcpt option, you may suffer from a performance bottleneck caused
27531 by locking on the ratelimit hints database. Apart from making your ACLs less
27532 complicated, you can reduce the problem by using a RAM disk for Exim's hints
27533 directory (usually /var/spool/exim/db/). However this means that Exim will lose
27534 its hints data after a reboot (including retry hints, the callout cache, and
27535 ratelimit data).
27536
27537
27538 42.44 Address verification
27539 --------------------------
27540
27541 Several of the verify conditions described in section 42.26 cause addresses to
27542 be verified. Section 42.48 discusses the reporting of sender verification
27543 failures. The verification conditions can be followed by options that modify
27544 the verification process. The options are separated from the keyword and from
27545 each other by slashes, and some of them contain parameters. For example:
27546
27547 verify = sender/callout
27548 verify = recipient/defer_ok/callout=10s,defer_ok
27549
27550 The first stage of address verification, which always happens, is to run the
27551 address through the routers, in "verify mode". Routers can detect the
27552 difference between verification and routing for delivery, and their actions can
27553 be varied by a number of generic options such as verify and verify_only (see
27554 chapter 15). If routing fails, verification fails. The available options are as
27555 follows:
27556
27557 * If the callout option is specified, successful routing to one or more
27558 remote hosts is followed by a "callout" to those hosts as an additional
27559 check. Callouts and their sub-options are discussed in the next section.
27560
27561 * If there is a defer error while doing verification routing, the ACL
27562 normally returns "defer". However, if you include defer_ok in the options,
27563 the condition is forced to be true instead. Note that this is a main
27564 verification option as well as a suboption for callouts.
27565
27566 * The no_details option is covered in section 42.48, which discusses the
27567 reporting of sender address verification failures.
27568
27569 * The success_on_redirect option causes verification always to succeed
27570 immediately after a successful redirection. By default, if a redirection
27571 generates just one address, that address is also verified. See further
27572 discussion in section 42.49.
27573
27574 After an address verification failure, $acl_verify_message contains the error
27575 message that is associated with the failure. It can be preserved by coding like
27576 this:
27577
27578 warn !verify = sender
27579 set acl_m0 = $acl_verify_message
27580
27581 If you are writing your own custom rejection message or log message when
27582 denying access, you can use this variable to include information about the
27583 verification failure.
27584
27585 In addition, $sender_verify_failure or $recipient_verify_failure (as
27586 appropriate) contains one of the following words:
27587
27588 * qualify: The address was unqualified (no domain), and the message was
27589 neither local nor came from an exempted host.
27590
27591 * route: Routing failed.
27592
27593 * mail: Routing succeeded, and a callout was attempted; rejection occurred at
27594 or before the MAIL command (that is, on initial connection, HELO, or MAIL).
27595
27596 * recipient: The RCPT command in a callout was rejected.
27597
27598 * postmaster: The postmaster check in a callout was rejected.
27599
27600 The main use of these variables is expected to be to distinguish between
27601 rejections of MAIL and rejections of RCPT in callouts.
27602
27603
27604 42.45 Callout verification
27605 --------------------------
27606
27607 For non-local addresses, routing verifies the domain, but is unable to do any
27608 checking of the local part. There are situations where some means of verifying
27609 the local part is desirable. One way this can be done is to make an SMTP
27610 callback to a delivery host for the sender address or a callforward to a
27611 subsequent host for a recipient address, to see if the host accepts the
27612 address. We use the term callout to cover both cases. Note that for a sender
27613 address, the callback is not to the client host that is trying to deliver the
27614 message, but to one of the hosts that accepts incoming mail for the sender's
27615 domain.
27616
27617 Exim does not do callouts by default. If you want them to happen, you must
27618 request them by setting appropriate options on the verify condition, as
27619 described below. This facility should be used with care, because it can add a
27620 lot of resource usage to the cost of verifying an address. However, Exim does
27621 cache the results of callouts, which helps to reduce the cost. Details of
27622 caching are in section 42.47.
27623
27624 Recipient callouts are usually used only between hosts that are controlled by
27625 the same administration. For example, a corporate gateway host could use
27626 callouts to check for valid recipients on an internal mailserver. A successful
27627 callout does not guarantee that a real delivery to the address would succeed;
27628 on the other hand, a failing callout does guarantee that a delivery would fail.
27629
27630 If the callout option is present on a condition that verifies an address, a
27631 second stage of verification occurs if the address is successfully routed to
27632 one or more remote hosts. The usual case is routing by a dnslookup or a
27633 manualroute router, where the router specifies the hosts. However, if a router
27634 that does not set up hosts routes to an smtp transport with a hosts setting,
27635 the transport's hosts are used. If an smtp transport has hosts_override set,
27636 its hosts are always used, whether or not the router supplies a host list.
27637 Callouts are only supported on smtp transports.
27638
27639 The port that is used is taken from the transport, if it is specified and is a
27640 remote transport. (For routers that do verification only, no transport need be
27641 specified.) Otherwise, the default SMTP port is used. If a remote transport
27642 specifies an outgoing interface, this is used; otherwise the interface is not
27643 specified. Likewise, the text that is used for the HELO command is taken from
27644 the transport's helo_data option; if there is no transport, the value of
27645 $smtp_active_hostname is used.
27646
27647 For a sender callout check, Exim makes SMTP connections to the remote hosts, to
27648 test whether a bounce message could be delivered to the sender address. The
27649 following SMTP commands are sent:
27650
27651 HELO <local host name>
27652 MAIL FROM:<>
27653 RCPT TO:<the address to be tested>
27654 QUIT
27655
27656 LHLO is used instead of HELO if the transport's protocol option is set to
27657 "lmtp".
27658
27659 The callout may use EHLO, AUTH and/or STARTTLS given appropriate option
27660 settings.
27661
27662 A recipient callout check is similar. By default, it also uses an empty address
27663 for the sender. This default is chosen because most hosts do not make use of
27664 the sender address when verifying a recipient. Using the same address means
27665 that a single cache entry can be used for each recipient. Some sites, however,
27666 do make use of the sender address when verifying. These are catered for by the
27667 use_sender and use_postmaster options, described in the next section.
27668
27669 If the response to the RCPT command is a 2xx code, the verification succeeds.
27670 If it is 5xx, the verification fails. For any other condition, Exim tries the
27671 next host, if any. If there is a problem with all the remote hosts, the ACL
27672 yields "defer", unless the defer_ok parameter of the callout option is given,
27673 in which case the condition is forced to succeed.
27674
27675 A callout may take a little time. For this reason, Exim normally flushes SMTP
27676 output before performing a callout in an ACL, to avoid unexpected timeouts in
27677 clients when the SMTP PIPELINING extension is in use. The flushing can be
27678 disabled by using a control modifier to set no_callout_flush.
27679
27680
27681 42.46 Additional parameters for callouts
27682 ----------------------------------------
27683
27684 The callout option can be followed by an equals sign and a number of optional
27685 parameters, separated by commas. For example:
27686
27687 verify = recipient/callout=10s,defer_ok
27688
27689 The old syntax, which had callout_defer_ok and check_postmaster as separate
27690 verify options, is retained for backwards compatibility, but is now deprecated.
27691 The additional parameters for callout are as follows:
27692
27693 <a time interval>
27694
27695 This specifies the timeout that applies for the callout attempt to each
27696 host. For example:
27697
27698 verify = sender/callout=5s
27699
27700 The default is 30 seconds. The timeout is used for each response from the
27701 remote host. It is also used for the initial connection, unless overridden
27702 by the connect parameter.
27703
27704 connect = <time interval>
27705
27706 This parameter makes it possible to set a different (usually smaller)
27707 timeout for making the SMTP connection. For example:
27708
27709 verify = sender/callout=5s,connect=1s
27710
27711 If not specified, this timeout defaults to the general timeout value.
27712
27713 defer_ok
27714
27715 When this parameter is present, failure to contact any host, or any other
27716 kind of temporary error, is treated as success by the ACL. However, the
27717 cache is not updated in this circumstance.
27718
27719 fullpostmaster
27720
27721 This operates like the postmaster option (see below), but if the check for
27722 postmaster@domain fails, it tries just postmaster, without a domain, in
27723 accordance with the specification in RFC 2821. The RFC states that the
27724 unqualified address postmaster should be accepted.
27725
27726 mailfrom = <email address>
27727
27728 When verifying addresses in header lines using the header_sender
27729 verification option, Exim behaves by default as if the addresses are
27730 envelope sender addresses from a message. Callout verification therefore
27731 tests to see whether a bounce message could be delivered, by using an empty
27732 address in the MAIL command. However, it is arguable that these addresses
27733 might never be used as envelope senders, and could therefore justifiably
27734 reject bounce messages (empty senders). The mailfrom callout parameter
27735 allows you to specify what address to use in the MAIL command. For example:
27736
27737 require verify = header_sender/callout=mailfrom=abcd@x.y.z
27738
27739 This parameter is available only for the header_sender verification option.
27740
27741 maxwait = <time interval>
27742
27743 This parameter sets an overall timeout for performing a callout
27744 verification. For example:
27745
27746 verify = sender/callout=5s,maxwait=30s
27747
27748 This timeout defaults to four times the callout timeout for individual SMTP
27749 commands. The overall timeout applies when there is more than one host that
27750 can be tried. The timeout is checked before trying the next host. This
27751 prevents very long delays if there are a large number of hosts and all are
27752 timing out (for example, when network connections are timing out).
27753
27754 no_cache
27755
27756 When this parameter is given, the callout cache is neither read nor
27757 updated.
27758
27759 postmaster
27760
27761 When this parameter is set, a successful callout check is followed by a
27762 similar check for the local part postmaster at the same domain. If this
27763 address is rejected, the callout fails (but see fullpostmaster above). The
27764 result of the postmaster check is recorded in a cache record; if it is a
27765 failure, this is used to fail subsequent callouts for the domain without a
27766 connection being made, until the cache record expires.
27767
27768 postmaster_mailfrom = <email address>
27769
27770 The postmaster check uses an empty sender in the MAIL command by default.
27771 You can use this parameter to do a postmaster check using a different
27772 address. For example:
27773
27774 require verify = sender/callout=postmaster_mailfrom=abc@x.y.z
27775
27776 If both postmaster and postmaster_mailfrom are present, the rightmost one
27777 overrides. The postmaster parameter is equivalent to this example:
27778
27779 require verify = sender/callout=postmaster_mailfrom=
27780
27781 Warning: The caching arrangements for postmaster checking do not take
27782 account of the sender address. It is assumed that either the empty address
27783 or a fixed non-empty address will be used. All that Exim remembers is that
27784 the postmaster check for the domain succeeded or failed.
27785
27786 random
27787
27788 When this parameter is set, before doing the normal callout check, Exim
27789 does a check for a "random" local part at the same domain. The local part
27790 is not really random - it is defined by the expansion of the option
27791 callout_random_local_part, which defaults to
27792
27793 $primary_hostname-$tod_epoch-testing
27794
27795 The idea here is to try to determine whether the remote host accepts all
27796 local parts without checking. If it does, there is no point in doing
27797 callouts for specific local parts. If the "random" check succeeds, the
27798 result is saved in a cache record, and used to force the current and
27799 subsequent callout checks to succeed without a connection being made, until
27800 the cache record expires.
27801
27802 use_postmaster
27803
27804 This parameter applies to recipient callouts only. For example:
27805
27806 deny !verify = recipient/callout=use_postmaster
27807
27808 It causes a non-empty postmaster address to be used in the MAIL command
27809 when performing the callout for the recipient, and also for a "random"
27810 check if that is configured. The local part of the address is "postmaster"
27811 and the domain is the contents of $qualify_domain.
27812
27813 use_sender
27814
27815 This option applies to recipient callouts only. For example:
27816
27817 require verify = recipient/callout=use_sender
27818
27819 It causes the message's actual sender address to be used in the MAIL
27820 command when performing the callout, instead of an empty address. There is
27821 no need to use this option unless you know that the called hosts make use
27822 of the sender when checking recipients. If used indiscriminately, it
27823 reduces the usefulness of callout caching.
27824
27825 If you use any of the parameters that set a non-empty sender for the MAIL
27826 command (mailfrom, postmaster_mailfrom, use_postmaster, or use_sender), you
27827 should think about possible loops. Recipient checking is usually done between
27828 two hosts that are under the same management, and the host that receives the
27829 callouts is not normally configured to do callouts itself. Therefore, it is
27830 normally safe to use use_postmaster or use_sender in these circumstances.
27831
27832 However, if you use a non-empty sender address for a callout to an arbitrary
27833 host, there is the likelihood that the remote host will itself initiate a
27834 callout check back to your host. As it is checking what appears to be a message
27835 sender, it is likely to use an empty address in MAIL, thus avoiding a callout
27836 loop. However, to be on the safe side it would be best to set up your own ACLs
27837 so that they do not do sender verification checks when the recipient is the
27838 address you use for header sender or postmaster callout checking.
27839
27840 Another issue to think about when using non-empty senders for callouts is
27841 caching. When you set mailfrom or use_sender, the cache record is keyed by the
27842 sender/recipient combination; thus, for any given recipient, many more actual
27843 callouts are performed than when an empty sender or postmaster is used.
27844
27845
27846 42.47 Callout caching
27847 ---------------------
27848
27849 Exim caches the results of callouts in order to reduce the amount of resources
27850 used, unless you specify the no_cache parameter with the callout option. A
27851 hints database called "callout" is used for the cache. Two different record
27852 types are used: one records the result of a callout check for a specific
27853 address, and the other records information that applies to the entire domain
27854 (for example, that it accepts the local part postmaster).
27855
27856 When an original callout fails, a detailed SMTP error message is given about
27857 the failure. However, for subsequent failures use the cache data, this message
27858 is not available.
27859
27860 The expiry times for negative and positive address cache records are
27861 independent, and can be set by the global options callout_negative_expire
27862 (default 2h) and callout_positive_expire (default 24h), respectively.
27863
27864 If a host gives a negative response to an SMTP connection, or rejects any
27865 commands up to and including
27866
27867 MAIL FROM:<>
27868
27869 (but not including the MAIL command with a non-empty address), any callout
27870 attempt is bound to fail. Exim remembers such failures in a domain cache
27871 record, which it uses to fail callouts for the domain without making new
27872 connections, until the domain record times out. There are two separate expiry
27873 times for domain cache records: callout_domain_negative_expire (default 3h) and
27874 callout_domain_positive_expire (default 7d).
27875
27876 Domain records expire when the negative expiry time is reached if callouts
27877 cannot be made for the domain, or if the postmaster check failed. Otherwise,
27878 they expire when the positive expiry time is reached. This ensures that, for
27879 example, a host that stops accepting "random" local parts will eventually be
27880 noticed.
27881
27882 The callout caching mechanism is based on the domain of the address that is
27883 being tested. If the domain routes to several hosts, it is assumed that their
27884 behaviour will be the same.
27885
27886
27887 42.48 Sender address verification reporting
27888 -------------------------------------------
27889
27890 See section 42.44 for a general discussion of verification. When sender
27891 verification fails in an ACL, the details of the failure are given as
27892 additional output lines before the 550 response to the relevant SMTP command
27893 (RCPT or DATA). For example, if sender callout is in use, you might see:
27894
27895 MAIL FROM:<xyz@abc.example>
27896 250 OK
27897 RCPT TO:<pqr@def.example>
27898 550-Verification failed for <xyz@abc.example>
27899 550-Called: 192.168.34.43
27900 550-Sent: RCPT TO:<xyz@abc.example>
27901 550-Response: 550 Unknown local part xyz in <xyz@abc.example>
27902 550 Sender verification failed
27903
27904 If more than one RCPT command fails in the same way, the details are given only
27905 for the first of them. However, some administrators do not want to send out
27906 this much information. You can suppress the details by adding "/no_details" to
27907 the ACL statement that requests sender verification. For example:
27908
27909 verify = sender/no_details
27910
27911
27912 42.49 Redirection while verifying
27913 ---------------------------------
27914
27915 A dilemma arises when a local address is redirected by aliasing or forwarding
27916 during verification: should the generated addresses themselves be verified, or
27917 should the successful expansion of the original address be enough to verify it?
27918 By default, Exim takes the following pragmatic approach:
27919
27920 * When an incoming address is redirected to just one child address,
27921 verification continues with the child address, and if that fails to verify,
27922 the original verification also fails.
27923
27924 * When an incoming address is redirected to more than one child address,
27925 verification does not continue. A success result is returned.
27926
27927 This seems the most reasonable behaviour for the common use of aliasing as a
27928 way of redirecting different local parts to the same mailbox. It means, for
27929 example, that a pair of alias entries of the form
27930
27931 A.Wol: aw123
27932 aw123: :fail: Gone away, no forwarding address
27933
27934 work as expected, with both local parts causing verification failure. When a
27935 redirection generates more than one address, the behaviour is more like a
27936 mailing list, where the existence of the alias itself is sufficient for
27937 verification to succeed.
27938
27939 It is possible, however, to change the default behaviour so that all successful
27940 redirections count as successful verifications, however many new addresses are
27941 generated. This is specified by the success_on_redirect verification option.
27942 For example:
27943
27944 require verify = recipient/success_on_redirect/callout=10s
27945
27946 In this example, verification succeeds if a router generates a new address, and
27947 the callout does not occur, because no address was routed to a remote host.
27948
27949 When verification is being tested via the -bv option, the treatment of
27950 redirections is as just described, unless the -v or any debugging option is
27951 also specified. In that case, full verification is done for every generated
27952 address and a report is output for each of them.
27953
27954
27955 42.50 Client SMTP authorization (CSA)
27956 -------------------------------------
27957
27958 Client SMTP Authorization is a system that allows a site to advertise which
27959 machines are and are not permitted to send email. This is done by placing
27960 special SRV records in the DNS; these are looked up using the client's HELO
27961 domain. At the time of writing, CSA is still an Internet Draft. Client SMTP
27962 Authorization checks in Exim are performed by the ACL condition:
27963
27964 verify = csa
27965
27966 This fails if the client is not authorized. If there is a DNS problem, or if no
27967 valid CSA SRV record is found, or if the client is authorized, the condition
27968 succeeds. These three cases can be distinguished using the expansion variable
27969 $csa_status, which can take one of the values "fail", "defer", "unknown", or
27970 "ok". The condition does not itself defer because that would be likely to cause
27971 problems for legitimate email.
27972
27973 The error messages produced by the CSA code include slightly more detail. If
27974 $csa_status is "defer", this may be because of problems looking up the CSA SRV
27975 record, or problems looking up the CSA target address record. There are four
27976 reasons for $csa_status being "fail":
27977
27978 * The client's host name is explicitly not authorized.
27979
27980 * The client's IP address does not match any of the CSA target IP addresses.
27981
27982 * The client's host name is authorized but it has no valid target IP
27983 addresses (for example, the target's addresses are IPv6 and the client is
27984 using IPv4).
27985
27986 * The client's host name has no CSA SRV record but a parent domain has
27987 asserted that all subdomains must be explicitly authorized.
27988
27989 The csa verification condition can take an argument which is the domain to use
27990 for the DNS query. The default is:
27991
27992 verify = csa/$sender_helo_name
27993
27994 This implementation includes an extension to CSA. If the query domain is an
27995 address literal such as [192.0.2.95], or if it is a bare IP address, Exim
27996 searches for CSA SRV records in the reverse DNS as if the HELO domain was (for
27997 example) 95.2.0.192.in-addr.arpa. Therefore it is meaningful to say:
27998
27999 verify = csa/$sender_host_address
28000
28001 In fact, this is the check that Exim performs if the client does not say HELO.
28002 This extension can be turned off by setting the main configuration option
28003 dns_csa_use_reverse to be false.
28004
28005 If a CSA SRV record is not found for the domain itself, a search is performed
28006 through its parent domains for a record which might be making assertions about
28007 subdomains. The maximum depth of this search is limited using the main
28008 configuration option dns_csa_search_limit, which is 5 by default. Exim does not
28009 look for CSA SRV records in a top level domain, so the default settings handle
28010 HELO domains as long as seven (hostname.five.four.three.two.one.com). This
28011 encompasses the vast majority of legitimate HELO domains.
28012
28013 The dnsdb lookup also has support for CSA. Although dnsdb also supports direct
28014 SRV lookups, this is not sufficient because of the extra parent domain search
28015 behaviour of CSA, and (as with PTR lookups) dnsdb also turns IP addresses into
28016 lookups in the reverse DNS space. The result of a successful lookup such as:
28017
28018 ${lookup dnsdb {csa=$sender_helo_name}}
28019
28020 has two space-separated fields: an authorization code and a target host name.
28021 The authorization code can be "Y" for yes, "N" for no, "X" for explicit
28022 authorization required but absent, or "?" for unknown.
28023
28024
28025 42.51 Bounce address tag validation
28026 -----------------------------------
28027
28028 Bounce address tag validation (BATV) is a scheme whereby the envelope senders
28029 of outgoing messages have a cryptographic, timestamped "tag" added to them.
28030 Genuine incoming bounce messages should therefore always be addressed to
28031 recipients that have a valid tag. This scheme is a way of detecting unwanted
28032 bounce messages caused by sender address forgeries (often called "collateral
28033 spam"), because the recipients of such messages do not include valid tags.
28034
28035 There are two expansion items to help with the implementation of the BATV
28036 "prvs" (private signature) scheme in an Exim configuration. This scheme signs
28037 the original envelope sender address by using a simple key to add a hash of the
28038 address and some time-based randomizing information. The prvs expansion item
28039 creates a signed address, and the prvscheck expansion item checks one. The
28040 syntax of these expansion items is described in section 11.5.
28041
28042 As an example, suppose the secret per-address keys are stored in an MySQL
28043 database. A query to look up the key for an address could be defined as a macro
28044 like this:
28045
28046 PRVSCHECK_SQL = ${lookup mysql{SELECT secret FROM batv_prvs \
28047 WHERE sender='${quote_mysql:$prvscheck_address}'\
28048 }{$value}}
28049
28050 Suppose also that the senders who make use of BATV are defined by an address
28051 list called batv_senders. Then, in the ACL for RCPT commands, you could use
28052 this:
28053
28054 # Bounces: drop unsigned addresses for BATV senders
28055 deny message = This address does not send an unsigned reverse path
28056 senders = :
28057 recipients = +batv_senders
28058
28059 # Bounces: In case of prvs-signed address, check signature.
28060 deny message = Invalid reverse path signature.
28061 senders = :
28062 condition = ${prvscheck {$local_part@$domain}\
28063 {PRVSCHECK_SQL}{1}}
28064 !condition = $prvscheck_result
28065
28066 The first statement rejects recipients for bounce messages that are addressed
28067 to plain BATV sender addresses, because it is known that BATV senders do not
28068 send out messages with plain sender addresses. The second statement rejects
28069 recipients that are prvs-signed, but with invalid signatures (either because
28070 the key is wrong, or the signature has timed out).
28071
28072 A non-prvs-signed address is not rejected by the second statement, because the
28073 prvscheck expansion yields an empty string if its first argument is not a
28074 prvs-signed address, thus causing the condition condition to be false. If the
28075 first argument is a syntactically valid prvs-signed address, the yield is the
28076 third string (in this case "1"), whether or not the cryptographic and timeout
28077 checks succeed. The $prvscheck_result variable contains the result of the
28078 checks (empty for failure, "1" for success).
28079
28080 There is one more issue you must consider when implementing prvs-signing: you
28081 have to ensure that the routers accept prvs-signed addresses and deliver them
28082 correctly. The easiest way to handle this is to use a redirect router to remove
28083 the signature with a configuration along these lines:
28084
28085 batv_redirect:
28086 driver = redirect
28087 data = ${prvscheck {$local_part@$domain}{PRVSCHECK_SQL}}
28088
28089 This works because, if the third argument of prvscheck is empty, the result of
28090 the expansion of a prvs-signed address is the decoded value of the original
28091 address. This router should probably be the first of your routers that handles
28092 local addresses.
28093
28094 To create BATV-signed addresses in the first place, a transport of this form
28095 can be used:
28096
28097 external_smtp_batv:
28098 driver = smtp
28099 return_path = ${prvs {$return_path} \
28100 {${lookup mysql{SELECT \
28101 secret FROM batv_prvs WHERE \
28102 sender='${quote_mysql:$sender_address}'} \
28103 {$value}fail}}}
28104
28105 If no key can be found for the existing return path, no signing takes place.
28106
28107
28108 42.52 Using an ACL to control relaying
28109 --------------------------------------
28110
28111 An MTA is said to relay a message if it receives it from some host and delivers
28112 it directly to another host as a result of a remote address contained within
28113 it. Redirecting a local address via an alias or forward file and then passing
28114 the message on to another host is not relaying, but a redirection as a result
28115 of the "percent hack" is.
28116
28117 Two kinds of relaying exist, which are termed "incoming" and "outgoing". A host
28118 which is acting as a gateway or an MX backup is concerned with incoming
28119 relaying from arbitrary hosts to a specific set of domains. On the other hand,
28120 a host which is acting as a smart host for a number of clients is concerned
28121 with outgoing relaying from those clients to the Internet at large. Often the
28122 same host is fulfilling both functions, but in principle these two kinds of
28123 relaying are entirely independent. What is not wanted is the transmission of
28124 mail from arbitrary remote hosts through your system to arbitrary domains.
28125
28126 You can implement relay control by means of suitable statements in the ACL that
28127 runs for each RCPT command. For convenience, it is often easiest to use Exim's
28128 named list facility to define the domains and hosts involved. For example,
28129 suppose you want to do the following:
28130
28131 * Deliver a number of domains to mailboxes on the local host (or process them
28132 locally in some other way). Let's say these are my.dom1.example and
28133 my.dom2.example.
28134
28135 * Relay mail for a number of other domains for which you are the secondary
28136 MX. These might be friend1.example and friend2.example.
28137
28138 * Relay mail from the hosts on your local LAN, to whatever domains are
28139 involved. Suppose your LAN is 192.168.45.0/24.
28140
28141 In the main part of the configuration, you put the following definitions:
28142
28143 domainlist local_domains = my.dom1.example : my.dom2.example
28144 domainlist relay_to_domains = friend1.example : friend2.example
28145 hostlist relay_from_hosts = 192.168.45.0/24
28146
28147 Now you can use these definitions in the ACL that is run for every RCPT
28148 command:
28149
28150 acl_check_rcpt:
28151 accept domains = +local_domains : +relay_to_domains
28152 accept hosts = +relay_from_hosts
28153
28154 The first statement accepts any RCPT command that contains an address in the
28155 local or relay domains. For any other domain, control passes to the second
28156 statement, which accepts the command only if it comes from one of the relay
28157 hosts. In practice, you will probably want to make your ACL more sophisticated
28158 than this, for example, by including sender and recipient verification. The
28159 default configuration includes a more comprehensive example, which is described
28160 in chapter 7.
28161
28162
28163 42.53 Checking a relay configuration
28164 ------------------------------------
28165
28166 You can check the relay characteristics of your configuration in the same way
28167 that you can test any ACL behaviour for an incoming SMTP connection, by using
28168 the -bh option to run a fake SMTP session with which you interact.
28169
28170 For specifically testing for unwanted relaying, the host
28171 relay-test.mail-abuse.org provides a useful service. If you telnet to this host
28172 from the host on which Exim is running, using the normal telnet port, you will
28173 see a normal telnet connection message and then quite a long delay. Be patient.
28174 The remote host is making an SMTP connection back to your host, and trying a
28175 number of common probes to test for open relay vulnerability. The results of
28176 the tests will eventually appear on your terminal.
28177
28178
28179
28180 ===============================================================================
28181 43. CONTENT SCANNING AT ACL TIME
28182
28183 The extension of Exim to include content scanning at ACL time, formerly known
28184 as "exiscan", was originally implemented as a patch by Tom Kistner. The code
28185 was integrated into the main source for Exim release 4.50, and Tom continues to
28186 maintain it. Most of the wording of this chapter is taken from Tom's
28187 specification.
28188
28189 It is also possible to scan the content of messages at other times. The
28190 local_scan() function (see chapter 44) allows for content scanning after all
28191 the ACLs have run. A transport filter can be used to scan messages at delivery
28192 time (see the transport_filter option, described in chapter 24).
28193
28194 If you want to include the ACL-time content-scanning features when you compile
28195 Exim, you need to arrange for WITH_CONTENT_SCAN to be defined in your Local/
28196 Makefile. When you do that, the Exim binary is built with:
28197
28198 * Two additional ACLs (acl_smtp_mime and acl_not_smtp_mime) that are run for
28199 all MIME parts for SMTP and non-SMTP messages, respectively.
28200
28201 * Additional ACL conditions and modifiers: decode, malware, mime_regex, regex
28202 , and spam. These can be used in the ACL that is run at the end of message
28203 reception (the acl_smtp_data ACL).
28204
28205 * An additional control feature ("no_mbox_unspool") that saves spooled copies
28206 of messages, or parts of messages, for debugging purposes.
28207
28208 * Additional expansion variables that are set in the new ACL and by the new
28209 conditions.
28210
28211 * Two new main configuration options: av_scanner and spamd_address.
28212
28213 There is another content-scanning configuration option for Local/Makefile,
28214 called WITH_OLD_DEMIME. If this is set, the old, deprecated demime ACL
28215 condition is compiled, in addition to all the other content-scanning features.
28216
28217 Content-scanning is continually evolving, and new features are still being
28218 added. While such features are still unstable and liable to incompatible
28219 changes, they are made available in Exim by setting options whose names begin
28220 EXPERIMENTAL_ in Local/Makefile. Such features are not documented in this
28221 manual. You can find out about them by reading the file called doc/
28222 experimental.txt.
28223
28224 All the content-scanning facilities work on a MBOX copy of the message that is
28225 temporarily created in a file called:
28226
28227 <spool_directory>/scan/<message_id>/<message_id>.eml
28228
28229 The .eml extension is a friendly hint to virus scanners that they can expect an
28230 MBOX-like structure inside that file. The file is created when the first
28231 content scanning facility is called. Subsequent calls to content scanning
28232 conditions open the same file again. The directory is recursively removed when
28233 the acl_smtp_data ACL has finished running, unless
28234
28235 control = no_mbox_unspool
28236
28237 has been encountered. When the MIME ACL decodes files, they are put into the
28238 same directory by default.
28239
28240
28241 43.1 Scanning for viruses
28242 -------------------------
28243
28244 The malware ACL condition lets you connect virus scanner software to Exim. It
28245 supports a "generic" interface to scanners called via the shell, and
28246 specialized interfaces for "daemon" type virus scanners, which are resident in
28247 memory and thus are much faster.
28248
28249 You can set the av_scanner option in first part of the Exim configuration file
28250 to specify which scanner to use, together with any additional options that are
28251 needed. The basic syntax is as follows:
28252
28253 av_scanner = <scanner-type>:<option1>:<option2>:[...]
28254
28255 If you do not set av_scanner, it defaults to
28256
28257 av_scanner = sophie:/var/run/sophie
28258
28259 If the value of av_scanner starts with a dollar character, it is expanded
28260 before use. The usual list-parsing of the content (see 6.19) applies. The
28261 following scanner types are supported in this release:
28262
28263 aveserver
28264
28265 This is the scanner daemon of Kaspersky Version 5. You can get a trial
28266 version at http://www.kaspersky.com. This scanner type takes one option,
28267 which is the path to the daemon's UNIX socket. The default is shown in this
28268 example:
28269
28270 av_scanner = aveserver:/var/run/aveserver
28271
28272 clamd
28273
28274 This daemon-type scanner is GPL and free. You can get it at http://
28275 www.clamav.net/. Some older versions of clamd do not seem to unpack MIME
28276 containers, so it used to be recommended to unpack MIME attachments in the
28277 MIME ACL. This no longer believed to be necessary. One option is required:
28278 either the path and name of a UNIX socket file, or a hostname or IP number,
28279 and a port, separated by space, as in the second of these examples:
28280
28281 av_scanner = clamd:/opt/clamd/socket
28282 av_scanner = clamd:192.0.2.3 1234
28283 av_scanner = clamd:192.0.2.3 1234:local
28284 av_scanner = clamd:192.0.2.3 1234 : 192.0.2.4 1234
28285
28286 If the value of av_scanner points to a UNIX socket file or contains the
28287 local keyword, then the ClamAV interface will pass a filename containing
28288 the data to be scanned, which will should normally result in less I/O
28289 happening and be more efficient. Normally in the TCP case, the data is
28290 streamed to ClamAV as Exim does not assume that there is a common
28291 filesystem with the remote host. There is an option WITH_OLD_CLAMAV_STREAM
28292 in src/EDITME available, should you be running a version of ClamAV prior to
28293 0.95.
28294
28295 The final example shows that multiple TCP targets can be specified. Exim
28296 will randomly use one for each incoming email (i.e. it load balances them).
28297 Note that only TCP targets may be used if specifying a list of scanners; a
28298 UNIX socket cannot be mixed in with TCP targets. If one of the servers
28299 becomes unavailable, Exim will try the remaining one(s) until it finds one
28300 that works. When a clamd server becomes unreachable, Exim will log a
28301 message. Exim does not keep track of scanner state between multiple
28302 messages, and the scanner selection is random, so the message will get
28303 logged in the mainlog for each email that the down scanner gets chosen
28304 first (message wrapped to be readable):
28305
28306 2013-10-09 14:30:39 1VTumd-0000Y8-BQ malware acl condition:
28307 clamd: connection to localhost, port 3310 failed
28308 (Connection refused)
28309
28310 If the option is unset, the default is /tmp/clamd. Thanks to David Saez for
28311 contributing the code for this scanner.
28312
28313 cmdline
28314
28315 This is the keyword for the generic command line scanner interface. It can
28316 be used to attach virus scanners that are invoked from the shell. This
28317 scanner type takes 3 mandatory options:
28318
28319 1. The full path and name of the scanner binary, with all command line
28320 options, and a placeholder ("%s") for the directory to scan.
28321
28322 2. A regular expression to match against the STDOUT and STDERR output of
28323 the virus scanner. If the expression matches, a virus was found. You
28324 must make absolutely sure that this expression matches on "virus
28325 found". This is called the "trigger" expression.
28326
28327 3. Another regular expression, containing exactly one pair of parentheses,
28328 to match the name of the virus found in the scanners output. This is
28329 called the "name" expression.
28330
28331 For example, Sophos Sweep reports a virus on a line like this:
28332
28333 Virus 'W32/Magistr-B' found in file ./those.bat
28334
28335 For the trigger expression, we can match the phrase "found in file". For
28336 the name expression, we want to extract the W32/Magistr-B string, so we can
28337 match for the single quotes left and right of it. Altogether, this makes
28338 the configuration setting:
28339
28340 av_scanner = cmdline:\
28341 /path/to/sweep -ss -all -rec -archive %s:\
28342 found in file:'(.+)'
28343
28344 drweb
28345
28346 The DrWeb daemon scanner (http://www.sald.com/) interface takes one
28347 argument, either a full path to a UNIX socket, or an IP address and port
28348 separated by white space, as in these examples:
28349
28350 av_scanner = drweb:/var/run/drwebd.sock
28351 av_scanner = drweb:192.168.2.20 31337
28352
28353 If you omit the argument, the default path /usr/local/drweb/run/drwebd.sock
28354 is used. Thanks to Alex Miller for contributing the code for this scanner.
28355
28356 fsecure
28357
28358 The F-Secure daemon scanner (http://www.f-secure.com) takes one argument
28359 which is the path to a UNIX socket. For example:
28360
28361 av_scanner = fsecure:/path/to/.fsav
28362
28363 If no argument is given, the default is /var/run/.fsav. Thanks to Johan
28364 Thelmen for contributing the code for this scanner.
28365
28366 kavdaemon
28367
28368 This is the scanner daemon of Kaspersky Version 4. This version of the
28369 Kaspersky scanner is outdated. Please upgrade (see aveserver above). This
28370 scanner type takes one option, which is the path to the daemon's UNIX
28371 socket. For example:
28372
28373 av_scanner = kavdaemon:/opt/AVP/AvpCtl
28374
28375 The default path is /var/run/AvpCtl.
28376
28377 mksd
28378
28379 This is a daemon type scanner that is aimed mainly at Polish users, though
28380 some parts of documentation are now available in English. You can get it at
28381 http://linux.mks.com.pl/. The only option for this scanner type is the
28382 maximum number of processes used simultaneously to scan the attachments,
28383 provided that the demime facility is employed and also provided that mksd
28384 has been run with at least the same number of child processes. For example:
28385
28386 av_scanner = mksd:2
28387
28388 You can safely omit this option (the default value is 1).
28389
28390 sock
28391
28392 This is a general-purpose way of talking to simple scanner daemons running
28393 on the local machine. There are four options: an address (which may be an
28394 IP addres and port, or the path of a Unix socket), a commandline to send
28395 (may include a single %s which will be replaced with the path to the mail
28396 file to be scanned), an RE to trigger on from the returned data, an RE to
28397 extract malware_name from the returned data. For example:
28398
28399 av_scanner = sock:127.0.0.1 6001:%s:(SPAM|VIRUS):(.*)\$
28400
28401 Default for the socket specifier is /tmp/malware.sock. Default for the
28402 commandline is %s\n. Both regular-expressions are required.
28403
28404 sophie
28405
28406 Sophie is a daemon that uses Sophos' libsavi library to scan for viruses.
28407 You can get Sophie at http://www.clanfield.info/sophie/. The only option
28408 for this scanner type is the path to the UNIX socket that Sophie uses for
28409 client communication. For example:
28410
28411 av_scanner = sophie:/tmp/sophie
28412
28413 The default path is /var/run/sophie, so if you are using this, you can omit
28414 the option.
28415
28416 When av_scanner is correctly set, you can use the malware condition in the DATA
28417 ACL. Note: You cannot use the malware condition in the MIME ACL.
28418
28419 The av_scanner option is expanded each time malware is called. This makes it
28420 possible to use different scanners. See further below for an example. The
28421 malware condition caches its results, so when you use it multiple times for the
28422 same message, the actual scanning process is only carried out once. However,
28423 using expandable items in av_scanner disables this caching, in which case each
28424 use of the malware condition causes a new scan of the message.
28425
28426 The malware condition takes a right-hand argument that is expanded before use.
28427 It can then be one of
28428
28429 * "true", "*", or "1", in which case the message is scanned for viruses. The
28430 condition succeeds if a virus was found, and fail otherwise. This is the
28431 recommended usage.
28432
28433 * "false" or "0" or an empty string, in which case no scanning is done and
28434 the condition fails immediately.
28435
28436 * A regular expression, in which case the message is scanned for viruses. The
28437 condition succeeds if a virus is found and its name matches the regular
28438 expression. This allows you to take special actions on certain types of
28439 virus.
28440
28441 You can append "/defer_ok" to the malware condition to accept messages even if
28442 there is a problem with the virus scanner. Otherwise, such a problem causes the
28443 ACL to defer.
28444
28445 When a virus is found, the condition sets up an expansion variable called
28446 $malware_name that contains the name of the virus. You can use it in a message
28447 modifier that specifies the error returned to the sender, and/or in logging
28448 data.
28449
28450 If your virus scanner cannot unpack MIME and TNEF containers itself, you should
28451 use the demime condition (see section 43.6) before the malware condition.
28452
28453 Beware the interaction of Exim's message_size_limit with any size limits
28454 imposed by your anti-virus scanner.
28455
28456 Here is a very simple scanning example:
28457
28458 deny message = This message contains malware ($malware_name)
28459 demime = *
28460 malware = *
28461
28462 The next example accepts messages when there is a problem with the scanner:
28463
28464 deny message = This message contains malware ($malware_name)
28465 demime = *
28466 malware = */defer_ok
28467
28468 The next example shows how to use an ACL variable to scan with both sophie and
28469 aveserver. It assumes you have set:
28470
28471 av_scanner = $acl_m0
28472
28473 in the main Exim configuration.
28474
28475 deny message = This message contains malware ($malware_name)
28476 set acl_m0 = sophie
28477 malware = *
28478
28479 deny message = This message contains malware ($malware_name)
28480 set acl_m0 = aveserver
28481 malware = *
28482
28483
28484 43.2 Scanning with SpamAssassin
28485 -------------------------------
28486
28487 The spam ACL condition calls SpamAssassin's spamd daemon to get a spam score
28488 and a report for the message. You can get SpamAssassin at http://
28489 www.spamassassin.org, or, if you have a working Perl installation, you can use
28490 CPAN by running:
28491
28492 perl -MCPAN -e 'install Mail::SpamAssassin'
28493
28494 SpamAssassin has its own set of configuration files. Please review its
28495 documentation to see how you can tweak it. The default installation should work
28496 nicely, however.
28497
28498 After having installed and configured SpamAssassin, start the spamd daemon. By
28499 default, it listens on 127.0.0.1, TCP port 783. If you use another host or port
28500 for spamd, you must set the spamd_address option in the global part of the Exim
28501 configuration as follows (example):
28502
28503 spamd_address = 192.168.99.45 387
28504
28505 You do not need to set this option if you use the default. As of version 2.60,
28506 spamd also supports communication over UNIX sockets. If you want to use these,
28507 supply spamd_address with an absolute file name instead of a address/port pair:
28508
28509 spamd_address = /var/run/spamd_socket
28510
28511 You can have multiple spamd servers to improve scalability. These can reside on
28512 other hardware reachable over the network. To specify multiple spamd servers,
28513 put multiple address/port pairs in the spamd_address option, separated with
28514 colons:
28515
28516 spamd_address = 192.168.2.10 783 : \
28517 192.168.2.11 783 : \
28518 192.168.2.12 783
28519
28520 Up to 32 spamd servers are supported. The servers are queried in a random
28521 fashion. When a server fails to respond to the connection attempt, all other
28522 servers are tried until one succeeds. If no server responds, the spam condition
28523 defers.
28524
28525 Warning: It is not possible to use the UNIX socket connection method with
28526 multiple spamd servers.
28527
28528 The spamd_address variable is expanded before use if it starts with a dollar
28529 sign. In this case, the expansion may return a string that is used as the list
28530 so that multiple spamd servers can be the result of an expansion.
28531
28532
28533 43.3 Calling SpamAssassin from an Exim ACL
28534 ------------------------------------------
28535
28536 Here is a simple example of the use of the spam condition in a DATA ACL:
28537
28538 deny message = This message was classified as SPAM
28539 spam = joe
28540
28541 The right-hand side of the spam condition specifies a name. This is relevant if
28542 you have set up multiple SpamAssassin profiles. If you do not want to scan
28543 using a specific profile, but rather use the SpamAssassin system-wide default
28544 profile, you can scan for an unknown name, or simply use "nobody". However, you
28545 must put something on the right-hand side.
28546
28547 The name allows you to use per-domain or per-user antispam profiles in
28548 principle, but this is not straightforward in practice, because a message may
28549 have multiple recipients, not necessarily all in the same domain. Because the
28550 spam condition has to be called from a DATA ACL in order to be able to read the
28551 contents of the message, the variables $local_part and $domain are not set.
28552
28553 The right-hand side of the spam condition is expanded before being used, so you
28554 can put lookups or conditions there. When the right-hand side evaluates to "0"
28555 or "false", no scanning is done and the condition fails immediately.
28556
28557 Scanning with SpamAssassin uses a lot of resources. If you scan every message,
28558 large ones may cause significant performance degradation. As most spam messages
28559 are quite small, it is recommended that you do not scan the big ones. For
28560 example:
28561
28562 deny message = This message was classified as SPAM
28563 condition = ${if < {$message_size}{10K}}
28564 spam = nobody
28565
28566 The spam condition returns true if the threshold specified in the user's
28567 SpamAssassin profile has been matched or exceeded. If you want to use the spam
28568 condition for its side effects (see the variables below), you can make it
28569 always return "true" by appending ":true" to the username.
28570
28571 When the spam condition is run, it sets up a number of expansion variables.
28572 These variables are saved with the received message, thus they are available
28573 for use at delivery time.
28574
28575 $spam_score
28576
28577 The spam score of the message, for example "3.4" or "30.5". This is useful
28578 for inclusion in log or reject messages.
28579
28580 $spam_score_int
28581
28582 The spam score of the message, multiplied by ten, as an integer value. For
28583 example "34" or "305". It may appear to disagree with $spam_score because
28584 $spam_score is rounded and $spam_score_int is truncated. The integer value
28585 is useful for numeric comparisons in conditions.
28586
28587 $spam_bar
28588
28589 A string consisting of a number of "+" or "-" characters, representing the
28590 integer part of the spam score value. A spam score of 4.4 would have a
28591 $spam_bar value of "++++". This is useful for inclusion in warning headers,
28592 since MUAs can match on such strings.
28593
28594 $spam_report
28595
28596 A multiline text table, containing the full SpamAssassin report for the
28597 message. Useful for inclusion in headers or reject messages.
28598
28599 The spam condition caches its results unless expansion in spamd_address was
28600 used. If you call it again with the same user name, it does not scan again, but
28601 rather returns the same values as before.
28602
28603 The spam condition returns DEFER if there is any error while running the
28604 message through SpamAssassin or if the expansion of spamd_address failed. If
28605 you want to treat DEFER as FAIL (to pass on to the next ACL statement block),
28606 append "/defer_ok" to the right-hand side of the spam condition, like this:
28607
28608 deny message = This message was classified as SPAM
28609 spam = joe/defer_ok
28610
28611 This causes messages to be accepted even if there is a problem with spamd.
28612
28613 Here is a longer, commented example of the use of the spam condition:
28614
28615 # put headers in all messages (no matter if spam or not)
28616 warn spam = nobody:true
28617 add_header = X-Spam-Score: $spam_score ($spam_bar)
28618 add_header = X-Spam-Report: $spam_report
28619
28620 # add second subject line with *SPAM* marker when message
28621 # is over threshold
28622 warn spam = nobody
28623 add_header = Subject: *SPAM* $h_Subject:
28624
28625 # reject spam at high scores (> 12)
28626 deny message = This message scored $spam_score spam points.
28627 spam = nobody:true
28628 condition = ${if >{$spam_score_int}{120}{1}{0}}
28629
28630
28631 43.4 Scanning MIME parts
28632 ------------------------
28633
28634 The acl_smtp_mime global option specifies an ACL that is called once for each
28635 MIME part of an SMTP message, including multipart types, in the sequence of
28636 their position in the message. Similarly, the acl_not_smtp_mime option
28637 specifies an ACL that is used for the MIME parts of non-SMTP messages. These
28638 options may both refer to the same ACL if you want the same processing in both
28639 cases.
28640
28641 These ACLs are called (possibly many times) just before the acl_smtp_data ACL
28642 in the case of an SMTP message, or just before the acl_not_smtp ACL in the case
28643 of a non-SMTP message. However, a MIME ACL is called only if the message
28644 contains a Content-Type: header line. When a call to a MIME ACL does not yield
28645 "accept", ACL processing is aborted and the appropriate result code is sent to
28646 the client. In the case of an SMTP message, the acl_smtp_data ACL is not called
28647 when this happens.
28648
28649 You cannot use the malware or spam conditions in a MIME ACL; these can only be
28650 used in the DATA or non-SMTP ACLs. However, you can use the regex condition to
28651 match against the raw MIME part. You can also use the mime_regex condition to
28652 match against the decoded MIME part (see section 43.5).
28653
28654 At the start of a MIME ACL, a number of variables are set from the header
28655 information for the relevant MIME part. These are described below. The contents
28656 of the MIME part are not by default decoded into a disk file except for MIME
28657 parts whose content-type is "message/rfc822". If you want to decode a MIME part
28658 into a disk file, you can use the decode condition. The general syntax is:
28659
28660 decode = [/<path>/]<filename>
28661
28662 The right hand side is expanded before use. After expansion, the value can be:
28663
28664 1. "0" or "false", in which case no decoding is done.
28665
28666 2. The string "default". In that case, the file is put in the temporary
28667 "default" directory <spool_directory>/scan/<message_id>/ with a sequential
28668 file name consisting of the message id and a sequence number. The full path
28669 and name is available in $mime_decoded_filename after decoding.
28670
28671 3. A full path name starting with a slash. If the full name is an existing
28672 directory, it is used as a replacement for the default directory. The
28673 filename is then sequentially assigned. If the path does not exist, it is
28674 used as the full path and file name.
28675
28676 4. If the string does not start with a slash, it is used as the filename, and
28677 the default path is then used.
28678
28679 The decode condition normally succeeds. It is only false for syntax errors or
28680 unusual circumstances such as memory shortages. You can easily decode a file
28681 with its original, proposed filename using
28682
28683 decode = $mime_filename
28684
28685 However, you should keep in mind that $mime_filename might contain anything. If
28686 you place files outside of the default path, they are not automatically
28687 unlinked.
28688
28689 For RFC822 attachments (these are messages attached to messages, with a
28690 content-type of "message/rfc822"), the ACL is called again in the same manner
28691 as for the primary message, only that the $mime_is_rfc822 expansion variable is
28692 set (see below). Attached messages are always decoded to disk before being
28693 checked, and the files are unlinked once the check is done.
28694
28695 The MIME ACL supports the regex and mime_regex conditions. These can be used to
28696 match regular expressions against raw and decoded MIME parts, respectively.
28697 They are described in section 43.5.
28698
28699 The following list describes all expansion variables that are available in the
28700 MIME ACL:
28701
28702 $mime_boundary
28703
28704 If the current part is a multipart (see $mime_is_multipart) below, it
28705 should have a boundary string, which is stored in this variable. If the
28706 current part has no boundary parameter in the Content-Type: header, this
28707 variable contains the empty string.
28708
28709 $mime_charset
28710
28711 This variable contains the character set identifier, if one was found in
28712 the Content-Type: header. Examples for charset identifiers are:
28713
28714 us-ascii
28715 gb2312 (Chinese)
28716 iso-8859-1
28717
28718 Please note that this value is not normalized, so you should do matches
28719 case-insensitively.
28720
28721 $mime_content_description
28722
28723 This variable contains the normalized content of the Content-Description:
28724 header. It can contain a human-readable description of the parts content.
28725 Some implementations repeat the filename for attachments here, but they are
28726 usually only used for display purposes.
28727
28728 $mime_content_disposition
28729
28730 This variable contains the normalized content of the Content-Disposition:
28731 header. You can expect strings like "attachment" or "inline" here.
28732
28733 $mime_content_id
28734
28735 This variable contains the normalized content of the Content-ID: header.
28736 This is a unique ID that can be used to reference a part from another part.
28737
28738 $mime_content_size
28739
28740 This variable is set only after the decode modifier (see above) has been
28741 successfully run. It contains the size of the decoded part in kilobytes.
28742 The size is always rounded up to full kilobytes, so only a completely empty
28743 part has a $mime_content_size of zero.
28744
28745 $mime_content_transfer_encoding
28746
28747 This variable contains the normalized content of the
28748 Content-transfer-encoding: header. This is a symbolic name for an encoding
28749 type. Typical values are "base64" and "quoted-printable".
28750
28751 $mime_content_type
28752
28753 If the MIME part has a Content-Type: header, this variable contains its
28754 value, lowercased, and without any options (like "name" or "charset"). Here
28755 are some examples of popular MIME types, as they may appear in this
28756 variable:
28757
28758 text/plain
28759 text/html
28760 application/octet-stream
28761 image/jpeg
28762 audio/midi
28763
28764 If the MIME part has no Content-Type: header, this variable contains the
28765 empty string.
28766
28767 $mime_decoded_filename
28768
28769 This variable is set only after the decode modifier (see above) has been
28770 successfully run. It contains the full path and file name of the file
28771 containing the decoded data.
28772
28773 $mime_filename
28774
28775 This is perhaps the most important of the MIME variables. It contains a
28776 proposed filename for an attachment, if one was found in either the
28777 Content-Type: or Content-Disposition: headers. The filename will be RFC2047
28778 decoded, but no additional sanity checks are done. If no filename was
28779 found, this variable contains the empty string.
28780
28781 $mime_is_coverletter
28782
28783 This variable attempts to differentiate the "cover letter" of an e-mail
28784 from attached data. It can be used to clamp down on flashy or unnecessarily
28785 encoded content in the cover letter, while not restricting attachments at
28786 all.
28787
28788 The variable contains 1 (true) for a MIME part believed to be part of the
28789 cover letter, and 0 (false) for an attachment. At present, the algorithm is
28790 as follows:
28791
28792 1. The outermost MIME part of a message is always a cover letter.
28793
28794 2. If a multipart/alternative or multipart/related MIME part is a cover
28795 letter, so are all MIME subparts within that multipart.
28796
28797 3. If any other multipart is a cover letter, the first subpart is a cover
28798 letter, and the rest are attachments.
28799
28800 4. All parts contained within an attachment multipart are attachments.
28801
28802 As an example, the following will ban "HTML mail" (including that sent with
28803 alternative plain text), while allowing HTML files to be attached. HTML
28804 coverletter mail attached to non-HMTL coverletter mail will also be
28805 allowed:
28806
28807 deny message = HTML mail is not accepted here
28808 !condition = $mime_is_rfc822
28809 condition = $mime_is_coverletter
28810 condition = ${if eq{$mime_content_type}{text/html}{1}{0}}
28811
28812 $mime_is_multipart
28813
28814 This variable has the value 1 (true) when the current part has the main
28815 type "multipart", for example "multipart/alternative" or "multipart/mixed".
28816 Since multipart entities only serve as containers for other parts, you may
28817 not want to carry out specific actions on them.
28818
28819 $mime_is_rfc822
28820
28821 This variable has the value 1 (true) if the current part is not a part of
28822 the checked message itself, but part of an attached message. Attached
28823 message decoding is fully recursive.
28824
28825 $mime_part_count
28826
28827 This variable is a counter that is raised for each processed MIME part. It
28828 starts at zero for the very first part (which is usually a multipart). The
28829 counter is per-message, so it is reset when processing RFC822 attachments
28830 (see $mime_is_rfc822). The counter stays set after acl_smtp_mime is
28831 complete, so you can use it in the DATA ACL to determine the number of MIME
28832 parts of a message. For non-MIME messages, this variable contains the value
28833 -1.
28834
28835
28836 43.5 Scanning with regular expressions
28837 --------------------------------------
28838
28839 You can specify your own custom regular expression matches on the full body of
28840 the message, or on individual MIME parts.
28841
28842 The regex condition takes one or more regular expressions as arguments and
28843 matches them against the full message (when called in the DATA ACL) or a raw
28844 MIME part (when called in the MIME ACL). The regex condition matches linewise,
28845 with a maximum line length of 32K characters. That means you cannot have
28846 multiline matches with the regex condition.
28847
28848 The mime_regex condition can be called only in the MIME ACL. It matches up to
28849 32K of decoded content (the whole content at once, not linewise). If the part
28850 has not been decoded with the decode modifier earlier in the ACL, it is decoded
28851 automatically when mime_regex is executed (using default path and filename
28852 values). If the decoded data is larger than 32K, only the first 32K characters
28853 are checked.
28854
28855 The regular expressions are passed as a colon-separated list. To include a
28856 literal colon, you must double it. Since the whole right-hand side string is
28857 expanded before being used, you must also escape dollar signs and backslashes
28858 with more backslashes, or use the "\N" facility to disable expansion. Here is a
28859 simple example that contains two regular expressions:
28860
28861 deny message = contains blacklisted regex ($regex_match_string)
28862 regex = [Mm]ortgage : URGENT BUSINESS PROPOSAL
28863
28864 The conditions returns true if any one of the regular expressions matches. The
28865 $regex_match_string expansion variable is then set up and contains the matching
28866 regular expression.
28867
28868 Warning: With large messages, these conditions can be fairly CPU-intensive.
28869
28870
28871 43.6 The demime condition
28872 -------------------------
28873
28874 The demime ACL condition provides MIME unpacking, sanity checking and file
28875 extension blocking. It is usable only in the DATA and non-SMTP ACLs. The demime
28876 condition uses a simpler interface to MIME decoding than the MIME ACL
28877 functionality, but provides no additional facilities. Please note that this
28878 condition is deprecated and kept only for backward compatibility. You must set
28879 the WITH_OLD_DEMIME option in Local/Makefile at build time to be able to use
28880 the demime condition.
28881
28882 The demime condition unpacks MIME containers in the message. It detects errors
28883 in MIME containers and can match file extensions found in the message against a
28884 list. Using this facility produces files containing the unpacked MIME parts of
28885 the message in the temporary scan directory. If you do antivirus scanning, it
28886 is recommended that you use the demime condition before the antivirus (malware)
28887 condition.
28888
28889 On the right-hand side of the demime condition you can pass a colon-separated
28890 list of file extensions that it should match against. For example:
28891
28892 deny message = Found blacklisted file attachment
28893 demime = vbs:com:bat:pif:prf:lnk
28894
28895 If one of the file extensions is found, the condition is true, otherwise it is
28896 false. If there is a temporary error while demimeing (for example, "disk
28897 full"), the condition defers, and the message is temporarily rejected (unless
28898 the condition is on a warn verb).
28899
28900 The right-hand side is expanded before being treated as a list, so you can have
28901 conditions and lookups there. If it expands to an empty string, "false", or
28902 zero ("0"), no demimeing is done and the condition is false.
28903
28904 The demime condition set the following variables:
28905
28906 $demime_errorlevel
28907
28908 When an error is detected in a MIME container, this variable contains the
28909 severity of the error, as an integer number. The higher the value, the more
28910 severe the error (the current maximum value is 3). If this variable is
28911 unset or zero, no error occurred.
28912
28913 $demime_reason
28914
28915 When $demime_errorlevel is greater than zero, this variable contains a
28916 human-readable text string describing the MIME error that occurred.
28917
28918 $found_extension
28919
28920 When the demime condition is true, this variable contains the file
28921 extension it found.
28922
28923 Both $demime_errorlevel and $demime_reason are set by the first call of the
28924 demime condition, and are not changed on subsequent calls.
28925
28926 If you do not want to check for file extensions, but rather use the demime
28927 condition for unpacking or error checking purposes, pass "*" as the right-hand
28928 side value. Here is a more elaborate example of how to use this facility:
28929
28930 # Reject messages with serious MIME container errors
28931 deny message = Found MIME error ($demime_reason).
28932 demime = *
28933 condition = ${if >{$demime_errorlevel}{2}{1}{0}}
28934
28935 # Reject known virus spreading file extensions.
28936 # Accepting these is pretty much braindead.
28937 deny message = contains $found_extension file (blacklisted).
28938 demime = com:vbs:bat:pif:scr
28939
28940 # Freeze .exe and .doc files. Postmaster can
28941 # examine them and eventually thaw them.
28942 deny log_message = Another $found_extension file.
28943 demime = exe:doc
28944 control = freeze
28945
28946
28947
28948 ===============================================================================
28949 44. ADDING A LOCAL SCAN FUNCTION TO EXIM
28950
28951 In these days of email worms, viruses, and ever-increasing spam, some sites
28952 want to apply a lot of checking to messages before accepting them.
28953
28954 The content scanning extension (chapter 43) has facilities for passing messages
28955 to external virus and spam scanning software. You can also do a certain amount
28956 in Exim itself through string expansions and the condition condition in the ACL
28957 that runs after the SMTP DATA command or the ACL for non-SMTP messages (see
28958 chapter 42), but this has its limitations.
28959
28960 To allow for further customization to a site's own requirements, there is the
28961 possibility of linking Exim with a private message scanning function, written
28962 in C. If you want to run code that is written in something other than C, you
28963 can of course use a little C stub to call it.
28964
28965 The local scan function is run once for every incoming message, at the point
28966 when Exim is just about to accept the message. It can therefore be used to
28967 control non-SMTP messages from local processes as well as messages arriving via
28968 SMTP.
28969
28970 Exim applies a timeout to calls of the local scan function, and there is an
28971 option called local_scan_timeout for setting it. The default is 5 minutes. Zero
28972 means "no timeout". Exim also sets up signal handlers for SIGSEGV, SIGILL,
28973 SIGFPE, and SIGBUS before calling the local scan function, so that the most
28974 common types of crash are caught. If the timeout is exceeded or one of those
28975 signals is caught, the incoming message is rejected with a temporary error if
28976 it is an SMTP message. For a non-SMTP message, the message is dropped and Exim
28977 ends with a non-zero code. The incident is logged on the main and reject logs.
28978
28979
28980 44.1 Building Exim to use a local scan function
28981 -----------------------------------------------
28982
28983 To make use of the local scan function feature, you must tell Exim where your
28984 function is before building Exim, by setting LOCAL_SCAN_SOURCE in your Local/
28985 Makefile. A recommended place to put it is in the Local directory, so you might
28986 set
28987
28988 LOCAL_SCAN_SOURCE=Local/local_scan.c
28989
28990 for example. The function must be called local_scan(). It is called by Exim
28991 after it has received a message, when the success return code is about to be
28992 sent. This is after all the ACLs have been run. The return code from your
28993 function controls whether the message is actually accepted or not. There is a
28994 commented template function (that just accepts the message) in the file _src/
28995 local_scan.c_.
28996
28997 If you want to make use of Exim's run time configuration file to set options
28998 for your local_scan() function, you must also set
28999
29000 LOCAL_SCAN_HAS_OPTIONS=yes
29001
29002 in Local/Makefile (see section 44.3 below).
29003
29004
29005 44.2 API for local_scan()
29006 -------------------------
29007
29008 You must include this line near the start of your code:
29009
29010 #include "local_scan.h"
29011
29012 This header file defines a number of variables and other values, and the
29013 prototype for the function itself. Exim is coded to use unsigned char values
29014 almost exclusively, and one of the things this header defines is a shorthand
29015 for "unsigned char" called "uschar". It also contains the following macro
29016 definitions, to simplify casting character strings and pointers to character
29017 strings:
29018
29019 #define CS (char *)
29020 #define CCS (const char *)
29021 #define CSS (char **)
29022 #define US (unsigned char *)
29023 #define CUS (const unsigned char *)
29024 #define USS (unsigned char **)
29025
29026 The function prototype for local_scan() is:
29027
29028 extern int local_scan(int fd, uschar **return_text);
29029
29030 The arguments are as follows:
29031
29032 * fd is a file descriptor for the file that contains the body of the message
29033 (the -D file). The file is open for reading and writing, but updating it is
29034 not recommended. Warning: You must not close this file descriptor.
29035
29036 The descriptor is positioned at character 19 of the file, which is the
29037 first character of the body itself, because the first 19 characters are the
29038 message id followed by "-D" and a newline. If you rewind the file, you
29039 should use the macro SPOOL_DATA_START_OFFSET to reset to the start of the
29040 data, just in case this changes in some future version.
29041
29042 * return_text is an address which you can use to return a pointer to a text
29043 string at the end of the function. The value it points to on entry is NULL.
29044
29045 The function must return an int value which is one of the following macros:
29046
29047 "LOCAL_SCAN_ACCEPT"
29048
29049 The message is accepted. If you pass back a string of text, it is saved
29050 with the message, and made available in the variable $local_scan_data. No
29051 newlines are permitted (if there are any, they are turned into spaces) and
29052 the maximum length of text is 1000 characters.
29053
29054 "LOCAL_SCAN_ACCEPT_FREEZE"
29055
29056 This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is
29057 queued without immediate delivery, and is frozen.
29058
29059 "LOCAL_SCAN_ACCEPT_QUEUE"
29060
29061 This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is
29062 queued without immediate delivery.
29063
29064 "LOCAL_SCAN_REJECT"
29065
29066 The message is rejected; the returned text is used as an error message
29067 which is passed back to the sender and which is also logged. Newlines are
29068 permitted - they cause a multiline response for SMTP rejections, but are
29069 converted to "\n" in log lines. If no message is given, "Administrative
29070 prohibition" is used.
29071
29072 "LOCAL_SCAN_TEMPREJECT"
29073
29074 The message is temporarily rejected; the returned text is used as an error
29075 message as for LOCAL_SCAN_REJECT. If no message is given, "Temporary local
29076 problem" is used.
29077
29078 "LOCAL_SCAN_REJECT_NOLOGHDR"
29079
29080 This behaves as LOCAL_SCAN_REJECT, except that the header of the rejected
29081 message is not written to the reject log. It has the effect of unsetting
29082 the rejected_header log selector for just this rejection. If
29083 rejected_header is already unset (see the discussion of the log_selection
29084 option in section 51.15), this code is the same as LOCAL_SCAN_REJECT.
29085
29086 "LOCAL_SCAN_TEMPREJECT_NOLOGHDR"
29087
29088 This code is a variation of LOCAL_SCAN_TEMPREJECT in the same way that
29089 LOCAL_SCAN_REJECT_NOLOGHDR is a variation of LOCAL_SCAN_REJECT.
29090
29091 If the message is not being received by interactive SMTP, rejections are
29092 reported by writing to stderr or by sending an email, as configured by the -oe
29093 command line options.
29094
29095
29096 44.3 Configuration options for local_scan()
29097 -------------------------------------------
29098
29099 It is possible to have option settings in the main configuration file that set
29100 values in static variables in the local_scan() module. If you want to do this,
29101 you must have the line
29102
29103 LOCAL_SCAN_HAS_OPTIONS=yes
29104
29105 in your Local/Makefile when you build Exim. (This line is in OS/
29106 Makefile-Default, commented out). Then, in the local_scan() source file, you
29107 must define static variables to hold the option values, and a table to define
29108 them.
29109
29110 The table must be a vector called local_scan_options, of type "optionlist".
29111 Each entry is a triplet, consisting of a name, an option type, and a pointer to
29112 the variable that holds the value. The entries must appear in alphabetical
29113 order. Following local_scan_options you must also define a variable called
29114 local_scan_options_count that contains the number of entries in the table. Here
29115 is a short example, showing two kinds of option:
29116
29117 static int my_integer_option = 42;
29118 static uschar *my_string_option = US"a default string";
29119
29120 optionlist local_scan_options[] = {
29121 { "my_integer", opt_int, &my_integer_option },
29122 { "my_string", opt_stringptr, &my_string_option }
29123 };
29124
29125 int local_scan_options_count =
29126 sizeof(local_scan_options)/sizeof(optionlist);
29127
29128 The values of the variables can now be changed from Exim's runtime
29129 configuration file by including a local scan section as in this example:
29130
29131 begin local_scan
29132 my_integer = 99
29133 my_string = some string of text...
29134
29135 The available types of option data are as follows:
29136
29137 opt_bool
29138
29139 This specifies a boolean (true/false) option. The address should point to a
29140 variable of type "BOOL", which will be set to TRUE or FALSE, which are
29141 macros that are defined as "1" and "0", respectively. If you want to detect
29142 whether such a variable has been set at all, you can initialize it to
29143 TRUE_UNSET. (BOOL variables are integers underneath, so can hold more than
29144 two values.)
29145
29146 opt_fixed
29147
29148 This specifies a fixed point number, such as is used for load averages. The
29149 address should point to a variable of type "int". The value is stored
29150 multiplied by 1000, so, for example, 1.4142 is truncated and stored as
29151 1414.
29152
29153 opt_int
29154
29155 This specifies an integer; the address should point to a variable of type
29156 "int". The value may be specified in any of the integer formats accepted by
29157 Exim.
29158
29159 opt_mkint
29160
29161 This is the same as opt_int, except that when such a value is output in a
29162 -bP listing, if it is an exact number of kilobytes or megabytes, it is
29163 printed with the suffix K or M.
29164
29165 opt_octint
29166
29167 This also specifies an integer, but the value is always interpreted as an
29168 octal integer, whether or not it starts with the digit zero, and it is
29169 always output in octal.
29170
29171 opt_stringptr
29172
29173 This specifies a string value; the address must be a pointer to a variable
29174 that points to a string (for example, of type "uschar *").
29175
29176 opt_time
29177
29178 This specifies a time interval value. The address must point to a variable
29179 of type "int". The value that is placed there is a number of seconds.
29180
29181 If the -bP command line option is followed by "local_scan", Exim prints out the
29182 values of all the local_scan() options.
29183
29184
29185 44.4 Available Exim variables
29186 -----------------------------
29187
29188 The header local_scan.h gives you access to a number of C variables. These are
29189 the only ones that are guaranteed to be maintained from release to release.
29190 Note, however, that you can obtain the value of any Exim expansion variable,
29191 including $recipients, by calling expand_string(). The exported C variables are
29192 as follows:
29193
29194 int body_linecount
29195
29196 This variable contains the number of lines in the message's body.
29197
29198 int body_zerocount
29199
29200 This variable contains the number of binary zero bytes in the message's
29201 body.
29202
29203 unsigned int debug_selector
29204
29205 This variable is set to zero when no debugging is taking place. Otherwise,
29206 it is a bitmap of debugging selectors. Two bits are identified for use in
29207 local_scan(); they are defined as macros:
29208
29209 * The "D_v" bit is set when -v was present on the command line. This is a
29210 testing option that is not privileged - any caller may set it. All the
29211 other selector bits can be set only by admin users.
29212
29213 * The "D_local_scan" bit is provided for use by local_scan(); it is set
29214 by the "+local_scan" debug selector. It is not included in the default
29215 set of debugging bits.
29216
29217 Thus, to write to the debugging output only when "+local_scan" has been
29218 selected, you should use code like this:
29219
29220 if ((debug_selector & D_local_scan) != 0)
29221 debug_printf("xxx", ...);
29222
29223 uschar *expand_string_message
29224
29225 After a failing call to expand_string() (returned value NULL), the variable
29226 expand_string_message contains the error message, zero-terminated.
29227
29228 header_line *header_list
29229
29230 A pointer to a chain of header lines. The header_line structure is
29231 discussed below.
29232
29233 header_line *header_last
29234
29235 A pointer to the last of the header lines.
29236
29237 uschar *headers_charset
29238
29239 The value of the headers_charset configuration option.
29240
29241 BOOL host_checking
29242
29243 This variable is TRUE during a host checking session that is initiated by
29244 the -bh command line option.
29245
29246 uschar *interface_address
29247
29248 The IP address of the interface that received the message, as a string.
29249 This is NULL for locally submitted messages.
29250
29251 int interface_port
29252
29253 The port on which this message was received. When testing with the -bh
29254 command line option, the value of this variable is -1 unless a port has
29255 been specified via the -oMi option.
29256
29257 uschar *message_id
29258
29259 This variable contains Exim's message id for the incoming message (the
29260 value of $message_exim_id) as a zero-terminated string.
29261
29262 uschar *received_protocol
29263
29264 The name of the protocol by which the message was received.
29265
29266 int recipients_count
29267
29268 The number of accepted recipients.
29269
29270 recipient_item *recipients_list
29271
29272 The list of accepted recipients, held in a vector of length
29273 recipients_count. The recipient_item structure is discussed below. You can
29274 add additional recipients by calling receive_add_recipient() (see below).
29275 You can delete recipients by removing them from the vector and adjusting
29276 the value in recipients_count. In particular, by setting recipients_count
29277 to zero you remove all recipients. If you then return the value
29278 "LOCAL_SCAN_ACCEPT", the message is accepted, but immediately blackholed.
29279 To replace the recipients, you can set recipients_count to zero and then
29280 call receive_add_recipient() as often as needed.
29281
29282 uschar *sender_address
29283
29284 The envelope sender address. For bounce messages this is the empty string.
29285
29286 uschar *sender_host_address
29287
29288 The IP address of the sending host, as a string. This is NULL for
29289 locally-submitted messages.
29290
29291 uschar *sender_host_authenticated
29292
29293 The name of the authentication mechanism that was used, or NULL if the
29294 message was not received over an authenticated SMTP connection.
29295
29296 uschar *sender_host_name
29297
29298 The name of the sending host, if known.
29299
29300 int sender_host_port
29301
29302 The port on the sending host.
29303
29304 BOOL smtp_input
29305
29306 This variable is TRUE for all SMTP input, including BSMTP.
29307
29308 BOOL smtp_batched_input
29309
29310 This variable is TRUE for BSMTP input.
29311
29312 int store_pool
29313
29314 The contents of this variable control which pool of memory is used for new
29315 requests. See section 44.8 for details.
29316
29317
29318 44.5 Structure of header lines
29319 ------------------------------
29320
29321 The header_line structure contains the members listed below. You can add
29322 additional header lines by calling the header_add() function (see below). You
29323 can cause header lines to be ignored (deleted) by setting their type to *.
29324
29325 struct header_line *next
29326
29327 A pointer to the next header line, or NULL for the last line.
29328
29329 int type
29330
29331 A code identifying certain headers that Exim recognizes. The codes are
29332 printing characters, and are documented in chapter 55 of this manual.
29333 Notice in particular that any header line whose type is * is not
29334 transmitted with the message. This flagging is used for header lines that
29335 have been rewritten, or are to be removed (for example, Envelope-sender:
29336 header lines.) Effectively, * means "deleted".
29337
29338 int slen
29339
29340 The number of characters in the header line, including the terminating and
29341 any internal newlines.
29342
29343 uschar *text
29344
29345 A pointer to the text of the header. It always ends with a newline,
29346 followed by a zero byte. Internal newlines are preserved.
29347
29348
29349 44.6 Structure of recipient items
29350 ---------------------------------
29351
29352 The recipient_item structure contains these members:
29353
29354 uschar *address
29355
29356 This is a pointer to the recipient address as it was received.
29357
29358 int pno
29359
29360 This is used in later Exim processing when top level addresses are created
29361 by the one_time option. It is not relevant at the time local_scan() is run
29362 and must always contain -1 at this stage.
29363
29364 uschar *errors_to
29365
29366 If this value is not NULL, bounce messages caused by failing to deliver to
29367 the recipient are sent to the address it contains. In other words, it
29368 overrides the envelope sender for this one recipient. (Compare the
29369 errors_to generic router option.) If a local_scan() function sets an
29370 errors_to field to an unqualified address, Exim qualifies it using the
29371 domain from qualify_recipient. When local_scan() is called, the errors_to
29372 field is NULL for all recipients.
29373
29374
29375 44.7 Available Exim functions
29376 -----------------------------
29377
29378 The header local_scan.h gives you access to a number of Exim functions. These
29379 are the only ones that are guaranteed to be maintained from release to release:
29380
29381 pid_t child_open
29382 (uschar **argv, uschar **envp, int newumask, int *infdptr, int *outfdptr,
29383 BOOL make_leader)
29384
29385 This function creates a child process that runs the command specified by
29386 argv. The environment for the process is specified by envp, which can be
29387 NULL if no environment variables are to be passed. A new umask is supplied
29388 for the process in newumask.
29389
29390 Pipes to the standard input and output of the new process are set up and
29391 returned to the caller via the infdptr and outfdptr arguments. The standard
29392 error is cloned to the standard output. If there are any file descriptors
29393 "in the way" in the new process, they are closed. If the final argument is
29394 TRUE, the new process is made into a process group leader.
29395
29396 The function returns the pid of the new process, or -1 if things go wrong.
29397
29398 int child_close(pid_t pid, int timeout)
29399
29400 This function waits for a child process to terminate, or for a timeout (in
29401 seconds) to expire. A timeout value of zero means wait as long as it takes.
29402 The return value is as follows:
29403
29404 * >= 0
29405
29406 The process terminated by a normal exit and the value is the process
29407 ending status.
29408
29409 * < 0 and > -256
29410
29411 The process was terminated by a signal and the value is the negation of
29412 the signal number.
29413
29414 * -256
29415
29416 The process timed out.
29417
29418 * -257
29419
29420 The was some other error in wait(); errno is still set.
29421
29422 pid_t child_open_exim(int *fd)
29423
29424 This function provide you with a means of submitting a new message to Exim.
29425 (Of course, you can also call /usr/sbin/sendmail yourself if you want, but
29426 this packages it all up for you.) The function creates a pipe, forks a
29427 subprocess that is running
29428
29429 exim -t -oem -oi -f <>
29430
29431 and returns to you (via the "int *" argument) a file descriptor for the
29432 pipe that is connected to the standard input. The yield of the function is
29433 the PID of the subprocess. You can then write a message to the file
29434 descriptor, with recipients in To:, Cc:, and/or Bcc: header lines.
29435
29436 When you have finished, call child_close() to wait for the process to
29437 finish and to collect its ending status. A timeout value of zero is usually
29438 fine in this circumstance. Unless you have made a mistake with the
29439 recipient addresses, you should get a return code of zero.
29440
29441 pid_t child_open_exim2(int *fd, uschar *sender, uschar *sender_authentication)
29442
29443 This function is a more sophisticated version of child_open(). The command
29444 that it runs is:
29445
29446 exim -t -oem -oi -f sender -oMas sender_authentication
29447
29448 The third argument may be NULL, in which case the -oMas option is omitted.
29449
29450 void debug_printf(char *, ...)
29451
29452 This is Exim's debugging function, with arguments as for (printf(). The
29453 output is written to the standard error stream. If no debugging is
29454 selected, calls to debug_printf() have no effect. Normally, you should make
29455 calls conditional on the "local_scan" debug selector by coding like this:
29456
29457 if ((debug_selector & D_local_scan) != 0)
29458 debug_printf("xxx", ...);
29459
29460 uschar *expand_string(uschar *string)
29461
29462 This is an interface to Exim's string expansion code. The return value is
29463 the expanded string, or NULL if there was an expansion failure. The C
29464 variable expand_string_message contains an error message after an expansion
29465 failure. If expansion does not change the string, the return value is the
29466 pointer to the input string. Otherwise, the return value points to a new
29467 block of memory that was obtained by a call to store_get(). See section
29468 44.8 below for a discussion of memory handling.
29469
29470 void header_add(int type, char *format, ...)
29471
29472 This function allows you to an add additional header line at the end of the
29473 existing ones. The first argument is the type, and should normally be a
29474 space character. The second argument is a format string and any number of
29475 substitution arguments as for sprintf(). You may include internal newlines
29476 if you want, and you must ensure that the string ends with a newline.
29477
29478 void header_add_at_position
29479 (BOOL after, uschar *name, BOOL topnot, int type, char *format, ...)
29480
29481 This function adds a new header line at a specified point in the header
29482 chain. The header itself is specified as for header_add().
29483
29484 If name is NULL, the new header is added at the end of the chain if after
29485 is true, or at the start if after is false. If name is not NULL, the header
29486 lines are searched for the first non-deleted header that matches the name.
29487 If one is found, the new header is added before it if after is false. If
29488 after is true, the new header is added after the found header and any
29489 adjacent subsequent ones with the same name (even if marked "deleted"). If
29490 no matching non-deleted header is found, the topnot option controls where
29491 the header is added. If it is true, addition is at the top; otherwise at
29492 the bottom. Thus, to add a header after all the Received: headers, or at
29493 the top if there are no Received: headers, you could use
29494
29495 header_add_at_position(TRUE, US"Received", TRUE,
29496 ' ', "X-xxx: ...");
29497
29498 Normally, there is always at least one non-deleted Received: header, but
29499 there may not be if received_header_text expands to an empty string.
29500
29501 void header_remove(int occurrence, uschar *name)
29502
29503 This function removes header lines. If occurrence is zero or negative, all
29504 occurrences of the header are removed. If occurrence is greater than zero,
29505 that particular instance of the header is removed. If no header(s) can be
29506 found that match the specification, the function does nothing.
29507
29508 BOOL header_testname(header_line *hdr, uschar *name, int length, BOOL notdel)
29509
29510 This function tests whether the given header has the given name. It is not
29511 just a string comparison, because white space is permitted between the name
29512 and the colon. If the notdel argument is true, a false return is forced for
29513 all "deleted" headers; otherwise they are not treated specially. For
29514 example:
29515
29516 if (header_testname(h, US"X-Spam", 6, TRUE)) ...
29517
29518 uschar *lss_b64encode(uschar *cleartext, int length)
29519
29520 This function base64-encodes a string, which is passed by address and
29521 length. The text may contain bytes of any value, including zero. The result
29522 is passed back in dynamic memory that is obtained by calling store_get().
29523 It is zero-terminated.
29524
29525 int lss_b64decode(uschar *codetext, uschar **cleartext)
29526
29527 This function decodes a base64-encoded string. Its arguments are a
29528 zero-terminated base64-encoded string and the address of a variable that is
29529 set to point to the result, which is in dynamic memory. The length of the
29530 decoded string is the yield of the function. If the input is invalid base64
29531 data, the yield is -1. A zero byte is added to the end of the output string
29532 to make it easy to interpret as a C string (assuming it contains no zeros
29533 of its own). The added zero byte is not included in the returned count.
29534
29535 int lss_match_domain(uschar *domain, uschar *list)
29536
29537 This function checks for a match in a domain list. Domains are always
29538 matched caselessly. The return value is one of the following:
29539
29540 OK match succeeded
29541 FAIL match failed
29542 DEFER match deferred
29543
29544 DEFER is usually caused by some kind of lookup defer, such as the inability
29545 to contact a database.
29546
29547 int lss_match_local_part(uschar *localpart, uschar *list, BOOL caseless)
29548
29549 This function checks for a match in a local part list. The third argument
29550 controls case-sensitivity. The return values are as for lss_match_domain().
29551
29552 int lss_match_address(uschar *address, uschar *list, BOOL caseless)
29553
29554 This function checks for a match in an address list. The third argument
29555 controls the case-sensitivity of the local part match. The domain is always
29556 matched caselessly. The return values are as for lss_match_domain().
29557
29558 int lss_match_host(uschar *host_name, uschar *host_address, uschar *list)
29559
29560 This function checks for a match in a host list. The most common usage is
29561 expected to be
29562
29563 lss_match_host(sender_host_name, sender_host_address, ...)
29564
29565 An empty address field matches an empty item in the host list. If the host
29566 name is NULL, the name corresponding to $sender_host_address is
29567 automatically looked up if a host name is required to match an item in the
29568 list. The return values are as for lss_match_domain(), but in addition,
29569 lss_match_host() returns ERROR in the case when it had to look up a host
29570 name, but the lookup failed.
29571
29572 void log_write(unsigned int selector, int which, char *format, ...)
29573
29574 This function writes to Exim's log files. The first argument should be zero
29575 (it is concerned with log_selector). The second argument can be "LOG_MAIN"
29576 or "LOG_REJECT" or "LOG_PANIC" or the inclusive "or" of any combination of
29577 them. It specifies to which log or logs the message is written. The
29578 remaining arguments are a format and relevant insertion arguments. The
29579 string should not contain any newlines, not even at the end.
29580
29581 void receive_add_recipient(uschar *address, int pno)
29582
29583 This function adds an additional recipient to the message. The first
29584 argument is the recipient address. If it is unqualified (has no domain), it
29585 is qualified with the qualify_recipient domain. The second argument must
29586 always be -1.
29587
29588 This function does not allow you to specify a private errors_to address (as
29589 described with the structure of recipient_item above), because it pre-dates
29590 the addition of that field to the structure. However, it is easy to add
29591 such a value afterwards. For example:
29592
29593 receive_add_recipient(US"monitor@mydom.example", -1);
29594 recipients_list[recipients_count-1].errors_to =
29595 US"postmaster@mydom.example";
29596
29597 BOOL receive_remove_recipient(uschar *recipient)
29598
29599 This is a convenience function to remove a named recipient from the list of
29600 recipients. It returns true if a recipient was removed, and false if no
29601 matching recipient could be found. The argument must be a complete email
29602 address.
29603
29604 uschar rfc2047_decode
29605 (uschar *string, BOOL lencheck, uschar *target, int zeroval, int *lenptr,
29606 uschar **error)
29607
29608 This function decodes strings that are encoded according to RFC 2047.
29609 Typically these are the contents of header lines. First, each "encoded
29610 word" is decoded from the Q or B encoding into a byte-string. Then, if
29611 provided with the name of a charset encoding, and if the iconv() function
29612 is available, an attempt is made to translate the result to the named
29613 character set. If this fails, the binary string is returned with an error
29614 message.
29615
29616 The first argument is the string to be decoded. If lencheck is TRUE, the
29617 maximum MIME word length is enforced. The third argument is the target
29618 encoding, or NULL if no translation is wanted.
29619
29620 If a binary zero is encountered in the decoded string, it is replaced by
29621 the contents of the zeroval argument. For use with Exim headers, the value
29622 must not be 0 because header lines are handled as zero-terminated strings.
29623
29624 The function returns the result of processing the string, zero-terminated;
29625 if lenptr is not NULL, the length of the result is set in the variable to
29626 which it points. When zeroval is 0, lenptr should not be NULL.
29627
29628 If an error is encountered, the function returns NULL and uses the error
29629 argument to return an error message. The variable pointed to by error is
29630 set to NULL if there is no error; it may be set non-NULL even when the
29631 function returns a non-NULL value if decoding was successful, but there was
29632 a problem with translation.
29633
29634 int smtp_fflush(void)
29635
29636 This function is used in conjunction with smtp_printf(), as described
29637 below.
29638
29639 void smtp_printf(char *, ...)
29640
29641 The arguments of this function are like printf(); it writes to the SMTP
29642 output stream. You should use this function only when there is an SMTP
29643 output stream, that is, when the incoming message is being received via
29644 interactive SMTP. This is the case when smtp_input is TRUE and
29645 smtp_batched_input is FALSE. If you want to test for an incoming message
29646 from another host (as opposed to a local process that used the -bs command
29647 line option), you can test the value of sender_host_address, which is
29648 non-NULL when a remote host is involved.
29649
29650 If an SMTP TLS connection is established, smtp_printf() uses the TLS output
29651 function, so it can be used for all forms of SMTP connection.
29652
29653 Strings that are written by smtp_printf() from within local_scan() must
29654 start with an appropriate response code: 550 if you are going to return
29655 LOCAL_SCAN_REJECT, 451 if you are going to return LOCAL_SCAN_TEMPREJECT,
29656 and 250 otherwise. Because you are writing the initial lines of a
29657 multi-line response, the code must be followed by a hyphen to indicate that
29658 the line is not the final response line. You must also ensure that the
29659 lines you write terminate with CRLF. For example:
29660
29661 smtp_printf("550-this is some extra info\r\n");
29662 return LOCAL_SCAN_REJECT;
29663
29664 Note that you can also create multi-line responses by including newlines in
29665 the data returned via the return_text argument. The added value of using
29666 smtp_printf() is that, for instance, you could introduce delays between
29667 multiple output lines.
29668
29669 The smtp_printf() function does not return any error indication, because it
29670 does not automatically flush pending output, and therefore does not test
29671 the state of the stream. (In the main code of Exim, flushing and error
29672 detection is done when Exim is ready for the next SMTP input command.) If
29673 you want to flush the output and check for an error (for example, the
29674 dropping of a TCP/IP connection), you can call smtp_fflush(), which has no
29675 arguments. It flushes the output stream, and returns a non-zero value if
29676 there is an error.
29677
29678 void *store_get(int)
29679
29680 This function accesses Exim's internal store (memory) manager. It gets a
29681 new chunk of memory whose size is given by the argument. Exim bombs out if
29682 it ever runs out of memory. See the next section for a discussion of memory
29683 handling.
29684
29685 void *store_get_perm(int)
29686
29687 This function is like store_get(), but it always gets memory from the
29688 permanent pool. See the next section for a discussion of memory handling.
29689
29690 uschar *string_copy(uschar *string)
29691
29692 See below.
29693
29694 uschar *string_copyn(uschar *string, int length)
29695
29696 See below.
29697
29698 uschar *string_sprintf(char *format, ...)
29699
29700 These three functions create strings using Exim's dynamic memory
29701 facilities. The first makes a copy of an entire string. The second copies
29702 up to a maximum number of characters, indicated by the second argument. The
29703 third uses a format and insertion arguments to create a new string. In each
29704 case, the result is a pointer to a new string in the current memory pool.
29705 See the next section for more discussion.
29706
29707
29708 44.8 More about Exim's memory handling
29709 --------------------------------------
29710
29711 No function is provided for freeing memory, because that is never needed. The
29712 dynamic memory that Exim uses when receiving a message is automatically
29713 recycled if another message is received by the same process (this applies only
29714 to incoming SMTP connections - other input methods can supply only one message
29715 at a time). After receiving the last message, a reception process terminates.
29716
29717 Because it is recycled, the normal dynamic memory cannot be used for holding
29718 data that must be preserved over a number of incoming messages on the same SMTP
29719 connection. However, Exim in fact uses two pools of dynamic memory; the second
29720 one is not recycled, and can be used for this purpose.
29721
29722 If you want to allocate memory that remains available for subsequent messages
29723 in the same SMTP connection, you should set
29724
29725 store_pool = POOL_PERM
29726
29727 before calling the function that does the allocation. There is no need to
29728 restore the value if you do not need to; however, if you do want to revert to
29729 the normal pool, you can either restore the previous value of store_pool or set
29730 it explicitly to POOL_MAIN.
29731
29732 The pool setting applies to all functions that get dynamic memory, including
29733 expand_string(), store_get(), and the string_xxx() functions. There is also a
29734 convenience function called store_get_perm() that gets a block of memory from
29735 the permanent pool while preserving the value of store_pool.
29736
29737
29738
29739 ===============================================================================
29740 45. SYSTEM-WIDE MESSAGE FILTERING
29741
29742 The previous chapters (on ACLs and the local scan function) describe checks
29743 that can be applied to messages before they are accepted by a host. There is
29744 also a mechanism for checking messages once they have been received, but before
29745 they are delivered. This is called the system filter.
29746
29747 The system filter operates in a similar manner to users' filter files, but it
29748 is run just once per message (however many recipients the message has). It
29749 should not normally be used as a substitute for routing, because deliver
29750 commands in a system router provide new envelope recipient addresses. The
29751 system filter must be an Exim filter. It cannot be a Sieve filter.
29752
29753 The system filter is run at the start of a delivery attempt, before any routing
29754 is done. If a message fails to be completely delivered at the first attempt,
29755 the system filter is run again at the start of every retry. If you want your
29756 filter to do something only once per message, you can make use of the
29757 first_delivery condition in an if command in the filter to prevent it happening
29758 on retries.
29759
29760 Warning: Because the system filter runs just once, variables that are specific
29761 to individual recipient addresses, such as $local_part and $domain, are not
29762 set, and the "personal" condition is not meaningful. If you want to run a
29763 centrally-specified filter for each recipient address independently, you can do
29764 so by setting up a suitable redirect router, as described in section 45.8
29765 below.
29766
29767
29768 45.1 Specifying a system filter
29769 -------------------------------
29770
29771 The name of the file that contains the system filter must be specified by
29772 setting system_filter. If you want the filter to run under a uid and gid other
29773 than root, you must also set system_filter_user and system_filter_group as
29774 appropriate. For example:
29775
29776 system_filter = /etc/mail/exim.filter
29777 system_filter_user = exim
29778
29779 If a system filter generates any deliveries directly to files or pipes (via the
29780 save or pipe commands), transports to handle these deliveries must be specified
29781 by setting system_filter_file_transport and system_filter_pipe_transport,
29782 respectively. Similarly, system_filter_reply_transport must be set to handle
29783 any messages generated by the reply command.
29784
29785
29786 45.2 Testing a system filter
29787 ----------------------------
29788
29789 You can run simple tests of a system filter in the same way as for a user
29790 filter, but you should use -bF rather than -bf, so that features that are
29791 permitted only in system filters are recognized.
29792
29793 If you want to test the combined effect of a system filter and a user filter,
29794 you can use both -bF and -bf on the same command line.
29795
29796
29797 45.3 Contents of a system filter
29798 --------------------------------
29799
29800 The language used to specify system filters is the same as for users' filter
29801 files. It is described in the separate end-user document Exim's interface to
29802 mail filtering. However, there are some additional features that are available
29803 only in system filters; these are described in subsequent sections. If they are
29804 encountered in a user's filter file or when testing with -bf, they cause
29805 errors.
29806
29807 There are two special conditions which, though available in users' filter
29808 files, are designed for use in system filters. The condition first_delivery is
29809 true only for the first attempt at delivering a message, and manually_thawed is
29810 true only if the message has been frozen, and subsequently thawed by an admin
29811 user. An explicit forced delivery counts as a manual thaw, but thawing as a
29812 result of the auto_thaw setting does not.
29813
29814 Warning: If a system filter uses the first_delivery condition to specify an
29815 "unseen" (non-significant) delivery, and that delivery does not succeed, it
29816 will not be tried again. If you want Exim to retry an unseen delivery until it
29817 succeeds, you should arrange to set it up every time the filter runs.
29818
29819 When a system filter finishes running, the values of the variables $n0 - $n9
29820 are copied into $sn0 - $sn9 and are thereby made available to users' filter
29821 files. Thus a system filter can, for example, set up "scores" to which users'
29822 filter files can refer.
29823
29824
29825 45.4 Additional variable for system filters
29826 -------------------------------------------
29827
29828 The expansion variable $recipients, containing a list of all the recipients of
29829 the message (separated by commas and white space), is available in system
29830 filters. It is not available in users' filters for privacy reasons.
29831
29832
29833 45.5 Defer, freeze, and fail commands for system filters
29834 --------------------------------------------------------
29835
29836 There are three extra commands (defer, freeze and fail) which are always
29837 available in system filters, but are not normally enabled in users' filters.
29838 (See the allow_defer, allow_freeze and allow_fail options for the redirect
29839 router.) These commands can optionally be followed by the word text and a
29840 string containing an error message, for example:
29841
29842 fail text "this message looks like spam to me"
29843
29844 The keyword text is optional if the next character is a double quote.
29845
29846 The defer command defers delivery of the original recipients of the message.
29847 The fail command causes all the original recipients to be failed, and a bounce
29848 message to be created. The freeze command suspends all delivery attempts for
29849 the original recipients. In all cases, any new deliveries that are specified by
29850 the filter are attempted as normal after the filter has run.
29851
29852 The freeze command is ignored if the message has been manually unfrozen and not
29853 manually frozen since. This means that automatic freezing by a system filter
29854 can be used as a way of checking out suspicious messages. If a message is found
29855 to be all right, manually unfreezing it allows it to be delivered.
29856
29857 The text given with a fail command is used as part of the bounce message as
29858 well as being written to the log. If the message is quite long, this can fill
29859 up a lot of log space when such failures are common. To reduce the size of the
29860 log message, Exim interprets the text in a special way if it starts with the
29861 two characters "<<" and contains ">>" later. The text between these two strings
29862 is written to the log, and the rest of the text is used in the bounce message.
29863 For example:
29864
29865 fail "<<filter test 1>>Your message is rejected \
29866 because it contains attachments that we are \
29867 not prepared to receive."
29868
29869 Take great care with the fail command when basing the decision to fail on the
29870 contents of the message, because the bounce message will of course include the
29871 contents of the original message and will therefore trigger the fail command
29872 again (causing a mail loop) unless steps are taken to prevent this. Testing the
29873 error_message condition is one way to prevent this. You could use, for example
29874
29875 if $message_body contains "this is spam" and not error_message
29876 then fail text "spam is not wanted here" endif
29877
29878 though of course that might let through unwanted bounce messages. The
29879 alternative is clever checking of the body and/or headers to detect bounces
29880 generated by the filter.
29881
29882 The interpretation of a system filter file ceases after a defer, freeze, or
29883 fail command is obeyed. However, any deliveries that were set up earlier in the
29884 filter file are honoured, so you can use a sequence such as
29885
29886 mail ...
29887 freeze
29888
29889 to send a specified message when the system filter is freezing (or deferring or
29890 failing) a message. The normal deliveries for the message do not, of course,
29891 take place.
29892
29893
29894 45.6 Adding and removing headers in a system filter
29895 ---------------------------------------------------
29896
29897 Two filter commands that are available only in system filters are:
29898
29899 headers add <string>
29900 headers remove <string>
29901
29902 The argument for the headers add is a string that is expanded and then added to
29903 the end of the message's headers. It is the responsibility of the filter
29904 maintainer to make sure it conforms to RFC 2822 syntax. Leading white space is
29905 ignored, and if the string is otherwise empty, or if the expansion is forced to
29906 fail, the command has no effect.
29907
29908 You can use "\n" within the string, followed by white space, to specify
29909 continued header lines. More than one header may be added in one command by
29910 including "\n" within the string without any following white space. For
29911 example:
29912
29913 headers add "X-header-1: ....\n \
29914 continuation of X-header-1 ...\n\
29915 X-header-2: ...."
29916
29917 Note that the header line continuation white space after the first newline must
29918 be placed before the backslash that continues the input string, because white
29919 space after input continuations is ignored.
29920
29921 The argument for headers remove is a colon-separated list of header names. This
29922 command applies only to those headers that are stored with the message; those
29923 that are added at delivery time (such as Envelope-To: and Return-Path:) cannot
29924 be removed by this means. If there is more than one header with the same name,
29925 they are all removed.
29926
29927 The headers command in a system filter makes an immediate change to the set of
29928 header lines that was received with the message (with possible additions from
29929 ACL processing). Subsequent commands in the system filter operate on the
29930 modified set, which also forms the basis for subsequent message delivery.
29931 Unless further modified during routing or transporting, this set of headers is
29932 used for all recipients of the message.
29933
29934 During routing and transporting, the variables that refer to the contents of
29935 header lines refer only to those lines that are in this set. Thus, header lines
29936 that are added by a system filter are visible to users' filter files and to all
29937 routers and transports. This contrasts with the manipulation of header lines by
29938 routers and transports, which is not immediate, but which instead is saved up
29939 until the message is actually being written (see section 46.17).
29940
29941 If the message is not delivered at the first attempt, header lines that were
29942 added by the system filter are stored with the message, and so are still
29943 present at the next delivery attempt. Header lines that were removed are still
29944 present, but marked "deleted" so that they are not transported with the
29945 message. For this reason, it is usual to make the headers command conditional
29946 on first_delivery so that the set of header lines is not modified more than
29947 once.
29948
29949 Because header modification in a system filter acts immediately, you have to
29950 use an indirect approach if you want to modify the contents of a header line.
29951 For example:
29952
29953 headers add "Old-Subject: $h_subject:"
29954 headers remove "Subject"
29955 headers add "Subject: new subject (was: $h_old-subject:)"
29956 headers remove "Old-Subject"
29957
29958
29959 45.7 Setting an errors address in a system filter
29960 -------------------------------------------------
29961
29962 In a system filter, if a deliver command is followed by
29963
29964 errors_to <some address>
29965
29966 in order to change the envelope sender (and hence the error reporting) for that
29967 delivery, any address may be specified. (In a user filter, only the current
29968 user's address can be set.) For example, if some mail is being monitored, you
29969 might use
29970
29971 unseen deliver monitor@spying.example errors_to root@local.example
29972
29973 to take a copy which would not be sent back to the normal error reporting
29974 address if its delivery failed.
29975
29976
29977 45.8 Per-address filtering
29978 --------------------------
29979
29980 In contrast to the system filter, which is run just once per message for each
29981 delivery attempt, it is also possible to set up a system-wide filtering
29982 operation that runs once for each recipient address. In this case, variables
29983 such as $local_part and $domain can be used, and indeed, the choice of filter
29984 file could be made dependent on them. This is an example of a router which
29985 implements such a filter:
29986
29987 central_filter:
29988 check_local_user
29989 driver = redirect
29990 domains = +local_domains
29991 file = /central/filters/$local_part
29992 no_verify
29993 allow_filter
29994 allow_freeze
29995
29996 The filter is run in a separate process under its own uid. Therefore, either
29997 check_local_user must be set (as above), in which case the filter is run as the
29998 local user, or the user option must be used to specify which user to use. If
29999 both are set, user overrides.
30000
30001 Care should be taken to ensure that none of the commands in the filter file
30002 specify a significant delivery if the message is to go on to be delivered to
30003 its intended recipient. The router will not then claim to have dealt with the
30004 address, so it will be passed on to subsequent routers to be delivered in the
30005 normal way.
30006
30007
30008
30009 ===============================================================================
30010 46. MESSAGE PROCESSING
30011
30012 Exim performs various transformations on the sender and recipient addresses of
30013 all messages that it handles, and also on the messages' header lines. Some of
30014 these are optional and configurable, while others always take place. All of
30015 this processing, except rewriting as a result of routing, and the addition or
30016 removal of header lines while delivering, happens when a message is received,
30017 before it is placed on Exim's queue.
30018
30019 Some of the automatic processing takes place by default only for
30020 "locally-originated" messages. This adjective is used to describe messages that
30021 are not received over TCP/IP, but instead are passed to an Exim process on its
30022 standard input. This includes the interactive "local SMTP" case that is set up
30023 by the -bs command line option.
30024
30025 Note: Messages received over TCP/IP on the loopback interface (127.0.0.1 or
30026 ::1) are not considered to be locally-originated. Exim does not treat the
30027 loopback interface specially in any way.
30028
30029 If you want the loopback interface to be treated specially, you must ensure
30030 that there are appropriate entries in your ACLs.
30031
30032
30033 46.1 Submission mode for non-local messages
30034 -------------------------------------------
30035
30036 Processing that happens automatically for locally-originated messages (unless
30037 suppress_local_fixups is set) can also be requested for messages that are
30038 received over TCP/IP. The term "submission mode" is used to describe this
30039 state. Submission mode is set by the modifier
30040
30041 control = submission
30042
30043 in a MAIL, RCPT, or pre-data ACL for an incoming message (see sections 42.21
30044 and 42.22). This makes Exim treat the message as a local submission, and is
30045 normally used when the source of the message is known to be an MUA running on a
30046 client host (as opposed to an MTA). For example, to set submission mode for
30047 messages originating on the IPv4 loopback interface, you could include the
30048 following in the MAIL ACL:
30049
30050 warn hosts = 127.0.0.1
30051 control = submission
30052
30053 There are some options that can be used when setting submission mode. A slash
30054 is used to separate options. For example:
30055
30056 control = submission/sender_retain
30057
30058 Specifying sender_retain has the effect of setting local_sender_retain true and
30059 local_from_check false for the current incoming message. The first of these
30060 allows an existing Sender: header in the message to remain, and the second
30061 suppresses the check to ensure that From: matches the authenticated sender.
30062 With this setting, Exim still fixes up messages by adding Date: and Message-ID:
30063 header lines if they are missing, but makes no attempt to check sender
30064 authenticity in header lines.
30065
30066 When sender_retain is not set, a submission mode setting may specify a domain
30067 to be used when generating a From: or Sender: header line. For example:
30068
30069 control = submission/domain=some.domain
30070
30071 The domain may be empty. How this value is used is described in sections 46.11
30072 and 46.16. There is also a name option that allows you to specify the user's
30073 full name for inclusion in a created Sender: or From: header line. For example:
30074
30075 accept authenticated = *
30076 control = submission/domain=wonderland.example/\
30077 name=${lookup {$authenticated_id} \
30078 lsearch {/etc/exim/namelist}}
30079
30080 Because the name may contain any characters, including slashes, the name option
30081 must be given last. The remainder of the string is used as the name. For the
30082 example above, if /etc/exim/namelist contains:
30083
30084 bigegg: Humpty Dumpty
30085
30086 then when the sender has authenticated as bigegg, the generated Sender: line
30087 would be:
30088
30089 Sender: Humpty Dumpty <bigegg@wonderland.example>
30090
30091 By default, submission mode forces the return path to the same address as is
30092 used to create the Sender: header. However, if sender_retain is specified, the
30093 return path is also left unchanged.
30094
30095 Note: The changes caused by submission mode take effect after the predata ACL.
30096 This means that any sender checks performed before the fix-ups use the
30097 untrusted sender address specified by the user, not the trusted sender address
30098 specified by submission mode. Although this might be slightly unexpected, it
30099 does mean that you can configure ACL checks to spot that a user is trying to
30100 spoof another's address.
30101
30102
30103 46.2 Line endings
30104 -----------------
30105
30106 RFC 2821 specifies that CRLF (two characters: carriage-return, followed by
30107 linefeed) is the line ending for messages transmitted over the Internet using
30108 SMTP over TCP/IP. However, within individual operating systems, different
30109 conventions are used. For example, Unix-like systems use just LF, but others
30110 use CRLF or just CR.
30111
30112 Exim was designed for Unix-like systems, and internally, it stores messages
30113 using the system's convention of a single LF as a line terminator. When
30114 receiving a message, all line endings are translated to this standard format.
30115 Originally, it was thought that programs that passed messages directly to an
30116 MTA within an operating system would use that system's convention. Experience
30117 has shown that this is not the case; for example, there are Unix applications
30118 that use CRLF in this circumstance. For this reason, and for compatibility with
30119 other MTAs, the way Exim handles line endings for all messages is now as
30120 follows:
30121
30122 * LF not preceded by CR is treated as a line ending.
30123
30124 * CR is treated as a line ending; if it is immediately followed by LF, the LF
30125 is ignored.
30126
30127 * The sequence "CR, dot, CR" does not terminate an incoming SMTP message, nor
30128 a local message in the state where a line containing only a dot is a
30129 terminator.
30130
30131 * If a bare CR is encountered within a header line, an extra space is added
30132 after the line terminator so as not to end the header line. The reasoning
30133 behind this is that bare CRs in header lines are most likely either to be
30134 mistakes, or people trying to play silly games.
30135
30136 * If the first header line received in a message ends with CRLF, a subsequent
30137 bare LF in a header line is treated in the same way as a bare CR in a
30138 header line.
30139
30140
30141 46.3 Unqualified addresses
30142 --------------------------
30143
30144 By default, Exim expects every envelope address it receives from an external
30145 host to be fully qualified. Unqualified addresses cause negative responses to
30146 SMTP commands. However, because SMTP is used as a means of transporting
30147 messages from MUAs running on personal workstations, there is sometimes a
30148 requirement to accept unqualified addresses from specific hosts or IP networks.
30149
30150 Exim has two options that separately control which hosts may send unqualified
30151 sender or recipient addresses in SMTP commands, namely sender_unqualified_hosts
30152 and recipient_unqualified_hosts. In both cases, if an unqualified address is
30153 accepted, it is qualified by adding the value of qualify_domain or
30154 qualify_recipient, as appropriate.
30155
30156 Unqualified addresses in header lines are automatically qualified for messages
30157 that are locally originated, unless the -bnq option is given on the command
30158 line. For messages received over SMTP, unqualified addresses in header lines
30159 are qualified only if unqualified addresses are permitted in SMTP commands. In
30160 other words, such qualification is also controlled by sender_unqualified_hosts
30161 and recipient_unqualified_hosts,
30162
30163
30164 46.4 The UUCP From line
30165 -----------------------
30166
30167 Messages that have come from UUCP (and some other applications) often begin
30168 with a line containing the envelope sender and a timestamp, following the word
30169 "From". Examples of two common formats are:
30170
30171 From a.oakley@berlin.mus Fri Jan 5 12:35 GMT 1996
30172 From f.butler@berlin.mus Fri, 7 Jan 97 14:00:00 GMT
30173
30174 This line precedes the RFC 2822 header lines. For compatibility with Sendmail,
30175 Exim recognizes such lines at the start of messages that are submitted to it
30176 via the command line (that is, on the standard input). It does not recognize
30177 such lines in incoming SMTP messages, unless the sending host matches
30178 ignore_fromline_hosts or the -bs option was used for a local message and
30179 ignore_fromline_local is set. The recognition is controlled by a regular
30180 expression that is defined by the uucp_from_pattern option, whose default value
30181 matches the two common cases shown above and puts the address that follows
30182 "From" into $1.
30183
30184 When the caller of Exim for a non-SMTP message that contains a "From" line is a
30185 trusted user, the message's sender address is constructed by expanding the
30186 contents of uucp_sender_address, whose default value is "$1". This is then
30187 parsed as an RFC 2822 address. If there is no domain, the local part is
30188 qualified with qualify_domain unless it is the empty string. However, if the
30189 command line -f option is used, it overrides the "From" line.
30190
30191 If the caller of Exim is not trusted, the "From" line is recognized, but the
30192 sender address is not changed. This is also the case for incoming SMTP messages
30193 that are permitted to contain "From" lines.
30194
30195 Only one "From" line is recognized. If there is more than one, the second is
30196 treated as a data line that starts the body of the message, as it is not valid
30197 as a header line. This also happens if a "From" line is present in an incoming
30198 SMTP message from a source that is not permitted to send them.
30199
30200
30201 46.5 Resent- header lines
30202 -------------------------
30203
30204 RFC 2822 makes provision for sets of header lines starting with the string
30205 "Resent-" to be added to a message when it is resent by the original recipient
30206 to somebody else. These headers are Resent-Date:, Resent-From:, Resent-Sender:,
30207 Resent-To:, Resent-Cc:, Resent-Bcc: and Resent-Message-ID:. The RFC says:
30208
30209 Resent fields are strictly informational. They MUST NOT be used in the
30210 normal processing of replies or other such automatic actions on messages.
30211
30212 This leaves things a bit vague as far as other processing actions such as
30213 address rewriting are concerned. Exim treats Resent- header lines as follows:
30214
30215 * A Resent-From: line that just contains the login id of the submitting user
30216 is automatically rewritten in the same way as From: (see below).
30217
30218 * If there's a rewriting rule for a particular header line, it is also
30219 applied to Resent- header lines of the same type. For example, a rule that
30220 rewrites From: also rewrites Resent-From:.
30221
30222 * For local messages, if Sender: is removed on input, Resent-Sender: is also
30223 removed.
30224
30225 * For a locally-submitted message, if there are any Resent- header lines but
30226 no Resent-Date:, Resent-From:, or Resent-Message-Id:, they are added as
30227 necessary. It is the contents of Resent-Message-Id: (rather than
30228 Message-Id:) which are included in log lines in this case.
30229
30230 * The logic for adding Sender: is duplicated for Resent-Sender: when any
30231 Resent- header lines are present.
30232
30233
30234 46.6 The Auto-Submitted: header line
30235 ------------------------------------
30236
30237 Whenever Exim generates an autoreply, a bounce, or a delay warning message, it
30238 includes the header line:
30239
30240 Auto-Submitted: auto-replied
30241
30242
30243 46.7 The Bcc: header line
30244 -------------------------
30245
30246 If Exim is called with the -t option, to take recipient addresses from a
30247 message's header, it removes any Bcc: header line that may exist (after
30248 extracting its addresses). If -t is not present on the command line, any
30249 existing Bcc: is not removed.
30250
30251
30252 46.8 The Date: header line
30253 --------------------------
30254
30255 If a locally-generated or submission-mode message has no Date: header line,
30256 Exim adds one, using the current date and time, unless the
30257 suppress_local_fixups control has been specified.
30258
30259
30260 46.9 The Delivery-date: header line
30261 -----------------------------------
30262
30263 Delivery-date: header lines are not part of the standard RFC 2822 header set.
30264 Exim can be configured to add them to the final delivery of messages. (See the
30265 generic delivery_date_add transport option.) They should not be present in
30266 messages in transit. If the delivery_date_remove configuration option is set
30267 (the default), Exim removes Delivery-date: header lines from incoming messages.
30268
30269
30270 46.10 The Envelope-to: header line
30271 ----------------------------------
30272
30273 Envelope-to: header lines are not part of the standard RFC 2822 header set.
30274 Exim can be configured to add them to the final delivery of messages. (See the
30275 generic envelope_to_add transport option.) They should not be present in
30276 messages in transit. If the envelope_to_remove configuration option is set (the
30277 default), Exim removes Envelope-to: header lines from incoming messages.
30278
30279
30280 46.11 The From: header line
30281 ---------------------------
30282
30283 If a submission-mode message does not contain a From: header line, Exim adds
30284 one if either of the following conditions is true:
30285
30286 * The envelope sender address is not empty (that is, this is not a bounce
30287 message). The added header line copies the envelope sender address.
30288
30289 * The SMTP session is authenticated and $authenticated_id is not empty.
30290
30291 1. If no domain is specified by the submission control, the local part is
30292 $authenticated_id and the domain is $qualify_domain.
30293
30294 2. If a non-empty domain is specified by the submission control, the local
30295 part is $authenticated_id, and the domain is the specified domain.
30296
30297 3. If an empty domain is specified by the submission control,
30298 $authenticated_id is assumed to be the complete address.
30299
30300 A non-empty envelope sender takes precedence.
30301
30302 If a locally-generated incoming message does not contain a From: header line,
30303 and the suppress_local_fixups control is not set, Exim adds one containing the
30304 sender's address. The calling user's login name and full name are used to
30305 construct the address, as described in section 46.18. They are obtained from
30306 the password data by calling getpwuid() (but see the unknown_login
30307 configuration option). The address is qualified with qualify_domain.
30308
30309 For compatibility with Sendmail, if an incoming, non-SMTP message has a From:
30310 header line containing just the unqualified login name of the calling user,
30311 this is replaced by an address containing the user's login name and full name
30312 as described in section 46.18.
30313
30314
30315 46.12 The Message-ID: header line
30316 ---------------------------------
30317
30318 If a locally-generated or submission-mode incoming message does not contain a
30319 Message-ID: or Resent-Message-ID: header line, and the suppress_local_fixups
30320 control is not set, Exim adds a suitable header line to the message. If there
30321 are any Resent-: headers in the message, it creates Resent-Message-ID:. The id
30322 is constructed from Exim's internal message id, preceded by the letter E to
30323 ensure it starts with a letter, and followed by @ and the primary host name.
30324 Additional information can be included in this header line by setting the
30325 message_id_header_text and/or message_id_header_domain options.
30326
30327
30328 46.13 The Received: header line
30329 -------------------------------
30330
30331 A Received: header line is added at the start of every message. The contents
30332 are defined by the received_header_text configuration option, and Exim
30333 automatically adds a semicolon and a timestamp to the configured string.
30334
30335 The Received: header is generated as soon as the message's header lines have
30336 been received. At this stage, the timestamp in the Received: header line is the
30337 time that the message started to be received. This is the value that is seen by
30338 the DATA ACL and by the local_scan() function.
30339
30340 Once a message is accepted, the timestamp in the Received: header line is
30341 changed to the time of acceptance, which is (apart from a small delay while the
30342 -H spool file is written) the earliest time at which delivery could start.
30343
30344
30345 46.14 The References: header line
30346 ---------------------------------
30347
30348 Messages created by the autoreply transport include a References: header line.
30349 This is constructed according to the rules that are described in section 3.64
30350 of RFC 2822 (which states that replies should contain such a header line), and
30351 section 3.14 of RFC 3834 (which states that automatic responses are not
30352 different in this respect). However, because some mail processing software does
30353 not cope well with very long header lines, no more than 12 message IDs are
30354 copied from the References: header line in the incoming message. If there are
30355 more than 12, the first one and then the final 11 are copied, before adding the
30356 message ID of the incoming message.
30357
30358
30359 46.15 The Return-path: header line
30360 ----------------------------------
30361
30362 Return-path: header lines are defined as something an MTA may insert when it
30363 does the final delivery of messages. (See the generic return_path_add transport
30364 option.) Therefore, they should not be present in messages in transit. If the
30365 return_path_remove configuration option is set (the default), Exim removes
30366 Return-path: header lines from incoming messages.
30367
30368
30369 46.16 The Sender: header line
30370 -----------------------------
30371
30372 For a locally-originated message from an untrusted user, Exim may remove an
30373 existing Sender: header line, and it may add a new one. You can modify these
30374 actions by setting the local_sender_retain option true, the local_from_check
30375 option false, or by using the suppress_local_fixups control setting.
30376
30377 When a local message is received from an untrusted user and local_from_check is
30378 true (the default), and the suppress_local_fixups control has not been set, a
30379 check is made to see if the address given in the From: header line is the
30380 correct (local) sender of the message. The address that is expected has the
30381 login name as the local part and the value of qualify_domain as the domain.
30382 Prefixes and suffixes for the local part can be permitted by setting
30383 local_from_prefix and local_from_suffix appropriately. If From: does not
30384 contain the correct sender, a Sender: line is added to the message.
30385
30386 If you set local_from_check false, this checking does not occur. However, the
30387 removal of an existing Sender: line still happens, unless you also set
30388 local_sender_retain to be true. It is not possible to set both of these options
30389 true at the same time.
30390
30391 By default, no processing of Sender: header lines is done for messages received
30392 over TCP/IP or for messages submitted by trusted users. However, when a message
30393 is received over TCP/IP in submission mode, and sender_retain is not specified
30394 on the submission control, the following processing takes place:
30395
30396 First, any existing Sender: lines are removed. Then, if the SMTP session is
30397 authenticated, and $authenticated_id is not empty, a sender address is created
30398 as follows:
30399
30400 * If no domain is specified by the submission control, the local part is
30401 $authenticated_id and the domain is $qualify_domain.
30402
30403 * If a non-empty domain is specified by the submission control, the local
30404 part is $authenticated_id, and the domain is the specified domain.
30405
30406 * If an empty domain is specified by the submission control,
30407 $authenticated_id is assumed to be the complete address.
30408
30409 This address is compared with the address in the From: header line. If they are
30410 different, a Sender: header line containing the created address is added.
30411 Prefixes and suffixes for the local part in From: can be permitted by setting
30412 local_from_prefix and local_from_suffix appropriately.
30413
30414 Note: Whenever a Sender: header line is created, the return path for the
30415 message (the envelope sender address) is changed to be the same address, except
30416 in the case of submission mode when sender_retain is specified.
30417
30418
30419 46.17 Adding and removing header lines in routers and transports
30420 ----------------------------------------------------------------
30421
30422 When a message is delivered, the addition and removal of header lines can be
30423 specified in a system filter, or on any of the routers and transports that
30424 process the message. Section 45.6 contains details about modifying headers in a
30425 system filter. Header lines can also be added in an ACL as a message is
30426 received (see section 42.24).
30427
30428 In contrast to what happens in a system filter, header modifications that are
30429 specified on routers and transports apply only to the particular recipient
30430 addresses that are being processed by those routers and transports. These
30431 changes do not actually take place until a copy of the message is being
30432 transported. Therefore, they do not affect the basic set of header lines, and
30433 they do not affect the values of the variables that refer to header lines.
30434
30435 Note: In particular, this means that any expansions in the configuration of the
30436 transport cannot refer to the modified header lines, because such expansions
30437 all occur before the message is actually transported.
30438
30439 For both routers and transports, the argument of a headers_add option must be
30440 in the form of one or more RFC 2822 header lines, separated by newlines (coded
30441 as "\n"). For example:
30442
30443 headers_add = X-added-header: added by $primary_hostname\n\
30444 X-added-second: another added header line
30445
30446 Exim does not check the syntax of these added header lines.
30447
30448 Multiple headers_add options for a single router or transport can be specified;
30449 the values will append to a single list of header lines. Each header-line is
30450 separately expanded.
30451
30452 The argument of a headers_remove option must consist of a colon-separated list
30453 of header names. This is confusing, because header names themselves are often
30454 terminated by colons. In this case, the colons are the list separators, not
30455 part of the names. For example:
30456
30457 headers_remove = return-receipt-to:acknowledge-to
30458
30459 Multiple headers_remove options for a single router or transport can be
30460 specified; the arguments will append to a single header-names list. Each item
30461 is separately expanded.
30462
30463 When headers_add or headers_remove is specified on a router, items are expanded
30464 at routing time, and then associated with all addresses that are accepted by
30465 that router, and also with any new addresses that it generates. If an address
30466 passes through several routers as a result of aliasing or forwarding, the
30467 changes are cumulative.
30468
30469 However, this does not apply to multiple routers that result from the use of
30470 the unseen option. Any header modifications that were specified by the "unseen"
30471 router or its predecessors apply only to the "unseen" delivery.
30472
30473 Addresses that end up with different headers_add or headers_remove settings
30474 cannot be delivered together in a batch, so a transport is always dealing with
30475 a set of addresses that have the same header-processing requirements.
30476
30477 The transport starts by writing the original set of header lines that arrived
30478 with the message, possibly modified by the system filter. As it writes out
30479 these lines, it consults the list of header names that were attached to the
30480 recipient address(es) by headers_remove options in routers, and it also
30481 consults the transport's own headers_remove option. Header lines whose names
30482 are on either of these lists are not written out. If there are multiple
30483 instances of any listed header, they are all skipped.
30484
30485 After the remaining original header lines have been written, new header lines
30486 that were specified by routers' headers_add options are written, in the order
30487 in which they were attached to the address. These are followed by any header
30488 lines specified by the transport's headers_add option.
30489
30490 This way of handling header line modifications in routers and transports has
30491 the following consequences:
30492
30493 * The original set of header lines, possibly modified by the system filter,
30494 remains "visible", in the sense that the $header_xxx variables refer to it,
30495 at all times.
30496
30497 * Header lines that are added by a router's headers_add option are not
30498 accessible by means of the $header_xxx expansion syntax in subsequent
30499 routers or the transport.
30500
30501 * Conversely, header lines that are specified for removal by headers_remove
30502 in a router remain visible to subsequent routers and the transport.
30503
30504 * Headers added to an address by headers_add in a router cannot be removed by
30505 a later router or by a transport.
30506
30507 * An added header can refer to the contents of an original header that is to
30508 be removed, even it has the same name as the added header. For example:
30509
30510 headers_remove = subject
30511 headers_add = Subject: new subject (was: $h_subject:)
30512
30513 Warning: The headers_add and headers_remove options cannot be used for a
30514 redirect router that has the one_time option set.
30515
30516
30517 46.18 Constructed addresses
30518 ---------------------------
30519
30520 When Exim constructs a sender address for a locally-generated message, it uses
30521 the form
30522
30523 <user name> <login@qualify_domain>
30524
30525 For example:
30526
30527 Zaphod Beeblebrox <zaphod@end.univ.example>
30528
30529 The user name is obtained from the -F command line option if set, or otherwise
30530 by looking up the calling user by getpwuid() and extracting the "gecos" field
30531 from the password entry. If the "gecos" field contains an ampersand character,
30532 this is replaced by the login name with the first letter upper cased, as is
30533 conventional in a number of operating systems. See the gecos_name option for a
30534 way to tailor the handling of the "gecos" field. The unknown_username option
30535 can be used to specify user names in cases when there is no password file
30536 entry.
30537
30538 In all cases, the user name is made to conform to RFC 2822 by quoting all or
30539 parts of it if necessary. In addition, if it contains any non-printing
30540 characters, it is encoded as described in RFC 2047, which defines a way of
30541 including non-ASCII characters in header lines. The value of the
30542 headers_charset option specifies the name of the encoding that is used (the
30543 characters are assumed to be in this encoding). The setting of
30544 print_topbitchars controls whether characters with the top bit set (that is,
30545 with codes greater than 127) count as printing characters or not.
30546
30547
30548 46.19 Case of local parts
30549 -------------------------
30550
30551 RFC 2822 states that the case of letters in the local parts of addresses cannot
30552 be assumed to be non-significant. Exim preserves the case of local parts of
30553 addresses, but by default it uses a lower-cased form when it is routing,
30554 because on most Unix systems, usernames are in lower case and case-insensitive
30555 routing is required. However, any particular router can be made to use the
30556 original case for local parts by setting the caseful_local_part generic router
30557 option.
30558
30559 If you must have mixed-case user names on your system, the best way to proceed,
30560 assuming you want case-independent handling of incoming email, is to set up
30561 your first router to convert incoming local parts in your domains to the
30562 correct case by means of a file lookup. For example:
30563
30564 correct_case:
30565 driver = redirect
30566 domains = +local_domains
30567 data = ${lookup{$local_part}cdb\
30568 {/etc/usercased.cdb}{$value}fail}\
30569 @$domain
30570
30571 For this router, the local part is forced to lower case by the default action (
30572 caseful_local_part is not set). The lower-cased local part is used to look up a
30573 new local part in the correct case. If you then set caseful_local_part on any
30574 subsequent routers which process your domains, they will operate on local parts
30575 with the correct case in a case-sensitive manner.
30576
30577
30578 46.20 Dots in local parts
30579 -------------------------
30580
30581 RFC 2822 forbids empty components in local parts. That is, an unquoted local
30582 part may not begin or end with a dot, nor have two consecutive dots in the
30583 middle. However, it seems that many MTAs do not enforce this, so Exim permits
30584 empty components for compatibility.
30585
30586
30587 46.21 Rewriting addresses
30588 -------------------------
30589
30590 Rewriting of sender and recipient addresses, and addresses in headers, can
30591 happen automatically, or as the result of configuration options, as described
30592 in chapter 31. The headers that may be affected by this are Bcc:, Cc:, From:,
30593 Reply-To:, Sender:, and To:.
30594
30595 Automatic rewriting includes qualification, as mentioned above. The other case
30596 in which it can happen is when an incomplete non-local domain is given. The
30597 routing process may cause this to be expanded into the full domain name. For
30598 example, a header such as
30599
30600 To: hare@teaparty
30601
30602 might get rewritten as
30603
30604 To: hare@teaparty.wonderland.fict.example
30605
30606 Rewriting as a result of routing is the one kind of message processing that
30607 does not happen at input time, as it cannot be done until the address has been
30608 routed.
30609
30610 Strictly, one should not do any deliveries of a message until all its addresses
30611 have been routed, in case any of the headers get changed as a result of
30612 routing. However, doing this in practice would hold up many deliveries for
30613 unreasonable amounts of time, just because one address could not immediately be
30614 routed. Exim therefore does not delay other deliveries when routing of one or
30615 more addresses is deferred.
30616
30617
30618
30619 ===============================================================================
30620 47. SMTP PROCESSING
30621
30622 Exim supports a number of different ways of using the SMTP protocol, and its
30623 LMTP variant, which is an interactive protocol for transferring messages into a
30624 closed mail store application. This chapter contains details of how SMTP is
30625 processed. For incoming mail, the following are available:
30626
30627 * SMTP over TCP/IP (Exim daemon or inetd);
30628
30629 * SMTP over the standard input and output (the -bs option);
30630
30631 * Batched SMTP on the standard input (the -bS option).
30632
30633 For mail delivery, the following are available:
30634
30635 * SMTP over TCP/IP (the smtp transport);
30636
30637 * LMTP over TCP/IP (the smtp transport with the protocol option set to
30638 "lmtp");
30639
30640 * LMTP over a pipe to a process running in the local host (the lmtp
30641 transport);
30642
30643 * Batched SMTP to a file or pipe (the appendfile and pipe transports with the
30644 use_bsmtp option set).
30645
30646 Batched SMTP is the name for a process in which batches of messages are stored
30647 in or read from files (or pipes), in a format in which SMTP commands are used
30648 to contain the envelope information.
30649
30650
30651 47.1 Outgoing SMTP and LMTP over TCP/IP
30652 ---------------------------------------
30653
30654 Outgoing SMTP and LMTP over TCP/IP is implemented by the smtp transport. The
30655 protocol option selects which protocol is to be used, but the actual processing
30656 is the same in both cases.
30657
30658 If, in response to its EHLO command, Exim is told that the SIZE parameter is
30659 supported, it adds SIZE=<n> to each subsequent MAIL command. The value of <n>
30660 is the message size plus the value of the size_addition option (default 1024)
30661 to allow for additions to the message such as per-transport header lines, or
30662 changes made in a transport filter. If size_addition is set negative, the use
30663 of SIZE is suppressed.
30664
30665 If the remote server advertises support for PIPELINING, Exim uses the
30666 pipelining extension to SMTP (RFC 2197) to reduce the number of TCP/IP packets
30667 required for the transaction.
30668
30669 If the remote server advertises support for the STARTTLS command, and Exim was
30670 built to support TLS encryption, it tries to start a TLS session unless the
30671 server matches hosts_avoid_tls. See chapter 41 for more details. Either a match
30672 in that or hosts_verify_avoid_tls apply when the transport is called for
30673 verification.
30674
30675 If the remote server advertises support for the AUTH command, Exim scans the
30676 authenticators configuration for any suitable client settings, as described in
30677 chapter 33.
30678
30679 Responses from the remote host are supposed to be terminated by CR followed by
30680 LF. However, there are known to be hosts that do not send CR characters, so in
30681 order to be able to interwork with such hosts, Exim treats LF on its own as a
30682 line terminator.
30683
30684 If a message contains a number of different addresses, all those with the same
30685 characteristics (for example, the same envelope sender) that resolve to the
30686 same set of hosts, in the same order, are sent in a single SMTP transaction,
30687 even if they are for different domains, unless there are more than the setting
30688 of the max_rcpts option in the smtp transport allows, in which case they are
30689 split into groups containing no more than max_rcpts addresses each. If
30690 remote_max_parallel is greater than one, such groups may be sent in parallel
30691 sessions. The order of hosts with identical MX values is not significant when
30692 checking whether addresses can be batched in this way.
30693
30694 When the smtp transport suffers a temporary failure that is not
30695 message-related, Exim updates its transport-specific database, which contains
30696 records indexed by host name that remember which messages are waiting for each
30697 particular host. It also updates the retry database with new retry times.
30698
30699 Exim's retry hints are based on host name plus IP address, so if one address of
30700 a multi-homed host is broken, it will soon be skipped most of the time. See the
30701 next section for more detail about error handling.
30702
30703 When a message is successfully delivered over a TCP/IP SMTP connection, Exim
30704 looks in the hints database for the transport to see if there are any queued
30705 messages waiting for the host to which it is connected. If it finds one, it
30706 creates a new Exim process using the -MC option (which can only be used by a
30707 process running as root or the Exim user) and passes the TCP/IP socket to it so
30708 that it can deliver another message using the same socket. The new process does
30709 only those deliveries that are routed to the connected host, and may in turn
30710 pass the socket on to a third process, and so on.
30711
30712 The connection_max_messages option of the smtp transport can be used to limit
30713 the number of messages sent down a single TCP/IP connection.
30714
30715 The second and subsequent messages delivered down an existing connection are
30716 identified in the main log by the addition of an asterisk after the closing
30717 square bracket of the IP address.
30718
30719
30720 47.2 Errors in outgoing SMTP
30721 ----------------------------
30722
30723 Three different kinds of error are recognized for outgoing SMTP: host errors,
30724 message errors, and recipient errors.
30725
30726 Host errors
30727
30728 A host error is not associated with a particular message or with a
30729 particular recipient of a message. The host errors are:
30730
30731 * Connection refused or timed out,
30732
30733 * Any error response code on connection,
30734
30735 * Any error response code to EHLO or HELO,
30736
30737 * Loss of connection at any time, except after ".",
30738
30739 * I/O errors at any time,
30740
30741 * Timeouts during the session, other than in response to MAIL, RCPT or
30742 the "." at the end of the data.
30743
30744 For a host error, a permanent error response on connection, or in response
30745 to EHLO, causes all addresses routed to the host to be failed. Any other
30746 host error causes all addresses to be deferred, and retry data to be
30747 created for the host. It is not tried again, for any message, until its
30748 retry time arrives. If the current set of addresses are not all delivered
30749 in this run (to some alternative host), the message is added to the list of
30750 those waiting for this host, so if it is still undelivered when a
30751 subsequent successful delivery is made to the host, it will be sent down
30752 the same SMTP connection.
30753
30754 Message errors
30755
30756 A message error is associated with a particular message when sent to a
30757 particular host, but not with a particular recipient of the message. The
30758 message errors are:
30759
30760 * Any error response code to MAIL, DATA, or the "." that terminates the
30761 data,
30762
30763 * Timeout after MAIL,
30764
30765 * Timeout or loss of connection after the "." that terminates the data. A
30766 timeout after the DATA command itself is treated as a host error, as is
30767 loss of connection at any other time.
30768
30769 For a message error, a permanent error response (5xx) causes all addresses
30770 to be failed, and a delivery error report to be returned to the sender. A
30771 temporary error response (4xx), or one of the timeouts, causes all
30772 addresses to be deferred. Retry data is not created for the host, but
30773 instead, a retry record for the combination of host plus message id is
30774 created. The message is not added to the list of those waiting for this
30775 host. This ensures that the failing message will not be sent to this host
30776 again until the retry time arrives. However, other messages that are routed
30777 to the host are not affected, so if it is some property of the message that
30778 is causing the error, it will not stop the delivery of other mail.
30779
30780 If the remote host specified support for the SIZE parameter in its response
30781 to EHLO, Exim adds SIZE=nnn to the MAIL command, so an over-large message
30782 will cause a message error because the error arrives as a response to MAIL.
30783
30784 Recipient errors
30785
30786 A recipient error is associated with a particular recipient of a message.
30787 The recipient errors are:
30788
30789 * Any error response to RCPT,
30790
30791 * Timeout after RCPT.
30792
30793 For a recipient error, a permanent error response (5xx) causes the
30794 recipient address to be failed, and a bounce message to be returned to the
30795 sender. A temporary error response (4xx) or a timeout causes the failing
30796 address to be deferred, and routing retry data to be created for it. This
30797 is used to delay processing of the address in subsequent queue runs, until
30798 its routing retry time arrives. This applies to all messages, but because
30799 it operates only in queue runs, one attempt will be made to deliver a new
30800 message to the failing address before the delay starts to operate. This
30801 ensures that, if the failure is really related to the message rather than
30802 the recipient ("message too big for this recipient" is a possible example),
30803 other messages have a chance of getting delivered. If a delivery to the
30804 address does succeed, the retry information gets cleared, so all stuck
30805 messages get tried again, and the retry clock is reset.
30806
30807 The message is not added to the list of those waiting for this host. Use of
30808 the host for other messages is unaffected, and except in the case of a
30809 timeout, other recipients are processed independently, and may be
30810 successfully delivered in the current SMTP session. After a timeout it is
30811 of course impossible to proceed with the session, so all addresses get
30812 deferred. However, those other than the one that failed do not suffer any
30813 subsequent retry delays. Therefore, if one recipient is causing trouble,
30814 the others have a chance of getting through when a subsequent delivery
30815 attempt occurs before the failing recipient's retry time.
30816
30817 In all cases, if there are other hosts (or IP addresses) available for the
30818 current set of addresses (for example, from multiple MX records), they are
30819 tried in this run for any undelivered addresses, subject of course to their own
30820 retry data. In other words, recipient error retry data does not take effect
30821 until the next delivery attempt.
30822
30823 Some hosts have been observed to give temporary error responses to every MAIL
30824 command at certain times ("insufficient space" has been seen). It would be nice
30825 if such circumstances could be recognized, and defer data for the host itself
30826 created, but this is not possible within the current Exim design. What actually
30827 happens is that retry data for every (host, message) combination is created.
30828
30829 The reason that timeouts after MAIL and RCPT are treated specially is that
30830 these can sometimes arise as a result of the remote host's verification
30831 procedures. Exim makes this assumption, and treats them as if a temporary error
30832 response had been received. A timeout after "." is treated specially because it
30833 is known that some broken implementations fail to recognize the end of the
30834 message if the last character of the last line is a binary zero. Thus, it is
30835 helpful to treat this case as a message error.
30836
30837 Timeouts at other times are treated as host errors, assuming a problem with the
30838 host, or the connection to it. If a timeout after MAIL, RCPT, or "." is really
30839 a connection problem, the assumption is that at the next try the timeout is
30840 likely to occur at some other point in the dialogue, causing it then to be
30841 treated as a host error.
30842
30843 There is experimental evidence that some MTAs drop the connection after the
30844 terminating "." if they do not like the contents of the message for some
30845 reason, in contravention of the RFC, which indicates that a 5xx response should
30846 be given. That is why Exim treats this case as a message rather than a host
30847 error, in order not to delay other messages to the same host.
30848
30849
30850 47.3 Incoming SMTP messages over TCP/IP
30851 ---------------------------------------
30852
30853 Incoming SMTP messages can be accepted in one of two ways: by running a
30854 listening daemon, or by using inetd. In the latter case, the entry in /etc/
30855 inetd.conf should be like this:
30856
30857 smtp stream tcp nowait exim /opt/exim/bin/exim in.exim -bs
30858
30859 Exim distinguishes between this case and the case of a locally running user
30860 agent using the -bs option by checking whether or not the standard input is a
30861 socket. When it is, either the port must be privileged (less than 1024), or the
30862 caller must be root or the Exim user. If any other user passes a socket with an
30863 unprivileged port number, Exim prints a message on the standard error stream
30864 and exits with an error code.
30865
30866 By default, Exim does not make a log entry when a remote host connects or
30867 disconnects (either via the daemon or inetd), unless the disconnection is
30868 unexpected. It can be made to write such log entries by setting the
30869 smtp_connection log selector.
30870
30871 Commands from the remote host are supposed to be terminated by CR followed by
30872 LF. However, there are known to be hosts that do not send CR characters. In
30873 order to be able to interwork with such hosts, Exim treats LF on its own as a
30874 line terminator. Furthermore, because common code is used for receiving
30875 messages from all sources, a CR on its own is also interpreted as a line
30876 terminator. However, the sequence "CR, dot, CR" does not terminate incoming
30877 SMTP data.
30878
30879 One area that sometimes gives rise to problems concerns the EHLO or HELO
30880 commands. Some clients send syntactically invalid versions of these commands,
30881 which Exim rejects by default. (This is nothing to do with verifying the data
30882 that is sent, so helo_verify_hosts is not relevant.) You can tell Exim not to
30883 apply a syntax check by setting helo_accept_junk_hosts to match the broken
30884 hosts that send invalid commands.
30885
30886 The amount of disk space available is checked whenever SIZE is received on a
30887 MAIL command, independently of whether message_size_limit or check_spool_space
30888 is configured, unless smtp_check_spool_space is set false. A temporary error is
30889 given if there is not enough space. If check_spool_space is set, the check is
30890 for that amount of space plus the value given with SIZE, that is, it checks
30891 that the addition of the incoming message will not reduce the space below the
30892 threshold.
30893
30894 When a message is successfully received, Exim includes the local message id in
30895 its response to the final "." that terminates the data. If the remote host logs
30896 this text it can help with tracing what has happened to a message.
30897
30898 The Exim daemon can limit the number of simultaneous incoming connections it is
30899 prepared to handle (see the smtp_accept_max option). It can also limit the
30900 number of simultaneous incoming connections from a single remote host (see the
30901 smtp_accept_max_per_host option). Additional connection attempts are rejected
30902 using the SMTP temporary error code 421.
30903
30904 The Exim daemon does not rely on the SIGCHLD signal to detect when a subprocess
30905 has finished, as this can get lost at busy times. Instead, it looks for
30906 completed subprocesses every time it wakes up. Provided there are other things
30907 happening (new incoming calls, starts of queue runs), completed processes will
30908 be noticed and tidied away. On very quiet systems you may sometimes see a
30909 "defunct" Exim process hanging about. This is not a problem; it will be noticed
30910 when the daemon next wakes up.
30911
30912 When running as a daemon, Exim can reserve some SMTP slots for specific hosts,
30913 and can also be set up to reject SMTP calls from non-reserved hosts at times of
30914 high system load - for details see the smtp_accept_reserve, smtp_load_reserve,
30915 and smtp_reserve_hosts options. The load check applies in both the daemon and
30916 inetd cases.
30917
30918 Exim normally starts a delivery process for each message received, though this
30919 can be varied by means of the -odq command line option and the queue_only,
30920 queue_only_file, and queue_only_load options. The number of simultaneously
30921 running delivery processes started in this way from SMTP input can be limited
30922 by the smtp_accept_queue and smtp_accept_queue_per_connection options. When
30923 either limit is reached, subsequently received messages are just put on the
30924 input queue without starting a delivery process.
30925
30926 The controls that involve counts of incoming SMTP calls (smtp_accept_max,
30927 smtp_accept_queue, smtp_accept_reserve) are not available when Exim is started
30928 up from the inetd daemon, because in that case each connection is handled by an
30929 entirely independent Exim process. Control by load average is, however,
30930 available with inetd.
30931
30932 Exim can be configured to verify addresses in incoming SMTP commands as they
30933 are received. See chapter 42 for details. It can also be configured to rewrite
30934 addresses at this time - before any syntax checking is done. See section 31.9.
30935
30936 Exim can also be configured to limit the rate at which a client host submits
30937 MAIL and RCPT commands in a single SMTP session. See the smtp_ratelimit_hosts
30938 option.
30939
30940
30941 47.4 Unrecognized SMTP commands
30942 -------------------------------
30943
30944 If Exim receives more than smtp_max_unknown_commands unrecognized SMTP commands
30945 during a single SMTP connection, it drops the connection after sending the
30946 error response to the last command. The default value for
30947 smtp_max_unknown_commands is 3. This is a defence against some kinds of abuse
30948 that subvert web servers into making connections to SMTP ports; in these
30949 circumstances, a number of non-SMTP lines are sent first.
30950
30951
30952 47.5 Syntax and protocol errors in SMTP commands
30953 ------------------------------------------------
30954
30955 A syntax error is detected if an SMTP command is recognized, but there is
30956 something syntactically wrong with its data, for example, a malformed email
30957 address in a RCPT command. Protocol errors include invalid command sequencing
30958 such as RCPT before MAIL. If Exim receives more than smtp_max_synprot_errors
30959 such commands during a single SMTP connection, it drops the connection after
30960 sending the error response to the last command. The default value for
30961 smtp_max_synprot_errors is 3. This is a defence against broken clients that
30962 loop sending bad commands (yes, it has been seen).
30963
30964
30965 47.6 Use of non-mail SMTP commands
30966 ----------------------------------
30967
30968 The "non-mail" SMTP commands are those other than MAIL, RCPT, and DATA. Exim
30969 counts such commands, and drops the connection if there are too many of them in
30970 a single SMTP session. This action catches some denial-of-service attempts and
30971 things like repeated failing AUTHs, or a mad client looping sending EHLO. The
30972 global option smtp_accept_max_nonmail defines what "too many" means. Its
30973 default value is 10.
30974
30975 When a new message is expected, one occurrence of RSET is not counted. This
30976 allows a client to send one RSET between messages (this is not necessary, but
30977 some clients do it). Exim also allows one uncounted occurrence of HELO or EHLO,
30978 and one occurrence of STARTTLS between messages. After starting up a TLS
30979 session, another EHLO is expected, and so it too is not counted.
30980
30981 The first occurrence of AUTH in a connection, or immediately following STARTTLS
30982 is also not counted. Otherwise, all commands other than MAIL, RCPT, DATA, and
30983 QUIT are counted.
30984
30985 You can control which hosts are subject to the limit set by
30986 smtp_accept_max_nonmail by setting smtp_accept_max_nonmail_hosts. The default
30987 value is "*", which makes the limit apply to all hosts. This option means that
30988 you can exclude any specific badly-behaved hosts that you have to live with.
30989
30990
30991 47.7 The VRFY and EXPN commands
30992 -------------------------------
30993
30994 When Exim receives a VRFY or EXPN command on a TCP/IP connection, it runs the
30995 ACL specified by acl_smtp_vrfy or acl_smtp_expn (as appropriate) in order to
30996 decide whether the command should be accepted or not. If no ACL is defined, the
30997 command is rejected.
30998
30999 When VRFY is accepted, it runs exactly the same code as when Exim is called
31000 with the -bv option.
31001
31002 When EXPN is accepted, a single-level expansion of the address is done. EXPN is
31003 treated as an "address test" (similar to the -bt option) rather than a
31004 verification (the -bv option). If an unqualified local part is given as the
31005 argument to EXPN, it is qualified with qualify_domain. Rejections of VRFY and
31006 EXPN commands are logged on the main and reject logs, and VRFY verification
31007 failures are logged on the main log for consistency with RCPT failures.
31008
31009
31010 47.8 The ETRN command
31011 ---------------------
31012
31013 RFC 1985 describes an SMTP command called ETRN that is designed to overcome the
31014 security problems of the TURN command (which has fallen into disuse). When Exim
31015 receives an ETRN command on a TCP/IP connection, it runs the ACL specified by
31016 acl_smtp_etrn in order to decide whether the command should be accepted or not.
31017 If no ACL is defined, the command is rejected.
31018
31019 The ETRN command is concerned with "releasing" messages that are awaiting
31020 delivery to certain hosts. As Exim does not organize its message queue by host,
31021 the only form of ETRN that is supported by default is the one where the text
31022 starts with the "#" prefix, in which case the remainder of the text is specific
31023 to the SMTP server. A valid ETRN command causes a run of Exim with the -R
31024 option to happen, with the remainder of the ETRN text as its argument. For
31025 example,
31026
31027 ETRN #brigadoon
31028
31029 runs the command
31030
31031 exim -R brigadoon
31032
31033 which causes a delivery attempt on all messages with undelivered addresses
31034 containing the text "brigadoon". When smtp_etrn_serialize is set (the default),
31035 Exim prevents the simultaneous execution of more than one queue run for the
31036 same argument string as a result of an ETRN command. This stops a misbehaving
31037 client from starting more than one queue runner at once.
31038
31039 Exim implements the serialization by means of a hints database in which a
31040 record is written whenever a process is started by ETRN, and deleted when the
31041 process completes. However, Exim does not keep the SMTP session waiting for the
31042 ETRN process to complete. Once ETRN is accepted, the client is sent a "success"
31043 return code. Obviously there is scope for hints records to get left lying
31044 around if there is a system or program crash. To guard against this, Exim
31045 ignores any records that are more than six hours old.
31046
31047 For more control over what ETRN does, the smtp_etrn_command option can used.
31048 This specifies a command that is run whenever ETRN is received, whatever the
31049 form of its argument. For example:
31050
31051 smtp_etrn_command = /etc/etrn_command $domain \
31052 $sender_host_address
31053
31054 The string is split up into arguments which are independently expanded. The
31055 expansion variable $domain is set to the argument of the ETRN command, and no
31056 syntax checking is done on the contents of this argument. Exim does not wait
31057 for the command to complete, so its status code is not checked. Exim runs under
31058 its own uid and gid when receiving incoming SMTP, so it is not possible for it
31059 to change them before running the command.
31060
31061
31062 47.9 Incoming local SMTP
31063 ------------------------
31064
31065 Some user agents use SMTP to pass messages to their local MTA using the
31066 standard input and output, as opposed to passing the envelope on the command
31067 line and writing the message to the standard input. This is supported by the
31068 -bs option. This form of SMTP is handled in the same way as incoming messages
31069 over TCP/IP (including the use of ACLs), except that the envelope sender given
31070 in a MAIL command is ignored unless the caller is trusted. In an ACL you can
31071 detect this form of SMTP input by testing for an empty host identification. It
31072 is common to have this as the first line in the ACL that runs for RCPT
31073 commands:
31074
31075 accept hosts = :
31076
31077 This accepts SMTP messages from local processes without doing any other tests.
31078
31079
31080 47.10 Outgoing batched SMTP
31081 ---------------------------
31082
31083 Both the appendfile and pipe transports can be used for handling batched SMTP.
31084 Each has an option called use_bsmtp which causes messages to be output in BSMTP
31085 format. No SMTP responses are possible for this form of delivery. All it is
31086 doing is using SMTP commands as a way of transmitting the envelope along with
31087 the message.
31088
31089 The message is written to the file or pipe preceded by the SMTP commands MAIL
31090 and RCPT, and followed by a line containing a single dot. Lines in the message
31091 that start with a dot have an extra dot added. The SMTP command HELO is not
31092 normally used. If it is required, the message_prefix option can be used to
31093 specify it.
31094
31095 Because appendfile and pipe are both local transports, they accept only one
31096 recipient address at a time by default. However, you can arrange for them to
31097 handle several addresses at once by setting the batch_max option. When this is
31098 done for BSMTP, messages may contain multiple RCPT commands. See chapter 25 for
31099 more details.
31100
31101 When one or more addresses are routed to a BSMTP transport by a router that
31102 sets up a host list, the name of the first host on the list is available to the
31103 transport in the variable $host. Here is an example of such a transport and
31104 router:
31105
31106 begin routers
31107 route_append:
31108 driver = manualroute
31109 transport = smtp_appendfile
31110 route_list = domain.example batch.host.example
31111
31112 begin transports
31113 smtp_appendfile:
31114 driver = appendfile
31115 directory = /var/bsmtp/$host
31116 batch_max = 1000
31117 use_bsmtp
31118 user = exim
31119
31120 This causes messages addressed to domain.example to be written in BSMTP format
31121 to /var/bsmtp/batch.host.example, with only a single copy of each message
31122 (unless there are more than 1000 recipients).
31123
31124
31125 47.11 Incoming batched SMTP
31126 ---------------------------
31127
31128 The -bS command line option causes Exim to accept one or more messages by
31129 reading SMTP on the standard input, but to generate no responses. If the caller
31130 is trusted, the senders in the MAIL commands are believed; otherwise the sender
31131 is always the caller of Exim. Unqualified senders and receivers are not
31132 rejected (there seems little point) but instead just get qualified. HELO and
31133 EHLO act as RSET; VRFY, EXPN, ETRN and HELP, act as NOOP; QUIT quits.
31134
31135 Minimal policy checking is done for BSMTP input. Only the non-SMTP ACL is run
31136 in the same way as for non-SMTP local input.
31137
31138 If an error is detected while reading a message, including a missing "." at the
31139 end, Exim gives up immediately. It writes details of the error to the standard
31140 output in a stylized way that the calling program should be able to make some
31141 use of automatically, for example:
31142
31143 554 Unexpected end of file
31144 Transaction started in line 10
31145 Error detected in line 14
31146
31147 It writes a more verbose version, for human consumption, to the standard error
31148 file, for example:
31149
31150 An error was detected while processing a file of BSMTP input.
31151 The error message was:
31152
31153 501 '>' missing at end of address
31154
31155 The SMTP transaction started in line 10.
31156 The error was detected in line 12.
31157 The SMTP command at fault was:
31158
31159 rcpt to:<malformed@in.com.plete
31160
31161 1 previous message was successfully processed.
31162 The rest of the batch was abandoned.
31163
31164 The return code from Exim is zero only if there were no errors. It is 1 if some
31165 messages were accepted before an error was detected, and 2 if no messages were
31166 accepted.
31167
31168
31169
31170 ===============================================================================
31171 48. CUSTOMIZING BOUNCE AND WARNING MESSAGES
31172
31173 When a message fails to be delivered, or remains on the queue for more than a
31174 configured amount of time, Exim sends a message to the original sender, or to
31175 an alternative configured address. The text of these messages is built into the
31176 code of Exim, but it is possible to change it, either by adding a single
31177 string, or by replacing each of the paragraphs by text supplied in a file.
31178
31179 The From: and To: header lines are automatically generated; you can cause a
31180 Reply-To: line to be added by setting the errors_reply_to option. Exim also
31181 adds the line
31182
31183 Auto-Submitted: auto-generated
31184
31185 to all warning and bounce messages,
31186
31187
31188 48.1 Customizing bounce messages
31189 --------------------------------
31190
31191 If bounce_message_text is set, its contents are included in the default message
31192 immediately after "This message was created automatically by mail delivery
31193 software." The string is not expanded. It is not used if bounce_message_file is
31194 set.
31195
31196 When bounce_message_file is set, it must point to a template file for
31197 constructing error messages. The file consists of a series of text items,
31198 separated by lines consisting of exactly four asterisks. If the file cannot be
31199 opened, default text is used and a message is written to the main and panic
31200 logs. If any text item in the file is empty, default text is used for that
31201 item.
31202
31203 Each item of text that is read from the file is expanded, and there are two
31204 expansion variables which can be of use here: $bounce_recipient is set to the
31205 recipient of an error message while it is being created, and
31206 $bounce_return_size_limit contains the value of the return_size_limit option,
31207 rounded to a whole number.
31208
31209 The items must appear in the file in the following order:
31210
31211 * The first item is included in the headers, and should include at least a
31212 Subject: header. Exim does not check the syntax of these headers.
31213
31214 * The second item forms the start of the error message. After it, Exim lists
31215 the failing addresses with their error messages.
31216
31217 * The third item is used to introduce any text from pipe transports that is
31218 to be returned to the sender. It is omitted if there is no such text.
31219
31220 * The fourth item is used to introduce the copy of the message that is
31221 returned as part of the error report.
31222
31223 * The fifth item is added after the fourth one if the returned message is
31224 truncated because it is bigger than return_size_limit.
31225
31226 * The sixth item is added after the copy of the original message.
31227
31228 The default state (bounce_message_file unset) is equivalent to the following
31229 file, in which the sixth item is empty. The Subject: and some other lines have
31230 been split in order to fit them on the page:
31231
31232 Subject: Mail delivery failed
31233 ${if eq{$sender_address}{$bounce_recipient}
31234 {: returning message to sender}}
31235 ****
31236 This message was created automatically by mail delivery software.
31237
31238 A message ${if eq{$sender_address}{$bounce_recipient}
31239 {that you sent }{sent by
31240
31241 <$sender_address>
31242
31243 }}could not be delivered to all of its recipients.
31244 This is a permanent error. The following address(es) failed:
31245 ****
31246 The following text was generated during the delivery attempt(s):
31247 ****
31248 ------ This is a copy of the message, including all the headers.
31249 ------
31250 ****
31251 ------ The body of the message is $message_size characters long;
31252 only the first
31253 ------ $bounce_return_size_limit or so are included here.
31254 ****
31255
31256
31257 48.2 Customizing warning messages
31258 ---------------------------------
31259
31260 The option warn_message_file can be pointed at a template file for use when
31261 warnings about message delays are created. In this case there are only three
31262 text sections:
31263
31264 * The first item is included in the headers, and should include at least a
31265 Subject: header. Exim does not check the syntax of these headers.
31266
31267 * The second item forms the start of the warning message. After it, Exim
31268 lists the delayed addresses.
31269
31270 * The third item then ends the message.
31271
31272 The default state is equivalent to the following file, except that some lines
31273 have been split here, in order to fit them on the page:
31274
31275 Subject: Warning: message $message_exim_id delayed
31276 $warn_message_delay
31277 ****
31278 This message was created automatically by mail delivery software.
31279
31280 A message ${if eq{$sender_address}{$warn_message_recipients}
31281 {that you sent }{sent by
31282
31283 <$sender_address>
31284
31285 }}has not been delivered to all of its recipients after
31286 more than $warn_message_delay on the queue on $primary_hostname.
31287
31288 The message identifier is: $message_exim_id
31289 The subject of the message is: $h_subject
31290 The date of the message is: $h_date
31291
31292 The following address(es) have not yet been delivered:
31293 ****
31294 No action is required on your part. Delivery attempts will
31295 continue for some time, and this warning may be repeated at
31296 intervals if the message remains undelivered. Eventually the
31297 mail delivery software will give up, and when that happens,
31298 the message will be returned to you.
31299
31300 However, in the default state the subject and date lines are omitted if no
31301 appropriate headers exist. During the expansion of this file,
31302 $warn_message_delay is set to the delay time in one of the forms "<n> minutes"
31303 or "<n> hours", and $warn_message_recipients contains a list of recipients for
31304 the warning message. There may be more than one if there are multiple addresses
31305 with different errors_to settings on the routers that handled them.
31306
31307
31308
31309 ===============================================================================
31310 49. SOME COMMON CONFIGURATION SETTINGS
31311
31312 This chapter discusses some configuration settings that seem to be fairly
31313 common. More examples and discussion can be found in the Exim book.
31314
31315
31316 49.1 Sending mail to a smart host
31317 ---------------------------------
31318
31319 If you want to send all mail for non-local domains to a "smart host", you
31320 should replace the default dnslookup router with a router which does the
31321 routing explicitly:
31322
31323 send_to_smart_host:
31324 driver = manualroute
31325 route_list = !+local_domains smart.host.name
31326 transport = remote_smtp
31327
31328 You can use the smart host's IP address instead of the name if you wish. If you
31329 are using Exim only to submit messages to a smart host, and not for receiving
31330 incoming messages, you can arrange for it to do the submission synchronously by
31331 setting the mua_wrapper option (see chapter 50).
31332
31333
31334 49.2 Using Exim to handle mailing lists
31335 ---------------------------------------
31336
31337 Exim can be used to run simple mailing lists, but for large and/or complicated
31338 requirements, the use of additional specialized mailing list software such as
31339 Majordomo or Mailman is recommended.
31340
31341 The redirect router can be used to handle mailing lists where each list is
31342 maintained in a separate file, which can therefore be managed by an independent
31343 manager. The domains router option can be used to run these lists in a separate
31344 domain from normal mail. For example:
31345
31346 lists:
31347 driver = redirect
31348 domains = lists.example
31349 file = /usr/lists/$local_part
31350 forbid_pipe
31351 forbid_file
31352 errors_to = $local_part-request@lists.example
31353 no_more
31354
31355 This router is skipped for domains other than lists.example. For addresses in
31356 that domain, it looks for a file that matches the local part. If there is no
31357 such file, the router declines, but because no_more is set, no subsequent
31358 routers are tried, and so the whole delivery fails.
31359
31360 The forbid_pipe and forbid_file options prevent a local part from being
31361 expanded into a file name or a pipe delivery, which is usually inappropriate in
31362 a mailing list.
31363
31364 The errors_to option specifies that any delivery errors caused by addresses
31365 taken from a mailing list are to be sent to the given address rather than the
31366 original sender of the message. However, before acting on this, Exim verifies
31367 the error address, and ignores it if verification fails.
31368
31369 For example, using the configuration above, mail sent to dicts@lists.example is
31370 passed on to those addresses contained in /usr/lists/dicts, with error reports
31371 directed to dicts-request@lists.example, provided that this address can be
31372 verified. There could be a file called /usr/lists/dicts-request containing the
31373 address(es) of this particular list's manager(s), but other approaches, such as
31374 setting up an earlier router (possibly using the local_part_prefix or
31375 local_part_suffix options) to handle addresses of the form owner-xxx or xxx-
31376 request, are also possible.
31377
31378
31379 49.3 Syntax errors in mailing lists
31380 -----------------------------------
31381
31382 If an entry in redirection data contains a syntax error, Exim normally defers
31383 delivery of the original address. That means that a syntax error in a mailing
31384 list holds up all deliveries to the list. This may not be appropriate when a
31385 list is being maintained automatically from data supplied by users, and the
31386 addresses are not rigorously checked.
31387
31388 If the skip_syntax_errors option is set, the redirect router just skips entries
31389 that fail to parse, noting the incident in the log. If in addition
31390 syntax_errors_to is set to a verifiable address, a message is sent to it
31391 whenever a broken address is skipped. It is usually appropriate to set
31392 syntax_errors_to to the same address as errors_to.
31393
31394
31395 49.4 Re-expansion of mailing lists
31396 ----------------------------------
31397
31398 Exim remembers every individual address to which a message has been delivered,
31399 in order to avoid duplication, but it normally stores only the original
31400 recipient addresses with a message. If all the deliveries to a mailing list
31401 cannot be done at the first attempt, the mailing list is re-expanded when the
31402 delivery is next tried. This means that alterations to the list are taken into
31403 account at each delivery attempt, so addresses that have been added to the list
31404 since the message arrived will therefore receive a copy of the message, even
31405 though it pre-dates their subscription.
31406
31407 If this behaviour is felt to be undesirable, the one_time option can be set on
31408 the redirect router. If this is done, any addresses generated by the router
31409 that fail to deliver at the first attempt are added to the message as "top
31410 level" addresses, and the parent address that generated them is marked
31411 "delivered". Thus, expansion of the mailing list does not happen again at the
31412 subsequent delivery attempts. The disadvantage of this is that if any of the
31413 failing addresses are incorrect, correcting them in the file has no effect on
31414 pre-existing messages.
31415
31416 The original top-level address is remembered with each of the generated
31417 addresses, and is output in any log messages. However, any intermediate parent
31418 addresses are not recorded. This makes a difference to the log only if the
31419 all_parents selector is set, but for mailing lists there is normally only one
31420 level of expansion anyway.
31421
31422
31423 49.5 Closed mailing lists
31424 -------------------------
31425
31426 The examples so far have assumed open mailing lists, to which anybody may send
31427 mail. It is also possible to set up closed lists, where mail is accepted from
31428 specified senders only. This is done by making use of the generic senders
31429 option to restrict the router that handles the list.
31430
31431 The following example uses the same file as a list of recipients and as a list
31432 of permitted senders. It requires three routers:
31433
31434 lists_request:
31435 driver = redirect
31436 domains = lists.example
31437 local_part_suffix = -request
31438 file = /usr/lists/$local_part$local_part_suffix
31439 no_more
31440
31441 lists_post:
31442 driver = redirect
31443 domains = lists.example
31444 senders = ${if exists {/usr/lists/$local_part}\
31445 {lsearch;/usr/lists/$local_part}{*}}
31446 file = /usr/lists/$local_part
31447 forbid_pipe
31448 forbid_file
31449 errors_to = $local_part-request@lists.example
31450 no_more
31451
31452 lists_closed:
31453 driver = redirect
31454 domains = lists.example
31455 allow_fail
31456 data = :fail: $local_part@lists.example is a closed mailing list
31457
31458 All three routers have the same domains setting, so for any other domains, they
31459 are all skipped. The first router runs only if the local part ends in -request.
31460 It handles messages to the list manager(s) by means of an open mailing list.
31461
31462 The second router runs only if the senders precondition is satisfied. It checks
31463 for the existence of a list that corresponds to the local part, and then checks
31464 that the sender is on the list by means of a linear search. It is necessary to
31465 check for the existence of the file before trying to search it, because
31466 otherwise Exim thinks there is a configuration error. If the file does not
31467 exist, the expansion of senders is *, which matches all senders. This means
31468 that the router runs, but because there is no list, declines, and no_more
31469 ensures that no further routers are run. The address fails with an "unrouteable
31470 address" error.
31471
31472 The third router runs only if the second router is skipped, which happens when
31473 a mailing list exists, but the sender is not on it. This router forcibly fails
31474 the address, giving a suitable error message.
31475
31476
31477 49.6 Variable Envelope Return Paths (VERP)
31478 ------------------------------------------
31479
31480 Variable Envelope Return Paths - see http://cr.yp.to/proto/verp.txt - are a way
31481 of helping mailing list administrators discover which subscription address is
31482 the cause of a particular delivery failure. The idea is to encode the original
31483 recipient address in the outgoing envelope sender address, so that if the
31484 message is forwarded by another host and then subsequently bounces, the
31485 original recipient can be extracted from the recipient address of the bounce.
31486
31487 Envelope sender addresses can be modified by Exim using two different
31488 facilities: the errors_to option on a router (as shown in previous mailing list
31489 examples), or the return_path option on a transport. The second of these is
31490 effective only if the message is successfully delivered to another host; it is
31491 not used for errors detected on the local host (see the description of
31492 return_path in chapter 24). Here is an example of the use of return_path to
31493 implement VERP on an smtp transport:
31494
31495 verp_smtp:
31496 driver = smtp
31497 max_rcpt = 1
31498 return_path = \
31499 ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\
31500 {$1-request+$local_part=$domain@your.dom.example}fail}
31501
31502 This has the effect of rewriting the return path (envelope sender) on outgoing
31503 SMTP messages, if the local part of the original return path ends in
31504 "-request", and the domain is your.dom.example. The rewriting inserts the local
31505 part and domain of the recipient into the return path. Suppose, for example,
31506 that a message whose return path has been set to
31507 somelist-request@your.dom.example is sent to subscriber@other.dom.example. In
31508 the transport, the return path is rewritten as
31509
31510 somelist-request+subscriber=other.dom.example@your.dom.example
31511
31512 For this to work, you must tell Exim to send multiple copies of messages that
31513 have more than one recipient, so that each copy has just one recipient. This is
31514 achieved by setting max_rcpt to 1. Without this, a single copy of a message
31515 might be sent to several different recipients in the same domain, in which case
31516 $local_part is not available in the transport, because it is not unique.
31517
31518 Unless your host is doing nothing but mailing list deliveries, you should
31519 probably use a separate transport for the VERP deliveries, so as not to use
31520 extra resources in making one-per-recipient copies for other deliveries. This
31521 can easily be done by expanding the transport option in the router:
31522
31523 dnslookup:
31524 driver = dnslookup
31525 domains = ! +local_domains
31526 transport = \
31527 ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\
31528 {verp_smtp}{remote_smtp}}
31529 no_more
31530
31531 If you want to change the return path using errors_to in a router instead of
31532 using return_path in the transport, you need to set errors_to on all routers
31533 that handle mailing list addresses. This will ensure that all delivery errors,
31534 including those detected on the local host, are sent to the VERP address.
31535
31536 On a host that does no local deliveries and has no manual routing, only the
31537 dnslookup router needs to be changed. A special transport is not needed for
31538 SMTP deliveries. Every mailing list recipient has its own return path value,
31539 and so Exim must hand them to the transport one at a time. Here is an example
31540 of a dnslookup router that implements VERP:
31541
31542 verp_dnslookup:
31543 driver = dnslookup
31544 domains = ! +local_domains
31545 transport = remote_smtp
31546 errors_to = \
31547 ${if match {$return_path}{^(.+?)-request@your.dom.example\$}}
31548 {$1-request+$local_part=$domain@your.dom.example}fail}
31549 no_more
31550
31551 Before you start sending out messages with VERPed return paths, you must also
31552 configure Exim to accept the bounce messages that come back to those paths.
31553 Typically this is done by setting a local_part_suffix option for a router, and
31554 using this to route the messages to wherever you want to handle them.
31555
31556 The overhead incurred in using VERP depends very much on the size of the
31557 message, the number of recipient addresses that resolve to the same remote
31558 host, and the speed of the connection over which the message is being sent. If
31559 a lot of addresses resolve to the same host and the connection is slow, sending
31560 a separate copy of the message for each address may take substantially longer
31561 than sending a single copy with many recipients (for which VERP cannot be
31562 used).
31563
31564
31565 49.7 Virtual domains
31566 --------------------
31567
31568 The phrase virtual domain is unfortunately used with two rather different
31569 meanings:
31570
31571 * A domain for which there are no real mailboxes; all valid local parts are
31572 aliases for other email addresses. Common examples are organizational
31573 top-level domains and "vanity" domains.
31574
31575 * One of a number of independent domains that are all handled by the same
31576 host, with mailboxes on that host, but where the mailbox owners do not
31577 necessarily have login accounts on that host.
31578
31579 The first usage is probably more common, and does seem more "virtual" than the
31580 second. This kind of domain can be handled in Exim with a straightforward
31581 aliasing router. One approach is to create a separate alias file for each
31582 virtual domain. Exim can test for the existence of the alias file to determine
31583 whether the domain exists. The dsearch lookup type is useful here, leading to a
31584 router of this form:
31585
31586 virtual:
31587 driver = redirect
31588 domains = dsearch;/etc/mail/virtual
31589 data = ${lookup{$local_part}lsearch{/etc/mail/virtual/$domain}}
31590 no_more
31591
31592 The domains option specifies that the router is to be skipped, unless there is
31593 a file in the /etc/mail/virtual directory whose name is the same as the domain
31594 that is being processed. When the router runs, it looks up the local part in
31595 the file to find a new address (or list of addresses). The no_more setting
31596 ensures that if the lookup fails (leading to data being an empty string), Exim
31597 gives up on the address without trying any subsequent routers.
31598
31599 This one router can handle all the virtual domains because the alias file names
31600 follow a fixed pattern. Permissions can be arranged so that appropriate people
31601 can edit the different alias files. A successful aliasing operation results in
31602 a new envelope recipient address, which is then routed from scratch.
31603
31604 The other kind of "virtual" domain can also be handled in a straightforward
31605 way. One approach is to create a file for each domain containing a list of
31606 valid local parts, and use it in a router like this:
31607
31608 my_domains:
31609 driver = accept
31610 domains = dsearch;/etc/mail/domains
31611 local_parts = lsearch;/etc/mail/domains/$domain
31612 transport = my_mailboxes
31613
31614 The address is accepted if there is a file for the domain, and the local part
31615 can be found in the file. The domains option is used to check for the file's
31616 existence because domains is tested before the local_parts option (see section
31617 3.12). You cannot use require_files, because that option is tested after
31618 local_parts. The transport is as follows:
31619
31620 my_mailboxes:
31621 driver = appendfile
31622 file = /var/mail/$domain/$local_part
31623 user = mail
31624
31625 This uses a directory of mailboxes for each domain. The user setting is
31626 required, to specify which uid is to be used for writing to the mailboxes.
31627
31628 The configuration shown here is just one example of how you might support this
31629 requirement. There are many other ways this kind of configuration can be set
31630 up, for example, by using a database instead of separate files to hold all the
31631 information about the domains.
31632
31633
31634 49.8 Multiple user mailboxes
31635 ----------------------------
31636
31637 Heavy email users often want to operate with multiple mailboxes, into which
31638 incoming mail is automatically sorted. A popular way of handling this is to
31639 allow users to use multiple sender addresses, so that replies can easily be
31640 identified. Users are permitted to add prefixes or suffixes to their local
31641 parts for this purpose. The wildcard facility of the generic router options
31642 local_part_prefix and local_part_suffix can be used for this. For example,
31643 consider this router:
31644
31645 userforward:
31646 driver = redirect
31647 check_local_user
31648 file = $home/.forward
31649 local_part_suffix = -*
31650 local_part_suffix_optional
31651 allow_filter
31652
31653 It runs a user's .forward file for all local parts of the form username-*.
31654 Within the filter file the user can distinguish different cases by testing the
31655 variable $local_part_suffix. For example:
31656
31657 if $local_part_suffix contains -special then
31658 save /home/$local_part/Mail/special
31659 endif
31660
31661 If the filter file does not exist, or does not deal with such addresses, they
31662 fall through to subsequent routers, and, assuming no subsequent use of the
31663 local_part_suffix option is made, they presumably fail. Thus, users have
31664 control over which suffixes are valid.
31665
31666 Alternatively, a suffix can be used to trigger the use of a different .forward
31667 file - which is the way a similar facility is implemented in another MTA:
31668
31669 userforward:
31670 driver = redirect
31671 check_local_user
31672 file = $home/.forward$local_part_suffix
31673 local_part_suffix = -*
31674 local_part_suffix_optional
31675 allow_filter
31676
31677 If there is no suffix, .forward is used; if the suffix is -special, for
31678 example, .forward-special is used. Once again, if the appropriate file does not
31679 exist, or does not deal with the address, it is passed on to subsequent
31680 routers, which could, if required, look for an unqualified .forward file to use
31681 as a default.
31682
31683
31684 49.9 Simplified vacation processing
31685 -----------------------------------
31686
31687 The traditional way of running the vacation program is for a user to set up a
31688 pipe command in a .forward file (see section 22.6 for syntax details). This is
31689 prone to error by inexperienced users. There are two features of Exim that can
31690 be used to make this process simpler for users:
31691
31692 * A local part prefix such as "vacation-" can be specified on a router which
31693 can cause the message to be delivered directly to the vacation program, or
31694 alternatively can use Exim's autoreply transport. The contents of a user's
31695 .forward file are then much simpler. For example:
31696
31697 spqr, vacation-spqr
31698
31699 * The require_files generic router option can be used to trigger a vacation
31700 delivery by checking for the existence of a certain file in the user's home
31701 directory. The unseen generic option should also be used, to ensure that
31702 the original delivery also proceeds. In this case, all the user has to do
31703 is to create a file called, say, .vacation, containing a vacation message.
31704
31705 Another advantage of both these methods is that they both work even when the
31706 use of arbitrary pipes by users is locked out.
31707
31708
31709 49.10 Taking copies of mail
31710 ---------------------------
31711
31712 Some installations have policies that require archive copies of all messages to
31713 be made. A single copy of each message can easily be taken by an appropriate
31714 command in a system filter, which could, for example, use a different file for
31715 each day's messages.
31716
31717 There is also a shadow transport mechanism that can be used to take copies of
31718 messages that are successfully delivered by local transports, one copy per
31719 delivery. This could be used, inter alia, to implement automatic notification
31720 of delivery by sites that insist on doing such things.
31721
31722
31723 49.11 Intermittently connected hosts
31724 ------------------------------------
31725
31726 It has become quite common (because it is cheaper) for hosts to connect to the
31727 Internet periodically rather than remain connected all the time. The normal
31728 arrangement is that mail for such hosts accumulates on a system that is
31729 permanently connected.
31730
31731 Exim was designed for use on permanently connected hosts, and so it is not
31732 particularly well-suited to use in an intermittently connected environment.
31733 Nevertheless there are some features that can be used.
31734
31735
31736 49.12 Exim on the upstream server host
31737 --------------------------------------
31738
31739 It is tempting to arrange for incoming mail for the intermittently connected
31740 host to remain on Exim's queue until the client connects. However, this
31741 approach does not scale very well. Two different kinds of waiting message are
31742 being mixed up in the same queue - those that cannot be delivered because of
31743 some temporary problem, and those that are waiting for their destination host
31744 to connect. This makes it hard to manage the queue, as well as wasting
31745 resources, because each queue runner scans the entire queue.
31746
31747 A better approach is to separate off those messages that are waiting for an
31748 intermittently connected host. This can be done by delivering these messages
31749 into local files in batch SMTP, "mailstore", or other envelope-preserving
31750 format, from where they are transmitted by other software when their
31751 destination connects. This makes it easy to collect all the mail for one host
31752 in a single directory, and to apply local timeout rules on a per-message basis
31753 if required.
31754
31755 On a very small scale, leaving the mail on Exim's queue can be made to work. If
31756 you are doing this, you should configure Exim with a long retry period for the
31757 intermittent host. For example:
31758
31759 cheshire.wonderland.fict.example * F,5d,24h
31760
31761 This stops a lot of failed delivery attempts from occurring, but Exim remembers
31762 which messages it has queued up for that host. Once the intermittent host comes
31763 online, forcing delivery of one message (either by using the -M or -R options,
31764 or by using the ETRN SMTP command (see section 47.8) causes all the queued up
31765 messages to be delivered, often down a single SMTP connection. While the host
31766 remains connected, any new messages get delivered immediately.
31767
31768 If the connecting hosts do not have fixed IP addresses, that is, if a host is
31769 issued with a different IP address each time it connects, Exim's retry
31770 mechanisms on the holding host get confused, because the IP address is normally
31771 used as part of the key string for holding retry information. This can be
31772 avoided by unsetting retry_include_ip_address on the smtp transport. Since this
31773 has disadvantages for permanently connected hosts, it is best to arrange a
31774 separate transport for the intermittently connected ones.
31775
31776
31777 49.13 Exim on the intermittently connected client host
31778 ------------------------------------------------------
31779
31780 The value of smtp_accept_queue_per_connection should probably be increased, or
31781 even set to zero (that is, disabled) on the intermittently connected host, so
31782 that all incoming messages down a single connection get delivered immediately.
31783
31784 Mail waiting to be sent from an intermittently connected host will probably not
31785 have been routed, because without a connection DNS lookups are not possible.
31786 This means that if a normal queue run is done at connection time, each message
31787 is likely to be sent in a separate SMTP session. This can be avoided by
31788 starting the queue run with a command line option beginning with -qq instead of
31789 -q. In this case, the queue is scanned twice. In the first pass, routing is
31790 done but no deliveries take place. The second pass is a normal queue run; since
31791 all the messages have been previously routed, those destined for the same host
31792 are likely to get sent as multiple deliveries in a single SMTP connection.
31793
31794
31795
31796 ===============================================================================
31797 50. USING EXIM AS A NON-QUEUEING CLIENT
31798
31799 On a personal computer, it is a common requirement for all email to be sent to
31800 a "smart host". There are plenty of MUAs that can be configured to operate that
31801 way, for all the popular operating systems. However, there are some MUAs for
31802 Unix-like systems that cannot be so configured: they submit messages using the
31803 command line interface of /usr/sbin/sendmail. Furthermore, utility programs
31804 such as cron submit messages this way.
31805
31806 If the personal computer runs continuously, there is no problem, because it can
31807 run a conventional MTA that handles delivery to the smart host, and deal with
31808 any delays via its queueing mechanism. However, if the computer does not run
31809 continuously or runs different operating systems at different times, queueing
31810 email is not desirable.
31811
31812 There is therefore a requirement for something that can provide the /usr/sbin/
31813 sendmail interface but deliver messages to a smart host without any queueing or
31814 retrying facilities. Furthermore, the delivery to the smart host should be
31815 synchronous, so that if it fails, the sending MUA is immediately informed. In
31816 other words, we want something that extends an MUA that submits to a local MTA
31817 via the command line so that it behaves like one that submits to a remote smart
31818 host using TCP/SMTP.
31819
31820 There are a number of applications (for example, there is one called ssmtp)
31821 that do this job. However, people have found them to be lacking in various
31822 ways. For instance, you might want to allow aliasing and forwarding to be done
31823 before sending a message to the smart host.
31824
31825 Exim already had the necessary infrastructure for doing this job. Just a few
31826 tweaks were needed to make it behave as required, though it is somewhat of an
31827 overkill to use a fully-featured MTA for this purpose.
31828
31829 There is a Boolean global option called mua_wrapper, defaulting false. Setting
31830 mua_wrapper true causes Exim to run in a special mode where it assumes that it
31831 is being used to "wrap" a command-line MUA in the manner just described. As
31832 well as setting mua_wrapper, you also need to provide a compatible router and
31833 transport configuration. Typically there will be just one router and one
31834 transport, sending everything to a smart host.
31835
31836 When run in MUA wrapping mode, the behaviour of Exim changes in the following
31837 ways:
31838
31839 * A daemon cannot be run, nor will Exim accept incoming messages from inetd.
31840 In other words, the only way to submit messages is via the command line.
31841
31842 * Each message is synchronously delivered as soon as it is received (-odi is
31843 assumed). All queueing options (queue_only, queue_smtp_domains, control in
31844 an ACL, etc.) are quietly ignored. The Exim reception process does not
31845 finish until the delivery attempt is complete. If the delivery is
31846 successful, a zero return code is given.
31847
31848 * Address redirection is permitted, but the final routing for all addresses
31849 must be to the same remote transport, and to the same list of hosts.
31850 Furthermore, the return address (envelope sender) must be the same for all
31851 recipients, as must any added or deleted header lines. In other words, it
31852 must be possible to deliver the message in a single SMTP transaction,
31853 however many recipients there are.
31854
31855 * If these conditions are not met, or if routing any address results in a
31856 failure or defer status, or if Exim is unable to deliver all the recipients
31857 successfully to one of the smart hosts, delivery of the entire message
31858 fails.
31859
31860 * Because no queueing is allowed, all failures are treated as permanent;
31861 there is no distinction between 4xx and 5xx SMTP response codes from the
31862 smart host. Furthermore, because only a single yes/no response can be given
31863 to the caller, it is not possible to deliver to some recipients and not
31864 others. If there is an error (temporary or permanent) for any recipient,
31865 all are failed.
31866
31867 * If more than one smart host is listed, Exim will try another host after a
31868 connection failure or a timeout, in the normal way. However, if this kind
31869 of failure happens for all the hosts, the delivery fails.
31870
31871 * When delivery fails, an error message is written to the standard error
31872 stream (as well as to Exim's log), and Exim exits to the caller with a
31873 return code value 1. The message is expunged from Exim's spool files. No
31874 bounce messages are ever generated.
31875
31876 * No retry data is maintained, and any retry rules are ignored.
31877
31878 * A number of Exim options are overridden: deliver_drop_privilege is forced
31879 true, max_rcpt in the smtp transport is forced to "unlimited",
31880 remote_max_parallel is forced to one, and fallback hosts are ignored.
31881
31882 The overall effect is that Exim makes a single synchronous attempt to deliver
31883 the message, failing if there is any kind of problem. Because no local
31884 deliveries are done and no daemon can be run, Exim does not need root
31885 privilege. It should be possible to run it setuid to exim instead of setuid to
31886 root. See section 54.3 for a general discussion about the advantages and
31887 disadvantages of running without root privilege.
31888
31889
31890
31891 ===============================================================================
31892 51. LOG FILES
31893
31894 Exim writes three different logs, referred to as the main log, the reject log,
31895 and the panic log:
31896
31897 * The main log records the arrival of each message and each delivery in a
31898 single line in each case. The format is as compact as possible, in an
31899 attempt to keep down the size of log files. Two-character flag sequences
31900 make it easy to pick out these lines. A number of other events are recorded
31901 in the main log. Some of them are optional, in which case the log_selector
31902 option controls whether they are included or not. A Perl script called
31903 eximstats, which does simple analysis of main log files, is provided in the
31904 Exim distribution (see section 52.7).
31905
31906 * The reject log records information from messages that are rejected as a
31907 result of a configuration option (that is, for policy reasons). The first
31908 line of each rejection is a copy of the line that is also written to the
31909 main log. Then, if the message's header has been read at the time the log
31910 is written, its contents are written to this log. Only the original header
31911 lines are available; header lines added by ACLs are not logged. You can use
31912 the reject log to check that your policy controls are working correctly; on
31913 a busy host this may be easier than scanning the main log for rejection
31914 messages. You can suppress the writing of the reject log by setting
31915 write_rejectlog false.
31916
31917 * When certain serious errors occur, Exim writes entries to its panic log. If
31918 the error is sufficiently disastrous, Exim bombs out afterwards. Panic log
31919 entries are usually written to the main log as well, but can get lost amid
31920 the mass of other entries. The panic log should be empty under normal
31921 circumstances. It is therefore a good idea to check it (or to have a cron
31922 script check it) regularly, in order to become aware of any problems. When
31923 Exim cannot open its panic log, it tries as a last resort to write to the
31924 system log (syslog). This is opened with LOG_PID+LOG_CONS and the facility
31925 code of LOG_MAIL. The message itself is written at priority LOG_CRIT.
31926
31927 Every log line starts with a timestamp, in the format shown in the following
31928 example. Note that many of the examples shown in this chapter are line-wrapped.
31929 In the log file, this would be all on one line:
31930
31931 2001-09-16 16:09:47 SMTP connection from [127.0.0.1] closed
31932 by QUIT
31933
31934 By default, the timestamps are in the local timezone. There are two ways of
31935 changing this:
31936
31937 * You can set the timezone option to a different time zone; in particular, if
31938 you set
31939
31940 timezone = UTC
31941
31942 the timestamps will be in UTC (aka GMT).
31943
31944 * If you set log_timezone true, the time zone is added to the timestamp, for
31945 example:
31946
31947 2003-04-25 11:17:07 +0100 Start queue run: pid=12762
31948
31949 Exim does not include its process id in log lines by default, but you can
31950 request that it does so by specifying the "pid" log selector (see section 51.15
31951 ). When this is set, the process id is output, in square brackets, immediately
31952 after the time and date.
31953
31954
31955 51.1 Where the logs are written
31956 -------------------------------
31957
31958 The logs may be written to local files, or to syslog, or both. However, it
31959 should be noted that many syslog implementations use UDP as a transport, and
31960 are therefore unreliable in the sense that messages are not guaranteed to
31961 arrive at the loghost, nor is the ordering of messages necessarily maintained.
31962 It has also been reported that on large log files (tens of megabytes) you may
31963 need to tweak syslog to prevent it syncing the file with each write - on Linux
31964 this has been seen to make syslog take 90% plus of CPU time.
31965
31966 The destination for Exim's logs is configured by setting LOG_FILE_PATH in Local
31967 /Makefile or by setting log_file_path in the run time configuration. This
31968 latter string is expanded, so it can contain, for example, references to the
31969 host name:
31970
31971 log_file_path = /var/log/$primary_hostname/exim_%slog
31972
31973 It is generally advisable, however, to set the string in Local/Makefile rather
31974 than at run time, because then the setting is available right from the start of
31975 Exim's execution. Otherwise, if there's something it wants to log before it has
31976 read the configuration file (for example, an error in the configuration file)
31977 it will not use the path you want, and may not be able to log at all.
31978
31979 The value of LOG_FILE_PATH or log_file_path is a colon-separated list,
31980 currently limited to at most two items. This is one option where the facility
31981 for changing a list separator may not be used. The list must always be
31982 colon-separated. If an item in the list is "syslog" then syslog is used;
31983 otherwise the item must either be an absolute path, containing "%s" at the
31984 point where "main", "reject", or "panic" is to be inserted, or be empty,
31985 implying the use of a default path.
31986
31987 When Exim encounters an empty item in the list, it searches the list defined by
31988 LOG_FILE_PATH, and uses the first item it finds that is neither empty nor
31989 "syslog". This means that an empty item in log_file_path can be used to mean
31990 "use the path specified at build time". It no such item exists, log files are
31991 written in the log subdirectory of the spool directory. This is equivalent to
31992 the setting:
31993
31994 log_file_path = $spool_directory/log/%slog
31995
31996 If you do not specify anything at build time or run time, that is where the
31997 logs are written.
31998
31999 A log file path may also contain "%D" or "%M" if datestamped log file names are
32000 in use - see section 51.3 below.
32001
32002 Here are some examples of possible settings:
32003
32004 LOG_FILE_PATH=syslog syslog only
32005 LOG_FILE_PATH=:syslog syslog and default path
32006 LOG_FILE_PATH=syslog : /usr/log/exim_%s syslog and specified path
32007 LOG_FILE_PATH=/usr/log/exim_%s specified path only
32008
32009 If there are more than two paths in the list, the first is used and a panic
32010 error is logged.
32011
32012
32013 51.2 Logging to local files that are periodically "cycled"
32014 ----------------------------------------------------------
32015
32016 Some operating systems provide centralized and standardized methods for cycling
32017 log files. For those that do not, a utility script called exicyclog is provided
32018 (see section 52.6). This renames and compresses the main and reject logs each
32019 time it is called. The maximum number of old logs to keep can be set. It is
32020 suggested this script is run as a daily cron job.
32021
32022 An Exim delivery process opens the main log when it first needs to write to it,
32023 and it keeps the file open in case subsequent entries are required - for
32024 example, if a number of different deliveries are being done for the same
32025 message. However, remote SMTP deliveries can take a long time, and this means
32026 that the file may be kept open long after it is renamed if exicyclog or
32027 something similar is being used to rename log files on a regular basis. To
32028 ensure that a switch of log files is noticed as soon as possible, Exim calls
32029 stat() on the main log's name before reusing an open file, and if the file does
32030 not exist, or its inode has changed, the old file is closed and Exim tries to
32031 open the main log from scratch. Thus, an old log file may remain open for quite
32032 some time, but no Exim processes should write to it once it has been renamed.
32033
32034
32035 51.3 Datestamped log files
32036 --------------------------
32037
32038 Instead of cycling the main and reject log files by renaming them periodically,
32039 some sites like to use files whose names contain a datestamp, for example,
32040 mainlog-20031225. The datestamp is in the form yyyymmdd or yyyymm. Exim has
32041 support for this way of working. It is enabled by setting the log_file_path
32042 option to a path that includes "%D" or "%M" at the point where the datestamp is
32043 required. For example:
32044
32045 log_file_path = /var/spool/exim/log/%slog-%D
32046 log_file_path = /var/log/exim-%s-%D.log
32047 log_file_path = /var/spool/exim/log/%D-%slog
32048 log_file_path = /var/log/exim/%s.%M
32049
32050 As before, "%s" is replaced by "main" or "reject"; the following are examples
32051 of names generated by the above examples:
32052
32053 /var/spool/exim/log/mainlog-20021225
32054 /var/log/exim-reject-20021225.log
32055 /var/spool/exim/log/20021225-mainlog
32056 /var/log/exim/main.200212
32057
32058 When this form of log file is specified, Exim automatically switches to new
32059 files at midnight. It does not make any attempt to compress old logs; you will
32060 need to write your own script if you require this. You should not run exicyclog
32061 with this form of logging.
32062
32063 The location of the panic log is also determined by log_file_path, but it is
32064 not datestamped, because rotation of the panic log does not make sense. When
32065 generating the name of the panic log, "%D" or "%M" are removed from the string.
32066 In addition, if it immediately follows a slash, a following non-alphanumeric
32067 character is removed; otherwise a preceding non-alphanumeric character is
32068 removed. Thus, the four examples above would give these panic log names:
32069
32070 /var/spool/exim/log/paniclog
32071 /var/log/exim-panic.log
32072 /var/spool/exim/log/paniclog
32073 /var/log/exim/panic
32074
32075
32076 51.4 Logging to syslog
32077 ----------------------
32078
32079 The use of syslog does not change what Exim logs or the format of its messages,
32080 except in one respect. If syslog_timestamp is set false, the timestamps on
32081 Exim's log lines are omitted when these lines are sent to syslog. Apart from
32082 that, the same strings are written to syslog as to log files. The syslog
32083 "facility" is set to LOG_MAIL, and the program name to "exim" by default, but
32084 you can change these by setting the syslog_facility and syslog_processname
32085 options, respectively. If Exim was compiled with SYSLOG_LOG_PID set in Local/
32086 Makefile (this is the default in src/EDITME), then, on systems that permit it
32087 (all except ULTRIX), the LOG_PID flag is set so that the syslog() call adds the
32088 pid as well as the time and host name to each line. The three log streams are
32089 mapped onto syslog priorities as follows:
32090
32091 * mainlog is mapped to LOG_INFO
32092
32093 * rejectlog is mapped to LOG_NOTICE
32094
32095 * paniclog is mapped to LOG_ALERT
32096
32097 Many log lines are written to both mainlog and rejectlog, and some are written
32098 to both mainlog and paniclog, so there will be duplicates if these are routed
32099 by syslog to the same place. You can suppress this duplication by setting
32100 syslog_duplication false.
32101
32102 Exim's log lines can sometimes be very long, and some of its rejectlog entries
32103 contain multiple lines when headers are included. To cope with both these
32104 cases, entries written to syslog are split into separate syslog() calls at each
32105 internal newline, and also after a maximum of 870 data characters. (This allows
32106 for a total syslog line length of 1024, when additions such as timestamps are
32107 added.) If you are running a syslog replacement that can handle lines longer
32108 than the 1024 characters allowed by RFC 3164, you should set
32109
32110 SYSLOG_LONG_LINES=yes
32111
32112 in Local/Makefile before building Exim. That stops Exim from splitting long
32113 lines, but it still splits at internal newlines in reject log entries.
32114
32115 To make it easy to re-assemble split lines later, each component of a split
32116 entry starts with a string of the form [<n>/<m>] or [<n>\<m>] where <n> is the
32117 component number and <m> is the total number of components in the entry. The /
32118 delimiter is used when the line was split because it was too long; if it was
32119 split because of an internal newline, the \ delimiter is used. For example,
32120 supposing the length limit to be 50 instead of 870, the following would be the
32121 result of a typical rejection message to mainlog (LOG_INFO), each line in
32122 addition being preceded by the time, host name, and pid as added by syslog:
32123
32124 [1/5] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected from
32125 [2/5] [127.0.0.1] (ph10): syntax error in 'From' header
32126 [3/5] when scanning for sender: missing or malformed lo
32127 [4/5] cal part in "<>" (envelope sender is <ph10@cam.exa
32128 [5/5] mple>)
32129
32130 The same error might cause the following lines to be written to "rejectlog"
32131 (LOG_NOTICE):
32132
32133 [1/18] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected fro
32134 [2/18] m [127.0.0.1] (ph10): syntax error in 'From' head
32135 [3/18] er when scanning for sender: missing or malformed
32136 [4/18] local part in "<>" (envelope sender is <ph10@cam
32137 [5\18] .example>)
32138 [6\18] Recipients: ph10@some.domain.cam.example
32139 [7\18] P Received: from [127.0.0.1] (ident=ph10)
32140 [8\18] by xxxxx.cam.example with smtp (Exim 4.00)
32141 [9\18] id 16RdAL-0006pc-00
32142 [10/18] for ph10@cam.example; Mon, 16 Sep 2002 16:
32143 [11\18] 09:43 +0100
32144 [12\18] F From: <>
32145 [13\18] Subject: this is a test header
32146 [18\18] X-something: this is another header
32147 [15/18] I Message-Id: <E16RdAL-0006pc-00@xxxxx.cam.examp
32148 [16\18] le>
32149 [17\18] B Bcc:
32150 [18/18] Date: Mon, 16 Sep 2002 16:09:43 +0100
32151
32152 Log lines that are neither too long nor contain newlines are written to syslog
32153 without modification.
32154
32155 If only syslog is being used, the Exim monitor is unable to provide a log tail
32156 display, unless syslog is routing mainlog to a file on the local host and the
32157 environment variable EXIMON_LOG_FILE_PATH is set to tell the monitor where it
32158 is.
32159
32160
32161 51.5 Log line flags
32162 -------------------
32163
32164 One line is written to the main log for each message received, and for each
32165 successful, unsuccessful, and delayed delivery. These lines can readily be
32166 picked out by the distinctive two-character flags that immediately follow the
32167 timestamp. The flags are:
32168
32169 <= message arrival
32170 => normal message delivery
32171 -> additional address in same delivery
32172 >> cutthrough message delivery
32173 *> delivery suppressed by -N
32174 ** delivery failed; address bounced
32175 == delivery deferred; temporary problem
32176
32177
32178 51.6 Logging message reception
32179 ------------------------------
32180
32181 The format of the single-line entry in the main log that is written for every
32182 message received is shown in the basic example below, which is split over
32183 several lines in order to fit it on the page:
32184
32185 2002-10-31 08:57:53 16ZCW1-0005MB-00 <= kryten@dwarf.fict.example
32186 H=mailer.fict.example [192.168.123.123] U=exim
32187 P=smtp S=5678 id=<incoming message id>
32188
32189 The address immediately following "<=" is the envelope sender address. A bounce
32190 message is shown with the sender address "<>", and if it is locally generated,
32191 this is followed by an item of the form
32192
32193 R=<message id>
32194
32195 which is a reference to the message that caused the bounce to be sent.
32196
32197 For messages from other hosts, the H and U fields identify the remote host and
32198 record the RFC 1413 identity of the user that sent the message, if one was
32199 received. The number given in square brackets is the IP address of the sending
32200 host. If there is a single, unparenthesized host name in the H field, as above,
32201 it has been verified to correspond to the IP address (see the host_lookup
32202 option). If the name is in parentheses, it was the name quoted by the remote
32203 host in the SMTP HELO or EHLO command, and has not been verified. If
32204 verification yields a different name to that given for HELO or EHLO, the
32205 verified name appears first, followed by the HELO or EHLO name in parentheses.
32206
32207 Misconfigured hosts (and mail forgers) sometimes put an IP address, with or
32208 without brackets, in the HELO or EHLO command, leading to entries in the log
32209 containing text like these examples:
32210
32211 H=(10.21.32.43) [192.168.8.34]
32212 H=([10.21.32.43]) [192.168.8.34]
32213
32214 This can be confusing. Only the final address in square brackets can be relied
32215 on.
32216
32217 For locally generated messages (that is, messages not received over TCP/IP),
32218 the H field is omitted, and the U field contains the login name of the caller
32219 of Exim.
32220
32221 For all messages, the P field specifies the protocol used to receive the
32222 message. This is the value that is stored in $received_protocol. In the case of
32223 incoming SMTP messages, the value indicates whether or not any SMTP extensions
32224 (ESMTP), encryption, or authentication were used. If the SMTP session was
32225 encrypted, there is an additional X field that records the cipher suite that
32226 was used.
32227
32228 The protocol is set to "esmtpsa" or "esmtpa" for messages received from hosts
32229 that have authenticated themselves using the SMTP AUTH command. The first value
32230 is used when the SMTP connection was encrypted ("secure"). In this case there
32231 is an additional item A= followed by the name of the authenticator that was
32232 used. If an authenticated identification was set up by the authenticator's
32233 server_set_id option, this is logged too, separated by a colon from the
32234 authenticator name.
32235
32236 The id field records the existing message id, if present. The size of the
32237 received message is given by the S field. When the message is delivered,
32238 headers may be removed or added, so that the size of delivered copies of the
32239 message may not correspond with this value (and indeed may be different to each
32240 other).
32241
32242 The log_selector option can be used to request the logging of additional data
32243 when a message is received. See section 51.15 below.
32244
32245
32246 51.7 Logging deliveries
32247 -----------------------
32248
32249 The format of the single-line entry in the main log that is written for every
32250 delivery is shown in one of the examples below, for local and remote
32251 deliveries, respectively. Each example has been split into two lines in order
32252 to fit it on the page:
32253
32254 2002-10-31 08:59:13 16ZCW1-0005MB-00 => marv
32255 <marv@hitch.fict.example> R=localuser T=local_delivery
32256 2002-10-31 09:00:10 16ZCW1-0005MB-00 =>
32257 monk@holistic.fict.example R=dnslookup T=remote_smtp
32258 H=holistic.fict.example [192.168.234.234]
32259
32260 For ordinary local deliveries, the original address is given in angle brackets
32261 after the final delivery address, which might be a pipe or a file. If
32262 intermediate address(es) exist between the original and the final address, the
32263 last of these is given in parentheses after the final address. The R and T
32264 fields record the router and transport that were used to process the address.
32265
32266 If SMTP AUTH was used for the delivery there is an additional item A= followed
32267 by the name of the authenticator that was used. If an authenticated
32268 identification was set up by the authenticator's client_set_id option, this is
32269 logged too, separated by a colon from the authenticator name.
32270
32271 If a shadow transport was run after a successful local delivery, the log line
32272 for the successful delivery has an item added on the end, of the form
32273
32274 ST=<shadow transport name>
32275
32276 If the shadow transport did not succeed, the error message is put in
32277 parentheses afterwards.
32278
32279 When more than one address is included in a single delivery (for example, two
32280 SMTP RCPT commands in one transaction) the second and subsequent addresses are
32281 flagged with "->" instead of "=>". When two or more messages are delivered down
32282 a single SMTP connection, an asterisk follows the IP address in the log lines
32283 for the second and subsequent messages.
32284
32285 When delivery is done in cutthrough mode it is flagged with ">>" and the log
32286 line precedes the reception line, since cutthrough waits for a possible
32287 rejection from the destination in case it can reject the sourced item.
32288
32289 The generation of a reply message by a filter file gets logged as a "delivery"
32290 to the addressee, preceded by ">".
32291
32292 The log_selector option can be used to request the logging of additional data
32293 when a message is delivered. See section 51.15 below.
32294
32295
32296 51.8 Discarded deliveries
32297 -------------------------
32298
32299 When a message is discarded as a result of the command "seen finish" being
32300 obeyed in a filter file which generates no deliveries, a log entry of the form
32301
32302 2002-12-10 00:50:49 16auJc-0001UB-00 => discarded
32303 <low.club@bridge.example> R=userforward
32304
32305 is written, to record why no deliveries are logged. When a message is discarded
32306 because it is aliased to ":blackhole:" the log line is like this:
32307
32308 1999-03-02 09:44:33 10HmaX-0005vi-00 => :blackhole:
32309 <hole@nowhere.example> R=blackhole_router
32310
32311
32312 51.9 Deferred deliveries
32313 ------------------------
32314
32315 When a delivery is deferred, a line of the following form is logged:
32316
32317 2002-12-19 16:20:23 16aiQz-0002Q5-00 == marvin@endrest.example
32318 R=dnslookup T=smtp defer (146): Connection refused
32319
32320 In the case of remote deliveries, the error is the one that was given for the
32321 last IP address that was tried. Details of individual SMTP failures are also
32322 written to the log, so the above line would be preceded by something like
32323
32324 2002-12-19 16:20:23 16aiQz-0002Q5-00 Failed to connect to
32325 mail1.endrest.example [192.168.239.239]: Connection refused
32326
32327 When a deferred address is skipped because its retry time has not been reached,
32328 a message is written to the log, but this can be suppressed by setting an
32329 appropriate value in log_selector.
32330
32331
32332 51.10 Delivery failures
32333 -----------------------
32334
32335 If a delivery fails because an address cannot be routed, a line of the
32336 following form is logged:
32337
32338 1995-12-19 16:20:23 0tRiQz-0002Q5-00 ** jim@trek99.example
32339 <jim@trek99.example>: unknown mail domain
32340
32341 If a delivery fails at transport time, the router and transport are shown, and
32342 the response from the remote host is included, as in this example:
32343
32344 2002-07-11 07:14:17 17SXDU-000189-00 ** ace400@pb.example
32345 R=dnslookup T=remote_smtp: SMTP error from remote mailer
32346 after pipelined RCPT TO:<ace400@pb.example>: host
32347 pbmail3.py.example [192.168.63.111]: 553 5.3.0
32348 <ace400@pb.example>...Addressee unknown
32349
32350 The word "pipelined" indicates that the SMTP PIPELINING extension was being
32351 used. See hosts_avoid_esmtp in the smtp transport for a way of disabling
32352 PIPELINING. The log lines for all forms of delivery failure are flagged with
32353 "**".
32354
32355
32356 51.11 Fake deliveries
32357 ---------------------
32358
32359 If a delivery does not actually take place because the -N option has been used
32360 to suppress it, a normal delivery line is written to the log, except that "=>"
32361 is replaced by "*>".
32362
32363
32364 51.12 Completion
32365 ----------------
32366
32367 A line of the form
32368
32369 2002-10-31 09:00:11 16ZCW1-0005MB-00 Completed
32370
32371 is written to the main log when a message is about to be removed from the spool
32372 at the end of its processing.
32373
32374
32375 51.13 Summary of Fields in Log Lines
32376 ------------------------------------
32377
32378 A summary of the field identifiers that are used in log lines is shown in the
32379 following table:
32380
32381 A authenticator name (and optional id and sender)
32382 C SMTP confirmation on delivery
32383 command list for "no mail in SMTP session"
32384 CV certificate verification status
32385 D duration of "no mail in SMTP session"
32386 DN distinguished name from peer certificate
32387 DT on => lines: time taken for a delivery
32388 F sender address (on delivery lines)
32389 H host name and IP address
32390 I local interface used
32391 id message id for incoming message
32392 P on <= lines: protocol used
32393 on => and ** lines: return path
32394 QT on => lines: time spent on queue so far
32395 on "Completed" lines: time spent on queue
32396 R on <= lines: reference for local bounce
32397 on => ** and == lines: router name
32398 S size of message
32399 SNI server name indication from TLS client hello
32400 ST shadow transport name
32401 T on <= lines: message subject (topic)
32402 on => ** and == lines: transport name
32403 U local user or RFC 1413 identity
32404 X TLS cipher suite
32405
32406
32407 51.14 Other log entries
32408 -----------------------
32409
32410 Various other types of log entry are written from time to time. Most should be
32411 self-explanatory. Among the more common are:
32412
32413 * retry time not reached An address previously suffered a temporary error
32414 during routing or local delivery, and the time to retry has not yet
32415 arrived. This message is not written to an individual message log file
32416 unless it happens during the first delivery attempt.
32417
32418 * retry time not reached for any host An address previously suffered
32419 temporary errors during remote delivery, and the retry time has not yet
32420 arrived for any of the hosts to which it is routed.
32421
32422 * spool file locked An attempt to deliver a message cannot proceed because
32423 some other Exim process is already working on the message. This can be
32424 quite common if queue running processes are started at frequent intervals.
32425 The exiwhat utility script can be used to find out what Exim processes are
32426 doing.
32427
32428 * error ignored There are several circumstances that give rise to this
32429 message:
32430
32431 1. Exim failed to deliver a bounce message whose age was greater than
32432 ignore_bounce_errors_after. The bounce was discarded.
32433
32434 2. A filter file set up a delivery using the "noerror" option, and the
32435 delivery failed. The delivery was discarded.
32436
32437 3. A delivery set up by a router configured with
32438
32439 errors_to = <>
32440
32441 failed. The delivery was discarded.
32442
32443
32444 51.15 Reducing or increasing what is logged
32445 -------------------------------------------
32446
32447 By setting the log_selector global option, you can disable some of Exim's
32448 default logging, or you can request additional logging. The value of
32449 log_selector is made up of names preceded by plus or minus characters. For
32450 example:
32451
32452 log_selector = +arguments -retry_defer
32453
32454 The list of optional log items is in the following table, with the default
32455 selection marked by asterisks:
32456
32457 8bitmime received 8BITMIME status
32458 *acl_warn_skipped skipped warn statement in ACL
32459 address_rewrite address rewriting
32460 all_parents all parents in => lines
32461 arguments command line arguments
32462 *connection_reject connection rejections
32463 *delay_delivery immediate delivery delayed
32464 deliver_time time taken to perform delivery
32465 delivery_size add S=nnn to => lines
32466 *dnslist_defer defers of DNS list (aka RBL) lookups
32467 *etrn ETRN commands
32468 *host_lookup_failed as it says
32469 ident_timeout timeout for ident connection
32470 incoming_interface incoming interface on <= lines
32471 incoming_port incoming port on <= lines
32472 *lost_incoming_connection as it says (includes timeouts)
32473 outgoing_port add remote port to => lines
32474 *queue_run start and end queue runs
32475 queue_time time on queue for one recipient
32476 queue_time_overall time on queue for whole message
32477 pid Exim process id
32478 received_recipients recipients on <= lines
32479 received_sender sender on <= lines
32480 *rejected_header header contents on reject log
32481 *retry_defer "retry time not reached"
32482 return_path_on_delivery put return path on => and ** lines
32483 sender_on_delivery add sender to => lines
32484 *sender_verify_fail sender verification failures
32485 *size_reject rejection because too big
32486 *skip_delivery delivery skipped in a queue run
32487 *smtp_confirmation SMTP confirmation on => lines
32488 smtp_connection SMTP connections
32489 smtp_incomplete_transaction incomplete SMTP transactions
32490 smtp_mailauth AUTH argument to MAIL commands
32491 smtp_no_mail session with no MAIL commands
32492 smtp_protocol_error SMTP protocol errors
32493 smtp_syntax_error SMTP syntax errors
32494 subject contents of Subject: on <= lines
32495 tls_certificate_verified certificate verification status
32496 *tls_cipher TLS cipher suite on <= and => lines
32497 tls_peerdn TLS peer DN on <= and => lines
32498 tls_sni TLS SNI on <= lines
32499 unknown_in_list DNS lookup failed in list match
32500
32501 all all of the above
32502
32503 More details on each of these items follows:
32504
32505 * 8bitmime: This causes Exim to log any 8BITMIME status of received messages,
32506 which may help in tracking down interoperability issues with ancient MTAs
32507 that are not 8bit clean. This is added to the "<=" line, tagged with "M8S="
32508 and a value of "0", "7" or "8", corresponding to "not given", "7BIT" and
32509 "8BITMIME" respectively.
32510
32511 * acl_warn_skipped: When an ACL warn statement is skipped because one of its
32512 conditions cannot be evaluated, a log line to this effect is written if
32513 this log selector is set.
32514
32515 * address_rewrite: This applies both to global rewrites and per-transport
32516 rewrites, but not to rewrites in filters run as an unprivileged user
32517 (because such users cannot access the log).
32518
32519 * all_parents: Normally only the original and final addresses are logged on
32520 delivery lines; with this selector, intermediate parents are given in
32521 parentheses between them.
32522
32523 * arguments: This causes Exim to write the arguments with which it was called
32524 to the main log, preceded by the current working directory. This is a
32525 debugging feature, added to make it easier to find out how certain MUAs
32526 call /usr/sbin/sendmail. The logging does not happen if Exim has given up
32527 root privilege because it was called with the -C or -D options. Arguments
32528 that are empty or that contain white space are quoted. Non-printing
32529 characters are shown as escape sequences. This facility cannot log
32530 unrecognized arguments, because the arguments are checked before the
32531 configuration file is read. The only way to log such cases is to interpose
32532 a script such as util/logargs.sh between the caller and Exim.
32533
32534 * connection_reject: A log entry is written whenever an incoming SMTP
32535 connection is rejected, for whatever reason.
32536
32537 * delay_delivery: A log entry is written whenever a delivery process is not
32538 started for an incoming message because the load is too high or too many
32539 messages were received on one connection. Logging does not occur if no
32540 delivery process is started because queue_only is set or -odq was used.
32541
32542 * deliver_time: For each delivery, the amount of real time it has taken to
32543 perform the actual delivery is logged as DT=<time>, for example, "DT=1s".
32544
32545 * delivery_size: For each delivery, the size of message delivered is added to
32546 the "=>" line, tagged with S=.
32547
32548 * dnslist_defer: A log entry is written if an attempt to look up a host in a
32549 DNS black list suffers a temporary error.
32550
32551 * etrn: Every valid ETRN command that is received is logged, before the ACL
32552 is run to determine whether or not it is actually accepted. An invalid ETRN
32553 command, or one received within a message transaction is not logged by this
32554 selector (see smtp_syntax_error and smtp_protocol_error).
32555
32556 * host_lookup_failed: When a lookup of a host's IP addresses fails to find
32557 any addresses, or when a lookup of an IP address fails to find a host name,
32558 a log line is written. This logging does not apply to direct DNS lookups
32559 when routing email addresses, but it does apply to "byname" lookups.
32560
32561 * ident_timeout: A log line is written whenever an attempt to connect to a
32562 client's ident port times out.
32563
32564 * incoming_interface: The interface on which a message was received is added
32565 to the "<=" line as an IP address in square brackets, tagged by I= and
32566 followed by a colon and the port number. The local interface and port are
32567 also added to other SMTP log lines, for example "SMTP connection from", and
32568 to rejection lines.
32569
32570 * incoming_port: The remote port number from which a message was received is
32571 added to log entries and Received: header lines, following the IP address
32572 in square brackets, and separated from it by a colon. This is implemented
32573 by changing the value that is put in the $sender_fullhost and
32574 $sender_rcvhost variables. Recording the remote port number has become more
32575 important with the widening use of NAT (see RFC 2505).
32576
32577 * lost_incoming_connection: A log line is written when an incoming SMTP
32578 connection is unexpectedly dropped.
32579
32580 * outgoing_port: The remote port number is added to delivery log lines (those
32581 containing => tags) following the IP address. This option is not included
32582 in the default setting, because for most ordinary configurations, the
32583 remote port number is always 25 (the SMTP port).
32584
32585 * pid: The current process id is added to every log line, in square brackets,
32586 immediately after the time and date.
32587
32588 * queue_run: The start and end of every queue run are logged.
32589
32590 * queue_time: The amount of time the message has been in the queue on the
32591 local host is logged as QT=<time> on delivery ("=>") lines, for example,
32592 "QT=3m45s". The clock starts when Exim starts to receive the message, so it
32593 includes reception time as well as the delivery time for the current
32594 address. This means that it may be longer than the difference between the
32595 arrival and delivery log line times, because the arrival log line is not
32596 written until the message has been successfully received.
32597
32598 * queue_time_overall: The amount of time the message has been in the queue on
32599 the local host is logged as QT=<time> on "Completed" lines, for example,
32600 "QT=3m45s". The clock starts when Exim starts to receive the message, so it
32601 includes reception time as well as the total delivery time.
32602
32603 * received_recipients: The recipients of a message are listed in the main log
32604 as soon as the message is received. The list appears at the end of the log
32605 line that is written when a message is received, preceded by the word
32606 "for". The addresses are listed after they have been qualified, but before
32607 any rewriting has taken place. Recipients that were discarded by an ACL for
32608 MAIL or RCPT do not appear in the list.
32609
32610 * received_sender: The unrewritten original sender of a message is added to
32611 the end of the log line that records the message's arrival, after the word
32612 "from" (before the recipients if received_recipients is also set).
32613
32614 * rejected_header: If a message's header has been received at the time a
32615 rejection is written to the reject log, the complete header is added to the
32616 log. Header logging can be turned off individually for messages that are
32617 rejected by the local_scan() function (see section 44.2).
32618
32619 * retry_defer: A log line is written if a delivery is deferred because a
32620 retry time has not yet been reached. However, this "retry time not reached"
32621 message is always omitted from individual message logs after the first
32622 delivery attempt.
32623
32624 * return_path_on_delivery: The return path that is being transmitted with the
32625 message is included in delivery and bounce lines, using the tag P=. This is
32626 omitted if no delivery actually happens, for example, if routing fails, or
32627 if delivery is to /dev/null or to ":blackhole:".
32628
32629 * sender_on_delivery: The message's sender address is added to every delivery
32630 and bounce line, tagged by F= (for "from"). This is the original sender
32631 that was received with the message; it is not necessarily the same as the
32632 outgoing return path.
32633
32634 * sender_verify_fail: If this selector is unset, the separate log line that
32635 gives details of a sender verification failure is not written. Log lines
32636 for the rejection of SMTP commands contain just "sender verify failed", so
32637 some detail is lost.
32638
32639 * size_reject: A log line is written whenever a message is rejected because
32640 it is too big.
32641
32642 * skip_delivery: A log line is written whenever a message is skipped during a
32643 queue run because it is frozen or because another process is already
32644 delivering it. The message that is written is "spool file is locked".
32645
32646 * smtp_confirmation: The response to the final "." in the SMTP or LMTP
32647 dialogue for outgoing messages is added to delivery log lines in the form
32648 "C="<text>. A number of MTAs (including Exim) return an identifying string
32649 in this response.
32650
32651 * smtp_connection: A log line is written whenever an SMTP connection is
32652 established or closed, unless the connection is from a host that matches
32653 hosts_connection_nolog. (In contrast, lost_incoming_connection applies only
32654 when the closure is unexpected.) This applies to connections from local
32655 processes that use -bs as well as to TCP/IP connections. If a connection is
32656 dropped in the middle of a message, a log line is always written, whether
32657 or not this selector is set, but otherwise nothing is written at the start
32658 and end of connections unless this selector is enabled.
32659
32660 For TCP/IP connections to an Exim daemon, the current number of connections
32661 is included in the log message for each new connection, but note that the
32662 count is reset if the daemon is restarted. Also, because connections are
32663 closed (and the closure is logged) in subprocesses, the count may not
32664 include connections that have been closed but whose termination the daemon
32665 has not yet noticed. Thus, while it is possible to match up the opening and
32666 closing of connections in the log, the value of the logged counts may not
32667 be entirely accurate.
32668
32669 * smtp_incomplete_transaction: When a mail transaction is aborted by RSET,
32670 QUIT, loss of connection, or otherwise, the incident is logged, and the
32671 message sender plus any accepted recipients are included in the log line.
32672 This can provide evidence of dictionary attacks.
32673
32674 * smtp_no_mail: A line is written to the main log whenever an accepted SMTP
32675 connection terminates without having issued a MAIL command. This includes
32676 both the case when the connection is dropped, and the case when QUIT is
32677 used. It does not include cases where the connection is rejected right at
32678 the start (by an ACL, or because there are too many connections, or
32679 whatever). These cases already have their own log lines.
32680
32681 The log line that is written contains the identity of the client in the
32682 usual way, followed by D= and a time, which records the duration of the
32683 connection. If the connection was authenticated, this fact is logged
32684 exactly as it is for an incoming message, with an A= item. If the
32685 connection was encrypted, CV=, DN=, and X= items may appear as they do for
32686 an incoming message, controlled by the same logging options.
32687
32688 Finally, if any SMTP commands were issued during the connection, a C= item
32689 is added to the line, listing the commands that were used. For example,
32690
32691 C=EHLO,QUIT
32692
32693 shows that the client issued QUIT straight after EHLO. If there were fewer
32694 than 20 commands, they are all listed. If there were more than 20 commands,
32695 the last 20 are listed, preceded by "...". However, with the default
32696 setting of 10 for smtp_accep_max_nonmail, the connection will in any case
32697 have been aborted before 20 non-mail commands are processed.
32698
32699 * smtp_mailauth: A third subfield with the authenticated sender,
32700 colon-separated, is appended to the A= item for a message arrival or
32701 delivery log line, if an AUTH argument to the SMTP MAIL command (see 33.2)
32702 was accepted or used.
32703
32704 * smtp_protocol_error: A log line is written for every SMTP protocol error
32705 encountered. Exim does not have perfect detection of all protocol errors
32706 because of transmission delays and the use of pipelining. If PIPELINING has
32707 been advertised to a client, an Exim server assumes that the client will
32708 use it, and therefore it does not count "expected" errors (for example,
32709 RCPT received after rejecting MAIL) as protocol errors.
32710
32711 * smtp_syntax_error: A log line is written for every SMTP syntax error
32712 encountered. An unrecognized command is treated as a syntax error. For an
32713 external connection, the host identity is given; for an internal connection
32714 using -bs the sender identification (normally the calling user) is given.
32715
32716 * subject: The subject of the message is added to the arrival log line,
32717 preceded by "T=" (T for "topic", since S is already used for "size"). Any
32718 MIME "words" in the subject are decoded. The print_topbitchars option
32719 specifies whether characters with values greater than 127 should be logged
32720 unchanged, or whether they should be rendered as escape sequences.
32721
32722 * tls_certificate_verified: An extra item is added to <= and => log lines
32723 when TLS is in use. The item is "CV=yes" if the peer's certificate was
32724 verified, and "CV=no" if not.
32725
32726 * tls_cipher: When a message is sent or received over an encrypted
32727 connection, the cipher suite used is added to the log line, preceded by X=.
32728
32729 * tls_peerdn: When a message is sent or received over an encrypted
32730 connection, and a certificate is supplied by the remote host, the peer DN
32731 is added to the log line, preceded by DN=.
32732
32733 * tls_sni: When a message is received over an encrypted connection, and the
32734 remote host provided the Server Name Indication extension, the SNI is added
32735 to the log line, preceded by SNI=.
32736
32737 * unknown_in_list: This setting causes a log entry to be written when the
32738 result of a list match is failure because a DNS lookup failed.
32739
32740
32741 51.16 Message log
32742 -----------------
32743
32744 In addition to the general log files, Exim writes a log file for each message
32745 that it handles. The names of these per-message logs are the message ids, and
32746 they are kept in the msglog sub-directory of the spool directory. Each message
32747 log contains copies of the log lines that apply to the message. This makes it
32748 easier to inspect the status of an individual message without having to search
32749 the main log. A message log is deleted when processing of the message is
32750 complete, unless preserve_message_logs is set, but this should be used only
32751 with great care because they can fill up your disk very quickly.
32752
32753 On a heavily loaded system, it may be desirable to disable the use of
32754 per-message logs, in order to reduce disk I/O. This can be done by setting the
32755 message_logs option false.
32756
32757
32758
32759 ===============================================================================
32760 52. EXIM UTILITIES
32761
32762 A number of utility scripts and programs are supplied with Exim and are
32763 described in this chapter. There is also the Exim Monitor, which is covered in
32764 the next chapter. The utilities described here are:
32765
32766 52.1 exiwhat list what Exim processes are doing
32767 52.2 exiqgrep grep the queue
32768 52.3 exiqsumm summarize the queue
32769 52.4 exigrep search the main log
32770 52.5 exipick select messages on various criteria
32771 52.6 exicyclog cycle (rotate) log files
32772 52.7 eximstats extract statistics from the log
32773 52.8 exim_checkaccess check address acceptance from given IP
32774 52.9 exim_dbmbuild build a DBM file
32775 52.10 exinext extract retry information
32776 52.11 exim_dumpdb dump a hints database
32777 52.11 exim_tidydb clean up a hints database
32778 52.11 exim_fixdb patch a hints database
32779 52.15 exim_lock lock a mailbox file
32780
32781 Another utility that might be of use to sites with many MTAs is Tom Kistner's
32782 exilog. It provides log visualizations across multiple Exim servers. See http:/
32783 /duncanthrax.net/exilog/ for details.
32784
32785
32786 52.1 Finding out what Exim processes are doing (exiwhat)
32787 --------------------------------------------------------
32788
32789 On operating systems that can restart a system call after receiving a signal
32790 (most modern OS), an Exim process responds to the SIGUSR1 signal by writing a
32791 line describing what it is doing to the file exim-process.info in the Exim
32792 spool directory. The exiwhat script sends the signal to all Exim processes it
32793 can find, having first emptied the file. It then waits for one second to allow
32794 the Exim processes to react before displaying the results. In order to run
32795 exiwhat successfully you have to have sufficient privilege to send the signal
32796 to the Exim processes, so it is normally run as root.
32797
32798 Warning: This is not an efficient process. It is intended for occasional use by
32799 system administrators. It is not sensible, for example, to set up a script that
32800 sends SIGUSR1 signals to Exim processes at short intervals.
32801
32802 Unfortunately, the ps command that exiwhat uses to find Exim processes varies
32803 in different operating systems. Not only are different options used, but the
32804 format of the output is different. For this reason, there are some system
32805 configuration options that configure exactly how exiwhat works. If it doesn't
32806 seem to be working for you, check the following compile-time options:
32807
32808 EXIWHAT_PS_CMD the command for running ps
32809 EXIWHAT_PS_ARG the argument for ps
32810 EXIWHAT_EGREP_ARG the argument for egrep to select from ps output
32811 EXIWHAT_KILL_ARG the argument for the kill command
32812
32813 An example of typical output from exiwhat is
32814
32815 164 daemon: -q1h, listening on port 25
32816 10483 running queue: waiting for 0tAycK-0002ij-00 (10492)
32817 10492 delivering 0tAycK-0002ij-00 to mail.ref.example
32818 [10.19.42.42] (editor@ref.example)
32819 10592 handling incoming call from [192.168.243.242]
32820 10628 accepting a local non-SMTP message
32821
32822 The first number in the output line is the process number. The third line has
32823 been split here, in order to fit it on the page.
32824
32825
32826 52.2 Selective queue listing (exiqgrep)
32827 ---------------------------------------
32828
32829 This utility is a Perl script contributed by Matt Hubbard. It runs
32830
32831 exim -bpu
32832
32833 or (in case -a switch is specified)
32834
32835 exim -bp
32836
32837 The -C option is used to specify an alternate exim.conf which might contain
32838 alternate exim configuration the queue management might be using.
32839
32840 to obtain a queue listing, and then greps the output to select messages that
32841 match given criteria. The following selection options are available:
32842
32843 -f <regex>
32844
32845 Match the sender address using a case-insensitive search. The field that is
32846 tested is enclosed in angle brackets, so you can test for bounce messages
32847 with
32848
32849 exiqgrep -f '^<>$'
32850
32851 -r <regex>
32852
32853 Match a recipient address using a case-insensitve search. The field that is
32854 tested is not enclosed in angle brackets.
32855
32856 -s <regex>
32857
32858 Match against the size field.
32859
32860 -y <seconds>
32861
32862 Match messages that are younger than the given time.
32863
32864 -o <seconds>
32865
32866 Match messages that are older than the given time.
32867
32868 -z
32869
32870 Match only frozen messages.
32871
32872 -x
32873
32874 Match only non-frozen messages.
32875
32876 The following options control the format of the output:
32877
32878 -c
32879
32880 Display only the count of matching messages.
32881
32882 -l
32883
32884 Long format - display the full message information as output by Exim. This
32885 is the default.
32886
32887 -i
32888
32889 Display message ids only.
32890
32891 -b
32892
32893 Brief format - one line per message.
32894
32895 -R
32896
32897 Display messages in reverse order.
32898
32899 -a
32900
32901 Include delivered recipients in queue listing.
32902
32903 There is one more option, -h, which outputs a list of options.
32904
32905
32906 52.3 Summarizing the queue (exiqsumm)
32907 -------------------------------------
32908
32909 The exiqsumm utility is a Perl script which reads the output of "exim -bp" and
32910 produces a summary of the messages on the queue. Thus, you use it by running a
32911 command such as
32912
32913 exim -bp | exiqsumm
32914
32915 The output consists of one line for each domain that has messages waiting for
32916 it, as in the following example:
32917
32918 3 2322 74m 66m msn.com.example
32919
32920 Each line lists the number of pending deliveries for a domain, their total
32921 volume, and the length of time that the oldest and the newest messages have
32922 been waiting. Note that the number of pending deliveries is greater than the
32923 number of messages when messages have more than one recipient.
32924
32925 A summary line is output at the end. By default the output is sorted on the
32926 domain name, but exiqsumm has the options -a and -c, which cause the output to
32927 be sorted by oldest message and by count of messages, respectively. There are
32928 also three options that split the messages for each domain into two or more
32929 subcounts: -b separates bounce messages, -f separates frozen messages, and -s
32930 separates messages according to their sender.
32931
32932 The output of exim -bp contains the original addresses in the message, so this
32933 also applies to the output from exiqsumm. No domains from addresses generated
32934 by aliasing or forwarding are included (unless the one_time option of the
32935 redirect router has been used to convert them into "top level" addresses).
32936
32937
32938 52.4 Extracting specific information from the log (exigrep)
32939 -----------------------------------------------------------
32940
32941 The exigrep utility is a Perl script that searches one or more main log files
32942 for entries that match a given pattern. When it finds a match, it extracts all
32943 the log entries for the relevant message, not just those that match the
32944 pattern. Thus, exigrep can extract complete log entries for a given message, or
32945 all mail for a given user, or for a given host, for example. The input files
32946 can be in Exim log format or syslog format. If a matching log line is not
32947 associated with a specific message, it is included in exigrep's output without
32948 any additional lines. The usage is:
32949
32950 exigrep [-t<n>] [-I] [-l] [-v] <pattern> [<log file>] ...
32951
32952 If no log file names are given on the command line, the standard input is read.
32953
32954 The -t argument specifies a number of seconds. It adds an additional condition
32955 for message selection. Messages that are complete are shown only if they spent
32956 more than <n> seconds on the queue.
32957
32958 By default, exigrep does case-insensitive matching. The -I option makes it
32959 case-sensitive. This may give a performance improvement when searching large
32960 log files. Without -I, the Perl pattern matches use Perl's "/i" option; with -I
32961 they do not. In both cases it is possible to change the case sensitivity within
32962 the pattern by using "(?i)" or "(?-i)".
32963
32964 The -l option means "literal", that is, treat all characters in the pattern as
32965 standing for themselves. Otherwise the pattern must be a Perl regular
32966 expression.
32967
32968 The -v option inverts the matching condition. That is, a line is selected if it
32969 does not match the pattern.
32970
32971 If the location of a zcat command is known from the definition of ZCAT_COMMAND
32972 in Local/Makefile, exigrep automatically passes any file whose name ends in
32973 COMPRESS_SUFFIX through zcat as it searches it.
32974
32975
32976 52.5 Selecting messages by various criteria (exipick)
32977 -----------------------------------------------------
32978
32979 John Jetmore's exipick utility is included in the Exim distribution. It lists
32980 messages from the queue according to a variety of criteria. For details of
32981 exipick's facilities, visit the web page at http://www.exim.org/eximwiki/
32982 ToolExipickManPage or run exipick with the --help option.
32983
32984
32985 52.6 Cycling log files (exicyclog)
32986 ----------------------------------
32987
32988 The exicyclog script can be used to cycle (rotate) mainlog and rejectlog files.
32989 This is not necessary if only syslog is being used, or if you are using log
32990 files with datestamps in their names (see section 51.3). Some operating systems
32991 have their own standard mechanisms for log cycling, and these can be used
32992 instead of exicyclog if preferred. There are two command line options for
32993 exicyclog:
32994
32995 * -k <count> specifies the number of log files to keep, overriding the
32996 default that is set when Exim is built. The default default is 10.
32997
32998 * -l <path> specifies the log file path, in the same format as Exim's
32999 log_file_path option (for example, "/var/log/exim_%slog"), again overriding
33000 the script's default, which is to find the setting from Exim's
33001 configuration.
33002
33003 Each time exicyclog is run the file names get "shuffled down" by one. If the
33004 main log file name is mainlog (the default) then when exicyclog is run mainlog
33005 becomes mainlog.01, the previous mainlog.01 becomes mainlog.02 and so on, up to
33006 the limit that is set in the script or by the -k option. Log files whose
33007 numbers exceed the limit are discarded. Reject logs are handled similarly.
33008
33009 If the limit is greater than 99, the script uses 3-digit numbers such as
33010 mainlog.001, mainlog.002, etc. If you change from a number less than 99 to one
33011 that is greater, or vice versa, you will have to fix the names of any existing
33012 log files.
33013
33014 If no mainlog file exists, the script does nothing. Files that "drop off" the
33015 end are deleted. All files with numbers greater than 01 are compressed, using a
33016 compression command which is configured by the COMPRESS_COMMAND setting in
33017 Local/Makefile. It is usual to run exicyclog daily from a root crontab entry of
33018 the form
33019
33020 1 0 * * * su exim -c /usr/exim/bin/exicyclog
33021
33022 assuming you have used the name "exim" for the Exim user. You can run exicyclog
33023 as root if you wish, but there is no need.
33024
33025
33026 52.7 Mail statistics (eximstats)
33027 --------------------------------
33028
33029 A Perl script called eximstats is provided for extracting statistical
33030 information from log files. The output is either plain text, or HTML. Exim log
33031 files are also supported by the Lire system produced by the LogReport
33032 Foundation http://www.logreport.org.
33033
33034 The eximstats script has been hacked about quite a bit over time. The latest
33035 version is the result of some extensive revision by Steve Campbell. A lot of
33036 information is given by default, but there are options for suppressing various
33037 parts of it. Following any options, the arguments to the script are a list of
33038 files, which should be main log files. For example:
33039
33040 eximstats -nr /var/spool/exim/log/mainlog.01
33041
33042 By default, eximstats extracts information about the number and volume of
33043 messages received from or delivered to various hosts. The information is sorted
33044 both by message count and by volume, and the top fifty hosts in each category
33045 are listed on the standard output. Similar information, based on email
33046 addresses or domains instead of hosts can be requested by means of various
33047 options. For messages delivered and received locally, similar statistics are
33048 also produced per user.
33049
33050 The output also includes total counts and statistics about delivery errors, and
33051 histograms showing the number of messages received and deliveries made in each
33052 hour of the day. A delivery with more than one address in its envelope (for
33053 example, an SMTP transaction with more than one RCPT command) is counted as a
33054 single delivery by eximstats.
33055
33056 Though normally more deliveries than receipts are reported (as messages may
33057 have multiple recipients), it is possible for eximstats to report more messages
33058 received than delivered, even though the queue is empty at the start and end of
33059 the period in question. If an incoming message contains no valid recipients, no
33060 deliveries are recorded for it. A bounce message is handled as an entirely
33061 separate message.
33062
33063 eximstats always outputs a grand total summary giving the volume and number of
33064 messages received and deliveries made, and the number of hosts involved in each
33065 case. It also outputs the number of messages that were delayed (that is, not
33066 completely delivered at the first attempt), and the number that had at least
33067 one address that failed.
33068
33069 The remainder of the output is in sections that can be independently disabled
33070 or modified by various options. It consists of a summary of deliveries by
33071 transport, histograms of messages received and delivered per time interval
33072 (default per hour), information about the time messages spent on the queue, a
33073 list of relayed messages, lists of the top fifty sending hosts, local senders,
33074 destination hosts, and destination local users by count and by volume, and a
33075 list of delivery errors that occurred.
33076
33077 The relay information lists messages that were actually relayed, that is, they
33078 came from a remote host and were directly delivered to some other remote host,
33079 without being processed (for example, for aliasing or forwarding) locally.
33080
33081 There are quite a few options for eximstats to control exactly what it outputs.
33082 These are documented in the Perl script itself, and can be extracted by running
33083 the command perldoc on the script. For example:
33084
33085 perldoc /usr/exim/bin/eximstats
33086
33087
33088 52.8 Checking access policy (exim_checkaccess)
33089 ----------------------------------------------
33090
33091 The -bh command line argument allows you to run a fake SMTP session with
33092 debugging output, in order to check what Exim is doing when it is applying
33093 policy controls to incoming SMTP mail. However, not everybody is sufficiently
33094 familiar with the SMTP protocol to be able to make full use of -bh, and
33095 sometimes you just want to answer the question "Does this address have access?"
33096 without bothering with any further details.
33097
33098 The exim_checkaccess utility is a "packaged" version of -bh. It takes two
33099 arguments, an IP address and an email address:
33100
33101 exim_checkaccess 10.9.8.7 A.User@a.domain.example
33102
33103 The utility runs a call to Exim with the -bh option, to test whether the given
33104 email address would be accepted in a RCPT command in a TCP/IP connection from
33105 the host with the given IP address. The output of the utility is either the
33106 word "accepted", or the SMTP error response, for example:
33107
33108 Rejected:
33109 550 Relay not permitted
33110
33111 When running this test, the utility uses "<>" as the envelope sender address
33112 for the MAIL command, but you can change this by providing additional options.
33113 These are passed directly to the Exim command. For example, to specify that the
33114 test is to be run with the sender address himself@there.example you can use:
33115
33116 exim_checkaccess 10.9.8.7 A.User@a.domain.example \
33117 -f himself@there.example
33118
33119 Note that these additional Exim command line items must be given after the two
33120 mandatory arguments.
33121
33122 Because the exim_checkaccess uses -bh, it does not perform callouts while
33123 running its checks. You can run checks that include callouts by using -bhc, but
33124 this is not yet available in a "packaged" form.
33125
33126
33127 52.9 Making DBM files (exim_dbmbuild)
33128 -------------------------------------
33129
33130 The exim_dbmbuild program reads an input file containing keys and data in the
33131 format used by the lsearch lookup (see section 9.3). It writes a DBM file using
33132 the lower-cased alias names as keys and the remainder of the information as
33133 data. The lower-casing can be prevented by calling the program with the -nolc
33134 option.
33135
33136 A terminating zero is included as part of the key string. This is expected by
33137 the dbm lookup type. However, if the option -nozero is given, exim_dbmbuild
33138 creates files without terminating zeroes in either the key strings or the data
33139 strings. The dbmnz lookup type can be used with such files.
33140
33141 The program requires two arguments: the name of the input file (which can be a
33142 single hyphen to indicate the standard input), and the name of the output file.
33143 It creates the output under a temporary name, and then renames it if all went
33144 well.
33145
33146 If the native DB interface is in use (USE_DB is set in a compile-time
33147 configuration file - this is common in free versions of Unix) the two file
33148 names must be different, because in this mode the Berkeley DB functions create
33149 a single output file using exactly the name given. For example,
33150
33151 exim_dbmbuild /etc/aliases /etc/aliases.db
33152
33153 reads the system alias file and creates a DBM version of it in /etc/aliases.db.
33154
33155 In systems that use the ndbm routines (mostly proprietary versions of Unix),
33156 two files are used, with the suffixes .dir and .pag. In this environment, the
33157 suffixes are added to the second argument of exim_dbmbuild, so it can be the
33158 same as the first. This is also the case when the Berkeley functions are used
33159 in compatibility mode (though this is not recommended), because in that case it
33160 adds a .db suffix to the file name.
33161
33162 If a duplicate key is encountered, the program outputs a warning, and when it
33163 finishes, its return code is 1 rather than zero, unless the -noduperr option is
33164 used. By default, only the first of a set of duplicates is used - this makes it
33165 compatible with lsearch lookups. There is an option -lastdup which causes it to
33166 use the data for the last duplicate instead. There is also an option -nowarn,
33167 which stops it listing duplicate keys to stderr. For other errors, where it
33168 doesn't actually make a new file, the return code is 2.
33169
33170
33171 52.10 Finding individual retry times (exinext)
33172 ----------------------------------------------
33173
33174 A utility called exinext (mostly a Perl script) provides the ability to fish
33175 specific information out of the retry database. Given a mail domain (or a
33176 complete address), it looks up the hosts for that domain, and outputs any retry
33177 information for the hosts or for the domain. At present, the retry information
33178 is obtained by running exim_dumpdb (see below) and post-processing the output.
33179 For example:
33180
33181 $ exinext piglet@milne.fict.example
33182 kanga.milne.example:192.168.8.1 error 146: Connection refused
33183 first failed: 21-Feb-1996 14:57:34
33184 last tried: 21-Feb-1996 14:57:34
33185 next try at: 21-Feb-1996 15:02:34
33186 roo.milne.example:192.168.8.3 error 146: Connection refused
33187 first failed: 20-Jan-1996 13:12:08
33188 last tried: 21-Feb-1996 11:42:03
33189 next try at: 21-Feb-1996 19:42:03
33190 past final cutoff time
33191
33192 You can also give exinext a local part, without a domain, and it will give any
33193 retry information for that local part in your default domain. A message id can
33194 be used to obtain retry information pertaining to a specific message. This
33195 exists only when an attempt to deliver a message to a remote host suffers a
33196 message-specific error (see section 47.2). exinext is not particularly
33197 efficient, but then it is not expected to be run very often.
33198
33199 The exinext utility calls Exim to find out information such as the location of
33200 the spool directory. The utility has -C and -D options, which are passed on to
33201 the exim commands. The first specifies an alternate Exim configuration file,
33202 and the second sets macros for use within the configuration file. These
33203 features are mainly to help in testing, but might also be useful in
33204 environments where more than one configuration file is in use.
33205
33206
33207 52.11 Hints database maintenance
33208 --------------------------------
33209
33210 Three utility programs are provided for maintaining the DBM files that Exim
33211 uses to contain its delivery hint information. Each program requires two
33212 arguments. The first specifies the name of Exim's spool directory, and the
33213 second is the name of the database it is to operate on. These are as follows:
33214
33215 * retry: the database of retry information
33216
33217 * wait-<transport name>: databases of information about messages waiting for
33218 remote hosts
33219
33220 * callout: the callout cache
33221
33222 * ratelimit: the data for implementing the ratelimit ACL condition
33223
33224 * misc: other hints data
33225
33226 The misc database is used for
33227
33228 * Serializing ETRN runs (when smtp_etrn_serialize is set)
33229
33230 * Serializing delivery to a specific host (when serialize_hosts is set in an
33231 smtp transport)
33232
33233
33234 52.12 exim_dumpdb
33235 -----------------
33236
33237 The entire contents of a database are written to the standard output by the
33238 exim_dumpdb program, which has no options or arguments other than the spool and
33239 database names. For example, to dump the retry database:
33240
33241 exim_dumpdb /var/spool/exim retry
33242
33243 Two lines of output are produced for each entry:
33244
33245 T:mail.ref.example:192.168.242.242 146 77 Connection refused
33246 31-Oct-1995 12:00:12 02-Nov-1995 12:21:39 02-Nov-1995 20:21:39 *
33247
33248 The first item on the first line is the key of the record. It starts with one
33249 of the letters R, or T, depending on whether it refers to a routing or
33250 transport retry. For a local delivery, the next part is the local address; for
33251 a remote delivery it is the name of the remote host, followed by its failing IP
33252 address (unless retry_include_ip_address is set false on the smtp transport).
33253 If the remote port is not the standard one (port 25), it is added to the IP
33254 address. Then there follows an error code, an additional error code, and a
33255 textual description of the error.
33256
33257 The three times on the second line are the time of first failure, the time of
33258 the last delivery attempt, and the computed time for the next attempt. The line
33259 ends with an asterisk if the cutoff time for the last retry rule has been
33260 exceeded.
33261
33262 Each output line from exim_dumpdb for the wait-xxx databases consists of a host
33263 name followed by a list of ids for messages that are or were waiting to be
33264 delivered to that host. If there are a very large number for any one host,
33265 continuation records, with a sequence number added to the host name, may be
33266 seen. The data in these records is often out of date, because a message may be
33267 routed to several alternative hosts, and Exim makes no effort to keep
33268 cross-references.
33269
33270
33271 52.13 exim_tidydb
33272 -----------------
33273
33274 The exim_tidydb utility program is used to tidy up the contents of a hints
33275 database. If run with no options, it removes all records that are more than 30
33276 days old. The age is calculated from the date and time that the record was last
33277 updated. Note that, in the case of the retry database, it is not the time since
33278 the first delivery failure. Information about a host that has been down for
33279 more than 30 days will remain in the database, provided that the record is
33280 updated sufficiently often.
33281
33282 The cutoff date can be altered by means of the -t option, which must be
33283 followed by a time. For example, to remove all records older than a week from
33284 the retry database:
33285
33286 exim_tidydb -t 7d /var/spool/exim retry
33287
33288 Both the wait-xxx and retry databases contain items that involve message ids.
33289 In the former these appear as data in records keyed by host - they were
33290 messages that were waiting for that host - and in the latter they are the keys
33291 for retry information for messages that have suffered certain types of error.
33292 When exim_tidydb is run, a check is made to ensure that message ids in database
33293 records are those of messages that are still on the queue. Message ids for
33294 messages that no longer exist are removed from wait-xxx records, and if this
33295 leaves any records empty, they are deleted. For the retry database, records
33296 whose keys are non-existent message ids are removed. The exim_tidydb utility
33297 outputs comments on the standard output whenever it removes information from
33298 the database.
33299
33300 Certain records are automatically removed by Exim when they are no longer
33301 needed, but others are not. For example, if all the MX hosts for a domain are
33302 down, a retry record is created for each one. If the primary MX host comes back
33303 first, its record is removed when Exim successfully delivers to it, but the
33304 records for the others remain because Exim has not tried to use those hosts.
33305
33306 It is important, therefore, to run exim_tidydb periodically on all the hints
33307 databases. You should do this at a quiet time of day, because it requires a
33308 database to be locked (and therefore inaccessible to Exim) while it does its
33309 work. Removing records from a DBM file does not normally make the file smaller,
33310 but all the common DBM libraries are able to re-use the space that is released.
33311 After an initial phase of increasing in size, the databases normally reach a
33312 point at which they no longer get any bigger, as long as they are regularly
33313 tidied.
33314
33315 Warning: If you never run exim_tidydb, the space used by the hints databases is
33316 likely to keep on increasing.
33317
33318
33319 52.14 exim_fixdb
33320 ----------------
33321
33322 The exim_fixdb program is a utility for interactively modifying databases. Its
33323 main use is for testing Exim, but it might also be occasionally useful for
33324 getting round problems in a live system. It has no options, and its interface
33325 is somewhat crude. On entry, it prompts for input with a right angle-bracket. A
33326 key of a database record can then be entered, and the data for that record is
33327 displayed.
33328
33329 If "d" is typed at the next prompt, the entire record is deleted. For all
33330 except the retry database, that is the only operation that can be carried out.
33331 For the retry database, each field is output preceded by a number, and data for
33332 individual fields can be changed by typing the field number followed by new
33333 data, for example:
33334
33335 > 4 951102:1000
33336
33337 resets the time of the next delivery attempt. Time values are given as a
33338 sequence of digit pairs for year, month, day, hour, and minute. Colons can be
33339 used as optional separators.
33340
33341
33342 52.15 Mailbox maintenance (exim_lock)
33343 -------------------------------------
33344
33345 The exim_lock utility locks a mailbox file using the same algorithm as Exim.
33346 For a discussion of locking issues, see section 26.3. Exim_lock can be used to
33347 prevent any modification of a mailbox by Exim or a user agent while
33348 investigating a problem. The utility requires the name of the file as its first
33349 argument. If the locking is successful, the second argument is run as a command
33350 (using C's system() function); if there is no second argument, the value of the
33351 SHELL environment variable is used; if this is unset or empty, /bin/sh is run.
33352 When the command finishes, the mailbox is unlocked and the utility ends. The
33353 following options are available:
33354
33355 -fcntl
33356
33357 Use fcntl() locking on the open mailbox.
33358
33359 -flock
33360
33361 Use flock() locking on the open mailbox, provided the operating system
33362 supports it.
33363
33364 -interval
33365
33366 This must be followed by a number, which is a number of seconds; it sets
33367 the interval to sleep between retries (default 3).
33368
33369 -lockfile
33370
33371 Create a lock file before opening the mailbox.
33372
33373 -mbx
33374
33375 Lock the mailbox using MBX rules.
33376
33377 -q
33378
33379 Suppress verification output.
33380
33381 -retries
33382
33383 This must be followed by a number; it sets the number of times to try to
33384 get the lock (default 10).
33385
33386 -restore_time
33387
33388 This option causes exim_lock to restore the modified and read times to the
33389 locked file before exiting. This allows you to access a locked mailbox (for
33390 example, to take a backup copy) without disturbing the times that the user
33391 subsequently sees.
33392
33393 -timeout
33394
33395 This must be followed by a number, which is a number of seconds; it sets a
33396 timeout to be used with a blocking fcntl() lock. If it is not set (the
33397 default), a non-blocking call is used.
33398
33399 -v
33400
33401 Generate verbose output.
33402
33403 If none of -fcntl, -flock, -lockfile or -mbx are given, the default is to
33404 create a lock file and also to use fcntl() locking on the mailbox, which is the
33405 same as Exim's default. The use of -flock or -fcntl requires that the file be
33406 writeable; the use of -lockfile requires that the directory containing the file
33407 be writeable. Locking by lock file does not last for ever; Exim assumes that a
33408 lock file is expired if it is more than 30 minutes old.
33409
33410 The -mbx option can be used with either or both of -fcntl or -flock. It assumes
33411 -fcntl by default. MBX locking causes a shared lock to be taken out on the open
33412 mailbox, and an exclusive lock on the file /tmp/.n.m where n and m are the
33413 device number and inode number of the mailbox file. When the locking is
33414 released, if an exclusive lock can be obtained for the mailbox, the file in /
33415 tmp is deleted.
33416
33417 The default output contains verification of the locking that takes place. The
33418 -v option causes some additional information to be given. The -q option
33419 suppresses all output except error messages.
33420
33421 A command such as
33422
33423 exim_lock /var/spool/mail/spqr
33424
33425 runs an interactive shell while the file is locked, whereas
33426
33427 exim_lock -q /var/spool/mail/spqr <<End
33428 <some commands>
33429 End
33430
33431 runs a specific non-interactive sequence of commands while the file is locked,
33432 suppressing all verification output. A single command can be run by a command
33433 such as
33434
33435 exim_lock -q /var/spool/mail/spqr \
33436 "cp /var/spool/mail/spqr /some/where"
33437
33438 Note that if a command is supplied, it must be entirely contained within the
33439 second argument - hence the quotes.
33440
33441
33442
33443 ===============================================================================
33444 53. THE EXIM MONITOR
33445
33446 The Exim monitor is an application which displays in an X window information
33447 about the state of Exim's queue and what Exim is doing. An admin user can
33448 perform certain operations on messages from this GUI interface; however all
33449 such facilities are also available from the command line, and indeed, the
33450 monitor itself makes use of the command line to perform any actions requested.
33451
33452
33453 53.1 Running the monitor
33454 ------------------------
33455
33456 The monitor is started by running the script called eximon. This is a shell
33457 script that sets up a number of environment variables, and then runs the binary
33458 called eximon.bin. The default appearance of the monitor window can be changed
33459 by editing the Local/eximon.conf file created by editing exim_monitor/EDITME.
33460 Comments in that file describe what the various parameters are for.
33461
33462 The parameters that get built into the eximon script can be overridden for a
33463 particular invocation by setting up environment variables of the same names,
33464 preceded by "EXIMON_". For example, a shell command such as
33465
33466 EXIMON_LOG_DEPTH=400 eximon
33467
33468 (in a Bourne-compatible shell) runs eximon with an overriding setting of the
33469 LOG_DEPTH parameter. If EXIMON_LOG_FILE_PATH is set in the environment, it
33470 overrides the Exim log file configuration. This makes it possible to have
33471 eximon tailing log data that is written to syslog, provided that MAIL.INFO
33472 syslog messages are routed to a file on the local host.
33473
33474 X resources can be used to change the appearance of the window in the normal
33475 way. For example, a resource setting of the form
33476
33477 Eximon*background: gray94
33478
33479 changes the colour of the background to light grey rather than white. The
33480 stripcharts are drawn with both the data lines and the reference lines in
33481 black. This means that the reference lines are not visible when on top of the
33482 data. However, their colour can be changed by setting a resource called
33483 "highlight" (an odd name, but that's what the Athena stripchart widget uses).
33484 For example, if your X server is running Unix, you could set up lighter
33485 reference lines in the stripcharts by obeying
33486
33487 xrdb -merge <<End
33488 Eximon*highlight: gray
33489 End
33490
33491 In order to see the contents of messages on the queue, and to operate on them,
33492 eximon must either be run as root or by an admin user.
33493
33494 The command-line parameters of eximon are passed to eximon.bin and may contain
33495 X11 resource parameters interpreted by the X11 library. In addition, if the
33496 first parameter starts with the string "gdb" then it is removed and the binary
33497 is invoked under gdb (the parameter is used as the gdb command-name, so
33498 versioned variants of gdb can be invoked).
33499
33500 The monitor's window is divided into three parts. The first contains one or
33501 more stripcharts and two action buttons, the second contains a "tail" of the
33502 main log file, and the third is a display of the queue of messages awaiting
33503 delivery, with two more action buttons. The following sections describe these
33504 different parts of the display.
33505
33506
33507 53.2 The stripcharts
33508 --------------------
33509
33510 The first stripchart is always a count of messages on the queue. Its name can
33511 be configured by setting QUEUE_STRIPCHART_NAME in the Local/eximon.conf file.
33512 The remaining stripcharts are defined in the configuration script by regular
33513 expression matches on log file entries, making it possible to display, for
33514 example, counts of messages delivered to certain hosts or using certain
33515 transports. The supplied defaults display counts of received and delivered
33516 messages, and of local and SMTP deliveries. The default period between
33517 stripchart updates is one minute; this can be adjusted by a parameter in the
33518 Local/eximon.conf file.
33519
33520 The stripchart displays rescale themselves automatically as the value they are
33521 displaying changes. There are always 10 horizontal lines in each chart; the
33522 title string indicates the value of each division when it is greater than one.
33523 For example, "x2" means that each division represents a value of 2.
33524
33525 It is also possible to have a stripchart which shows the percentage fullness of
33526 a particular disk partition, which is useful when local deliveries are confined
33527 to a single partition.
33528
33529 This relies on the availability of the statvfs() function or equivalent in the
33530 operating system. Most, but not all versions of Unix that support Exim have
33531 this. For this particular stripchart, the top of the chart always represents
33532 100%, and the scale is given as "x10%". This chart is configured by setting
33533 SIZE_STRIPCHART and (optionally) SIZE_STRIPCHART_NAME in the Local/eximon.conf
33534 file.
33535
33536
33537 53.3 Main action buttons
33538 ------------------------
33539
33540 Below the stripcharts there is an action button for quitting the monitor. Next
33541 to this is another button marked "Size". They are placed here so that shrinking
33542 the window to its default minimum size leaves just the queue count stripchart
33543 and these two buttons visible. Pressing the "Size" button causes the window to
33544 expand to its maximum size, unless it is already at the maximum, in which case
33545 it is reduced to its minimum.
33546
33547 When expanding to the maximum, if the window cannot be fully seen where it
33548 currently is, it is moved back to where it was the last time it was at full
33549 size. When it is expanding from its minimum size, the old position is
33550 remembered, and next time it is reduced to the minimum it is moved back there.
33551
33552 The idea is that you can keep a reduced window just showing one or two
33553 stripcharts at a convenient place on your screen, easily expand it to show the
33554 full window when required, and just as easily put it back to what it was. The
33555 idea is copied from what the twm window manager does for its f.fullzoom action.
33556 The minimum size of the window can be changed by setting the MIN_HEIGHT and
33557 MIN_WIDTH values in Local/eximon.conf.
33558
33559 Normally, the monitor starts up with the window at its full size, but it can be
33560 built so that it starts up with the window at its smallest size, by setting
33561 START_SMALL=yes in Local/eximon.conf.
33562
33563
33564 53.4 The log display
33565 --------------------
33566
33567 The second section of the window is an area in which a display of the tail of
33568 the main log is maintained. To save space on the screen, the timestamp on each
33569 log line is shortened by removing the date and, if log_timezone is set, the
33570 timezone. The log tail is not available when the only destination for logging
33571 data is syslog, unless the syslog lines are routed to a local file whose name
33572 is passed to eximon via the EXIMON_LOG_FILE_PATH environment variable.
33573
33574 The log sub-window has a scroll bar at its lefthand side which can be used to
33575 move back to look at earlier text, and the up and down arrow keys also have a
33576 scrolling effect. The amount of log that is kept depends on the setting of
33577 LOG_BUFFER in Local/eximon.conf, which specifies the amount of memory to use.
33578 When this is full, the earlier 50% of data is discarded - this is much more
33579 efficient than throwing it away line by line. The sub-window also has a
33580 horizontal scroll bar for accessing the ends of long log lines. This is the
33581 only means of horizontal scrolling; the right and left arrow keys are not
33582 available. Text can be cut from this part of the window using the mouse in the
33583 normal way. The size of this subwindow is controlled by parameters in the
33584 configuration file Local/eximon.conf.
33585
33586 Searches of the text in the log window can be carried out by means of the ^R
33587 and ^S keystrokes, which default to a reverse and a forward search,
33588 respectively. The search covers only the text that is displayed in the window.
33589 It cannot go further back up the log.
33590
33591 The point from which the search starts is indicated by a caret marker. This is
33592 normally at the end of the text in the window, but can be positioned explicitly
33593 by pointing and clicking with the left mouse button, and is moved automatically
33594 by a successful search. If new text arrives in the window when it is scrolled
33595 back, the caret remains where it is, but if the window is not scrolled back,
33596 the caret is moved to the end of the new text.
33597
33598 Pressing ^R or ^S pops up a window into which the search text can be typed.
33599 There are buttons for selecting forward or reverse searching, for carrying out
33600 the search, and for cancelling. If the "Search" button is pressed, the search
33601 happens and the window remains so that further searches can be done. If the
33602 "Return" key is pressed, a single search is done and the window is closed. If ^
33603 C is typed the search is cancelled.
33604
33605 The searching facility is implemented using the facilities of the Athena text
33606 widget. By default this pops up a window containing both "search" and "replace"
33607 options. In order to suppress the unwanted "replace" portion for eximon, a
33608 modified version of the TextPop widget is distributed with Exim. However, the
33609 linkers in BSDI and HP-UX seem unable to handle an externally provided version
33610 of TextPop when the remaining parts of the text widget come from the standard
33611 libraries. The compile-time option EXIMON_TEXTPOP can be unset to cut out the
33612 modified TextPop, making it possible to build Eximon on these systems, at the
33613 expense of having unwanted items in the search popup window.
33614
33615
33616 53.5 The queue display
33617 ----------------------
33618
33619 The bottom section of the monitor window contains a list of all messages that
33620 are on the queue, which includes those currently being received or delivered,
33621 as well as those awaiting delivery. The size of this subwindow is controlled by
33622 parameters in the configuration file Local/eximon.conf, and the frequency at
33623 which it is updated is controlled by another parameter in the same file - the
33624 default is 5 minutes, since queue scans can be quite expensive. However, there
33625 is an "Update" action button just above the display which can be used to force
33626 an update of the queue display at any time.
33627
33628 When a host is down for some time, a lot of pending mail can build up for it,
33629 and this can make it hard to deal with other messages on the queue. To help
33630 with this situation there is a button next to "Update" called "Hide". If
33631 pressed, a dialogue box called "Hide addresses ending with" is put up. If you
33632 type anything in here and press "Return", the text is added to a chain of such
33633 texts, and if every undelivered address in a message matches at least one of
33634 the texts, the message is not displayed.
33635
33636 If there is an address that does not match any of the texts, all the addresses
33637 are displayed as normal. The matching happens on the ends of addresses so, for
33638 example, cam.ac.uk specifies all addresses in Cambridge, while
33639 xxx@foo.com.example specifies just one specific address. When any hiding has
33640 been set up, a button called "Unhide" is displayed. If pressed, it cancels all
33641 hiding. Also, to ensure that hidden messages do not get forgotten, a hide
33642 request is automatically cancelled after one hour.
33643
33644 While the dialogue box is displayed, you can't press any buttons or do anything
33645 else to the monitor window. For this reason, if you want to cut text from the
33646 queue display to use in the dialogue box, you have to do the cutting before
33647 pressing the "Hide" button.
33648
33649 The queue display contains, for each unhidden queued message, the length of
33650 time it has been on the queue, the size of the message, the message id, the
33651 message sender, and the first undelivered recipient, all on one line. If it is
33652 a bounce message, the sender is shown as "<>". If there is more than one
33653 recipient to which the message has not yet been delivered, subsequent ones are
33654 listed on additional lines, up to a maximum configured number, following which
33655 an ellipsis is displayed. Recipients that have already received the message are
33656 not shown.
33657
33658 If a message is frozen, an asterisk is displayed at the left-hand side.
33659
33660 The queue display has a vertical scroll bar, and can also be scrolled by means
33661 of the arrow keys. Text can be cut from it using the mouse in the normal way.
33662 The text searching facilities, as described above for the log window, are also
33663 available, but the caret is always moved to the end of the text when the queue
33664 display is updated.
33665
33666
33667 53.6 The queue menu
33668 -------------------
33669
33670 If the shift key is held down and the left button is clicked when the mouse
33671 pointer is over the text for any message, an action menu pops up, and the first
33672 line of the queue display for the message is highlighted. This does not affect
33673 any selected text.
33674
33675 If you want to use some other event for popping up the menu, you can set the
33676 MENU_EVENT parameter in Local/eximon.conf to change the default, or set
33677 EXIMON_MENU_EVENT in the environment before starting the monitor. The value set
33678 in this parameter is a standard X event description. For example, to run eximon
33679 using ctrl rather than shift you could use
33680
33681 EXIMON_MENU_EVENT='Ctrl<Btn1Down>' eximon
33682
33683 The title of the menu is the message id, and it contains entries which act as
33684 follows:
33685
33686 * message log: The contents of the message log for the message are displayed
33687 in a new text window.
33688
33689 * headers: Information from the spool file that contains the envelope
33690 information and headers is displayed in a new text window. See chapter 55
33691 for a description of the format of spool files.
33692
33693 * body: The contents of the spool file containing the body of the message are
33694 displayed in a new text window. There is a default limit of 20,000 bytes to
33695 the amount of data displayed. This can be changed by setting the BODY_MAX
33696 option at compile time, or the EXIMON_BODY_MAX option at run time.
33697
33698 * deliver message: A call to Exim is made using the -M option to request
33699 delivery of the message. This causes an automatic thaw if the message is
33700 frozen. The -v option is also set, and the output from Exim is displayed in
33701 a new text window. The delivery is run in a separate process, to avoid
33702 holding up the monitor while the delivery proceeds.
33703
33704 * freeze message: A call to Exim is made using the -Mf option to request that
33705 the message be frozen.
33706
33707 * thaw message: A call to Exim is made using the -Mt option to request that
33708 the message be thawed.
33709
33710 * give up on msg: A call to Exim is made using the -Mg option to request that
33711 Exim gives up trying to deliver the message. A bounce message is generated
33712 for any remaining undelivered addresses.
33713
33714 * remove message: A call to Exim is made using the -Mrm option to request
33715 that the message be deleted from the system without generating a bounce
33716 message.
33717
33718 * add recipient: A dialog box is displayed into which a recipient address can
33719 be typed. If the address is not qualified and the QUALIFY_DOMAIN parameter
33720 is set in Local/eximon.conf, the address is qualified with that domain.
33721 Otherwise it must be entered as a fully qualified address. Pressing RETURN
33722 causes a call to Exim to be made using the -Mar option to request that an
33723 additional recipient be added to the message, unless the entry box is
33724 empty, in which case no action is taken.
33725
33726 * mark delivered: A dialog box is displayed into which a recipient address
33727 can be typed. If the address is not qualified and the QUALIFY_DOMAIN
33728 parameter is set in Local/eximon.conf, the address is qualified with that
33729 domain. Otherwise it must be entered as a fully qualified address. Pressing
33730 RETURN causes a call to Exim to be made using the -Mmd option to mark the
33731 given recipient address as already delivered, unless the entry box is
33732 empty, in which case no action is taken.
33733
33734 * mark all delivered: A call to Exim is made using the -Mmad option to mark
33735 all recipient addresses as already delivered.
33736
33737 * edit sender: A dialog box is displayed initialized with the current
33738 sender's address. Pressing RETURN causes a call to Exim to be made using
33739 the -Mes option to replace the sender address, unless the entry box is
33740 empty, in which case no action is taken. If you want to set an empty sender
33741 (as in bounce messages), you must specify it as "<>". Otherwise, if the
33742 address is not qualified and the QUALIFY_DOMAIN parameter is set in Local/
33743 eximon.conf, the address is qualified with that domain.
33744
33745 When a delivery is forced, a window showing the -v output is displayed. In
33746 other cases when a call to Exim is made, if there is any output from Exim (in
33747 particular, if the command fails) a window containing the command and the
33748 output is displayed. Otherwise, the results of the action are normally apparent
33749 from the log and queue displays. However, if you set ACTION_OUTPUT=yes in Local
33750 /eximon.conf, a window showing the Exim command is always opened, even if no
33751 output is generated.
33752
33753 The queue display is automatically updated for actions such as freezing and
33754 thawing, unless ACTION_QUEUE_UPDATE=no has been set in Local/eximon.conf. In
33755 this case the "Update" button has to be used to force an update of the display
33756 after one of these actions.
33757
33758 In any text window that is displayed as result of a menu action, the normal
33759 cut-and-paste facility is available, and searching can be carried out using ^R
33760 and ^S, as described above for the log tail window.
33761
33762
33763
33764 ===============================================================================
33765 54. SECURITY CONSIDERATIONS
33766
33767 This chapter discusses a number of issues concerned with security, some of
33768 which are also covered in other parts of this manual.
33769
33770 For reasons that this author does not understand, some people have promoted
33771 Exim as a "particularly secure" mailer. Perhaps it is because of the existence
33772 of this chapter in the documentation. However, the intent of the chapter is
33773 simply to describe the way Exim works in relation to certain security concerns,
33774 not to make any specific claims about the effectiveness of its security as
33775 compared with other MTAs.
33776
33777 What follows is a description of the way Exim is supposed to be. Best efforts
33778 have been made to try to ensure that the code agrees with the theory, but an
33779 absence of bugs can never be guaranteed. Any that are reported will get fixed
33780 as soon as possible.
33781
33782
33783 54.1 Building a more "hardened" Exim
33784 ------------------------------------
33785
33786 There are a number of build-time options that can be set in Local/Makefile to
33787 create Exim binaries that are "harder" to attack, in particular by a rogue Exim
33788 administrator who does not have the root password, or by someone who has
33789 penetrated the Exim (but not the root) account. These options are as follows:
33790
33791 * ALT_CONFIG_PREFIX can be set to a string that is required to match the
33792 start of any file names used with the -C option. When it is set, these file
33793 names are also not allowed to contain the sequence "/../". (However, if the
33794 value of the -C option is identical to the value of CONFIGURE_FILE in Local
33795 /Makefile, Exim ignores -C and proceeds as usual.) There is no default
33796 setting for ALT_CONFIG_PREFIX.
33797
33798 If the permitted configuration files are confined to a directory to which
33799 only root has access, this guards against someone who has broken into the
33800 Exim account from running a privileged Exim with an arbitrary configuration
33801 file, and using it to break into other accounts.
33802
33803 * If a non-trusted configuration file (i.e. not the default configuration
33804 file or one which is trusted by virtue of being listed in the
33805 TRUSTED_CONFIG_LIST file) is specified with -C, or if macros are given with
33806 -D (but see the next item), then root privilege is retained only if the
33807 caller of Exim is root. This locks out the possibility of testing a
33808 configuration using -C right through message reception and delivery, even
33809 if the caller is root. The reception works, but by that time, Exim is
33810 running as the Exim user, so when it re-execs to regain privilege for the
33811 delivery, the use of -C causes privilege to be lost. However, root can test
33812 reception and delivery using two separate commands.
33813
33814 * The WHITELIST_D_MACROS build option declares some macros to be safe to
33815 override with -D if the real uid is one of root, the Exim run-time user or
33816 the CONFIGURE_OWNER, if defined. The potential impact of this option is
33817 limited by requiring the run-time value supplied to -D to match a regex
33818 that errs on the restrictive side. Requiring build-time selection of safe
33819 macros is onerous but this option is intended solely as a transition
33820 mechanism to permit previously-working configurations to continue to work
33821 after release 4.73.
33822
33823 * If DISABLE_D_OPTION is defined, the use of the -D command line option is
33824 disabled.
33825
33826 * FIXED_NEVER_USERS can be set to a colon-separated list of users that are
33827 never to be used for any deliveries. This is like the never_users runtime
33828 option, but it cannot be overridden; the runtime option adds additional
33829 users to the list. The default setting is "root"; this prevents a non-root
33830 user who is permitted to modify the runtime file from using Exim as a way
33831 to get root.
33832
33833
33834 54.2 Root privilege
33835 -------------------
33836
33837 The Exim binary is normally setuid to root, which means that it gains root
33838 privilege (runs as root) when it starts execution. In some special cases (for
33839 example, when the daemon is not in use and there are no local deliveries), it
33840 may be possible to run Exim setuid to some user other than root. This is
33841 discussed in the next section. However, in most installations, root privilege
33842 is required for two things:
33843
33844 * To set up a socket connected to the standard SMTP port (25) when
33845 initialising the listening daemon. If Exim is run from inetd, this
33846 privileged action is not required.
33847
33848 * To be able to change uid and gid in order to read users' .forward files and
33849 perform local deliveries as the receiving user or as specified in the
33850 configuration.
33851
33852 It is not necessary to be root to do any of the other things Exim does, such as
33853 receiving messages and delivering them externally over SMTP, and it is
33854 obviously more secure if Exim does not run as root except when necessary. For
33855 this reason, a user and group for Exim to use must be defined in Local/Makefile
33856 . These are known as "the Exim user" and "the Exim group". Their values can be
33857 changed by the run time configuration, though this is not recommended. Often a
33858 user called exim is used, but some sites use mail or another user name
33859 altogether.
33860
33861 Exim uses setuid() whenever it gives up root privilege. This is a permanent
33862 abdication; the process cannot regain root afterwards. Prior to release 4.00,
33863 seteuid() was used in some circumstances, but this is no longer the case.
33864
33865 After a new Exim process has interpreted its command line options, it changes
33866 uid and gid in the following cases:
33867
33868 * If the -C option is used to specify an alternate configuration file, or if
33869 the -D option is used to define macro values for the configuration, and the
33870 calling process is not running as root, the uid and gid are changed to
33871 those of the calling process. However, if DISABLE_D_OPTION is defined in
33872 Local/Makefile, the -D option may not be used at all. If WHITELIST_D_MACROS
33873 is defined in Local/Makefile, then some macro values can be supplied if the
33874 calling process is running as root, the Exim run-time user or
33875 CONFIGURE_OWNER, if defined.
33876
33877 * If the expansion test option (-be) or one of the filter testing options (
33878 -bf or -bF) are used, the uid and gid are changed to those of the calling
33879 process.
33880
33881 * If the process is not a daemon process or a queue runner process or a
33882 delivery process or a process for testing address routing (started with -bt
33883 ), the uid and gid are changed to the Exim user and group. This means that
33884 Exim always runs under its own uid and gid when receiving messages. This
33885 also applies when testing address verification (the -bv option) and testing
33886 incoming message policy controls (the -bh option).
33887
33888 * For a daemon, queue runner, delivery, or address testing process, the uid
33889 remains as root at this stage, but the gid is changed to the Exim group.
33890
33891 The processes that initially retain root privilege behave as follows:
33892
33893 * A daemon process changes the gid to the Exim group and the uid to the Exim
33894 user after setting up one or more listening sockets. The initgroups()
33895 function is called, so that if the Exim user is in any additional groups,
33896 they will be used during message reception.
33897
33898 * A queue runner process retains root privilege throughout its execution. Its
33899 job is to fork a controlled sequence of delivery processes.
33900
33901 * A delivery process retains root privilege throughout most of its execution,
33902 but any actual deliveries (that is, the transports themselves) are run in
33903 subprocesses which always change to a non-root uid and gid. For local
33904 deliveries this is typically the uid and gid of the owner of the mailbox;
33905 for remote deliveries, the Exim uid and gid are used. Once all the delivery
33906 subprocesses have been run, a delivery process changes to the Exim uid and
33907 gid while doing post-delivery tidying up such as updating the retry
33908 database and generating bounce and warning messages.
33909
33910 While the recipient addresses in a message are being routed, the delivery
33911 process runs as root. However, if a user's filter file has to be processed,
33912 this is done in a subprocess that runs under the individual user's uid and
33913 gid. A system filter is run as root unless system_filter_user is set.
33914
33915 * A process that is testing addresses (the -bt option) runs as root so that
33916 the routing is done in the same environment as a message delivery.
33917
33918
33919 54.3 Running Exim without privilege
33920 -----------------------------------
33921
33922 Some installations like to run Exim in an unprivileged state for more of its
33923 operation, for added security. Support for this mode of operation is provided
33924 by the global option deliver_drop_privilege. When this is set, the uid and gid
33925 are changed to the Exim user and group at the start of a delivery process (and
33926 also queue runner and address testing processes). This means that address
33927 routing is no longer run as root, and the deliveries themselves cannot change
33928 to any other uid.
33929
33930 Leaving the binary setuid to root, but setting deliver_drop_privilege means
33931 that the daemon can still be started in the usual way, and it can respond
33932 correctly to SIGHUP because the re-invocation regains root privilege.
33933
33934 An alternative approach is to make Exim setuid to the Exim user and also setgid
33935 to the Exim group. If you do this, the daemon must be started from a root
33936 process. (Calling Exim from a root process makes it behave in the way it does
33937 when it is setuid root.) However, the daemon cannot restart itself after a
33938 SIGHUP signal because it cannot regain privilege.
33939
33940 It is still useful to set deliver_drop_privilege in this case, because it stops
33941 Exim from trying to re-invoke itself to do a delivery after a message has been
33942 received. Such a re-invocation is a waste of resources because it has no
33943 effect.
33944
33945 If restarting the daemon is not an issue (for example, if mua_wrapper is set,
33946 or inetd is being used instead of a daemon), having the binary setuid to the
33947 Exim user seems a clean approach, but there is one complication:
33948
33949 In this style of operation, Exim is running with the real uid and gid set to
33950 those of the calling process, and the effective uid/gid set to Exim's values.
33951 Ideally, any association with the calling process' uid/gid should be dropped,
33952 that is, the real uid/gid should be reset to the effective values so as to
33953 discard any privileges that the caller may have. While some operating systems
33954 have a function that permits this action for a non-root effective uid, quite a
33955 number of them do not. Because of this lack of standardization, Exim does not
33956 address this problem at this time.
33957
33958 For this reason, the recommended approach for "mostly unprivileged" running is
33959 to keep the Exim binary setuid to root, and to set deliver_drop_privilege. This
33960 also has the advantage of allowing a daemon to be used in the most
33961 straightforward way.
33962
33963 If you configure Exim not to run delivery processes as root, there are a number
33964 of restrictions on what you can do:
33965
33966 * You can deliver only as the Exim user/group. You should explicitly use the
33967 user and group options to override routers or local transports that
33968 normally deliver as the recipient. This makes sure that configurations that
33969 work in this mode function the same way in normal mode. Any implicit or
33970 explicit specification of another user causes an error.
33971
33972 * Use of .forward files is severely restricted, such that it is usually not
33973 worthwhile to include them in the configuration.
33974
33975 * Users who wish to use .forward would have to make their home directory and
33976 the file itself accessible to the Exim user. Pipe and append-to-file
33977 entries, and their equivalents in Exim filters, cannot be used. While they
33978 could be enabled in the Exim user's name, that would be insecure and not
33979 very useful.
33980
33981 * Unless the local user mailboxes are all owned by the Exim user (possible in
33982 some POP3 or IMAP-only environments):
33983
33984 1. They must be owned by the Exim group and be writeable by that group.
33985 This implies you must set mode in the appendfile configuration, as well
33986 as the mode of the mailbox files themselves.
33987
33988 2. You must set no_check_owner, since most or all of the files will not be
33989 owned by the Exim user.
33990
33991 3. You must set file_must_exist, because Exim cannot set the owner
33992 correctly on a newly created mailbox when unprivileged. This also
33993 implies that new mailboxes need to be created manually.
33994
33995 These restrictions severely restrict what can be done in local deliveries.
33996 However, there are no restrictions on remote deliveries. If you are running a
33997 gateway host that does no local deliveries, setting deliver_drop_privilege
33998 gives more security at essentially no cost.
33999
34000 If you are using the mua_wrapper facility (see chapter 50),
34001 deliver_drop_privilege is forced to be true.
34002
34003
34004 54.4 Delivering to local files
34005 ------------------------------
34006
34007 Full details of the checks applied by appendfile before it writes to a file are
34008 given in chapter 26.
34009
34010
34011 54.5 Running local commands
34012 ---------------------------
34013
34014 There are a number of ways in which an administrator can configure Exim to run
34015 commands based upon received, untrustworthy, data. Further, in some
34016 configurations a user who can control a .forward file can also arrange to run
34017 commands. Configuration to check includes, but is not limited to:
34018
34019 * Use of use_shell in the pipe transport: various forms of shell command
34020 injection may be possible with this option present. It is dangerous and
34021 should be used only with considerable caution. Consider constraints which
34022 whitelist allowed characters in a variable which is to be used in a pipe
34023 transport that has use_shell enabled.
34024
34025 * A number of options such as forbid_filter_run, forbid_filter_perl,
34026 forbid_filter_dlfunc and so forth which restrict facilities available to
34027 .forward files in a redirect router. If Exim is running on a central mail
34028 hub to which ordinary users do not have shell access, but home directories
34029 are NFS mounted (for instance) then administrators should review the list
34030 of these forbid options available, and should bear in mind that the options
34031 that may need forbidding can change as new features are added between
34032 releases.
34033
34034 * The ${run...} expansion item does not use a shell by default, but
34035 administrators can configure use of /bin/sh as part of the command. Such
34036 invocations should be viewed with prejudicial suspicion.
34037
34038 * Administrators who use embedded Perl are advised to explore how Perl's
34039 taint checking might apply to their usage.
34040
34041 * Use of ${expand...} is somewhat analagous to shell's eval builtin and
34042 administrators are well advised to view its use with suspicion, in case
34043 (for instance) it allows a local-part to contain embedded Exim directives.
34044
34045 * Use of ${match_local_part...} and friends becomes more dangerous if Exim
34046 was built with EXPAND_LISTMATCH_RHS defined: the second string in each can
34047 reference arbitrary lists and files, rather than just being a list of
34048 opaque strings. The EXPAND_LISTMATCH_RHS option was added and set false by
34049 default because of real-world security vulnerabilities caused by its use
34050 with untrustworthy data injected in, for SQL injection attacks. Consider
34051 the use of the inlisti expansion condition instead.
34052
34053
34054 54.6 Trust in configuration data
34055 --------------------------------
34056
34057 If configuration data for Exim can come from untrustworthy sources, there are
34058 some issues to be aware of:
34059
34060 * Use of ${expand...} may provide a path for shell injection attacks.
34061
34062 * Letting untrusted data provide a regular expression is unwise.
34063
34064 * Using ${match...} to apply a fixed regular expression against untrusted
34065 data may result in pathological behaviour within PCRE. Be aware of what
34066 "backtracking" means and consider options for being more strict with a
34067 regular expression. Avenues to explore include limiting what can match
34068 (avoiding "." when "[a-z0-9]" or other character class will do), use of
34069 atomic grouping and possessive quantifiers or just not using regular
34070 expressions against untrusted data.
34071
34072 * It can be important to correctly use ${quote:...}, ${quote_local_part:...}
34073 and ${quote_<lookup-type>:...} expansion items to ensure that data is
34074 correctly constructed.
34075
34076 * Some lookups might return multiple results, even though normal usage is
34077 only expected to yield one result.
34078
34079
34080 54.7 IPv4 source routing
34081 ------------------------
34082
34083 Many operating systems suppress IP source-routed packets in the kernel, but
34084 some cannot be made to do this, so Exim does its own check. It logs incoming
34085 IPv4 source-routed TCP calls, and then drops them. Things are all different in
34086 IPv6. No special checking is currently done.
34087
34088
34089 54.8 The VRFY, EXPN, and ETRN commands in SMTP
34090 ----------------------------------------------
34091
34092 Support for these SMTP commands is disabled by default. If required, they can
34093 be enabled by defining suitable ACLs.
34094
34095
34096 54.9 Privileged users
34097 ---------------------
34098
34099 Exim recognizes two sets of users with special privileges. Trusted users are
34100 able to submit new messages to Exim locally, but supply their own sender
34101 addresses and information about a sending host. For other users submitting
34102 local messages, Exim sets up the sender address from the uid, and doesn't
34103 permit a remote host to be specified.
34104
34105 However, an untrusted user is permitted to use the -f command line option in
34106 the special form -f <> to indicate that a delivery failure for the message
34107 should not cause an error report. This affects the message's envelope, but it
34108 does not affect the Sender: header. Untrusted users may also be permitted to
34109 use specific forms of address with the -f option by setting the
34110 untrusted_set_sender option.
34111
34112 Trusted users are used to run processes that receive mail messages from some
34113 other mail domain and pass them on to Exim for delivery either locally, or over
34114 the Internet. Exim trusts a caller that is running as root, as the Exim user,
34115 as any user listed in the trusted_users configuration option, or under any
34116 group listed in the trusted_groups option.
34117
34118 Admin users are permitted to do things to the messages on Exim's queue. They
34119 can freeze or thaw messages, cause them to be returned to their senders, remove
34120 them entirely, or modify them in various ways. In addition, admin users can run
34121 the Exim monitor and see all the information it is capable of providing, which
34122 includes the contents of files on the spool.
34123
34124 By default, the use of the -M and -q options to cause Exim to attempt delivery
34125 of messages on its queue is restricted to admin users. This restriction can be
34126 relaxed by setting the no_prod_requires_admin option. Similarly, the use of -bp
34127 (and its variants) to list the contents of the queue is also restricted to
34128 admin users. This restriction can be relaxed by setting
34129 no_queue_list_requires_admin.
34130
34131 Exim recognizes an admin user if the calling process is running as root or as
34132 the Exim user or if any of the groups associated with the calling process is
34133 the Exim group. It is not necessary actually to be running under the Exim
34134 group. However, if admin users who are not root or the Exim user are to access
34135 the contents of files on the spool via the Exim monitor (which runs
34136 unprivileged), Exim must be built to allow group read access to its spool
34137 files.
34138
34139
34140 54.10 Spool files
34141 -----------------
34142
34143 Exim's spool directory and everything it contains is owned by the Exim user and
34144 set to the Exim group. The mode for spool files is defined in the Local/
34145 Makefile configuration file, and defaults to 0640. This means that any user who
34146 is a member of the Exim group can access these files.
34147
34148
34149 54.11 Use of argv[0]
34150 --------------------
34151
34152 Exim examines the last component of argv[0], and if it matches one of a set of
34153 specific strings, Exim assumes certain options. For example, calling Exim with
34154 the last component of argv[0] set to "rsmtp" is exactly equivalent to calling
34155 it with the option -bS. There are no security implications in this.
34156
34157
34158 54.12 Use of %f formatting
34159 --------------------------
34160
34161 The only use made of "%f" by Exim is in formatting load average values. These
34162 are actually stored in integer variables as 1000 times the load average.
34163 Consequently, their range is limited and so therefore is the length of the
34164 converted output.
34165
34166
34167 54.13 Embedded Exim path
34168 ------------------------
34169
34170 Exim uses its own path name, which is embedded in the code, only when it needs
34171 to re-exec in order to regain root privilege. Therefore, it is not root when it
34172 does so. If some bug allowed the path to get overwritten, it would lead to an
34173 arbitrary program's being run as exim, not as root.
34174
34175
34176 54.14 Dynamic module directory
34177 ------------------------------
34178
34179 Any dynamically loadable modules must be installed into the directory defined
34180 in "LOOKUP_MODULE_DIR" in Local/Makefile for Exim to permit loading it.
34181
34182
34183 54.15 Use of sprintf()
34184 ----------------------
34185
34186 A large number of occurrences of "sprintf" in the code are actually calls to
34187 string_sprintf(), a function that returns the result in malloc'd store. The
34188 intermediate formatting is done into a large fixed buffer by a function that
34189 runs through the format string itself, and checks the length of each conversion
34190 before performing it, thus preventing buffer overruns.
34191
34192 The remaining uses of sprintf() happen in controlled circumstances where the
34193 output buffer is known to be sufficiently long to contain the converted string.
34194
34195
34196 54.16 Use of debug_printf() and log_write()
34197 -------------------------------------------
34198
34199 Arbitrary strings are passed to both these functions, but they do their
34200 formatting by calling the function string_vformat(), which runs through the
34201 format string itself, and checks the length of each conversion.
34202
34203
34204 54.17 Use of strcat() and strcpy()
34205 ----------------------------------
34206
34207 These are used only in cases where the output buffer is known to be large
34208 enough to hold the result.
34209
34210
34211
34212 ===============================================================================
34213 55. FORMAT OF SPOOL FILES
34214
34215 A message on Exim's queue consists of two files, whose names are the message id
34216 followed by -D and -H, respectively. The data portion of the message is kept in
34217 the -D file on its own. The message's envelope, status, and headers are all
34218 kept in the -H file, whose format is described in this chapter. Each of these
34219 two files contains the final component of its own name as its first line. This
34220 is insurance against disk crashes where the directory is lost but the files
34221 themselves are recoverable.
34222
34223 Some people are tempted into editing -D files in order to modify messages. You
34224 need to be extremely careful if you do this; it is not recommended and you are
34225 on your own if you do it. Here are some of the pitfalls:
34226
34227 * You must ensure that Exim does not try to deliver the message while you are
34228 fiddling with it. The safest way is to take out a write lock on the -D
34229 file, which is what Exim itself does, using fcntl(). If you update the file
34230 in place, the lock will be retained. If you write a new file and rename it,
34231 the lock will be lost at the instant of rename.
34232
34233 * If you change the number of lines in the file, the value of $body_linecount
34234 , which is stored in the -H file, will be incorrect. At present, this value
34235 is not used by Exim, but there is no guarantee that this will always be the
34236 case.
34237
34238 * If the message is in MIME format, you must take care not to break it.
34239
34240 * If the message is cryptographically signed, any change will invalidate the
34241 signature.
34242
34243 All in all, modifying -D files is fraught with danger.
34244
34245 Files whose names end with -J may also be seen in the input directory (or its
34246 subdirectories when split_spool_directory is set). These are journal files,
34247 used to record addresses to which the message has been delivered during the
34248 course of a delivery attempt. If there are still undelivered recipients at the
34249 end, the -H file is updated, and the -J file is deleted. If, however, there is
34250 some kind of crash (for example, a power outage) before this happens, the -J
34251 file remains in existence. When Exim next processes the message, it notices the
34252 -J file and uses it to update the -H file before starting the next delivery
34253 attempt.
34254
34255
34256 55.1 Format of the -H file
34257 --------------------------
34258
34259 The second line of the -H file contains the login name for the uid of the
34260 process that called Exim to read the message, followed by the numerical uid and
34261 gid. For a locally generated message, this is normally the user who sent the
34262 message. For a message received over TCP/IP via the daemon, it is normally the
34263 Exim user.
34264
34265 The third line of the file contains the address of the message's sender as
34266 transmitted in the envelope, contained in angle brackets. The sender address is
34267 empty for bounce messages. For incoming SMTP mail, the sender address is given
34268 in the MAIL command. For locally generated mail, the sender address is created
34269 by Exim from the login name of the current user and the configured
34270 qualify_domain. However, this can be overridden by the -f option or a leading
34271 "From " line if the caller is trusted, or if the supplied address is "<>" or an
34272 address that matches untrusted_set_senders.
34273
34274 The fourth line contains two numbers. The first is the time that the message
34275 was received, in the conventional Unix form - the number of seconds since the
34276 start of the epoch. The second number is a count of the number of messages
34277 warning of delayed delivery that have been sent to the sender.
34278
34279 There follow a number of lines starting with a hyphen. These can appear in any
34280 order, and are omitted when not relevant:
34281
34282 -acl <number> <length>
34283
34284 This item is obsolete, and is not generated from Exim release 4.61 onwards;
34285 -aclc and -aclm are used instead. However, -acl is still recognized, to
34286 provide backward compatibility. In the old format, a line of this form is
34287 present for every ACL variable that is not empty. The number identifies the
34288 variable; the acl_cx variables are numbered 0-9 and the acl_mx variables
34289 are numbered 10-19. The length is the length of the data string for the
34290 variable. The string itself starts at the beginning of the next line, and
34291 is followed by a newline character. It may contain internal newlines.
34292
34293 -aclc <rest-of-name> <length>
34294
34295 A line of this form is present for every ACL connection variable that is
34296 defined. Note that there is a space between -aclc and the rest of the name.
34297 The length is the length of the data string for the variable. The string
34298 itself starts at the beginning of the next line, and is followed by a
34299 newline character. It may contain internal newlines.
34300
34301 -aclm <rest-of-name> <length>
34302
34303 A line of this form is present for every ACL message variable that is
34304 defined. Note that there is a space between -aclm and the rest of the name.
34305 The length is the length of the data string for the variable. The string
34306 itself starts at the beginning of the next line, and is followed by a
34307 newline character. It may contain internal newlines.
34308
34309 -active_hostname <hostname>
34310
34311 This is present if, when the message was received over SMTP, the value of
34312 $smtp_active_hostname was different to the value of $primary_hostname.
34313
34314 -allow_unqualified_recipient
34315
34316 This is present if unqualified recipient addresses are permitted in header
34317 lines (to stop such addresses from being qualified if rewriting occurs at
34318 transport time). Local messages that were input using -bnq and remote
34319 messages from hosts that match recipient_unqualified_hosts set this flag.
34320
34321 -allow_unqualified_sender
34322
34323 This is present if unqualified sender addresses are permitted in header
34324 lines (to stop such addresses from being qualified if rewriting occurs at
34325 transport time). Local messages that were input using -bnq and remote
34326 messages from hosts that match sender_unqualified_hosts set this flag.
34327
34328 -auth_id <text>
34329
34330 The id information for a message received on an authenticated SMTP
34331 connection - the value of the $authenticated_id variable.
34332
34333 -auth_sender <address>
34334
34335 The address of an authenticated sender - the value of the
34336 $authenticated_sender variable.
34337
34338 -body_linecount <number>
34339
34340 This records the number of lines in the body of the message, and is always
34341 present.
34342
34343 -body_zerocount <number>
34344
34345 This records the number of binary zero bytes in the body of the message,
34346 and is present if the number is greater than zero.
34347
34348 -deliver_firsttime
34349
34350 This is written when a new message is first added to the spool. When the
34351 spool file is updated after a deferral, it is omitted.
34352
34353 -frozen <time>
34354
34355 The message is frozen, and the freezing happened at <time>.
34356
34357 -helo_name <text>
34358
34359 This records the host name as specified by a remote host in a HELO or EHLO
34360 command.
34361
34362 -host_address <address>.<port>
34363
34364 This records the IP address of the host from which the message was received
34365 and the remote port number that was used. It is omitted for locally
34366 generated messages.
34367
34368 -host_auth <text>
34369
34370 If the message was received on an authenticated SMTP connection, this
34371 records the name of the authenticator - the value of the
34372 $sender_host_authenticated variable.
34373
34374 -host_lookup_failed
34375
34376 This is present if an attempt to look up the sending host's name from its
34377 IP address failed. It corresponds to the $host_lookup_failed variable.
34378
34379 -host_name <text>
34380
34381 This records the name of the remote host from which the message was
34382 received, if the host name was looked up from the IP address when the
34383 message was being received. It is not present if no reverse lookup was
34384 done.
34385
34386 -ident <text>
34387
34388 For locally submitted messages, this records the login of the originating
34389 user, unless it was a trusted user and the -oMt option was used to specify
34390 an ident value. For messages received over TCP/IP, this records the ident
34391 string supplied by the remote host, if any.
34392
34393 -interface_address <address>.<port>
34394
34395 This records the IP address of the local interface and the port number
34396 through which a message was received from a remote host. It is omitted for
34397 locally generated messages.
34398
34399 -local
34400
34401 The message is from a local sender.
34402
34403 -localerror
34404
34405 The message is a locally-generated bounce message.
34406
34407 -local_scan <string>
34408
34409 This records the data string that was returned by the local_scan() function
34410 when the message was received - the value of the $local_scan_data variable.
34411 It is omitted if no data was returned.
34412
34413 -manual_thaw
34414
34415 The message was frozen but has been thawed manually, that is, by an
34416 explicit Exim command rather than via the auto-thaw process.
34417
34418 -N
34419
34420 A testing delivery process was started using the -N option to suppress any
34421 actual deliveries, but delivery was deferred. At any further delivery
34422 attempts, -N is assumed.
34423
34424 -received_protocol
34425
34426 This records the value of the $received_protocol variable, which contains
34427 the name of the protocol by which the message was received.
34428
34429 -sender_set_untrusted
34430
34431 The envelope sender of this message was set by an untrusted local caller
34432 (used to ensure that the caller is displayed in queue listings).
34433
34434 -spam_score_int <number>
34435
34436 If a message was scanned by SpamAssassin, this is present. It records the
34437 value of $spam_score_int.
34438
34439 -tls_certificate_verified
34440
34441 A TLS certificate was received from the client that sent this message, and
34442 the certificate was verified by the server.
34443
34444 -tls_cipher <cipher name>
34445
34446 When the message was received over an encrypted connection, this records
34447 the name of the cipher suite that was used.
34448
34449 -tls_peerdn <peer DN>
34450
34451 When the message was received over an encrypted connection, and a
34452 certificate was received from the client, this records the Distinguished
34453 Name from that certificate.
34454
34455 Following the options there is a list of those addresses to which the message
34456 is not to be delivered. This set of addresses is initialized from the command
34457 line when the -t option is used and extract_addresses_remove_arguments is set;
34458 otherwise it starts out empty. Whenever a successful delivery is made, the
34459 address is added to this set. The addresses are kept internally as a balanced
34460 binary tree, and it is a representation of that tree which is written to the
34461 spool file. If an address is expanded via an alias or forward file, the
34462 original address is added to the tree when deliveries to all its child
34463 addresses are complete.
34464
34465 If the tree is empty, there is a single line in the spool file containing just
34466 the text "XX". Otherwise, each line consists of two letters, which are either Y
34467 or N, followed by an address. The address is the value for the node of the
34468 tree, and the letters indicate whether the node has a left branch and/or a
34469 right branch attached to it, respectively. If branches exist, they immediately
34470 follow. Here is an example of a three-node tree:
34471
34472 YY darcy@austen.fict.example
34473 NN alice@wonderland.fict.example
34474 NN editor@thesaurus.ref.example
34475
34476 After the non-recipients tree, there is a list of the message's recipients.
34477 This is a simple list, preceded by a count. It includes all the original
34478 recipients of the message, including those to whom the message has already been
34479 delivered. In the simplest case, the list contains one address per line. For
34480 example:
34481
34482 4
34483 editor@thesaurus.ref.example
34484 darcy@austen.fict.example
34485 rdo@foundation
34486 alice@wonderland.fict.example
34487
34488 However, when a child address has been added to the top-level addresses as a
34489 result of the use of the one_time option on a redirect router, each line is of
34490 the following form:
34491
34492 <top-level address> <errors_to address> <length>,<parent number>#<flag bits>
34493
34494 The 01 flag bit indicates the presence of the three other fields that follow
34495 the top-level address. Other bits may be used in future to support additional
34496 fields. The <parent number> is the offset in the recipients list of the
34497 original parent of the "one time" address. The first two fields are the
34498 envelope sender that is associated with this address and its length. If the
34499 length is zero, there is no special envelope sender (there are then two space
34500 characters in the line). A non-empty field can arise from a redirect router
34501 that has an errors_to setting.
34502
34503 A blank line separates the envelope and status information from the headers
34504 which follow. A header may occupy several lines of the file, and to save effort
34505 when reading it in, each header is preceded by a number and an identifying
34506 character. The number is the number of characters in the header, including any
34507 embedded newlines and the terminating newline. The character is one of the
34508 following:
34509
34510 <blank> header in which Exim has no special interest
34511 "B" Bcc: header
34512 "C" Cc: header
34513 "F" From: header
34514 "I" Message-id: header
34515 "P" Received: header - P for "postmark"
34516 "R" Reply-To: header
34517 "S" Sender: header
34518 "T" To: header
34519 "*" replaced or deleted header
34520
34521 Deleted or replaced (rewritten) headers remain in the spool file for debugging
34522 purposes. They are not transmitted when the message is delivered. Here is a
34523 typical set of headers:
34524
34525 111P Received: by hobbit.fict.example with local (Exim 4.00)
34526 id 14y9EI-00026G-00; Fri, 11 May 2001 10:28:59 +0100
34527 049 Message-Id: <E14y9EI-00026G-00@hobbit.fict.example>
34528 038* X-rewrote-sender: bb@hobbit.fict.example
34529 042* From: Bilbo Baggins <bb@hobbit.fict.example>
34530 049F From: Bilbo Baggins <B.Baggins@hobbit.fict.example>
34531 099* To: alice@wonderland.fict.example, rdo@foundation,
34532 darcy@austen.fict.example, editor@thesaurus.ref.example
34533 104T To: alice@wonderland.fict.example, rdo@foundation.example,
34534 darcy@austen.fict.example, editor@thesaurus.ref.example
34535 038 Date: Fri, 11 May 2001 10:28:59 +0100
34536
34537 The asterisked headers indicate that the envelope sender, From: header, and To:
34538 header have been rewritten, the last one because routing expanded the
34539 unqualified domain foundation.
34540
34541
34542
34543 ===============================================================================
34544 56. SUPPORT FOR DKIM (DOMAINKEYS IDENTIFIED MAIL)
34545
34546 DKIM is a mechanism by which messages sent by some entity can be provably
34547 linked to a domain which that entity controls. It permits reputation to be
34548 tracked on a per-domain basis, rather than merely upon source IP address. DKIM
34549 is documented in RFC 4871.
34550
34551 Since version 4.70, DKIM support is compiled into Exim by default. It can be
34552 disabled by setting DISABLE_DKIM=yes in Local/Makefile.
34553
34554 Exim's DKIM implementation allows to
34555
34556 1. Sign outgoing messages: This function is implemented in the SMTP transport.
34557 It can co-exist with all other Exim features (including transport filters)
34558 except cutthrough delivery.
34559
34560 2. Verify signatures in incoming messages: This is implemented by an
34561 additional ACL (acl_smtp_dkim), which can be called several times per
34562 message, with different signature contexts.
34563
34564 In typical Exim style, the verification implementation does not include any
34565 default "policy". Instead it enables you to build your own policy using Exim's
34566 standard controls.
34567
34568 Please note that verification of DKIM signatures in incoming mail is turned on
34569 by default for logging purposes. For each signature in incoming email, exim
34570 will log a line displaying the most important signature details, and the
34571 signature status. Here is an example (with line-breaks added for clarity):
34572
34573 2009-09-09 10:22:28 1MlIRf-0003LU-U3 DKIM:
34574 d=facebookmail.com s=q1-2009b
34575 c=relaxed/relaxed a=rsa-sha1
34576 i=@facebookmail.com t=1252484542 [verification succeeded]
34577
34578 You might want to turn off DKIM verification processing entirely for internal
34579 or relay mail sources. To do that, set the dkim_disable_verify ACL control
34580 modifier. This should typically be done in the RCPT ACL, at points where you
34581 accept mail from relay sources (internal hosts or authenticated senders).
34582
34583
34584 56.1 Signing outgoing messages
34585 ------------------------------
34586
34587 Signing is implemented by setting private options on the SMTP transport. These
34588 options take (expandable) strings as arguments.
34589
34590 +-----------+---------+-------------+--------------+
34591 |dkim_domain|Use: smtp|Type: string*|Default: unset|
34592 +-----------+---------+-------------+--------------+
34593
34594 MANDATORY: The domain you want to sign with. The result of this expanded option
34595 is put into the $dkim_domain expansion variable.
34596
34597 +-------------+---------+-------------+--------------+
34598 |dkim_selector|Use: smtp|Type: string*|Default: unset|
34599 +-------------+---------+-------------+--------------+
34600
34601 MANDATORY: This sets the key selector string. You can use the $dkim_domain
34602 expansion variable to look up a matching selector. The result is put in the
34603 expansion variable $dkim_selector which should be used in the dkim_private_key
34604 option along with $dkim_domain.
34605
34606 +----------------+---------+-------------+--------------+
34607 |dkim_private_key|Use: smtp|Type: string*|Default: unset|
34608 +----------------+---------+-------------+--------------+
34609
34610 MANDATORY: This sets the private key to use. You can use the $dkim_domain and
34611 $dkim_selector expansion variables to determine the private key to use. The
34612 result can either
34613
34614 * be a valid RSA private key in ASCII armor, including line breaks.
34615
34616 * start with a slash, in which case it is treated as a file that contains the
34617 private key.
34618
34619 * be "0", "false" or the empty string, in which case the message will not be
34620 signed. This case will not result in an error, even if dkim_strict is set.
34621
34622 +----------+---------+-------------+--------------+
34623 |dkim_canon|Use: smtp|Type: string*|Default: unset|
34624 +----------+---------+-------------+--------------+
34625
34626 OPTIONAL: This option sets the canonicalization method used when signing a
34627 message. The DKIM RFC currently supports two methods: "simple" and "relaxed".
34628 The option defaults to "relaxed" when unset. Note: the current implementation
34629 only supports using the same canonicalization method for both headers and body.
34630
34631 +-----------+---------+-------------+--------------+
34632 |dkim_strict|Use: smtp|Type: string*|Default: unset|
34633 +-----------+---------+-------------+--------------+
34634
34635 OPTIONAL: This option defines how Exim behaves when signing a message that
34636 should be signed fails for some reason. When the expansion evaluates to either
34637 "1" or "true", Exim will defer. Otherwise Exim will send the message unsigned.
34638 You can use the $dkim_domain and $dkim_selector expansion variables here.
34639
34640 +-----------------+---------+-------------+--------------+
34641 |dkim_sign_headers|Use: smtp|Type: string*|Default: unset|
34642 +-----------------+---------+-------------+--------------+
34643
34644 OPTIONAL: When set, this option must expand to (or be specified as) a
34645 colon-separated list of header names. Headers with these names will be included
34646 in the message signature. When unspecified, the header names recommended in
34647 RFC4871 will be used.
34648
34649
34650 56.2 Verifying DKIM signatures in incoming mail
34651 -----------------------------------------------
34652
34653 Verification of DKIM signatures in incoming email is implemented via the
34654 acl_smtp_dkim ACL. By default, this ACL is called once for each syntactically
34655 (!) correct signature in the incoming message. A missing ACL definition
34656 defaults to accept. If any ACL call does not acccept, the message is not
34657 accepted. If a cutthrough delivery was in progress for the message it is
34658 summarily dropped (having wasted the transmission effort).
34659
34660 To evaluate the signature in the ACL a large number of expansion variables
34661 containing the signature status and its details are set up during the runtime
34662 of the ACL.
34663
34664 Calling the ACL only for existing signatures is not sufficient to build more
34665 advanced policies. For that reason, the global option dkim_verify_signers, and
34666 a global expansion variable $dkim_signers exist.
34667
34668 The global option dkim_verify_signers can be set to a colon-separated list of
34669 DKIM domains or identities for which the ACL acl_smtp_dkim is called. It is
34670 expanded when the message has been received. At this point, the expansion
34671 variable $dkim_signers already contains a colon-separated list of signer
34672 domains and identities for the message. When dkim_verify_signers is not
34673 specified in the main configuration, it defaults as:
34674
34675 dkim_verify_signers = $dkim_signers
34676
34677 This leads to the default behaviour of calling acl_smtp_dkim for each DKIM
34678 signature in the message. Current DKIM verifiers may want to explicitly call
34679 the ACL for known domains or identities. This would be achieved as follows:
34680
34681 dkim_verify_signers = paypal.com:ebay.com:$dkim_signers
34682
34683 This would result in acl_smtp_dkim always being called for "paypal.com" and
34684 "ebay.com", plus all domains and identities that have signatures in the
34685 message. You can also be more creative in constructing your policy. For
34686 example:
34687
34688 dkim_verify_signers = $sender_address_domain:$dkim_signers
34689
34690 If a domain or identity is listed several times in the (expanded) value of
34691 dkim_verify_signers, the ACL is only called once for that domain or identity.
34692
34693 Inside the acl_smtp_dkim, the following expansion variables are available (from
34694 most to least important):
34695
34696 $dkim_cur_signer
34697
34698 The signer that is being evaluated in this ACL run. This can be a domain or
34699 an identity. This is one of the list items from the expanded main option
34700 dkim_verify_signers (see above).
34701
34702 $dkim_verify_status
34703
34704 A string describing the general status of the signature. One of
34705
34706 * none: There is no signature in the message for the current domain or
34707 identity (as reflected by $dkim_cur_signer).
34708
34709 * invalid: The signature could not be verified due to a processing error.
34710 More detail is available in $dkim_verify_reason.
34711
34712 * fail: Verification of the signature failed. More detail is available in
34713 $dkim_verify_reason.
34714
34715 * pass: The signature passed verification. It is valid.
34716
34717 $dkim_verify_reason
34718
34719 A string giving a litte bit more detail when $dkim_verify_status is either
34720 "fail" or "invalid". One of
34721
34722 * pubkey_unavailable (when $dkim_verify_status="invalid"): The public key
34723 for the domain could not be retrieved. This may be a temporary problem.
34724
34725 * pubkey_syntax (when $dkim_verify_status="invalid"): The public key
34726 record for the domain is syntactically invalid.
34727
34728 * bodyhash_mismatch (when $dkim_verify_status="fail"): The calculated
34729 body hash does not match the one specified in the signature header.
34730 This means that the message body was modified in transit.
34731
34732 * signature_incorrect (when $dkim_verify_status="fail"): The signature
34733 could not be verified. This may mean that headers were modified,
34734 re-written or otherwise changed in a way which is incompatible with
34735 DKIM verification. It may of course also mean that the signature is
34736 forged.
34737
34738 $dkim_domain
34739
34740 The signing domain. IMPORTANT: This variable is only populated if there is
34741 an actual signature in the message for the current domain or identity (as
34742 reflected by $dkim_cur_signer).
34743
34744 $dkim_identity
34745
34746 The signing identity, if present. IMPORTANT: This variable is only
34747 populated if there is an actual signature in the message for the current
34748 domain or identity (as reflected by $dkim_cur_signer).
34749
34750 $dkim_selector
34751
34752 The key record selector string.
34753
34754 $dkim_algo
34755
34756 The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'.
34757
34758 $dkim_canon_body
34759
34760 The body canonicalization method. One of 'relaxed' or 'simple'.
34761
34762 dkim_canon_headers
34763
34764 The header canonicalization method. One of 'relaxed' or 'simple'.
34765
34766 $dkim_copiedheaders
34767
34768 A transcript of headers and their values which are included in the
34769 signature (copied from the 'z=' tag of the signature).
34770
34771 $dkim_bodylength
34772
34773 The number of signed body bytes. If zero ("0"), the body is unsigned. If no
34774 limit was set by the signer, "9999999999999" is returned. This makes sure
34775 that this variable always expands to an integer value.
34776
34777 $dkim_created
34778
34779 UNIX timestamp reflecting the date and time when the signature was created.
34780 When this was not specified by the signer, "0" is returned.
34781
34782 $dkim_expires
34783
34784 UNIX timestamp reflecting the date and time when the signer wants the
34785 signature to be treated as "expired". When this was not specified by the
34786 signer, "9999999999999" is returned. This makes it possible to do useful
34787 integer size comparisons against this value.
34788
34789 $dkim_headernames
34790
34791 A colon-separated list of names of headers included in the signature.
34792
34793 $dkim_key_testing
34794
34795 "1" if the key record has the "testing" flag set, "0" if not.
34796
34797 $dkim_key_nosubdomains
34798
34799 "1" if the key record forbids subdomaining, "0" otherwise.
34800
34801 $dkim_key_srvtype
34802
34803 Service type (tag s=) from the key record. Defaults to "*" if not specified
34804 in the key record.
34805
34806 $dkim_key_granularity
34807
34808 Key granularity (tag g=) from the key record. Defaults to "*" if not
34809 specified in the key record.
34810
34811 $dkim_key_notes
34812
34813 Notes from the key record (tag n=).
34814
34815 In addition, two ACL conditions are provided:
34816
34817 dkim_signers
34818
34819 ACL condition that checks a colon-separated list of domains or identities
34820 for a match against the domain or identity that the ACL is currently
34821 verifying (reflected by $dkim_cur_signer). This is typically used to
34822 restrict an ACL verb to a group of domains or identities. For example:
34823
34824 # Warn when Mail purportedly from GMail has no signature at all
34825 warn log_message = GMail sender without DKIM signature
34826 sender_domains = gmail.com
34827 dkim_signers = gmail.com
34828 dkim_status = none
34829
34830 dkim_status
34831
34832 ACL condition that checks a colon-separated list of possible DKIM
34833 verification results against the actual result of verification. This is
34834 typically used to restrict an ACL verb to a list of verification outcomes,
34835 for example:
34836
34837 deny message = Mail from Paypal with invalid/missing signature
34838 sender_domains = paypal.com:paypal.de
34839 dkim_signers = paypal.com:paypal.de
34840 dkim_status = none:invalid:fail
34841
34842 The possible status keywords are: 'none','invalid','fail' and 'pass'.
34843 Please see the documentation of the $dkim_verify_status expansion variable
34844 above for more information of what they mean.
34845
34846
34847
34848 ===============================================================================
34849 57. ADDING NEW DRIVERS OR LOOKUP TYPES
34850
34851 The following actions have to be taken in order to add a new router, transport,
34852 authenticator, or lookup type to Exim:
34853
34854 1. Choose a name for the driver or lookup type that does not conflict with any
34855 existing name; I will use "newdriver" in what follows.
34856
34857 2. Add to src/EDITME the line:
34858
34859 <type>_NEWDRIVER=yes
34860
34861 where <type> is ROUTER, TRANSPORT, AUTH, or LOOKUP. If the code is not to
34862 be included in the binary by default, comment this line out. You should
34863 also add any relevant comments about the driver or lookup type.
34864
34865 3. Add to src/config.h.defaults the line:
34866
34867 #define <type>_NEWDRIVER
34868
34869 4. Edit src/drtables.c, adding conditional code to pull in the private header
34870 and create a table entry as is done for all the other drivers and lookup
34871 types.
34872
34873 5. Edit scripts/lookups-Makefile if this is a new lookup; there is a for-loop
34874 near the bottom, ranging the "name_mod" variable over a list of all
34875 lookups. Add your "NEWDRIVER" to that list. As long as the dynamic module
34876 would be named newdriver.so, you can use the simple form that most lookups
34877 have.
34878
34879 6. Edit Makefile in the appropriate sub-directory (src/routers, src/transports
34880 , src/auths, or src/lookups); add a line for the new driver or lookup type
34881 and add it to the definition of OBJ.
34882
34883 7. Create newdriver.h and newdriver.c in the appropriate sub-directory of src.
34884
34885 8. Edit scripts/MakeLinks and add commands to link the .h and .c files as for
34886 other drivers and lookups.
34887
34888 Then all you need to do is write the code! A good way to start is to make a
34889 proforma by copying an existing module of the same type, globally changing all
34890 occurrences of the name, and cutting out most of the code. Note that any
34891 options you create must be listed in alphabetical order, because the tables are
34892 searched using a binary chop procedure.
34893
34894 There is a README file in each of the sub-directories of src describing the
34895 interface that is expected.
34896