e400286d7ba6261081429082fc92537511c2ed80
[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