Import Upstream version 4.89
[hcoop/debian/exim4.git] / doc / spec.txt
1 Specification of the Exim Mail Transfer Agent
2
3 Exim Maintainers
4
5 Copyright (c) 2017 University of Cambridge
6
7 Revision 4.89 07 Mar 2017 EM
8
9 -------------------------------------------------------------------------------
10
11 TABLE OF CONTENTS
12
13 1. Introduction
14
15 1.1. Exim documentation
16 1.2. FTP and web sites
17 1.3. Mailing lists
18 1.4. Exim training
19 1.5. Bug reports
20 1.6. Where to find the Exim distribution
21 1.7. Limitations
22 1.8. Run time configuration
23 1.9. Calling interface
24 1.10. Terminology
25
26 2. Incorporated code
27 3. How Exim receives and delivers mail
28
29 3.1. Overall philosophy
30 3.2. Policy control
31 3.3. User filters
32 3.4. Message identification
33 3.5. Receiving mail
34 3.6. Handling an incoming message
35 3.7. Life of a message
36 3.8. Processing an address for delivery
37 3.9. Processing an address for verification
38 3.10. Running an individual router
39 3.11. Duplicate addresses
40 3.12. Router preconditions
41 3.13. Delivery in detail
42 3.14. Retry mechanism
43 3.15. Temporary delivery failure
44 3.16. Permanent delivery failure
45 3.17. Failures to deliver bounce messages
46
47 4. Building and installing Exim
48
49 4.1. Unpacking
50 4.2. Multiple machine architectures and operating systems
51 4.3. PCRE library
52 4.4. DBM libraries
53 4.5. Pre-building configuration
54 4.6. Support for iconv()
55 4.7. Including TLS/SSL encryption support
56 4.8. Use of tcpwrappers
57 4.9. Including support for IPv6
58 4.10. Dynamically loaded lookup module support
59 4.11. The building process
60 4.12. Output from "make"
61 4.13. Overriding build-time options for Exim
62 4.14. OS-specific header files
63 4.15. Overriding build-time options for the monitor
64 4.16. Installing Exim binaries and scripts
65 4.17. Installing info documentation
66 4.18. Setting up the spool directory
67 4.19. Testing
68 4.20. Replacing another MTA with Exim
69 4.21. Upgrading Exim
70 4.22. Stopping the Exim daemon on Solaris
71
72 5. The Exim command line
73
74 5.1. Setting options by program name
75 5.2. Trusted and admin users
76 5.3. Command line options
77
78 6. The Exim run time configuration file
79
80 6.1. Using a different configuration file
81 6.2. Configuration file format
82 6.3. File inclusions in the configuration file
83 6.4. Macros in the configuration file
84 6.5. Macro substitution
85 6.6. Redefining macros
86 6.7. Overriding macro values
87 6.8. Example of macro usage
88 6.9. Builtin macros
89 6.10. Conditional skips in the configuration file
90 6.11. Common option syntax
91 6.12. Boolean options
92 6.13. Integer values
93 6.14. Octal integer values
94 6.15. Fixed point numbers
95 6.16. Time intervals
96 6.17. String values
97 6.18. Expanded strings
98 6.19. User and group names
99 6.20. List construction
100 6.21. Changing list separators
101 6.22. Empty items in lists
102 6.23. Format of driver configurations
103
104 7. The default configuration file
105
106 7.1. Main configuration settings
107 7.2. ACL configuration
108 7.3. Router configuration
109 7.4. Transport configuration
110 7.5. Default retry rule
111 7.6. Rewriting configuration
112 7.7. Authenticators configuration
113
114 8. Regular expressions
115 9. File and database lookups
116
117 9.1. Examples of different lookup syntax
118 9.2. Lookup types
119 9.3. Single-key lookup types
120 9.4. Query-style lookup types
121 9.5. Temporary errors in lookups
122 9.6. Default values in single-key lookups
123 9.7. Partial matching in single-key lookups
124 9.8. Lookup caching
125 9.9. Quoting lookup data
126 9.10. More about dnsdb
127 9.11. Dnsdb lookup modifiers
128 9.12. Pseudo dnsdb record types
129 9.13. Multiple dnsdb lookups
130 9.14. More about LDAP
131 9.15. Format of LDAP queries
132 9.16. LDAP quoting
133 9.17. LDAP connections
134 9.18. LDAP authentication and control information
135 9.19. Format of data returned by LDAP
136 9.20. More about NIS+
137 9.21. SQL lookups
138 9.22. More about MySQL, PostgreSQL, Oracle, InterBase, and Redis
139 9.23. Specifying the server in the query
140 9.24. Special MySQL features
141 9.25. Special PostgreSQL features
142 9.26. More about SQLite
143 9.27. More about Redis
144
145 10. Domain, host, address, and local part lists
146
147 10.1. Expansion of lists
148 10.2. Negated items in lists
149 10.3. File names in lists
150 10.4. An lsearch file is not an out-of-line list
151 10.5. Named lists
152 10.6. Named lists compared with macros
153 10.7. Named list caching
154 10.8. Domain lists
155 10.9. Host lists
156 10.10. Special host list patterns
157 10.11. Host list patterns that match by IP address
158 10.12. Host list patterns for single-key lookups by host address
159 10.13. Host list patterns that match by host name
160 10.14. Behaviour when an IP address or name cannot be found
161 10.15. Mixing wildcarded host names and addresses in host lists
162 10.16. Temporary DNS errors when looking up host information
163 10.17. Host list patterns for single-key lookups by host name
164 10.18. Host list patterns for query-style lookups
165 10.19. Address lists
166 10.20. Case of letters in address lists
167 10.21. Local part lists
168
169 11. String expansions
170
171 11.1. Literal text in expanded strings
172 11.2. Character escape sequences in expanded strings
173 11.3. Testing string expansions
174 11.4. Forced expansion failure
175 11.5. Expansion items
176 11.6. Expansion operators
177 11.7. Expansion conditions
178 11.8. Combining expansion conditions
179 11.9. Expansion variables
180
181 12. Embedded Perl
182
183 12.1. Setting up so Perl can be used
184 12.2. Calling Perl subroutines
185 12.3. Calling Exim functions from Perl
186 12.4. Use of standard output and error by Perl
187
188 13. Starting the daemon and the use of network interfaces
189
190 13.1. Starting a listening daemon
191 13.2. Special IP listening addresses
192 13.3. Overriding local_interfaces and daemon_smtp_ports
193 13.4. Support for the obsolete SSMTP (or SMTPS) protocol
194 13.5. IPv6 address scopes
195 13.6. Disabling IPv6
196 13.7. Examples of starting a listening daemon
197 13.8. Recognizing the local host
198 13.9. Delivering to a remote host
199
200 14. Main configuration
201
202 14.1. Miscellaneous
203 14.2. Exim parameters
204 14.3. Privilege controls
205 14.4. Logging
206 14.5. Frozen messages
207 14.6. Data lookups
208 14.7. Message ids
209 14.8. Embedded Perl Startup
210 14.9. Daemon
211 14.10. Resource control
212 14.11. Policy controls
213 14.12. Callout cache
214 14.13. TLS
215 14.14. Local user handling
216 14.15. All incoming messages (SMTP and non-SMTP)
217 14.16. Non-SMTP incoming messages
218 14.17. Incoming SMTP messages
219 14.18. SMTP extensions
220 14.19. Processing messages
221 14.20. System filter
222 14.21. Routing and delivery
223 14.22. Bounce and warning messages
224 14.23. Alphabetical list of main options
225
226 15. Generic options for routers
227 16. The accept router
228 17. The dnslookup router
229
230 17.1. Problems with DNS lookups
231 17.2. Declining addresses by dnslookup
232 17.3. Private options for dnslookup
233 17.4. Effect of qualify_single and search_parents
234
235 18. The ipliteral router
236 19. The iplookup router
237 20. The manualroute router
238
239 20.1. Private options for manualroute
240 20.2. Routing rules in route_list
241 20.3. Routing rules in route_data
242 20.4. Format of the list of hosts
243 20.5. Format of one host item
244 20.6. How the list of hosts is used
245 20.7. How the options are used
246 20.8. Manualroute examples
247
248 21. The queryprogram router
249 22. The redirect router
250
251 22.1. Redirection data
252 22.2. Forward files and address verification
253 22.3. Interpreting redirection data
254 22.4. Items in a non-filter redirection list
255 22.5. Redirecting to a local mailbox
256 22.6. Special items in redirection lists
257 22.7. Duplicate addresses
258 22.8. Repeated redirection expansion
259 22.9. Errors in redirection lists
260 22.10. Private options for the redirect router
261
262 23. Environment for running local transports
263
264 23.1. Concurrent deliveries
265 23.2. Uids and gids
266 23.3. Current and home directories
267 23.4. Expansion variables derived from the address
268
269 24. Generic options for transports
270 25. Address batching in local transports
271 26. The appendfile transport
272
273 26.1. The file and directory options
274 26.2. Private options for appendfile
275 26.3. Operational details for appending
276 26.4. Operational details for delivery to a new file
277 26.5. Maildir delivery
278 26.6. Using tags to record message sizes
279 26.7. Using a maildirsize file
280 26.8. Mailstore delivery
281 26.9. Non-special new file delivery
282
283 27. The autoreply transport
284
285 27.1. Private options for autoreply
286
287 28. The lmtp transport
288 29. The pipe transport
289
290 29.1. Concurrent delivery
291 29.2. Returned status and data
292 29.3. How the command is run
293 29.4. Environment variables
294 29.5. Private options for pipe
295 29.6. Using an external local delivery agent
296
297 30. The smtp transport
298
299 30.1. Multiple messages on a single connection
300 30.2. Use of the $host and $host_address variables
301 30.3. Use of $tls_cipher and $tls_peerdn
302 30.4. Private options for smtp
303 30.5. How the limits for the number of hosts to try are used
304
305 31. Address rewriting
306
307 31.1. Explicitly configured address rewriting
308 31.2. When does rewriting happen?
309 31.3. Testing the rewriting rules that apply on input
310 31.4. Rewriting rules
311 31.5. Rewriting patterns
312 31.6. Rewriting replacements
313 31.7. Rewriting flags
314 31.8. Flags specifying which headers and envelope addresses to rewrite
315 31.9. The SMTP-time rewriting flag
316 31.10. Flags controlling the rewriting process
317 31.11. Rewriting examples
318
319 32. Retry configuration
320
321 32.1. Changing retry rules
322 32.2. Format of retry rules
323 32.3. Choosing which retry rule to use for address errors
324 32.4. Choosing which retry rule to use for host and message errors
325 32.5. Retry rules for specific errors
326 32.6. Retry rules for specified senders
327 32.7. Retry parameters
328 32.8. Retry rule examples
329 32.9. Timeout of retry data
330 32.10. Long-term failures
331 32.11. Deliveries that work intermittently
332
333 33. SMTP authentication
334
335 33.1. Generic options for authenticators
336 33.2. The AUTH parameter on MAIL commands
337 33.3. Authentication on an Exim server
338 33.4. Testing server authentication
339 33.5. Authentication by an Exim client
340
341 34. The plaintext authenticator
342
343 34.1. Plaintext options
344 34.2. Using plaintext in a server
345 34.3. The PLAIN authentication mechanism
346 34.4. The LOGIN authentication mechanism
347 34.5. Support for different kinds of authentication
348 34.6. Using plaintext in a client
349
350 35. The cram_md5 authenticator
351
352 35.1. Using cram_md5 as a server
353 35.2. Using cram_md5 as a client
354
355 36. The cyrus_sasl authenticator
356
357 36.1. Using cyrus_sasl as a server
358
359 37. The dovecot authenticator
360 38. The gsasl authenticator
361
362 38.1. gsasl auth variables
363
364 39. The heimdal_gssapi authenticator
365
366 39.1. heimdal_gssapi auth variables
367
368 40. The spa authenticator
369
370 40.1. Using spa as a server
371 40.2. Using spa as a client
372
373 41. The tls authenticator
374 42. Encrypted SMTP connections using TLS/SSL
375
376 42.1. Support for the legacy "ssmtp" (aka "smtps") protocol
377 42.2. OpenSSL vs GnuTLS
378 42.3. GnuTLS parameter computation
379 42.4. Requiring specific ciphers in OpenSSL
380 42.5. Requiring specific ciphers or other parameters in GnuTLS
381 42.6. Configuring an Exim server to use TLS
382 42.7. Requesting and verifying client certificates
383 42.8. Revoked certificates
384 42.9. Configuring an Exim client to use TLS
385 42.10. Use of TLS Server Name Indication
386 42.11. Multiple messages on the same encrypted TCP/IP connection
387 42.12. Certificates and all that
388 42.13. Certificate chains
389 42.14. Self-signed certificates
390
391 43. Access control lists
392
393 43.1. Testing ACLs
394 43.2. Specifying when ACLs are used
395 43.3. The non-SMTP ACLs
396 43.4. The SMTP connect ACL
397 43.5. The EHLO/HELO ACL
398 43.6. The DATA ACLs
399 43.7. The SMTP DKIM ACL
400 43.8. The SMTP MIME ACL
401 43.9. The SMTP PRDR ACL
402 43.10. The QUIT ACL
403 43.11. The not-QUIT ACL
404 43.12. Finding an ACL to use
405 43.13. ACL return codes
406 43.14. Unset ACL options
407 43.15. Data for message ACLs
408 43.16. Data for non-message ACLs
409 43.17. Format of an ACL
410 43.18. ACL verbs
411 43.19. ACL variables
412 43.20. Condition and modifier processing
413 43.21. ACL modifiers
414 43.22. Use of the control modifier
415 43.23. Summary of message fixup control
416 43.24. Adding header lines in ACLs
417 43.25. Removing header lines in ACLs
418 43.26. ACL conditions
419 43.27. Using DNS lists
420 43.28. Specifying the IP address for a DNS list lookup
421 43.29. DNS lists keyed on domain names
422 43.30. Multiple explicit keys for a DNS list
423 43.31. Data returned by DNS lists
424 43.32. Variables set from DNS lists
425 43.33. Additional matching conditions for DNS lists
426 43.34. Negated DNS matching conditions
427 43.35. Handling multiple DNS records from a DNS list
428 43.36. Detailed information from merged DNS lists
429 43.37. DNS lists and IPv6
430 43.38. Rate limiting incoming messages
431 43.39. Ratelimit options for what is being measured
432 43.40. Ratelimit update modes
433 43.41. Ratelimit options for handling fast clients
434 43.42. Limiting the rate of different events
435 43.43. Using rate limiting
436 43.44. Address verification
437 43.45. Callout verification
438 43.46. Additional parameters for callouts
439 43.47. Callout caching
440 43.48. Sender address verification reporting
441 43.49. Redirection while verifying
442 43.50. Client SMTP authorization (CSA)
443 43.51. Bounce address tag validation
444 43.52. Using an ACL to control relaying
445 43.53. Checking a relay configuration
446
447 44. Content scanning at ACL time
448
449 44.1. Scanning for viruses
450 44.2. Scanning with SpamAssassin and Rspamd
451 44.3. Calling SpamAssassin from an Exim ACL
452 44.4. Scanning MIME parts
453 44.5. Scanning with regular expressions
454
455 45. Adding a local scan function to Exim
456
457 45.1. Building Exim to use a local scan function
458 45.2. API for local_scan()
459 45.3. Configuration options for local_scan()
460 45.4. Available Exim variables
461 45.5. Structure of header lines
462 45.6. Structure of recipient items
463 45.7. Available Exim functions
464 45.8. More about Exim's memory handling
465
466 46. System-wide message filtering
467
468 46.1. Specifying a system filter
469 46.2. Testing a system filter
470 46.3. Contents of a system filter
471 46.4. Additional variable for system filters
472 46.5. Defer, freeze, and fail commands for system filters
473 46.6. Adding and removing headers in a system filter
474 46.7. Setting an errors address in a system filter
475 46.8. Per-address filtering
476
477 47. Message processing
478
479 47.1. Submission mode for non-local messages
480 47.2. Line endings
481 47.3. Unqualified addresses
482 47.4. The UUCP From line
483 47.5. Resent- header lines
484 47.6. The Auto-Submitted: header line
485 47.7. The Bcc: header line
486 47.8. The Date: header line
487 47.9. The Delivery-date: header line
488 47.10. The Envelope-to: header line
489 47.11. The From: header line
490 47.12. The Message-ID: header line
491 47.13. The Received: header line
492 47.14. The References: header line
493 47.15. The Return-path: header line
494 47.16. The Sender: header line
495 47.17. Adding and removing header lines in routers and transports
496 47.18. Constructed addresses
497 47.19. Case of local parts
498 47.20. Dots in local parts
499 47.21. Rewriting addresses
500
501 48. SMTP processing
502
503 48.1. Outgoing SMTP and LMTP over TCP/IP
504 48.2. Errors in outgoing SMTP
505 48.3. Incoming SMTP messages over TCP/IP
506 48.4. Unrecognized SMTP commands
507 48.5. Syntax and protocol errors in SMTP commands
508 48.6. Use of non-mail SMTP commands
509 48.7. The VRFY and EXPN commands
510 48.8. The ETRN command
511 48.9. Incoming local SMTP
512 48.10. Outgoing batched SMTP
513 48.11. Incoming batched SMTP
514
515 49. Customizing bounce and warning messages
516
517 49.1. Customizing bounce messages
518 49.2. Customizing warning messages
519
520 50. Some common configuration settings
521
522 50.1. Sending mail to a smart host
523 50.2. Using Exim to handle mailing lists
524 50.3. Syntax errors in mailing lists
525 50.4. Re-expansion of mailing lists
526 50.5. Closed mailing lists
527 50.6. Variable Envelope Return Paths (VERP)
528 50.7. Virtual domains
529 50.8. Multiple user mailboxes
530 50.9. Simplified vacation processing
531 50.10. Taking copies of mail
532 50.11. Intermittently connected hosts
533 50.12. Exim on the upstream server host
534 50.13. Exim on the intermittently connected client host
535
536 51. Using Exim as a non-queueing client
537 52. Log files
538
539 52.1. Where the logs are written
540 52.2. Logging to local files that are periodically "cycled"
541 52.3. Datestamped log files
542 52.4. Logging to syslog
543 52.5. Log line flags
544 52.6. Logging message reception
545 52.7. Logging deliveries
546 52.8. Discarded deliveries
547 52.9. Deferred deliveries
548 52.10. Delivery failures
549 52.11. Fake deliveries
550 52.12. Completion
551 52.13. Summary of Fields in Log Lines
552 52.14. Other log entries
553 52.15. Reducing or increasing what is logged
554 52.16. Message log
555
556 53. Exim utilities
557
558 53.1. Finding out what Exim processes are doing (exiwhat)
559 53.2. Selective queue listing (exiqgrep)
560 53.3. Summarizing the queue (exiqsumm)
561 53.4. Extracting specific information from the log (exigrep)
562 53.5. Selecting messages by various criteria (exipick)
563 53.6. Cycling log files (exicyclog)
564 53.7. Mail statistics (eximstats)
565 53.8. Checking access policy (exim_checkaccess)
566 53.9. Making DBM files (exim_dbmbuild)
567 53.10. Finding individual retry times (exinext)
568 53.11. Hints database maintenance
569 53.12. exim_dumpdb
570 53.13. exim_tidydb
571 53.14. exim_fixdb
572 53.15. Mailbox maintenance (exim_lock)
573
574 54. The Exim monitor
575
576 54.1. Running the monitor
577 54.2. The stripcharts
578 54.3. Main action buttons
579 54.4. The log display
580 54.5. The queue display
581 54.6. The queue menu
582
583 55. Security considerations
584
585 55.1. Building a more "hardened" Exim
586 55.2. Root privilege
587 55.3. Running Exim without privilege
588 55.4. Delivering to local files
589 55.5. Running local commands
590 55.6. Trust in configuration data
591 55.7. IPv4 source routing
592 55.8. The VRFY, EXPN, and ETRN commands in SMTP
593 55.9. Privileged users
594 55.10. Spool files
595 55.11. Use of argv[0]
596 55.12. Use of %f formatting
597 55.13. Embedded Exim path
598 55.14. Dynamic module directory
599 55.15. Use of sprintf()
600 55.16. Use of debug_printf() and log_write()
601 55.17. Use of strcat() and strcpy()
602
603 56. Format of spool files
604
605 56.1. Format of the -H file
606
607 57. Support for DKIM (DomainKeys Identified Mail)
608
609 57.1. Signing outgoing messages
610 57.2. Verifying DKIM signatures in incoming mail
611
612 58. Proxies
613
614 58.1. Inbound proxies
615 58.2. Outbound proxies
616 58.3. Logging
617
618 59. Internationalisation
619
620 59.1. MTA operations
621 59.2. MDA operations
622
623 60. Events
624 61. Adding new drivers or lookup types
625
626
627
628 ===============================================================================
629 1. INTRODUCTION
630
631 Exim is a mail transfer agent (MTA) for hosts that are running Unix or
632 Unix-like operating systems. It was designed on the assumption that it would be
633 run on hosts that are permanently connected to the Internet. However, it can be
634 used on intermittently connected hosts with suitable configuration adjustments.
635
636 Configuration files currently exist for the following operating systems: AIX,
637 BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, Dragonfly, FreeBSD, GNU/Hurd, GNU/
638 Linux, HI-OSF (Hitachi), HI-UX, HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD,
639 OpenUNIX, QNX, SCO, SCO SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4,
640 Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware.
641 Some of these operating systems are no longer current and cannot easily be
642 tested, so the configuration files may no longer work in practice.
643
644 There are also configuration files for compiling Exim in the Cygwin environment
645 that can be installed on systems running Windows. However, this document does
646 not contain any information about running Exim in the Cygwin environment.
647
648 The terms and conditions for the use and distribution of Exim are contained in
649 the file NOTICE. Exim is distributed under the terms of the GNU General Public
650 Licence, a copy of which may be found in the file LICENCE.
651
652 The use, supply or promotion of Exim for the purpose of sending bulk,
653 unsolicited electronic mail is incompatible with the basic aims of the program,
654 which revolve around the free provision of a service that enhances the quality
655 of personal communications. The author of Exim regards indiscriminate
656 mass-mailing as an antisocial, irresponsible abuse of the Internet.
657
658 Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the
659 experience of running and working on the Smail 3 code, I could never have
660 contemplated starting to write a new MTA. Many of the ideas and user interfaces
661 were originally taken from Smail 3, though the actual code of Exim is entirely
662 new, and has developed far beyond the initial concept.
663
664 Many people, both in Cambridge and around the world, have contributed to the
665 development and the testing of Exim, and to porting it to various operating
666 systems. I am grateful to them all. The distribution now contains a file called
667 ACKNOWLEDGMENTS, in which I have started recording the names of contributors.
668
669
670 1.1 Exim documentation
671 ----------------------
672
673 This edition of the Exim specification applies to version 4.89 of Exim.
674 Substantive changes from the 4.88 edition are marked in some renditions of the
675 document; this paragraph is so marked if the rendition is capable of showing a
676 change indicator.
677
678 This document is very much a reference manual; it is not a tutorial. The reader
679 is expected to have some familiarity with the SMTP mail transfer protocol and
680 with general Unix system administration. Although there are some discussions
681 and examples in places, the information is mostly organized in a way that makes
682 it easy to look up, rather than in a natural order for sequential reading.
683 Furthermore, the manual aims to cover every aspect of Exim in detail, including
684 a number of rarely-used, special-purpose features that are unlikely to be of
685 very wide interest.
686
687 An "easier" discussion of Exim which provides more in-depth explanatory,
688 introductory, and tutorial material can be found in a book entitled The Exim
689 SMTP Mail Server (second edition, 2007), published by UIT Cambridge (http://
690 www.uit.co.uk/exim-book/).
691
692 This book also contains a chapter that gives a general introduction to SMTP and
693 Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date
694 with the latest release of Exim. (Note that the earlier book about Exim,
695 published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.)
696
697 If you are using a Debian distribution of Exim, you will find information about
698 Debian-specific features in the file /usr/share/doc/exim4-base/README.Debian.
699 The command man update-exim.conf is another source of Debian-specific
700 information.
701
702 As the program develops, there may be features in newer versions that have not
703 yet made it into this document, which is updated only when the most significant
704 digit of the fractional part of the version number changes. Specifications of
705 new features that are not yet in this manual are placed in the file doc/
706 NewStuff in the Exim distribution.
707
708 Some features may be classified as "experimental". These may change
709 incompatibly while they are developing, or even be withdrawn. For this reason,
710 they are not documented in this manual. Information about experimental features
711 can be found in the file doc/experimental.txt.
712
713 All changes to the program (whether new features, bug fixes, or other kinds of
714 change) are noted briefly in the file called doc/ChangeLog.
715
716 This specification itself is available as an ASCII file in doc/spec.txt so that
717 it can easily be searched with a text editor. Other files in the doc directory
718 are:
719
720 OptionLists.txt list of all options in alphabetical order
721 dbm.discuss.txt discussion about DBM libraries
722 exim.8 a man page of Exim's command line options
723 experimental.txt documentation of experimental features
724 filter.txt specification of the filter language
725 Exim3.upgrade upgrade notes from release 2 to release 3
726 Exim4.upgrade upgrade notes from release 3 to release 4
727 openssl.txt installing a current OpenSSL release
728
729 The main specification and the specification of the filtering language are also
730 available in other formats (HTML, PostScript, PDF, and Texinfo). Section 1.6
731 below tells you how to get hold of these.
732
733
734 1.2 FTP and web sites
735 ---------------------
736
737 The primary site for Exim source distributions is currently the University of
738 Cambridge's FTP site, whose contents are described in Where to find the Exim
739 distribution below. In addition, there is a web site and an FTP site at
740 exim.org. These are now also hosted at the University of Cambridge. The
741 exim.org site was previously hosted for a number of years by Energis Squared,
742 formerly Planet Online Ltd, whose support I gratefully acknowledge.
743
744 As well as Exim distribution tar files, the Exim web site contains a number of
745 differently formatted versions of the documentation. A recent addition to the
746 online information is the Exim wiki (http://wiki.exim.org), which contains what
747 used to be a separate FAQ, as well as various other examples, tips, and
748 know-how that have been contributed by Exim users.
749
750 An Exim Bugzilla exists at http://bugs.exim.org. You can use this to report
751 bugs, and also to add items to the wish list. Please search first to check that
752 you are not duplicating a previous entry.
753
754
755 1.3 Mailing lists
756 -----------------
757
758 The following Exim mailing lists exist:
759
760 exim-announce@exim.org Moderated, low volume announcements list
761 exim-users@exim.org General discussion list
762 exim-dev@exim.org Discussion of bugs, enhancements, etc.
763 exim-cvs@exim.org Automated commit messages from the VCS
764
765 You can subscribe to these lists, change your existing subscriptions, and view
766 or search the archives via the mailing lists link on the Exim home page. If you
767 are using a Debian distribution of Exim, you may wish to subscribe to the
768 Debian-specific mailing list pkg-exim4-users@lists.alioth.debian.org via this
769 web page:
770
771 http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-users
772
773 Please ask Debian-specific questions on this list and not on the general Exim
774 lists.
775
776
777 1.4 Exim training
778 -----------------
779
780 Training courses in Cambridge (UK) used to be run annually by the author of
781 Exim, before he retired. At the time of writing, there are no plans to run
782 further Exim courses in Cambridge. However, if that changes, relevant
783 information will be posted at http://www-tus.csx.cam.ac.uk/courses/exim/.
784
785
786 1.5 Bug reports
787 ---------------
788
789 Reports of obvious bugs can be emailed to bugs@exim.org or reported via the
790 Bugzilla (http://bugs.exim.org). However, if you are unsure whether some
791 behaviour is a bug or not, the best thing to do is to post a message to the
792 exim-dev mailing list and have it discussed.
793
794
795 1.6 Where to find the Exim distribution
796 ---------------------------------------
797
798 The master ftp site for the Exim distribution is
799
800 ftp://ftp.csx.cam.ac.uk/pub/software/email/exim
801
802 This is mirrored by
803
804 ftp://ftp.exim.org/pub/exim
805
806 The file references that follow are relative to the exim directories at these
807 sites. There are now quite a number of independent mirror sites around the
808 world. Those that I know about are listed in the file called Mirrors.
809
810 Within the exim directory there are subdirectories called exim3 (for previous
811 Exim 3 distributions), exim4 (for the latest Exim 4 distributions), and Testing
812 for testing versions. In the exim4 subdirectory, the current release can always
813 be found in files called
814
815 exim-n.nn.tar.gz
816 exim-n.nn.tar.bz2
817
818 where n.nn is the highest such version number in the directory. The two files
819 contain identical data; the only difference is the type of compression. The
820 .bz2 file is usually a lot smaller than the .gz file.
821
822 The distributions will be PGP signed by an individual key of the Release
823 Coordinator. This key will have a uid containing an email address in the
824 exim.org domain and will have signatures from other people, including other
825 Exim maintainers. We expect that the key will be in the "strong set" of PGP
826 keys. There should be a trust path to that key from Nigel Metheringham's PGP
827 key, a version of which can be found in the release directory in the file
828 nigel-pubkey.asc. All keys used will be available in public keyserver pools,
829 such as pool.sks-keyservers.net.
830
831 At time of last update, releases were being made by Phil Pennock and signed
832 with key 0x403043153903637F, although that key is expected to be replaced in
833 2013. A trust path from Nigel's key to Phil's can be observed at https://
834 www.security.spodhuis.org/exim-trustpath.
835
836 Releases have also been authorized to be performed by Todd Lyons who signs with
837 key 0xC4F4F94804D29EBA. A direct trust path exists between previous RE Phil
838 Pennock and Todd Lyons through a common associate.
839
840 The signatures for the tar bundles are in:
841
842 exim-n.nn.tar.gz.asc
843 exim-n.nn.tar.bz2.asc
844
845 For each released version, the log of changes is made separately available in a
846 separate file in the directory ChangeLogs so that it is possible to find out
847 what has changed without having to download the entire distribution.
848
849 The main distribution contains ASCII versions of this specification and other
850 documentation; other formats of the documents are available in separate files
851 inside the exim4 directory of the FTP site:
852
853 exim-html-n.nn.tar.gz
854 exim-pdf-n.nn.tar.gz
855 exim-postscript-n.nn.tar.gz
856 exim-texinfo-n.nn.tar.gz
857
858 These tar files contain only the doc directory, not the complete distribution,
859 and are also available in .bz2 as well as .gz forms.
860
861
862 1.7 Limitations
863 ---------------
864
865 * Exim is designed for use as an Internet MTA, and therefore handles
866 addresses in RFC 2822 domain format only. It cannot handle UUCP "bang
867 paths", though simple two-component bang paths can be converted by a
868 straightforward rewriting configuration. This restriction does not prevent
869 Exim from being interfaced to UUCP as a transport mechanism, provided that
870 domain addresses are used.
871
872 * Exim insists that every address it handles has a domain attached. For
873 incoming local messages, domainless addresses are automatically qualified
874 with a configured domain value. Configuration options specify from which
875 remote systems unqualified addresses are acceptable. These are then
876 qualified on arrival.
877
878 * The only external transport mechanisms that are currently implemented are
879 SMTP and LMTP over a TCP/IP network (including support for IPv6). However,
880 a pipe transport is available, and there are facilities for writing
881 messages to files and pipes, optionally in batched SMTP format; these
882 facilities can be used to send messages to other transport mechanisms such
883 as UUCP, provided they can handle domain-style addresses. Batched SMTP
884 input is also catered for.
885
886 * Exim is not designed for storing mail for dial-in hosts. When the volumes
887 of such mail are large, it is better to get the messages "delivered" into
888 files (that is, off Exim's queue) and subsequently passed on to the dial-in
889 hosts by other means.
890
891 * Although Exim does have basic facilities for scanning incoming messages,
892 these are not comprehensive enough to do full virus or spam scanning. Such
893 operations are best carried out using additional specialized software
894 packages. If you compile Exim with the content-scanning extension,
895 straightforward interfaces to a number of common scanners are provided.
896
897
898 1.8 Run time configuration
899 --------------------------
900
901 Exim's run time configuration is held in a single text file that is divided
902 into a number of sections. The entries in this file consist of keywords and
903 values, in the style of Smail 3 configuration files. A default configuration
904 file which is suitable for simple online installations is provided in the
905 distribution, and is described in chapter 7 below.
906
907
908 1.9 Calling interface
909 ---------------------
910
911 Like many MTAs, Exim has adopted the Sendmail command line interface so that it
912 can be a straight replacement for /usr/lib/sendmail or /usr/sbin/sendmail when
913 sending mail, but you do not need to know anything about Sendmail in order to
914 run Exim. For actions other than sending messages, Sendmail-compatible options
915 also exist, but those that produce output (for example, -bp, which lists the
916 messages on the queue) do so in Exim's own format. There are also some
917 additional options that are compatible with Smail 3, and some further options
918 that are new to Exim. Chapter 5 documents all Exim's command line options. This
919 information is automatically made into the man page that forms part of the Exim
920 distribution.
921
922 Control of messages on the queue can be done via certain privileged command
923 line options. There is also an optional monitor program called eximon, which
924 displays current information in an X window, and which contains a menu
925 interface to Exim's command line administration options.
926
927
928 1.10 Terminology
929 ----------------
930
931 The body of a message is the actual data that the sender wants to transmit. It
932 is the last part of a message, and is separated from the header (see below) by
933 a blank line.
934
935 When a message cannot be delivered, it is normally returned to the sender in a
936 delivery failure message or a "non-delivery report" (NDR). The term bounce is
937 commonly used for this action, and the error reports are often called bounce
938 messages. This is a convenient shorthand for "delivery failure error report".
939 Such messages have an empty sender address in the message's envelope (see
940 below) to ensure that they cannot themselves give rise to further bounce
941 messages.
942
943 The term default appears frequently in this manual. It is used to qualify a
944 value which is used in the absence of any setting in the configuration. It may
945 also qualify an action which is taken unless a configuration setting specifies
946 otherwise.
947
948 The term defer is used when the delivery of a message to a specific destination
949 cannot immediately take place for some reason (a remote host may be down, or a
950 user's local mailbox may be full). Such deliveries are deferred until a later
951 time.
952
953 The word domain is sometimes used to mean all but the first component of a
954 host's name. It is not used in that sense here, where it normally refers to the
955 part of an email address following the @ sign.
956
957 A message in transit has an associated envelope, as well as a header and a
958 body. The envelope contains a sender address (to which bounce messages should
959 be delivered), and any number of recipient addresses. References to the sender
960 or the recipients of a message usually mean the addresses in the envelope. An
961 MTA uses these addresses for delivery, and for returning bounce messages, not
962 the addresses that appear in the header lines.
963
964 The header of a message is the first part of a message's text, consisting of a
965 number of lines, each of which has a name such as From:, To:, Subject:, etc.
966 Long header lines can be split over several text lines by indenting the
967 continuations. The header is separated from the body by a blank line.
968
969 The term local part, which is taken from RFC 2822, is used to refer to that
970 part of an email address that precedes the @ sign. The part that follows the @
971 sign is called the domain or mail domain.
972
973 The terms local delivery and remote delivery are used to distinguish delivery
974 to a file or a pipe on the local host from delivery by SMTP over TCP/IP to
975 another host. As far as Exim is concerned, all hosts other than the host it is
976 running on are remote.
977
978 Return path is another name that is used for the sender address in a message's
979 envelope.
980
981 The term queue is used to refer to the set of messages awaiting delivery,
982 because this term is in widespread use in the context of MTAs. However, in
983 Exim's case the reality is more like a pool than a queue, because there is
984 normally no ordering of waiting messages.
985
986 The term queue runner is used to describe a process that scans the queue and
987 attempts to deliver those messages whose retry times have come. This term is
988 used by other MTAs, and also relates to the command runq, but in Exim the
989 waiting messages are normally processed in an unpredictable order.
990
991 The term spool directory is used for a directory in which Exim keeps the
992 messages on its queue - that is, those that it is in the process of delivering.
993 This should not be confused with the directory in which local mailboxes are
994 stored, which is called a "spool directory" by some people. In the Exim
995 documentation, "spool" is always used in the first sense.
996
997
998
999 ===============================================================================
1000 2. INCORPORATED CODE
1001
1002 A number of pieces of external code are included in the Exim distribution.
1003
1004 * Regular expressions are supported in the main Exim program and in the Exim
1005 monitor using the freely-distributable PCRE library, copyright (c)
1006 University of Cambridge. The source to PCRE is no longer shipped with Exim,
1007 so you will need to use the version of PCRE shipped with your system, or
1008 obtain and install the full version of the library from ftp://
1009 ftp.csx.cam.ac.uk/pub/software/programming/pcre.
1010
1011 * Support for the cdb (Constant DataBase) lookup method is provided by code
1012 contributed by Nigel Metheringham of (at the time he contributed it) Planet
1013 Online Ltd. The implementation is completely contained within the code of
1014 Exim. It does not link against an external cdb library. The code contains
1015 the following statements:
1016
1017 Copyright (c) 1998 Nigel Metheringham, Planet Online Ltd
1018
1019 This program is free software; you can redistribute it and/or modify it
1020 under the terms of the GNU General Public License as published by the
1021 Free Software Foundation; either version 2 of the License, or (at your
1022 option) any later version. This code implements Dan Bernstein's
1023 Constant DataBase (cdb) spec. Information, the spec and sample code for
1024 cdb can be obtained from http://www.pobox.com/~djb/cdb.html. This
1025 implementation borrows some code from Dan Bernstein's implementation
1026 (which has no license restrictions applied to it).
1027
1028 * Client support for Microsoft's Secure Password Authentication is provided
1029 by code contributed by Marc Prud'hommeaux. Server support was contributed
1030 by Tom Kistner. This includes code taken from the Samba project, which is
1031 released under the Gnu GPL.
1032
1033 * Support for calling the Cyrus pwcheck and saslauthd daemons is provided by
1034 code taken from the Cyrus-SASL library and adapted by Alexander S.
1035 Sabourenkov. The permission notice appears below, in accordance with the
1036 conditions expressed therein.
1037
1038 Copyright (c) 2001 Carnegie Mellon University. All rights reserved.
1039
1040 Redistribution and use in source and binary forms, with or without
1041 modification, are permitted provided that the following conditions are
1042 met:
1043
1044 1. Redistributions of source code must retain the above copyright
1045 notice, this list of conditions and the following disclaimer.
1046
1047 2. Redistributions in binary form must reproduce the above copyright
1048 notice, this list of conditions and the following disclaimer in the
1049 documentation and/or other materials provided with the
1050 distribution.
1051
1052 3. The name "Carnegie Mellon University" must not be used to endorse
1053 or promote products derived from this software without prior
1054 written permission. For permission or any other legal details,
1055 please contact
1056
1057 Office of Technology Transfer
1058 Carnegie Mellon University
1059 5000 Forbes Avenue
1060 Pittsburgh, PA 15213-3890
1061 (412) 268-4387, fax: (412) 268-7395
1062 tech-transfer@andrew.cmu.edu
1063
1064 4. Redistributions of any form whatsoever must retain the following
1065 acknowledgment:
1066
1067 "This product includes software developed by Computing Services at
1068 Carnegie Mellon University (http://www.cmu.edu/computing/."
1069
1070 CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO
1071 THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
1072 AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE
1073 FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
1074 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
1075 AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
1076 OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
1077 SOFTWARE.
1078
1079 * The Exim Monitor program, which is an X-Window application, includes
1080 modified versions of the Athena StripChart and TextPop widgets. This code
1081 is copyright by DEC and MIT, and their permission notice appears below, in
1082 accordance with the conditions expressed therein.
1083
1084 Copyright 1987, 1988 by Digital Equipment Corporation, Maynard,
1085 Massachusetts, and the Massachusetts Institute of Technology,
1086 Cambridge, Massachusetts.
1087
1088 All Rights Reserved
1089
1090 Permission to use, copy, modify, and distribute this software and its
1091 documentation for any purpose and without fee is hereby granted,
1092 provided that the above copyright notice appear in all copies and that
1093 both that copyright notice and this permission notice appear in
1094 supporting documentation, and that the names of Digital or MIT not be
1095 used in advertising or publicity pertaining to distribution of the
1096 software without specific, written prior permission.
1097
1098 DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
1099 INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
1100 EVENT SHALL DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR
1101 CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
1102 USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
1103 OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
1104 PERFORMANCE OF THIS SOFTWARE.
1105
1106 * The DMARC implementation uses the OpenDMARC library which is Copyrighted by
1107 The Trusted Domain Project. Portions of Exim source which use OpenDMARC
1108 derived code are indicated in the respective source files. The full
1109 OpenDMARC license is provided in the LICENSE.opendmarc file contained in
1110 the distributed source code.
1111
1112 * Many people have contributed code fragments, some large, some small, that
1113 were not covered by any specific licence requirements. It is assumed that
1114 the contributors are happy to see their code incorporated into Exim under
1115 the GPL.
1116
1117
1118
1119 ===============================================================================
1120 3. HOW EXIM RECEIVES AND DELIVERS MAIL
1121
1122
1123 3.1 Overall philosophy
1124 ----------------------
1125
1126 Exim is designed to work efficiently on systems that are permanently connected
1127 to the Internet and are handling a general mix of mail. In such circumstances,
1128 most messages can be delivered immediately. Consequently, Exim does not
1129 maintain independent queues of messages for specific domains or hosts, though
1130 it does try to send several messages in a single SMTP connection after a host
1131 has been down, and it also maintains per-host retry information.
1132
1133
1134 3.2 Policy control
1135 ------------------
1136
1137 Policy controls are now an important feature of MTAs that are connected to the
1138 Internet. Perhaps their most important job is to stop MTAs being abused as
1139 "open relays" by misguided individuals who send out vast amounts of unsolicited
1140 junk, and want to disguise its source. Exim provides flexible facilities for
1141 specifying policy controls on incoming mail:
1142
1143 * Exim 4 (unlike previous versions of Exim) implements policy controls on
1144 incoming mail by means of Access Control Lists (ACLs). Each list is a
1145 series of statements that may either grant or deny access. ACLs can be used
1146 at several places in the SMTP dialogue while receiving a message from a
1147 remote host. However, the most common places are after each RCPT command,
1148 and at the very end of the message. The sysadmin can specify conditions for
1149 accepting or rejecting individual recipients or the entire message,
1150 respectively, at these two points (see chapter 43). Denial of access
1151 results in an SMTP error code.
1152
1153 * An ACL is also available for locally generated, non-SMTP messages. In this
1154 case, the only available actions are to accept or deny the entire message.
1155
1156 * When Exim is compiled with the content-scanning extension, facilities are
1157 provided in the ACL mechanism for passing the message to external virus and
1158 /or spam scanning software. The result of such a scan is passed back to the
1159 ACL, which can then use it to decide what to do with the message.
1160
1161 * When a message has been received, either from a remote host or from the
1162 local host, but before the final acknowledgment has been sent, a locally
1163 supplied C function called local_scan() can be run to inspect the message
1164 and decide whether to accept it or not (see chapter 45). If the message is
1165 accepted, the list of recipients can be modified by the function.
1166
1167 * Using the local_scan() mechanism is another way of calling external scanner
1168 software. The SA-Exim add-on package works this way. It does not require
1169 Exim to be compiled with the content-scanning extension.
1170
1171 * After a message has been accepted, a further checking mechanism is
1172 available in the form of the system filter (see chapter 46). This runs at
1173 the start of every delivery process.
1174
1175
1176 3.3 User filters
1177 ----------------
1178
1179 In a conventional Exim configuration, users are able to run private filters by
1180 setting up appropriate .forward files in their home directories. See chapter 22
1181 (about the redirect router) for the configuration needed to support this, and
1182 the separate document entitled Exim's interfaces to mail filtering for user
1183 details. Two different kinds of filtering are available:
1184
1185 * Sieve filters are written in the standard filtering language that is
1186 defined by RFC 3028.
1187
1188 * Exim filters are written in a syntax that is unique to Exim, but which is
1189 more powerful than Sieve, which it pre-dates.
1190
1191 User filters are run as part of the routing process, described below.
1192
1193
1194 3.4 Message identification
1195 --------------------------
1196
1197 Every message handled by Exim is given a message id which is sixteen characters
1198 long. It is divided into three parts, separated by hyphens, for example
1199 "16VDhn-0001bo-D3". Each part is a sequence of letters and digits, normally
1200 encoding numbers in base 62. However, in the Darwin operating system (Mac OS X)
1201 and when Exim is compiled to run under Cygwin, base 36 (avoiding the use of
1202 lower case letters) is used instead, because the message id is used to
1203 construct file names, and the names of files in those systems are not always
1204 case-sensitive.
1205
1206 The detail of the contents of the message id have changed as Exim has evolved.
1207 Earlier versions relied on the operating system not re-using a process id (pid)
1208 within one second. On modern operating systems, this assumption can no longer
1209 be made, so the algorithm had to be changed. To retain backward compatibility,
1210 the format of the message id was retained, which is why the following rules are
1211 somewhat eccentric:
1212
1213 * The first six characters of the message id are the time at which the
1214 message started to be received, to a granularity of one second. That is,
1215 this field contains the number of seconds since the start of the epoch (the
1216 normal Unix way of representing the date and time of day).
1217
1218 * After the first hyphen, the next six characters are the id of the process
1219 that received the message.
1220
1221 * There are two different possibilities for the final two characters:
1222
1223 1. If localhost_number is not set, this value is the fractional part of
1224 the time of reception, normally in units of 1/2000 of a second, but for
1225 systems that must use base 36 instead of base 62 (because of
1226 case-insensitive file systems), the units are 1/1000 of a second.
1227
1228 2. If localhost_number is set, it is multiplied by 200 (100) and added to
1229 the fractional part of the time, which in this case is in units of 1/
1230 200 (1/100) of a second.
1231
1232 After a message has been received, Exim waits for the clock to tick at the
1233 appropriate resolution before proceeding, so that if another message is
1234 received by the same process, or by another process with the same (re-used)
1235 pid, it is guaranteed that the time will be different. In most cases, the clock
1236 will already have ticked while the message was being received.
1237
1238
1239 3.5 Receiving mail
1240 ------------------
1241
1242 The only way Exim can receive mail from another host is using SMTP over TCP/IP,
1243 in which case the sender and recipient addresses are transferred using SMTP
1244 commands. However, from a locally running process (such as a user's MUA), there
1245 are several possibilities:
1246
1247 * If the process runs Exim with the -bm option, the message is read
1248 non-interactively (usually via a pipe), with the recipients taken from the
1249 command line, or from the body of the message if -t is also used.
1250
1251 * If the process runs Exim with the -bS option, the message is also read
1252 non-interactively, but in this case the recipients are listed at the start
1253 of the message in a series of SMTP RCPT commands, terminated by a DATA
1254 command. This is so-called "batch SMTP" format, but it isn't really SMTP.
1255 The SMTP commands are just another way of passing envelope addresses in a
1256 non-interactive submission.
1257
1258 * If the process runs Exim with the -bs option, the message is read
1259 interactively, using the SMTP protocol. A two-way pipe is normally used for
1260 passing data between the local process and the Exim process. This is "real"
1261 SMTP and is handled in the same way as SMTP over TCP/IP. For example, the
1262 ACLs for SMTP commands are used for this form of submission.
1263
1264 * A local process may also make a TCP/IP call to the host's loopback address
1265 (127.0.0.1) or any other of its IP addresses. When receiving messages, Exim
1266 does not treat the loopback address specially. It treats all such
1267 connections in the same way as connections from other hosts.
1268
1269 In the three cases that do not involve TCP/IP, the sender address is
1270 constructed from the login name of the user that called Exim and a default
1271 qualification domain (which can be set by the qualify_domain configuration
1272 option). For local or batch SMTP, a sender address that is passed using the
1273 SMTP MAIL command is ignored. However, the system administrator may allow
1274 certain users ("trusted users") to specify a different sender address
1275 unconditionally, or all users to specify certain forms of different sender
1276 address. The -f option or the SMTP MAIL command is used to specify these
1277 different addresses. See section 5.2 for details of trusted users, and the
1278 untrusted_set_sender option for a way of allowing untrusted users to change
1279 sender addresses.
1280
1281 Messages received by either of the non-interactive mechanisms are subject to
1282 checking by the non-SMTP ACL, if one is defined. Messages received using SMTP
1283 (either over TCP/IP, or interacting with a local process) can be checked by a
1284 number of ACLs that operate at different times during the SMTP session. Either
1285 individual recipients, or the entire message, can be rejected if local policy
1286 requirements are not met. The local_scan() function (see chapter 45) is run for
1287 all incoming messages.
1288
1289 Exim can be configured not to start a delivery process when a message is
1290 received; this can be unconditional, or depend on the number of incoming SMTP
1291 connections or the system load. In these situations, new messages wait on the
1292 queue until a queue runner process picks them up. However, in standard
1293 configurations under normal conditions, delivery is started as soon as a
1294 message is received.
1295
1296
1297 3.6 Handling an incoming message
1298 --------------------------------
1299
1300 When Exim accepts a message, it writes two files in its spool directory. The
1301 first contains the envelope information, the current status of the message, and
1302 the header lines, and the second contains the body of the message. The names of
1303 the two spool files consist of the message id, followed by "-H" for the file
1304 containing the envelope and header, and "-D" for the data file.
1305
1306 By default all these message files are held in a single directory called input
1307 inside the general Exim spool directory. Some operating systems do not perform
1308 very well if the number of files in a directory gets large; to improve
1309 performance in such cases, the split_spool_directory option can be used. This
1310 causes Exim to split up the input files into 62 sub-directories whose names are
1311 single letters or digits. When this is done, the queue is processed one
1312 sub-directory at a time instead of all at once, which can improve overall
1313 performance even when there are not enough files in each directory to affect
1314 file system performance.
1315
1316 The envelope information consists of the address of the message's sender and
1317 the addresses of the recipients. This information is entirely separate from any
1318 addresses contained in the header lines. The status of the message includes a
1319 list of recipients who have already received the message. The format of the
1320 first spool file is described in chapter 56.
1321
1322 Address rewriting that is specified in the rewrite section of the configuration
1323 (see chapter 31) is done once and for all on incoming addresses, both in the
1324 header lines and the envelope, at the time the message is accepted. If during
1325 the course of delivery additional addresses are generated (for example, via
1326 aliasing), these new addresses are rewritten as soon as they are generated. At
1327 the time a message is actually delivered (transported) further rewriting can
1328 take place; because this is a transport option, it can be different for
1329 different forms of delivery. It is also possible to specify the addition or
1330 removal of certain header lines at the time the message is delivered (see
1331 chapters 15 and 24).
1332
1333
1334 3.7 Life of a message
1335 ---------------------
1336
1337 A message remains in the spool directory until it is completely delivered to
1338 its recipients or to an error address, or until it is deleted by an
1339 administrator or by the user who originally created it. In cases when delivery
1340 cannot proceed - for example, when a message can neither be delivered to its
1341 recipients nor returned to its sender, the message is marked "frozen" on the
1342 spool, and no more deliveries are attempted.
1343
1344 An administrator can "thaw" such messages when the problem has been corrected,
1345 and can also freeze individual messages by hand if necessary. In addition, an
1346 administrator can force a delivery error, causing a bounce message to be sent.
1347
1348 There are options called ignore_bounce_errors_after and timeout_frozen_after,
1349 which discard frozen messages after a certain time. The first applies only to
1350 frozen bounces, the second to any frozen messages.
1351
1352 While Exim is working on a message, it writes information about each delivery
1353 attempt to its main log file. This includes successful, unsuccessful, and
1354 delayed deliveries for each recipient (see chapter 52). The log lines are also
1355 written to a separate message log file for each message. These logs are solely
1356 for the benefit of the administrator, and are normally deleted along with the
1357 spool files when processing of a message is complete. The use of individual
1358 message logs can be disabled by setting no_message_logs; this might give an
1359 improvement in performance on very busy systems.
1360
1361 All the information Exim itself needs to set up a delivery is kept in the first
1362 spool file, along with the header lines. When a successful delivery occurs, the
1363 address is immediately written at the end of a journal file, whose name is the
1364 message id followed by "-J". At the end of a delivery run, if there are some
1365 addresses left to be tried again later, the first spool file (the "-H" file) is
1366 updated to indicate which these are, and the journal file is then deleted.
1367 Updating the spool file is done by writing a new file and renaming it, to
1368 minimize the possibility of data loss.
1369
1370 Should the system or the program crash after a successful delivery but before
1371 the spool file has been updated, the journal is left lying around. The next
1372 time Exim attempts to deliver the message, it reads the journal file and
1373 updates the spool file before proceeding. This minimizes the chances of double
1374 deliveries caused by crashes.
1375
1376
1377 3.8 Processing an address for delivery
1378 --------------------------------------
1379
1380 The main delivery processing elements of Exim are called routers and transports
1381 , and collectively these are known as drivers. Code for a number of them is
1382 provided in the source distribution, and compile-time options specify which
1383 ones are included in the binary. Run time options specify which ones are
1384 actually used for delivering messages.
1385
1386 Each driver that is specified in the run time configuration is an instance of
1387 that particular driver type. Multiple instances are allowed; for example, you
1388 can set up several different smtp transports, each with different option values
1389 that might specify different ports or different timeouts. Each instance has its
1390 own identifying name. In what follows we will normally use the instance name
1391 when discussing one particular instance (that is, one specific configuration of
1392 the driver), and the generic driver name when discussing the driver's features
1393 in general.
1394
1395 A router is a driver that operates on an address, either determining how its
1396 delivery should happen, by assigning it to a specific transport, or converting
1397 the address into one or more new addresses (for example, via an alias file). A
1398 router may also explicitly choose to fail an address, causing it to be bounced.
1399
1400 A transport is a driver that transmits a copy of the message from Exim's spool
1401 to some destination. There are two kinds of transport: for a local transport,
1402 the destination is a file or a pipe on the local host, whereas for a remote
1403 transport the destination is some other host. A message is passed to a specific
1404 transport as a result of successful routing. If a message has several
1405 recipients, it may be passed to a number of different transports.
1406
1407 An address is processed by passing it to each configured router instance in
1408 turn, subject to certain preconditions, until a router accepts the address or
1409 specifies that it should be bounced. We will describe this process in more
1410 detail shortly. First, as a simple example, we consider how each recipient
1411 address in a message is processed in a small configuration of three routers.
1412
1413 To make this a more concrete example, it is described in terms of some actual
1414 routers, but remember, this is only an example. You can configure Exim's
1415 routers in many different ways, and there may be any number of routers in a
1416 configuration.
1417
1418 The first router that is specified in a configuration is often one that handles
1419 addresses in domains that are not recognized specially by the local host. These
1420 are typically addresses for arbitrary domains on the Internet. A precondition
1421 is set up which looks for the special domains known to the host (for example,
1422 its own domain name), and the router is run for addresses that do not match.
1423 Typically, this is a router that looks up domains in the DNS in order to find
1424 the hosts to which this address routes. If it succeeds, the address is assigned
1425 to a suitable SMTP transport; if it does not succeed, the router is configured
1426 to fail the address.
1427
1428 The second router is reached only when the domain is recognized as one that
1429 "belongs" to the local host. This router does redirection - also known as
1430 aliasing and forwarding. When it generates one or more new addresses from the
1431 original, each of them is routed independently from the start. Otherwise, the
1432 router may cause an address to fail, or it may simply decline to handle the
1433 address, in which case the address is passed to the next router.
1434
1435 The final router in many configurations is one that checks to see if the
1436 address belongs to a local mailbox. The precondition may involve a check to see
1437 if the local part is the name of a login account, or it may look up the local
1438 part in a file or a database. If its preconditions are not met, or if the
1439 router declines, we have reached the end of the routers. When this happens, the
1440 address is bounced.
1441
1442
1443 3.9 Processing an address for verification
1444 ------------------------------------------
1445
1446 As well as being used to decide how to deliver to an address, Exim's routers
1447 are also used for address verification. Verification can be requested as one of
1448 the checks to be performed in an ACL for incoming messages, on both sender and
1449 recipient addresses, and it can be tested using the -bv and -bvs command line
1450 options.
1451
1452 When an address is being verified, the routers are run in "verify mode". This
1453 does not affect the way the routers work, but it is a state that can be
1454 detected. By this means, a router can be skipped or made to behave differently
1455 when verifying. A common example is a configuration in which the first router
1456 sends all messages to a message-scanning program, unless they have been
1457 previously scanned. Thus, the first router accepts all addresses without any
1458 checking, making it useless for verifying. Normally, the no_verify option would
1459 be set for such a router, causing it to be skipped in verify mode.
1460
1461
1462 3.10 Running an individual router
1463 ---------------------------------
1464
1465 As explained in the example above, a number of preconditions are checked before
1466 running a router. If any are not met, the router is skipped, and the address is
1467 passed to the next router. When all the preconditions on a router are met, the
1468 router is run. What happens next depends on the outcome, which is one of the
1469 following:
1470
1471 * accept: The router accepts the address, and either assigns it to a
1472 transport, or generates one or more "child" addresses. Processing the
1473 original address ceases, unless the unseen option is set on the router.
1474 This option can be used to set up multiple deliveries with different
1475 routing (for example, for keeping archive copies of messages). When unseen
1476 is set, the address is passed to the next router. Normally, however, an
1477 accept return marks the end of routing.
1478
1479 Any child addresses generated by the router are processed independently,
1480 starting with the first router by default. It is possible to change this by
1481 setting the redirect_router option to specify which router to start at for
1482 child addresses. Unlike pass_router (see below) the router specified by
1483 redirect_router may be anywhere in the router configuration.
1484
1485 * pass: The router recognizes the address, but cannot handle it itself. It
1486 requests that the address be passed to another router. By default the
1487 address is passed to the next router, but this can be changed by setting
1488 the pass_router option. However, (unlike redirect_router) the named router
1489 must be below the current router (to avoid loops).
1490
1491 * decline: The router declines to accept the address because it does not
1492 recognize it at all. By default, the address is passed to the next router,
1493 but this can be prevented by setting the no_more option. When no_more is
1494 set, all the remaining routers are skipped. In effect, no_more converts
1495 decline into fail.
1496
1497 * fail: The router determines that the address should fail, and queues it for
1498 the generation of a bounce message. There is no further processing of the
1499 original address unless unseen is set on the router.
1500
1501 * defer: The router cannot handle the address at the present time. (A
1502 database may be offline, or a DNS lookup may have timed out.) No further
1503 processing of the address happens in this delivery attempt. It is tried
1504 again next time the message is considered for delivery.
1505
1506 * error: There is some error in the router (for example, a syntax error in
1507 its configuration). The action is as for defer.
1508
1509 If an address reaches the end of the routers without having been accepted by
1510 any of them, it is bounced as unrouteable. The default error message in this
1511 situation is "unrouteable address", but you can set your own message by making
1512 use of the cannot_route_message option. This can be set for any router; the
1513 value from the last router that "saw" the address is used.
1514
1515 Sometimes while routing you want to fail a delivery when some conditions are
1516 met but others are not, instead of passing the address on for further routing.
1517 You can do this by having a second router that explicitly fails the delivery
1518 when the relevant conditions are met. The redirect router has a "fail" facility
1519 for this purpose.
1520
1521
1522 3.11 Duplicate addresses
1523 ------------------------
1524
1525 Once routing is complete, Exim scans the addresses that are assigned to local
1526 and remote transports, and discards any duplicates that it finds. During this
1527 check, local parts are treated as case-sensitive. This happens only when
1528 actually delivering a message; when testing routers with -bt, all the routed
1529 addresses are shown.
1530
1531
1532 3.12 Router preconditions
1533 -------------------------
1534
1535 The preconditions that are tested for each router are listed below, in the
1536 order in which they are tested. The individual configuration options are
1537 described in more detail in chapter 15.
1538
1539 * The local_part_prefix and local_part_suffix options can specify that the
1540 local parts handled by the router may or must have certain prefixes and/or
1541 suffixes. If a mandatory affix (prefix or suffix) is not present, the
1542 router is skipped. These conditions are tested first. When an affix is
1543 present, it is removed from the local part before further processing,
1544 including the evaluation of any other conditions.
1545
1546 * Routers can be designated for use only when not verifying an address, that
1547 is, only when routing it for delivery (or testing its delivery routing). If
1548 the verify option is set false, the router is skipped when Exim is
1549 verifying an address. Setting the verify option actually sets two options,
1550 verify_sender and verify_recipient, which independently control the use of
1551 the router for sender and recipient verification. You can set these options
1552 directly if you want a router to be used for only one type of verification.
1553 Note that cutthrough delivery is classed as a recipient verification for
1554 this purpose.
1555
1556 * If the address_test option is set false, the router is skipped when Exim is
1557 run with the -bt option to test an address routing. This can be helpful
1558 when the first router sends all new messages to a scanner of some sort; it
1559 makes it possible to use -bt to test subsequent delivery routing without
1560 having to simulate the effect of the scanner.
1561
1562 * Routers can be designated for use only when verifying an address, as
1563 opposed to routing it for delivery. The verify_only option controls this.
1564 Again, cutthrough delivery counts as a verification.
1565
1566 * Individual routers can be explicitly skipped when running the routers to
1567 check an address given in the SMTP EXPN command (see the expn option).
1568
1569 * If the domains option is set, the domain of the address must be in the set
1570 of domains that it defines.
1571
1572 * If the local_parts option is set, the local part of the address must be in
1573 the set of local parts that it defines. If local_part_prefix or
1574 local_part_suffix is in use, the prefix or suffix is removed from the local
1575 part before this check. If you want to do precondition tests on local parts
1576 that include affixes, you can do so by using a condition option (see below)
1577 that uses the variables $local_part, $local_part_prefix, and
1578 $local_part_suffix as necessary.
1579
1580 * If the check_local_user option is set, the local part must be the name of
1581 an account on the local host. If this check succeeds, the uid and gid of
1582 the local user are placed in $local_user_uid and $local_user_gid and the
1583 user's home directory is placed in $home; these values can be used in the
1584 remaining preconditions.
1585
1586 * If the router_home_directory option is set, it is expanded at this point,
1587 because it overrides the value of $home. If this expansion were left till
1588 later, the value of $home as set by check_local_user would be used in
1589 subsequent tests. Having two different values of $home in the same router
1590 could lead to confusion.
1591
1592 * If the senders option is set, the envelope sender address must be in the
1593 set of addresses that it defines.
1594
1595 * If the require_files option is set, the existence or non-existence of
1596 specified files is tested.
1597
1598 * If the condition option is set, it is evaluated and tested. This option
1599 uses an expanded string to allow you to set up your own custom
1600 preconditions. Expanded strings are described in chapter 11.
1601
1602 Note that require_files comes near the end of the list, so you cannot use it to
1603 check for the existence of a file in which to lookup up a domain, local part,
1604 or sender. However, as these options are all expanded, you can use the exists
1605 expansion condition to make such tests within each condition. The require_files
1606 option is intended for checking files that the router may be going to use
1607 internally, or which are needed by a specific transport (for example,
1608 .procmailrc).
1609
1610
1611 3.13 Delivery in detail
1612 -----------------------
1613
1614 When a message is to be delivered, the sequence of events is as follows:
1615
1616 * If a system-wide filter file is specified, the message is passed to it. The
1617 filter may add recipients to the message, replace the recipients, discard
1618 the message, cause a new message to be generated, or cause the message
1619 delivery to fail. The format of the system filter file is the same as for
1620 Exim user filter files, described in the separate document entitled Exim's
1621 interfaces to mail filtering. (Note: Sieve cannot be used for system filter
1622 files.)
1623
1624 Some additional features are available in system filters - see chapter 46
1625 for details. Note that a message is passed to the system filter only once
1626 per delivery attempt, however many recipients it has. However, if there are
1627 several delivery attempts because one or more addresses could not be
1628 immediately delivered, the system filter is run each time. The filter
1629 condition first_delivery can be used to detect the first run of the system
1630 filter.
1631
1632 * Each recipient address is offered to each configured router in turn,
1633 subject to its preconditions, until one is able to handle it. If no router
1634 can handle the address, that is, if they all decline, the address is
1635 failed. Because routers can be targeted at particular domains, several
1636 locally handled domains can be processed entirely independently of each
1637 other.
1638
1639 * A router that accepts an address may assign it to a local or a remote
1640 transport. However, the transport is not run at this time. Instead, the
1641 address is placed on a list for the particular transport, which will be run
1642 later. Alternatively, the router may generate one or more new addresses
1643 (typically from alias, forward, or filter files). New addresses are fed
1644 back into this process from the top, but in order to avoid loops, a router
1645 ignores any address which has an identically-named ancestor that was
1646 processed by itself.
1647
1648 * When all the routing has been done, addresses that have been successfully
1649 handled are passed to their assigned transports. When local transports are
1650 doing real local deliveries, they handle only one address at a time, but if
1651 a local transport is being used as a pseudo-remote transport (for example,
1652 to collect batched SMTP messages for transmission by some other means)
1653 multiple addresses can be handled. Remote transports can always handle more
1654 than one address at a time, but can be configured not to do so, or to
1655 restrict multiple addresses to the same domain.
1656
1657 * Each local delivery to a file or a pipe runs in a separate process under a
1658 non-privileged uid, and these deliveries are run one at a time. Remote
1659 deliveries also run in separate processes, normally under a uid that is
1660 private to Exim ("the Exim user"), but in this case, several remote
1661 deliveries can be run in parallel. The maximum number of simultaneous
1662 remote deliveries for any one message is set by the remote_max_parallel
1663 option. The order in which deliveries are done is not defined, except that
1664 all local deliveries happen before any remote deliveries.
1665
1666 * When it encounters a local delivery during a queue run, Exim checks its
1667 retry database to see if there has been a previous temporary delivery
1668 failure for the address before running the local transport. If there was a
1669 previous failure, Exim does not attempt a new delivery until the retry time
1670 for the address is reached. However, this happens only for delivery
1671 attempts that are part of a queue run. Local deliveries are always
1672 attempted when delivery immediately follows message reception, even if
1673 retry times are set for them. This makes for better behaviour if one
1674 particular message is causing problems (for example, causing quota
1675 overflow, or provoking an error in a filter file).
1676
1677 * Remote transports do their own retry handling, since an address may be
1678 deliverable to one of a number of hosts, each of which may have a different
1679 retry time. If there have been previous temporary failures and no host has
1680 reached its retry time, no delivery is attempted, whether in a queue run or
1681 not. See chapter 32 for details of retry strategies.
1682
1683 * If there were any permanent errors, a bounce message is returned to an
1684 appropriate address (the sender in the common case), with details of the
1685 error for each failing address. Exim can be configured to send copies of
1686 bounce messages to other addresses.
1687
1688 * If one or more addresses suffered a temporary failure, the message is left
1689 on the queue, to be tried again later. Delivery of these addresses is said
1690 to be deferred.
1691
1692 * When all the recipient addresses have either been delivered or bounced,
1693 handling of the message is complete. The spool files and message log are
1694 deleted, though the message log can optionally be preserved if required.
1695
1696
1697 3.14 Retry mechanism
1698 --------------------
1699
1700 Exim's mechanism for retrying messages that fail to get delivered at the first
1701 attempt is the queue runner process. You must either run an Exim daemon that
1702 uses the -q option with a time interval to start queue runners at regular
1703 intervals, or use some other means (such as cron) to start them. If you do not
1704 arrange for queue runners to be run, messages that fail temporarily at the
1705 first attempt will remain on your queue for ever. A queue runner process works
1706 its way through the queue, one message at a time, trying each delivery that has
1707 passed its retry time. You can run several queue runners at once.
1708
1709 Exim uses a set of configured rules to determine when next to retry the failing
1710 address (see chapter 32). These rules also specify when Exim should give up
1711 trying to deliver to the address, at which point it generates a bounce message.
1712 If no retry rules are set for a particular host, address, and error
1713 combination, no retries are attempted, and temporary errors are treated as
1714 permanent.
1715
1716
1717 3.15 Temporary delivery failure
1718 -------------------------------
1719
1720 There are many reasons why a message may not be immediately deliverable to a
1721 particular address. Failure to connect to a remote machine (because it, or the
1722 connection to it, is down) is one of the most common. Temporary failures may be
1723 detected during routing as well as during the transport stage of delivery.
1724 Local deliveries may be delayed if NFS files are unavailable, or if a mailbox
1725 is on a file system where the user is over quota. Exim can be configured to
1726 impose its own quotas on local mailboxes; where system quotas are set they will
1727 also apply.
1728
1729 If a host is unreachable for a period of time, a number of messages may be
1730 waiting for it by the time it recovers, and sending them in a single SMTP
1731 connection is clearly beneficial. Whenever a delivery to a remote host is
1732 deferred, Exim makes a note in its hints database, and whenever a successful
1733 SMTP delivery has happened, it looks to see if any other messages are waiting
1734 for the same host. If any are found, they are sent over the same SMTP
1735 connection, subject to a configuration limit as to the maximum number in any
1736 one connection.
1737
1738
1739 3.16 Permanent delivery failure
1740 -------------------------------
1741
1742 When a message cannot be delivered to some or all of its intended recipients, a
1743 bounce message is generated. Temporary delivery failures turn into permanent
1744 errors when their timeout expires. All the addresses that fail in a given
1745 delivery attempt are listed in a single message. If the original message has
1746 many recipients, it is possible for some addresses to fail in one delivery
1747 attempt and others to fail subsequently, giving rise to more than one bounce
1748 message. The wording of bounce messages can be customized by the administrator.
1749 See chapter 49 for details.
1750
1751 Bounce messages contain an X-Failed-Recipients: header line that lists the
1752 failed addresses, for the benefit of programs that try to analyse such messages
1753 automatically.
1754
1755 A bounce message is normally sent to the sender of the original message, as
1756 obtained from the message's envelope. For incoming SMTP messages, this is the
1757 address given in the MAIL command. However, when an address is expanded via a
1758 forward or alias file, an alternative address can be specified for delivery
1759 failures of the generated addresses. For a mailing list expansion (see section
1760 50.2) it is common to direct bounce messages to the manager of the list.
1761
1762
1763 3.17 Failures to deliver bounce messages
1764 ----------------------------------------
1765
1766 If a bounce message (either locally generated or received from a remote host)
1767 itself suffers a permanent delivery failure, the message is left on the queue,
1768 but it is frozen, awaiting the attention of an administrator. There are options
1769 that can be used to make Exim discard such failed messages, or to keep them for
1770 only a short time (see timeout_frozen_after and ignore_bounce_errors_after).
1771
1772
1773
1774 ===============================================================================
1775 4. BUILDING AND INSTALLING EXIM
1776
1777
1778 4.1 Unpacking
1779 -------------
1780
1781 Exim is distributed as a gzipped or bzipped tar file which, when unpacked,
1782 creates a directory with the name of the current release (for example,
1783 exim-4.89) into which the following files are placed:
1784
1785 ACKNOWLEDGMENTS contains some acknowledgments
1786 CHANGES contains a reference to where changes are documented
1787 LICENCE the GNU General Public Licence
1788 Makefile top-level make file
1789 NOTICE conditions for the use of Exim
1790 README list of files, directories and simple build instructions
1791
1792 Other files whose names begin with README may also be present. The following
1793 subdirectories are created:
1794
1795 Local an empty directory for local configuration files
1796 OS OS-specific files
1797 doc documentation files
1798 exim_monitor source files for the Exim monitor
1799 scripts scripts used in the build process
1800 src remaining source files
1801 util independent utilities
1802
1803 The main utility programs are contained in the src directory, and are built
1804 with the Exim binary. The util directory contains a few optional scripts that
1805 may be useful to some sites.
1806
1807
1808 4.2 Multiple machine architectures and operating systems
1809 --------------------------------------------------------
1810
1811 The building process for Exim is arranged to make it easy to build binaries for
1812 a number of different architectures and operating systems from the same set of
1813 source files. Compilation does not take place in the src directory. Instead, a
1814 build directory is created for each architecture and operating system. Symbolic
1815 links to the sources are installed in this directory, which is where the actual
1816 building takes place. In most cases, Exim can discover the machine architecture
1817 and operating system for itself, but the defaults can be overridden if
1818 necessary.
1819
1820
1821 4.3 PCRE library
1822 ----------------
1823
1824 Exim no longer has an embedded PCRE library as the vast majority of modern
1825 systems include PCRE as a system library, although you may need to install the
1826 PCRE or PCRE development package for your operating system. If your system has
1827 a normal PCRE installation the Exim build process will need no further
1828 configuration. If the library or the headers are in an unusual location you
1829 will need to either set the PCRE_LIBS and INCLUDE directives appropriately, or
1830 set PCRE_CONFIG=yes to use the installed pcre-config command. If your operating
1831 system has no PCRE support then you will need to obtain and build the current
1832 PCRE from ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/. More
1833 information on PCRE is available at http://www.pcre.org/.
1834
1835
1836 4.4 DBM libraries
1837 -----------------
1838
1839 Even if you do not use any DBM files in your configuration, Exim still needs a
1840 DBM library in order to operate, because it uses indexed files for its hints
1841 databases. Unfortunately, there are a number of DBM libraries in existence, and
1842 different operating systems often have different ones installed.
1843
1844 If you are using Solaris, IRIX, one of the modern BSD systems, or a modern
1845 Linux distribution, the DBM configuration should happen automatically, and you
1846 may be able to ignore this section. Otherwise, you may have to learn more than
1847 you would like about DBM libraries from what follows.
1848
1849 Licensed versions of Unix normally contain a library of DBM functions operating
1850 via the ndbm interface, and this is what Exim expects by default. Free versions
1851 of Unix seem to vary in what they contain as standard. In particular, some
1852 early versions of Linux have no default DBM library, and different distributors
1853 have chosen to bundle different libraries with their packaged versions.
1854 However, the more recent releases seem to have standardized on the Berkeley DB
1855 library.
1856
1857 Different DBM libraries have different conventions for naming the files they
1858 use. When a program opens a file called dbmfile, there are several
1859 possibilities:
1860
1861 1. A traditional ndbm implementation, such as that supplied as part of
1862 Solaris, operates on two files called dbmfile.dir and dbmfile.pag.
1863
1864 2. The GNU library, gdbm, operates on a single file. If used via its ndbm
1865 compatibility interface it makes two different hard links to it with names
1866 dbmfile.dir and dbmfile.pag, but if used via its native interface, the file
1867 name is used unmodified.
1868
1869 3. The Berkeley DB package, if called via its ndbm compatibility interface,
1870 operates on a single file called dbmfile.db, but otherwise looks to the
1871 programmer exactly the same as the traditional ndbm implementation.
1872
1873 4. If the Berkeley package is used in its native mode, it operates on a single
1874 file called dbmfile; the programmer's interface is somewhat different to
1875 the traditional ndbm interface.
1876
1877 5. To complicate things further, there are several very different versions of
1878 the Berkeley DB package. Version 1.85 was stable for a very long time,
1879 releases 2.x and 3.x were current for a while, but the latest versions are
1880 now numbered 4.x. Maintenance of some of the earlier releases has ceased.
1881 All versions of Berkeley DB can be obtained from http://www.sleepycat.com/.
1882
1883 6. Yet another DBM library, called tdb, is available from http://
1884 download.sourceforge.net/tdb. It has its own interface, and also operates
1885 on a single file.
1886
1887 Exim and its utilities can be compiled to use any of these interfaces. In order
1888 to use any version of the Berkeley DB package in native mode, you must set
1889 USE_DB in an appropriate configuration file (typically Local/Makefile). For
1890 example:
1891
1892 USE_DB=yes
1893
1894 Similarly, for gdbm you set USE_GDBM, and for tdb you set USE_TDB. An error is
1895 diagnosed if you set more than one of these.
1896
1897 At the lowest level, the build-time configuration sets none of these options,
1898 thereby assuming an interface of type (1). However, some operating system
1899 configuration files (for example, those for the BSD operating systems and
1900 Linux) assume type (4) by setting USE_DB as their default, and the
1901 configuration files for Cygwin set USE_GDBM. Anything you set in Local/Makefile
1902 , however, overrides these system defaults.
1903
1904 As well as setting USE_DB, USE_GDBM, or USE_TDB, it may also be necessary to
1905 set DBMLIB, to cause inclusion of the appropriate library, as in one of these
1906 lines:
1907
1908 DBMLIB = -ldb
1909 DBMLIB = -ltdb
1910
1911 Settings like that will work if the DBM library is installed in the standard
1912 place. Sometimes it is not, and the library's header file may also not be in
1913 the default path. You may need to set INCLUDE to specify where the header file
1914 is, and to specify the path to the library more fully in DBMLIB, as in this
1915 example:
1916
1917 INCLUDE=-I/usr/local/include/db-4.1
1918 DBMLIB=/usr/local/lib/db-4.1/libdb.a
1919
1920 There is further detailed discussion about the various DBM libraries in the
1921 file doc/dbm.discuss.txt in the Exim distribution.
1922
1923
1924 4.5 Pre-building configuration
1925 ------------------------------
1926
1927 Before building Exim, a local configuration file that specifies options
1928 independent of any operating system has to be created with the name Local/
1929 Makefile. A template for this file is supplied as the file src/EDITME, and it
1930 contains full descriptions of all the option settings therein. These
1931 descriptions are therefore not repeated here. If you are building Exim for the
1932 first time, the simplest thing to do is to copy src/EDITME to Local/Makefile,
1933 then read it and edit it appropriately.
1934
1935 There are three settings that you must supply, because Exim will not build
1936 without them. They are the location of the run time configuration file
1937 (CONFIGURE_FILE), the directory in which Exim binaries will be installed
1938 (BIN_DIRECTORY), and the identity of the Exim user (EXIM_USER and maybe
1939 EXIM_GROUP as well). The value of CONFIGURE_FILE can in fact be a
1940 colon-separated list of file names; Exim uses the first of them that exists.
1941
1942 There are a few other parameters that can be specified either at build time or
1943 at run time, to enable the same binary to be used on a number of different
1944 machines. However, if the locations of Exim's spool directory and log file
1945 directory (if not within the spool directory) are fixed, it is recommended that
1946 you specify them in Local/Makefile instead of at run time, so that errors
1947 detected early in Exim's execution (such as a malformed configuration file) can
1948 be logged.
1949
1950 Exim's interfaces for calling virus and spam scanning software directly from
1951 access control lists are not compiled by default. If you want to include these
1952 facilities, you need to set
1953
1954 WITH_CONTENT_SCAN=yes
1955
1956 in your Local/Makefile. For details of the facilities themselves, see chapter
1957 44.
1958
1959 If you are going to build the Exim monitor, a similar configuration process is
1960 required. The file exim_monitor/EDITME must be edited appropriately for your
1961 installation and saved under the name Local/eximon.conf. If you are happy with
1962 the default settings described in exim_monitor/EDITME, Local/eximon.conf can be
1963 empty, but it must exist.
1964
1965 This is all the configuration that is needed in straightforward cases for known
1966 operating systems. However, the building process is set up so that it is easy
1967 to override options that are set by default or by operating-system-specific
1968 configuration files, for example to change the name of the C compiler, which
1969 defaults to gcc. See section 4.13 below for details of how to do this.
1970
1971
1972 4.6 Support for iconv()
1973 -----------------------
1974
1975 The contents of header lines in messages may be encoded according to the rules
1976 described RFC 2047. This makes it possible to transmit characters that are not
1977 in the ASCII character set, and to label them as being in a particular
1978 character set. When Exim is inspecting header lines by means of the $h_
1979 mechanism, it decodes them, and translates them into a specified character set
1980 (default is set at build time). The translation is possible only if the
1981 operating system supports the iconv() function.
1982
1983 However, some of the operating systems that supply iconv() do not support very
1984 many conversions. The GNU libiconv library (available from http://www.gnu.org/
1985 software/libiconv/) can be installed on such systems to remedy this deficiency,
1986 as well as on systems that do not supply iconv() at all. After installing
1987 libiconv, you should add
1988
1989 HAVE_ICONV=yes
1990
1991 to your Local/Makefile and rebuild Exim.
1992
1993
1994 4.7 Including TLS/SSL encryption support
1995 ----------------------------------------
1996
1997 Exim can be built to support encrypted SMTP connections, using the STARTTLS
1998 command as per RFC 2487. It can also support legacy clients that expect to
1999 start a TLS session immediately on connection to a non-standard port (see the
2000 tls_on_connect_ports runtime option and the -tls-on-connect command line
2001 option).
2002
2003 If you want to build Exim with TLS support, you must first install either the
2004 OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for
2005 implementing SSL.
2006
2007 If OpenSSL is installed, you should set
2008
2009 SUPPORT_TLS=yes
2010 TLS_LIBS=-lssl -lcrypto
2011
2012 in Local/Makefile. You may also need to specify the locations of the OpenSSL
2013 library and include files. For example:
2014
2015 SUPPORT_TLS=yes
2016 TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto
2017 TLS_INCLUDE=-I/usr/local/openssl/include/
2018
2019 If you have pkg-config available, then instead you can just use:
2020
2021 SUPPORT_TLS=yes
2022 USE_OPENSSL_PC=openssl
2023
2024 If GnuTLS is installed, you should set
2025
2026 SUPPORT_TLS=yes
2027 USE_GNUTLS=yes
2028 TLS_LIBS=-lgnutls -ltasn1 -lgcrypt
2029
2030 in Local/Makefile, and again you may need to specify the locations of the
2031 library and include files. For example:
2032
2033 SUPPORT_TLS=yes
2034 USE_GNUTLS=yes
2035 TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt
2036 TLS_INCLUDE=-I/usr/gnu/include
2037
2038 If you have pkg-config available, then instead you can just use:
2039
2040 SUPPORT_TLS=yes
2041 USE_GNUTLS=yes
2042 USE_GNUTLS_PC=gnutls
2043
2044 You do not need to set TLS_INCLUDE if the relevant directory is already
2045 specified in INCLUDE. Details of how to configure Exim to make use of TLS are
2046 given in chapter 42.
2047
2048
2049 4.8 Use of tcpwrappers
2050 ----------------------
2051
2052 Exim can be linked with the tcpwrappers library in order to check incoming SMTP
2053 calls using the tcpwrappers control files. This may be a convenient alternative
2054 to Exim's own checking facilities for installations that are already making use
2055 of tcpwrappers for other purposes. To do this, you should set USE_TCP_WRAPPERS
2056 in Local/Makefile, arrange for the file tcpd.h to be available at compile time,
2057 and also ensure that the library libwrap.a is available at link time, typically
2058 by including -lwrap in EXTRALIBS_EXIM. For example, if tcpwrappers is installed
2059 in /usr/local, you might have
2060
2061 USE_TCP_WRAPPERS=yes
2062 CFLAGS=-O -I/usr/local/include
2063 EXTRALIBS_EXIM=-L/usr/local/lib -lwrap
2064
2065 in Local/Makefile. The daemon name to use in the tcpwrappers control files is
2066 "exim". For example, the line
2067
2068 exim : LOCAL 192.168.1. .friendly.domain.example
2069
2070 in your /etc/hosts.allow file allows connections from the local host, from the
2071 subnet 192.168.1.0/24, and from all hosts in friendly.domain.example. All other
2072 connections are denied. The daemon name used by tcpwrappers can be changed at
2073 build time by setting TCP_WRAPPERS_DAEMON_NAME in Local/Makefile, or by setting
2074 tcp_wrappers_daemon_name in the configure file. Consult the tcpwrappers
2075 documentation for further details.
2076
2077
2078 4.9 Including support for IPv6
2079 ------------------------------
2080
2081 Exim contains code for use on systems that have IPv6 support. Setting
2082 "HAVE_IPV6=YES" in Local/Makefile causes the IPv6 code to be included; it may
2083 also be necessary to set IPV6_INCLUDE and IPV6_LIBS on systems where the IPv6
2084 support is not fully integrated into the normal include and library files.
2085
2086 Two different types of DNS record for handling IPv6 addresses have been
2087 defined. AAAA records (analogous to A records for IPv4) are in use, and are
2088 currently seen as the mainstream. Another record type called A6 was proposed as
2089 better than AAAA because it had more flexibility. However, it was felt to be
2090 over-complex, and its status was reduced to "experimental". Exim used to have a
2091 compile option for including A6 record support but this has now been withdrawn.
2092
2093
2094 4.10 Dynamically loaded lookup module support
2095 ---------------------------------------------
2096
2097 On some platforms, Exim supports not compiling all lookup types directly into
2098 the main binary, instead putting some into external modules which can be loaded
2099 on demand. This permits packagers to build Exim with support for lookups with
2100 extensive library dependencies without requiring all users to install all of
2101 those dependencies. Most, but not all, lookup types can be built this way.
2102
2103 Set "LOOKUP_MODULE_DIR" to the directory into which the modules will be
2104 installed; Exim will only load modules from that directory, as a security
2105 measure. You will need to set "CFLAGS_DYNAMIC" if not already defined for your
2106 OS; see OS/Makefile-Linux for an example. Some other requirements for adjusting
2107 "EXTRALIBS" may also be necessary, see src/EDITME for details.
2108
2109 Then, for each module to be loaded dynamically, define the relevant "LOOKUP_"<
2110 lookup_type> flags to have the value "2" instead of "yes". For example, this
2111 will build in lsearch but load sqlite and mysql support on demand:
2112
2113 LOOKUP_LSEARCH=yes
2114 LOOKUP_SQLITE=2
2115 LOOKUP_MYSQL=2
2116
2117
2118 4.11 The building process
2119 -------------------------
2120
2121 Once Local/Makefile (and Local/eximon.conf, if required) have been created, run
2122 make at the top level. It determines the architecture and operating system
2123 types, and creates a build directory if one does not exist. For example, on a
2124 Sun system running Solaris 8, the directory build-SunOS5-5.8-sparc is created.
2125 Symbolic links to relevant source files are installed in the build directory.
2126
2127 If this is the first time make has been run, it calls a script that builds a
2128 make file inside the build directory, using the configuration files from the
2129 Local directory. The new make file is then passed to another instance of make.
2130 This does the real work, building a number of utility scripts, and then
2131 compiling and linking the binaries for the Exim monitor (if configured), a
2132 number of utility programs, and finally Exim itself. The command "make
2133 makefile" can be used to force a rebuild of the make file in the build
2134 directory, should this ever be necessary.
2135
2136 If you have problems building Exim, check for any comments there may be in the
2137 README file concerning your operating system, and also take a look at the FAQ,
2138 where some common problems are covered.
2139
2140
2141 4.12 Output from "make"
2142 -----------------------
2143
2144 The output produced by the make process for compile lines is often very
2145 unreadable, because these lines can be very long. For this reason, the normal
2146 output is suppressed by default, and instead output similar to that which
2147 appears when compiling the 2.6 Linux kernel is generated: just a short line for
2148 each module that is being compiled or linked. However, it is still possible to
2149 get the full output, by calling make like this:
2150
2151 FULLECHO='' make -e
2152
2153 The value of FULLECHO defaults to "@", the flag character that suppresses
2154 command reflection in make. When you ask for the full output, it is given in
2155 addition to the short output.
2156
2157
2158 4.13 Overriding build-time options for Exim
2159 -------------------------------------------
2160
2161 The main make file that is created at the beginning of the building process
2162 consists of the concatenation of a number of files which set configuration
2163 values, followed by a fixed set of make instructions. If a value is set more
2164 than once, the last setting overrides any previous ones. This provides a
2165 convenient way of overriding defaults. The files that are concatenated are, in
2166 order:
2167
2168 OS/Makefile-Default
2169 OS/Makefile-<ostype>
2170 Local/Makefile
2171 Local/Makefile-<ostype>
2172 Local/Makefile-<archtype>
2173 Local/Makefile-<ostype>-<archtype>
2174 OS/Makefile-Base
2175
2176 where <ostype> is the operating system type and <archtype> is the architecture
2177 type. Local/Makefile is required to exist, and the building process fails if it
2178 is absent. The other three Local files are optional, and are often not needed.
2179
2180 The values used for <ostype> and <archtype> are obtained from scripts called
2181 scripts/os-type and scripts/arch-type respectively. If either of the
2182 environment variables EXIM_OSTYPE or EXIM_ARCHTYPE is set, their values are
2183 used, thereby providing a means of forcing particular settings. Otherwise, the
2184 scripts try to get values from the uname command. If this fails, the shell
2185 variables OSTYPE and ARCHTYPE are inspected. A number of ad hoc transformations
2186 are then applied, to produce the standard names that Exim expects. You can run
2187 these scripts directly from the shell in order to find out what values are
2188 being used on your system.
2189
2190 OS/Makefile-Default contains comments about the variables that are set therein.
2191 Some (but not all) are mentioned below. If there is something that needs
2192 changing, review the contents of this file and the contents of the make file
2193 for your operating system (OS/Makefile-<ostype>) to see what the default values
2194 are.
2195
2196 If you need to change any of the values that are set in OS/Makefile-Default or
2197 in OS/Makefile-<ostype>, or to add any new definitions, you do not need to
2198 change the original files. Instead, you should make the changes by putting the
2199 new values in an appropriate Local file. For example, when building Exim in
2200 many releases of the Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1)
2201 operating system, it is necessary to specify that the C compiler is called cc
2202 rather than gcc. Also, the compiler must be called with the option -std1, to
2203 make it recognize some of the features of Standard C that Exim uses. (Most
2204 other compilers recognize Standard C by default.) To do this, you should create
2205 a file called Local/Makefile-OSF1 containing the lines
2206
2207 CC=cc
2208 CFLAGS=-std1
2209
2210 If you are compiling for just one operating system, it may be easier to put
2211 these lines directly into Local/Makefile.
2212
2213 Keeping all your local configuration settings separate from the distributed
2214 files makes it easy to transfer them to new versions of Exim simply by copying
2215 the contents of the Local directory.
2216
2217 Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file
2218 lookup, but not all systems have these components installed, so the default is
2219 not to include the relevant code in the binary. All the different kinds of file
2220 and database lookup that Exim supports are implemented as separate code modules
2221 which are included only if the relevant compile-time options are set. In the
2222 case of LDAP, NIS, and NIS+, the settings for Local/Makefile are:
2223
2224 LOOKUP_LDAP=yes
2225 LOOKUP_NIS=yes
2226 LOOKUP_NISPLUS=yes
2227
2228 and similar settings apply to the other lookup types. They are all listed in
2229 src/EDITME. In many cases the relevant include files and interface libraries
2230 need to be installed before compiling Exim. However, there are some optional
2231 lookup types (such as cdb) for which the code is entirely contained within
2232 Exim, and no external include files or libraries are required. When a lookup
2233 type is not included in the binary, attempts to configure Exim to use it cause
2234 run time configuration errors.
2235
2236 Many systems now use a tool called pkg-config to encapsulate information about
2237 how to compile against a library; Exim has some initial support for being able
2238 to use pkg-config for lookups and authenticators. For any given makefile
2239 variable which starts "LOOKUP_" or "AUTH_", you can add a new variable with the
2240 "_PC" suffix in the name and assign as the value the name of the package to be
2241 queried. The results of querying via the pkg-config command will be added to
2242 the appropriate Makefile variables with "+=" directives, so your version of
2243 make will need to support that syntax. For instance:
2244
2245 LOOKUP_SQLITE=yes
2246 LOOKUP_SQLITE_PC=sqlite3
2247 AUTH_GSASL=yes
2248 AUTH_GSASL_PC=libgsasl
2249 AUTH_HEIMDAL_GSSAPI=yes
2250 AUTH_HEIMDAL_GSSAPI_PC=heimdal-gssapi
2251
2252 Exim can be linked with an embedded Perl interpreter, allowing Perl subroutines
2253 to be called during string expansion. To enable this facility,
2254
2255 EXIM_PERL=perl.o
2256
2257 must be defined in Local/Makefile. Details of this facility are given in
2258 chapter 12.
2259
2260 The location of the X11 libraries is something that varies a lot between
2261 operating systems, and there may be different versions of X11 to cope with.
2262 Exim itself makes no use of X11, but if you are compiling the Exim monitor, the
2263 X11 libraries must be available. The following three variables are set in OS/
2264 Makefile-Default:
2265
2266 X11=/usr/X11R6
2267 XINCLUDE=-I$(X11)/include
2268 XLFLAGS=-L$(X11)/lib
2269
2270 These are overridden in some of the operating-system configuration files. For
2271 example, in OS/Makefile-SunOS5 there is
2272
2273 X11=/usr/openwin
2274 XINCLUDE=-I$(X11)/include
2275 XLFLAGS=-L$(X11)/lib -R$(X11)/lib
2276
2277 If you need to override the default setting for your operating system, place a
2278 definition of all three of these variables into your Local/Makefile-<ostype>
2279 file.
2280
2281 If you need to add any extra libraries to the link steps, these can be put in a
2282 variable called EXTRALIBS, which appears in all the link commands, but by
2283 default is not defined. In contrast, EXTRALIBS_EXIM is used only on the command
2284 for linking the main Exim binary, and not for any associated utilities.
2285
2286 There is also DBMLIB, which appears in the link commands for binaries that use
2287 DBM functions (see also section 4.4). Finally, there is EXTRALIBS_EXIMON, which
2288 appears only in the link step for the Exim monitor binary, and which can be
2289 used, for example, to include additional X11 libraries.
2290
2291 The make file copes with rebuilding Exim correctly if any of the configuration
2292 files are edited. However, if an optional configuration file is deleted, it is
2293 necessary to touch the associated non-optional file (that is, Local/Makefile or
2294 Local/eximon.conf) before rebuilding.
2295
2296
2297 4.14 OS-specific header files
2298 -----------------------------
2299
2300 The OS directory contains a number of files with names of the form os.h-
2301 <ostype>. These are system-specific C header files that should not normally
2302 need to be changed. There is a list of macro settings that are recognized in
2303 the file OS/os.configuring, which should be consulted if you are porting Exim
2304 to a new operating system.
2305
2306
2307 4.15 Overriding build-time options for the monitor
2308 --------------------------------------------------
2309
2310 A similar process is used for overriding things when building the Exim monitor,
2311 where the files that are involved are
2312
2313 OS/eximon.conf-Default
2314 OS/eximon.conf-<ostype>
2315 Local/eximon.conf
2316 Local/eximon.conf-<ostype>
2317 Local/eximon.conf-<archtype>
2318 Local/eximon.conf-<ostype>-<archtype>
2319
2320 As with Exim itself, the final three files need not exist, and in this case the
2321 OS/eximon.conf-<ostype> file is also optional. The default values in OS/
2322 eximon.conf-Default can be overridden dynamically by setting environment
2323 variables of the same name, preceded by EXIMON_. For example, setting
2324 EXIMON_LOG_DEPTH in the environment overrides the value of LOG_DEPTH at run
2325 time.
2326
2327
2328 4.16 Installing Exim binaries and scripts
2329 -----------------------------------------
2330
2331 The command "make install" runs the exim_install script with no arguments. The
2332 script copies binaries and utility scripts into the directory whose name is
2333 specified by the BIN_DIRECTORY setting in Local/Makefile. The install script
2334 copies files only if they are newer than the files they are going to replace.
2335 The Exim binary is required to be owned by root and have the setuid bit set,
2336 for normal configurations. Therefore, you must run "make install" as root so
2337 that it can set up the Exim binary in this way. However, in some special
2338 situations (for example, if a host is doing no local deliveries) it may be
2339 possible to run Exim without making the binary setuid root (see chapter 55 for
2340 details).
2341
2342 Exim's run time configuration file is named by the CONFIGURE_FILE setting in
2343 Local/Makefile. If this names a single file, and the file does not exist, the
2344 default configuration file src/configure.default is copied there by the
2345 installation script. If a run time configuration file already exists, it is
2346 left alone. If CONFIGURE_FILE is a colon-separated list, naming several
2347 alternative files, no default is installed.
2348
2349 One change is made to the default configuration file when it is installed: the
2350 default configuration contains a router that references a system aliases file.
2351 The path to this file is set to the value specified by SYSTEM_ALIASES_FILE in
2352 Local/Makefile (/etc/aliases by default). If the system aliases file does not
2353 exist, the installation script creates it, and outputs a comment to the user.
2354
2355 The created file contains no aliases, but it does contain comments about the
2356 aliases a site should normally have. Mail aliases have traditionally been kept
2357 in /etc/aliases. However, some operating systems are now using /etc/mail/
2358 aliases. You should check if yours is one of these, and change Exim's
2359 configuration if necessary.
2360
2361 The default configuration uses the local host's name as the only local domain,
2362 and is set up to do local deliveries into the shared directory /var/mail,
2363 running as the local user. System aliases and .forward files in users' home
2364 directories are supported, but no NIS or NIS+ support is configured. Domains
2365 other than the name of the local host are routed using the DNS, with delivery
2366 over SMTP.
2367
2368 It is possible to install Exim for special purposes (such as building a binary
2369 distribution) in a private part of the file system. You can do this by a
2370 command such as
2371
2372 make DESTDIR=/some/directory/ install
2373
2374 This has the effect of pre-pending the specified directory to all the file
2375 paths, except the name of the system aliases file that appears in the default
2376 configuration. (If a default alias file is created, its name is modified.) For
2377 backwards compatibility, ROOT is used if DESTDIR is not set, but this usage is
2378 deprecated.
2379
2380 Running make install does not copy the Exim 4 conversion script convert4r4. You
2381 will probably run this only once if you are upgrading from Exim 3. None of the
2382 documentation files in the doc directory are copied, except for the info files
2383 when you have set INFO_DIRECTORY, as described in section 4.17 below.
2384
2385 For the utility programs, old versions are renamed by adding the suffix .O to
2386 their names. The Exim binary itself, however, is handled differently. It is
2387 installed under a name that includes the version number and the compile number,
2388 for example exim-4.89-1. The script then arranges for a symbolic link called
2389 exim to point to the binary. If you are updating a previous version of Exim,
2390 the script takes care to ensure that the name exim is never absent from the
2391 directory (as seen by other processes).
2392
2393 If you want to see what the make install will do before running it for real,
2394 you can pass the -n option to the installation script by this command:
2395
2396 make INSTALL_ARG=-n install
2397
2398 The contents of the variable INSTALL_ARG are passed to the installation script.
2399 You do not need to be root to run this test. Alternatively, you can run the
2400 installation script directly, but this must be from within the build directory.
2401 For example, from the top-level Exim directory you could use this command:
2402
2403 (cd build-SunOS5-5.5.1-sparc; ../scripts/exim_install -n)
2404
2405 There are two other options that can be supplied to the installation script.
2406
2407 * -no_chown bypasses the call to change the owner of the installed binary to
2408 root, and the call to make it a setuid binary.
2409
2410 * -no_symlink bypasses the setting up of the symbolic link exim to the
2411 installed binary.
2412
2413 INSTALL_ARG can be used to pass these options to the script. For example:
2414
2415 make INSTALL_ARG=-no_symlink install
2416
2417 The installation script can also be given arguments specifying which files are
2418 to be copied. For example, to install just the Exim binary, and nothing else,
2419 without creating the symbolic link, you could use:
2420
2421 make INSTALL_ARG='-no_symlink exim' install
2422
2423
2424 4.17 Installing info documentation
2425 ----------------------------------
2426
2427 Not all systems use the GNU info system for documentation, and for this reason,
2428 the Texinfo source of Exim's documentation is not included in the main
2429 distribution. Instead it is available separately from the ftp site (see section
2430 1.6).
2431
2432 If you have defined INFO_DIRECTORY in Local/Makefile and the Texinfo source of
2433 the documentation is found in the source tree, running "make install"
2434 automatically builds the info files and installs them.
2435
2436
2437 4.18 Setting up the spool directory
2438 -----------------------------------
2439
2440 When it starts up, Exim tries to create its spool directory if it does not
2441 exist. The Exim uid and gid are used for the owner and group of the spool
2442 directory. Sub-directories are automatically created in the spool directory as
2443 necessary.
2444
2445
2446 4.19 Testing
2447 ------------
2448
2449 Having installed Exim, you can check that the run time configuration file is
2450 syntactically valid by running the following command, which assumes that the
2451 Exim binary directory is within your PATH environment variable:
2452
2453 exim -bV
2454
2455 If there are any errors in the configuration file, Exim outputs error messages.
2456 Otherwise it outputs the version number and build date, the DBM library that is
2457 being used, and information about which drivers and other optional code modules
2458 are included in the binary. Some simple routing tests can be done by using the
2459 address testing option. For example,
2460
2461 exim -bt <local username>
2462
2463 should verify that it recognizes a local mailbox, and
2464
2465 exim -bt <remote address>
2466
2467 a remote one. Then try getting it to deliver mail, both locally and remotely.
2468 This can be done by passing messages directly to Exim, without going through a
2469 user agent. For example:
2470
2471 exim -v postmaster@your.domain.example
2472 From: user@your.domain.example
2473 To: postmaster@your.domain.example
2474 Subject: Testing Exim
2475
2476 This is a test message.
2477 ^D
2478
2479 The -v option causes Exim to output some verification of what it is doing. In
2480 this case you should see copies of three log lines, one for the message's
2481 arrival, one for its delivery, and one containing "Completed".
2482
2483 If you encounter problems, look at Exim's log files (mainlog and paniclog) to
2484 see if there is any relevant information there. Another source of information
2485 is running Exim with debugging turned on, by specifying the -d option. If a
2486 message is stuck on Exim's spool, you can force a delivery with debugging
2487 turned on by a command of the form
2488
2489 exim -d -M <exim-message-id>
2490
2491 You must be root or an "admin user" in order to do this. The -d option produces
2492 rather a lot of output, but you can cut this down to specific areas. For
2493 example, if you use -d-all+route only the debugging information relevant to
2494 routing is included. (See the -d option in chapter 5 for more details.)
2495
2496 One specific problem that has shown up on some sites is the inability to do
2497 local deliveries into a shared mailbox directory, because it does not have the
2498 "sticky bit" set on it. By default, Exim tries to create a lock file before
2499 writing to a mailbox file, and if it cannot create the lock file, the delivery
2500 is deferred. You can get round this either by setting the "sticky bit" on the
2501 directory, or by setting a specific group for local deliveries and allowing
2502 that group to create files in the directory (see the comments above the
2503 local_delivery transport in the default configuration file). Another approach
2504 is to configure Exim not to use lock files, but just to rely on fcntl() locking
2505 instead. However, you should do this only if all user agents also use fcntl()
2506 locking. For further discussion of locking issues, see chapter 26.
2507
2508 One thing that cannot be tested on a system that is already running an MTA is
2509 the receipt of incoming SMTP mail on the standard SMTP port. However, the -oX
2510 option can be used to run an Exim daemon that listens on some other port, or
2511 inetd can be used to do this. The -bh option and the exim_checkaccess utility
2512 can be used to check out policy controls on incoming SMTP mail.
2513
2514 Testing a new version on a system that is already running Exim can most easily
2515 be done by building a binary with a different CONFIGURE_FILE setting. From
2516 within the run time configuration, all other file and directory names that Exim
2517 uses can be altered, in order to keep it entirely clear of the production
2518 version.
2519
2520
2521 4.20 Replacing another MTA with Exim
2522 ------------------------------------
2523
2524 Building and installing Exim for the first time does not of itself put it in
2525 general use. The name by which the system's MTA is called by mail user agents
2526 is either /usr/sbin/sendmail, or /usr/lib/sendmail (depending on the operating
2527 system), and it is necessary to make this name point to the exim binary in
2528 order to get the user agents to pass messages to Exim. This is normally done by
2529 renaming any existing file and making /usr/sbin/sendmail or /usr/lib/sendmail a
2530 symbolic link to the exim binary. It is a good idea to remove any setuid
2531 privilege and executable status from the old MTA. It is then necessary to stop
2532 and restart the mailer daemon, if one is running.
2533
2534 Some operating systems have introduced alternative ways of switching MTAs. For
2535 example, if you are running FreeBSD, you need to edit the file /etc/mail/
2536 mailer.conf instead of setting up a symbolic link as just described. A typical
2537 example of the contents of this file for running Exim is as follows:
2538
2539 sendmail /usr/exim/bin/exim
2540 send-mail /usr/exim/bin/exim
2541 mailq /usr/exim/bin/exim -bp
2542 newaliases /usr/bin/true
2543
2544 Once you have set up the symbolic link, or edited /etc/mail/mailer.conf, your
2545 Exim installation is "live". Check it by sending a message from your favourite
2546 user agent.
2547
2548 You should consider what to tell your users about the change of MTA. Exim may
2549 have different capabilities to what was previously running, and there are
2550 various operational differences such as the text of messages produced by
2551 command line options and in bounce messages. If you allow your users to make
2552 use of Exim's filtering capabilities, you should make the document entitled
2553 Exim's interface to mail filtering available to them.
2554
2555
2556 4.21 Upgrading Exim
2557 -------------------
2558
2559 If you are already running Exim on your host, building and installing a new
2560 version automatically makes it available to MUAs, or any other programs that
2561 call the MTA directly. However, if you are running an Exim daemon, you do need
2562 to send it a HUP signal, to make it re-execute itself, and thereby pick up the
2563 new binary. You do not need to stop processing mail in order to install a new
2564 version of Exim. The install script does not modify an existing runtime
2565 configuration file.
2566
2567
2568 4.22 Stopping the Exim daemon on Solaris
2569 ----------------------------------------
2570
2571 The standard command for stopping the mailer daemon on Solaris is
2572
2573 /etc/init.d/sendmail stop
2574
2575 If /usr/lib/sendmail has been turned into a symbolic link, this script fails to
2576 stop Exim because it uses the command ps -e and greps the output for the text
2577 "sendmail"; this is not present because the actual program name (that is,
2578 "exim") is given by the ps command with these options. A solution is to replace
2579 the line that finds the process id with something like
2580
2581 pid=`cat /var/spool/exim/exim-daemon.pid`
2582
2583 to obtain the daemon's pid directly from the file that Exim saves it in.
2584
2585 Note, however, that stopping the daemon does not "stop Exim". Messages can
2586 still be received from local processes, and if automatic delivery is configured
2587 (the normal case), deliveries will still occur.
2588
2589
2590
2591 ===============================================================================
2592 5. THE EXIM COMMAND LINE
2593
2594 Exim's command line takes the standard Unix form of a sequence of options, each
2595 starting with a hyphen character, followed by a number of arguments. The
2596 options are compatible with the main options of Sendmail, and there are also
2597 some additional options, some of which are compatible with Smail 3. Certain
2598 combinations of options do not make sense, and provoke an error if used. The
2599 form of the arguments depends on which options are set.
2600
2601
2602 5.1 Setting options by program name
2603 -----------------------------------
2604
2605 If Exim is called under the name mailq, it behaves as if the option -bp were
2606 present before any other options. The -bp option requests a listing of the
2607 contents of the mail queue on the standard output. This feature is for
2608 compatibility with some systems that contain a command of that name in one of
2609 the standard libraries, symbolically linked to /usr/sbin/sendmail or /usr/lib/
2610 sendmail.
2611
2612 If Exim is called under the name rsmtp it behaves as if the option -bS were
2613 present before any other options, for compatibility with Smail. The -bS option
2614 is used for reading in a number of messages in batched SMTP format.
2615
2616 If Exim is called under the name rmail it behaves as if the -i and -oee options
2617 were present before any other options, for compatibility with Smail. The name
2618 rmail is used as an interface by some UUCP systems.
2619
2620 If Exim is called under the name runq it behaves as if the option -q were
2621 present before any other options, for compatibility with Smail. The -q option
2622 causes a single queue runner process to be started.
2623
2624 If Exim is called under the name newaliases it behaves as if the option -bi
2625 were present before any other options, for compatibility with Sendmail. This
2626 option is used for rebuilding Sendmail's alias file. Exim does not have the
2627 concept of a single alias file, but can be configured to run a given command if
2628 called with the -bi option.
2629
2630
2631 5.2 Trusted and admin users
2632 ---------------------------
2633
2634 Some Exim options are available only to trusted users and others are available
2635 only to admin users. In the description below, the phrases "Exim user" and
2636 "Exim group" mean the user and group defined by EXIM_USER and EXIM_GROUP in
2637 Local/Makefile or set by the exim_user and exim_group options. These do not
2638 necessarily have to use the name "exim".
2639
2640 * The trusted users are root, the Exim user, any user listed in the
2641 trusted_users configuration option, and any user whose current group or any
2642 supplementary group is one of those listed in the trusted_groups
2643 configuration option. Note that the Exim group is not automatically
2644 trusted.
2645
2646 Trusted users are always permitted to use the -f option or a leading
2647 "From " line to specify the envelope sender of a message that is passed to
2648 Exim through the local interface (see the -bm and -f options below). See
2649 the untrusted_set_sender option for a way of permitting non-trusted users
2650 to set envelope senders.
2651
2652 For a trusted user, there is never any check on the contents of the From:
2653 header line, and a Sender: line is never added. Furthermore, any existing
2654 Sender: line in incoming local (non-TCP/IP) messages is not removed.
2655
2656 Trusted users may also specify a host name, host address, interface
2657 address, protocol name, ident value, and authentication data when
2658 submitting a message locally. Thus, they are able to insert messages into
2659 Exim's queue locally that have the characteristics of messages received
2660 from a remote host. Untrusted users may in some circumstances use -f, but
2661 can never set the other values that are available to trusted users.
2662
2663 * The admin users are root, the Exim user, and any user that is a member of
2664 the Exim group or of any group listed in the admin_groups configuration
2665 option. The current group does not have to be one of these groups.
2666
2667 Admin users are permitted to list the queue, and to carry out certain
2668 operations on messages, for example, to force delivery failures. It is also
2669 necessary to be an admin user in order to see the full information provided
2670 by the Exim monitor, and full debugging output.
2671
2672 By default, the use of the -M, -q, -R, and -S options to cause Exim to
2673 attempt delivery of messages on its queue is restricted to admin users.
2674 However, this restriction can be relaxed by setting the prod_requires_admin
2675 option false (that is, specifying no_prod_requires_admin).
2676
2677 Similarly, the use of the -bp option to list all the messages in the queue
2678 is restricted to admin users unless queue_list_requires_admin is set false.
2679
2680 Warning: If you configure your system so that admin users are able to edit
2681 Exim's configuration file, you are giving those users an easy way of getting
2682 root. There is further discussion of this issue at the start of chapter 6.
2683
2684
2685 5.3 Command line options
2686 ------------------------
2687
2688 Exim's command line options are described in alphabetical order below. If none
2689 of the options that specifies a specific action (such as starting the daemon or
2690 a queue runner, or testing an address, or receiving a message in a specific
2691 format, or listing the queue) are present, and there is at least one argument
2692 on the command line, -bm (accept a local message on the standard input, with
2693 the arguments specifying the recipients) is assumed. Otherwise, Exim outputs a
2694 brief message about itself and exits.
2695
2696 --
2697
2698 This is a pseudo-option whose only purpose is to terminate the options and
2699 therefore to cause subsequent command line items to be treated as arguments
2700 rather than options, even if they begin with hyphens.
2701
2702 --help
2703
2704 This option causes Exim to output a few sentences stating what it is. The
2705 same output is generated if the Exim binary is called with no options and
2706 no arguments.
2707
2708 --version
2709
2710 This option is an alias for -bV and causes version information to be
2711 displayed.
2712
2713 -Ac, -Am
2714
2715 These options are used by Sendmail for selecting configuration files and
2716 are ignored by Exim.
2717
2718 -B<type>
2719
2720 This is a Sendmail option for selecting 7 or 8 bit processing. Exim is
2721 8-bit clean; it ignores this option.
2722
2723 -bd
2724
2725 This option runs Exim as a daemon, awaiting incoming SMTP connections.
2726 Usually the -bd option is combined with the -q<time> option, to specify
2727 that the daemon should also initiate periodic queue runs.
2728
2729 The -bd option can be used only by an admin user. If either of the -d
2730 (debugging) or -v (verifying) options are set, the daemon does not
2731 disconnect from the controlling terminal. When running this way, it can be
2732 stopped by pressing ctrl-C.
2733
2734 By default, Exim listens for incoming connections to the standard SMTP port
2735 on all the host's running interfaces. However, it is possible to listen on
2736 other ports, on multiple ports, and only on specific interfaces. Chapter 13
2737 contains a description of the options that control this.
2738
2739 When a listening daemon is started without the use of -oX (that is, without
2740 overriding the normal configuration), it writes its process id to a file
2741 called exim-daemon.pid in Exim's spool directory. This location can be
2742 overridden by setting PID_FILE_PATH in Local/Makefile. The file is written
2743 while Exim is still running as root.
2744
2745 When -oX is used on the command line to start a listening daemon, the
2746 process id is not written to the normal pid file path. However, -oP can be
2747 used to specify a path on the command line if a pid file is required.
2748
2749 The SIGHUP signal can be used to cause the daemon to re-execute itself.
2750 This should be done whenever Exim's configuration file, or any file that is
2751 incorporated into it by means of the .include facility, is changed, and
2752 also whenever a new version of Exim is installed. It is not necessary to do
2753 this when other files that are referenced from the configuration (for
2754 example, alias files) are changed, because these are reread each time they
2755 are used.
2756
2757 -bdf
2758
2759 This option has the same effect as -bd except that it never disconnects
2760 from the controlling terminal, even when no debugging is specified.
2761
2762 -be
2763
2764 Run Exim in expansion testing mode. Exim discards its root privilege, to
2765 prevent ordinary users from using this mode to read otherwise inaccessible
2766 files. If no arguments are given, Exim runs interactively, prompting for
2767 lines of data. Otherwise, it processes each argument in turn.
2768
2769 If Exim was built with USE_READLINE=yes in Local/Makefile, it tries to load
2770 the libreadline library dynamically whenever the -be option is used without
2771 command line arguments. If successful, it uses the readline() function,
2772 which provides extensive line-editing facilities, for reading the test
2773 data. A line history is supported.
2774
2775 Long expansion expressions can be split over several lines by using
2776 backslash continuations. As in Exim's run time configuration, white space
2777 at the start of continuation lines is ignored. Each argument or data line
2778 is passed through the string expansion mechanism, and the result is output.
2779 Variable values from the configuration file (for example, $qualify_domain)
2780 are available, but no message-specific values (such as $message_exim_id)
2781 are set, because no message is being processed (but see -bem and -Mset).
2782
2783 Note: If you use this mechanism to test lookups, and you change the data
2784 files or databases you are using, you must exit and restart Exim before
2785 trying the same lookup again. Otherwise, because each Exim process caches
2786 the results of lookups, you will just get the same result as before.
2787
2788 -bem <filename>
2789
2790 This option operates like -be except that it must be followed by the name
2791 of a file. For example:
2792
2793 exim -bem /tmp/testmessage
2794
2795 The file is read as a message (as if receiving a locally-submitted non-SMTP
2796 message) before any of the test expansions are done. Thus, message-specific
2797 variables such as $message_size and $header_from: are available. However,
2798 no Received: header is added to the message. If the -t option is set,
2799 recipients are read from the headers in the normal way, and are shown in
2800 the $recipients variable. Note that recipients cannot be given on the
2801 command line, because further arguments are taken as strings to expand
2802 (just like -be).
2803
2804 -bF <filename>
2805
2806 This option is the same as -bf except that it assumes that the filter being
2807 tested is a system filter. The additional commands that are available only
2808 in system filters are recognized.
2809
2810 -bf <filename>
2811
2812 This option runs Exim in user filter testing mode; the file is the filter
2813 file to be tested, and a test message must be supplied on the standard
2814 input. If there are no message-dependent tests in the filter, an empty file
2815 can be supplied.
2816
2817 If you want to test a system filter file, use -bF instead of -bf. You can
2818 use both -bF and -bf on the same command, in order to test a system filter
2819 and a user filter in the same run. For example:
2820
2821 exim -bF /system/filter -bf /user/filter </test/message
2822
2823 This is helpful when the system filter adds header lines or sets filter
2824 variables that are used by the user filter.
2825
2826 If the test filter file does not begin with one of the special lines
2827
2828 # Exim filter
2829 # Sieve filter
2830
2831 it is taken to be a normal .forward file, and is tested for validity under
2832 that interpretation. See sections 22.4 to 22.6 for a description of the
2833 possible contents of non-filter redirection lists.
2834
2835 The result of an Exim command that uses -bf, provided no errors are
2836 detected, is a list of the actions that Exim would try to take if presented
2837 with the message for real. More details of filter testing are given in the
2838 separate document entitled Exim's interfaces to mail filtering.
2839
2840 When testing a filter file, the envelope sender can be set by the -f
2841 option, or by a "From " line at the start of the test message. Various
2842 parameters that would normally be taken from the envelope recipient address
2843 of the message can be set by means of additional command line options (see
2844 the next four options).
2845
2846 -bfd <domain>
2847
2848 This sets the domain of the recipient address when a filter file is being
2849 tested by means of the -bf option. The default is the value of
2850 $qualify_domain.
2851
2852 -bfl <local part>
2853
2854 This sets the local part of the recipient address when a filter file is
2855 being tested by means of the -bf option. The default is the username of the
2856 process that calls Exim. A local part should be specified with any prefix
2857 or suffix stripped, because that is how it appears to the filter when a
2858 message is actually being delivered.
2859
2860 -bfp <prefix>
2861
2862 This sets the prefix of the local part of the recipient address when a
2863 filter file is being tested by means of the -bf option. The default is an
2864 empty prefix.
2865
2866 -bfs <suffix>
2867
2868 This sets the suffix of the local part of the recipient address when a
2869 filter file is being tested by means of the -bf option. The default is an
2870 empty suffix.
2871
2872 -bh <IP address>
2873
2874 This option runs a fake SMTP session as if from the given IP address, using
2875 the standard input and output. The IP address may include a port number at
2876 the end, after a full stop. For example:
2877
2878 exim -bh 10.9.8.7.1234
2879 exim -bh fe80::a00:20ff:fe86:a061.5678
2880
2881 When an IPv6 address is given, it is converted into canonical form. In the
2882 case of the second example above, the value of $sender_host_address after
2883 conversion to the canonical form is
2884 "fe80:0000:0000:0a00:20ff:fe86:a061.5678".
2885
2886 Comments as to what is going on are written to the standard error file.
2887 These include lines beginning with "LOG" for anything that would have been
2888 logged. This facility is provided for testing configuration options for
2889 incoming messages, to make sure they implement the required policy. For
2890 example, you can test your relay controls using -bh.
2891
2892 Warning 1: You can test features of the configuration that rely on ident
2893 (RFC 1413) information by using the -oMt option. However, Exim cannot
2894 actually perform an ident callout when testing using -bh because there is
2895 no incoming SMTP connection.
2896
2897 Warning 2: Address verification callouts (see section 43.45) are also
2898 skipped when testing using -bh. If you want these callouts to occur, use
2899 -bhc instead.
2900
2901 Messages supplied during the testing session are discarded, and nothing is
2902 written to any of the real log files. There may be pauses when DNS (and
2903 other) lookups are taking place, and of course these may time out. The -oMi
2904 option can be used to specify a specific IP interface and port if this is
2905 important, and -oMaa and -oMai can be used to set parameters as if the SMTP
2906 session were authenticated.
2907
2908 The exim_checkaccess utility is a "packaged" version of -bh whose output
2909 just states whether a given recipient address from a given host is
2910 acceptable or not. See section 53.8.
2911
2912 Features such as authentication and encryption, where the client input is
2913 not plain text, cannot easily be tested with -bh. Instead, you should use a
2914 specialized SMTP test program such as swaks.
2915
2916 -bhc <IP address>
2917
2918 This option operates in the same way as -bh, except that address
2919 verification callouts are performed if required. This includes consulting
2920 and updating the callout cache database.
2921
2922 -bi
2923
2924 Sendmail interprets the -bi option as a request to rebuild its alias file.
2925 Exim does not have the concept of a single alias file, and so it cannot
2926 mimic this behaviour. However, calls to /usr/lib/sendmail with the -bi
2927 option tend to appear in various scripts such as NIS make files, so the
2928 option must be recognized.
2929
2930 If -bi is encountered, the command specified by the bi_command
2931 configuration option is run, under the uid and gid of the caller of Exim.
2932 If the -oA option is used, its value is passed to the command as an
2933 argument. The command set by bi_command may not contain arguments. The
2934 command can use the exim_dbmbuild utility, or some other means, to rebuild
2935 alias files if this is required. If the bi_command option is not set,
2936 calling Exim with -bi is a no-op.
2937
2938 -bI:help
2939
2940 We shall provide various options starting "-bI:" for querying Exim for
2941 information. The output of many of these will be intended for machine
2942 consumption. This one is not. The -bI:help option asks Exim for a synopsis
2943 of supported options beginning "-bI:". Use of any of these options shall
2944 cause Exim to exit after producing the requested output.
2945
2946 -bI:dscp
2947
2948 This option causes Exim to emit an alphabetically sorted list of all
2949 recognised DSCP names.
2950
2951 -bI:sieve
2952
2953 This option causes Exim to emit an alphabetically sorted list of all
2954 supported Sieve protocol extensions on stdout, one per line. This is
2955 anticipated to be useful for ManageSieve (RFC 5804) implementations, in
2956 providing that protocol's "SIEVE" capability response line. As the precise
2957 list may depend upon compile-time build options, which this option will
2958 adapt to, this is the only way to guarantee a correct response.
2959
2960 -bm
2961
2962 This option runs an Exim receiving process that accepts an incoming,
2963 locally-generated message on the standard input. The recipients are given
2964 as the command arguments (except when -t is also present - see below). Each
2965 argument can be a comma-separated list of RFC 2822 addresses. This is the
2966 default option for selecting the overall action of an Exim call; it is
2967 assumed if no other conflicting option is present.
2968
2969 If any addresses in the message are unqualified (have no domain), they are
2970 qualified by the values of the qualify_domain or qualify_recipient options,
2971 as appropriate. The -bnq option (see below) provides a way of suppressing
2972 this for special cases.
2973
2974 Policy checks on the contents of local messages can be enforced by means of
2975 the non-SMTP ACL. See chapter 43 for details.
2976
2977 The return code is zero if the message is successfully accepted. Otherwise,
2978 the action is controlled by the -oex option setting - see below.
2979
2980 The format of the message must be as defined in RFC 2822, except that, for
2981 compatibility with Sendmail and Smail, a line in one of the forms
2982
2983 From sender Fri Jan 5 12:55 GMT 1997
2984 From sender Fri, 5 Jan 97 12:55:01
2985
2986 (with the weekday optional, and possibly with additional text after the
2987 date) is permitted to appear at the start of the message. There appears to
2988 be no authoritative specification of the format of this line. Exim
2989 recognizes it by matching against the regular expression defined by the
2990 uucp_from_pattern option, which can be changed if necessary.
2991
2992 The specified sender is treated as if it were given as the argument to the
2993 -f option, but if a -f option is also present, its argument is used in
2994 preference to the address taken from the message. The caller of Exim must
2995 be a trusted user for the sender of a message to be set in this way.
2996
2997 -bmalware <filename>
2998
2999 This debugging option causes Exim to scan the given file or directory
3000 (depending on the used scanner interface), using the malware scanning
3001 framework. The option of av_scanner influences this option, so if
3002 av_scanner's value is dependent upon an expansion then the expansion should
3003 have defaults which apply to this invocation. ACLs are not invoked, so if
3004 av_scanner references an ACL variable then that variable will never be
3005 populated and -bmalware will fail.
3006
3007 Exim will have changed working directory before resolving the filename, so
3008 using fully qualified pathnames is advisable. Exim will be running as the
3009 Exim user when it tries to open the file, rather than as the invoking user.
3010 This option requires admin privileges.
3011
3012 The -bmalware option will not be extended to be more generally useful,
3013 there are better tools for file-scanning. This option exists to help
3014 administrators verify their Exim and AV scanner configuration.
3015
3016 -bnq
3017
3018 By default, Exim automatically qualifies unqualified addresses (those
3019 without domains) that appear in messages that are submitted locally (that
3020 is, not over TCP/IP). This qualification applies both to addresses in
3021 envelopes, and addresses in header lines. Sender addresses are qualified
3022 using qualify_domain, and recipient addresses using qualify_recipient
3023 (which defaults to the value of qualify_domain).
3024
3025 Sometimes, qualification is not wanted. For example, if -bS (batch SMTP) is
3026 being used to re-submit messages that originally came from remote hosts
3027 after content scanning, you probably do not want to qualify unqualified
3028 addresses in header lines. (Such lines will be present only if you have not
3029 enabled a header syntax check in the appropriate ACL.)
3030
3031 The -bnq option suppresses all qualification of unqualified addresses in
3032 messages that originate on the local host. When this is used, unqualified
3033 addresses in the envelope provoke errors (causing message rejection) and
3034 unqualified addresses in header lines are left alone.
3035
3036 -bP
3037
3038 If this option is given with no arguments, it causes the values of all
3039 Exim's main configuration options to be written to the standard output. The
3040 values of one or more specific options can be requested by giving their
3041 names as arguments, for example:
3042
3043 exim -bP qualify_domain hold_domains
3044
3045 However, any option setting that is preceded by the word "hide" in the
3046 configuration file is not shown in full, except to an admin user. For other
3047 users, the output is as in this example:
3048
3049 mysql_servers = <value not displayable>
3050
3051 If config is given as an argument, the config is output, as it was parsed,
3052 any include file resolved, any comment removed.
3053
3054 If config_file is given as an argument, the name of the run time
3055 configuration file is output. (configure_file works too, for backward
3056 compatibility.) If a list of configuration files was supplied, the value
3057 that is output here is the name of the file that was actually used.
3058
3059 If the -n flag is given, then for most modes of -bP operation the name will
3060 not be output.
3061
3062 If log_file_path or pid_file_path are given, the names of the directories
3063 where log files and daemon pid files are written are output, respectively.
3064 If these values are unset, log files are written in a sub-directory of the
3065 spool directory called log, and the pid file is written directly into the
3066 spool directory.
3067
3068 If -bP is followed by a name preceded by "+", for example,
3069
3070 exim -bP +local_domains
3071
3072 it searches for a matching named list of any type (domain, host, address,
3073 or local part) and outputs what it finds.
3074
3075 If one of the words router, transport, or authenticator is given, followed
3076 by the name of an appropriate driver instance, the option settings for that
3077 driver are output. For example:
3078
3079 exim -bP transport local_delivery
3080
3081 The generic driver options are output first, followed by the driver's
3082 private options. A list of the names of drivers of a particular type can be
3083 obtained by using one of the words router_list, transport_list, or
3084 authenticator_list, and a complete list of all drivers with their option
3085 settings can be obtained by using routers, transports, or authenticators.
3086
3087 If environment is given as an argument, the set of environment variables is
3088 output, line by line. Using the -n flag suppresses the value of the
3089 variables.
3090
3091 If invoked by an admin user, then macro, macro_list and macros are
3092 available, similarly to the drivers. Because macros are sometimes used for
3093 storing passwords, this option is restricted. The output format is one item
3094 per line.
3095
3096 -bp
3097
3098 This option requests a listing of the contents of the mail queue on the
3099 standard output. If the -bp option is followed by a list of message ids,
3100 just those messages are listed. By default, this option can be used only by
3101 an admin user. However, the queue_list_requires_admin option can be set
3102 false to allow any user to see the queue.
3103
3104 Each message on the queue is displayed as in the following example:
3105
3106 25m 2.9K 0t5C6f-0000c8-00 <alice@wonderland.fict.example>
3107 red.king@looking-glass.fict.example
3108 <other addresses>
3109
3110 The first line contains the length of time the message has been on the
3111 queue (in this case 25 minutes), the size of the message (2.9K), the unique
3112 local identifier for the message, and the message sender, as contained in
3113 the envelope. For bounce messages, the sender address is empty, and appears
3114 as "<>". If the message was submitted locally by an untrusted user who
3115 overrode the default sender address, the user's login name is shown in
3116 parentheses before the sender address.
3117
3118 If the message is frozen (attempts to deliver it are suspended) then the
3119 text "*** frozen ***" is displayed at the end of this line.
3120
3121 The recipients of the message (taken from the envelope, not the headers)
3122 are displayed on subsequent lines. Those addresses to which the message has
3123 already been delivered are marked with the letter D. If an original address
3124 gets expanded into several addresses via an alias or forward file, the
3125 original is displayed with a D only when deliveries for all of its child
3126 addresses are complete.
3127
3128 -bpa
3129
3130 This option operates like -bp, but in addition it shows delivered addresses
3131 that were generated from the original top level address(es) in each message
3132 by alias or forwarding operations. These addresses are flagged with "+D"
3133 instead of just "D".
3134
3135 -bpc
3136
3137 This option counts the number of messages on the queue, and writes the
3138 total to the standard output. It is restricted to admin users, unless
3139 queue_list_requires_admin is set false.
3140
3141 -bpr
3142
3143 This option operates like -bp, but the output is not sorted into
3144 chronological order of message arrival. This can speed it up when there are
3145 lots of messages on the queue, and is particularly useful if the output is
3146 going to be post-processed in a way that doesn't need the sorting.
3147
3148 -bpra
3149
3150 This option is a combination of -bpr and -bpa.
3151
3152 -bpru
3153
3154 This option is a combination of -bpr and -bpu.
3155
3156 -bpu
3157
3158 This option operates like -bp but shows only undelivered top-level
3159 addresses for each message displayed. Addresses generated by aliasing or
3160 forwarding are not shown, unless the message was deferred after processing
3161 by a router with the one_time option set.
3162
3163 -brt
3164
3165 This option is for testing retry rules, and it must be followed by up to
3166 three arguments. It causes Exim to look for a retry rule that matches the
3167 values and to write it to the standard output. For example:
3168
3169 exim -brt bach.comp.mus.example
3170 Retry rule: *.comp.mus.example F,2h,15m; F,4d,30m;
3171
3172 See chapter 32 for a description of Exim's retry rules. The first argument,
3173 which is required, can be a complete address in the form local_part@domain,
3174 or it can be just a domain name. If the second argument contains a dot, it
3175 is interpreted as an optional second domain name; if no retry rule is found
3176 for the first argument, the second is tried. This ties in with Exim's
3177 behaviour when looking for retry rules for remote hosts - if no rule is
3178 found that matches the host, one that matches the mail domain is sought.
3179 Finally, an argument that is the name of a specific delivery error, as used
3180 in setting up retry rules, can be given. For example:
3181
3182 exim -brt haydn.comp.mus.example quota_3d
3183 Retry rule: *@haydn.comp.mus.example quota_3d F,1h,15m
3184
3185 -brw
3186
3187 This option is for testing address rewriting rules, and it must be followed
3188 by a single argument, consisting of either a local part without a domain,
3189 or a complete address with a fully qualified domain. Exim outputs how this
3190 address would be rewritten for each possible place it might appear. See
3191 chapter 31 for further details.
3192
3193 -bS
3194
3195 This option is used for batched SMTP input, which is an alternative
3196 interface for non-interactive local message submission. A number of
3197 messages can be submitted in a single run. However, despite its name, this
3198 is not really SMTP input. Exim reads each message's envelope from SMTP
3199 commands on the standard input, but generates no responses. If the caller
3200 is trusted, or untrusted_set_sender is set, the senders in the SMTP MAIL
3201 commands are believed; otherwise the sender is always the caller of Exim.
3202
3203 The message itself is read from the standard input, in SMTP format (leading
3204 dots doubled), terminated by a line containing just a single dot. An error
3205 is provoked if the terminating dot is missing. A further message may then
3206 follow.
3207
3208 As for other local message submissions, the contents of incoming batch SMTP
3209 messages can be checked using the non-SMTP ACL (see chapter 43).
3210 Unqualified addresses are automatically qualified using qualify_domain and
3211 qualify_recipient, as appropriate, unless the -bnq option is used.
3212
3213 Some other SMTP commands are recognized in the input. HELO and EHLO act as
3214 RSET; VRFY, EXPN, ETRN, and HELP act as NOOP; QUIT quits, ignoring the rest
3215 of the standard input.
3216
3217 If any error is encountered, reports are written to the standard output and
3218 error streams, and Exim gives up immediately. The return code is 0 if no
3219 error was detected; it is 1 if one or more messages were accepted before
3220 the error was detected; otherwise it is 2.
3221
3222 More details of input using batched SMTP are given in section 48.11.
3223
3224 -bs
3225
3226 This option causes Exim to accept one or more messages by reading SMTP
3227 commands on the standard input, and producing SMTP replies on the standard
3228 output. SMTP policy controls, as defined in ACLs (see chapter 43) are
3229 applied. Some user agents use this interface as a way of passing
3230 locally-generated messages to the MTA.
3231
3232 In this usage, if the caller of Exim is trusted, or untrusted_set_sender is
3233 set, the senders of messages are taken from the SMTP MAIL commands.
3234 Otherwise the content of these commands is ignored and the sender is set up
3235 as the calling user. Unqualified addresses are automatically qualified
3236 using qualify_domain and qualify_recipient, as appropriate, unless the -bnq
3237 option is used.
3238
3239 The -bs option is also used to run Exim from inetd, as an alternative to
3240 using a listening daemon. Exim can distinguish the two cases by checking
3241 whether the standard input is a TCP/IP socket. When Exim is called from
3242 inetd, the source of the mail is assumed to be remote, and the comments
3243 above concerning senders and qualification do not apply. In this situation,
3244 Exim behaves in exactly the same way as it does when receiving a message
3245 via the listening daemon.
3246
3247 -bt
3248
3249 This option runs Exim in address testing mode, in which each argument is
3250 taken as a recipient address to be tested for deliverability. The results
3251 are written to the standard output. If a test fails, and the caller is not
3252 an admin user, no details of the failure are output, because these might
3253 contain sensitive information such as usernames and passwords for database
3254 lookups.
3255
3256 If no arguments are given, Exim runs in an interactive manner, prompting
3257 with a right angle bracket for addresses to be tested.
3258
3259 Unlike the -be test option, you cannot arrange for Exim to use the readline
3260 () function, because it is running as root and there are security issues.
3261
3262 Each address is handled as if it were the recipient address of a message
3263 (compare the -bv option). It is passed to the routers and the result is
3264 written to the standard output. However, any router that has
3265 no_address_test set is bypassed. This can make -bt easier to use for
3266 genuine routing tests if your first router passes everything to a scanner
3267 program.
3268
3269 The return code is 2 if any address failed outright; it is 1 if no address
3270 failed outright but at least one could not be resolved for some reason.
3271 Return code 0 is given only when all addresses succeed.
3272
3273 Note: When actually delivering a message, Exim removes duplicate recipient
3274 addresses after routing is complete, so that only one delivery takes place.
3275 This does not happen when testing with -bt; the full results of routing are
3276 always shown.
3277
3278 Warning: -bt can only do relatively simple testing. If any of the routers
3279 in the configuration makes any tests on the sender address of a message,
3280 you can use the -f option to set an appropriate sender when running -bt
3281 tests. Without it, the sender is assumed to be the calling user at the
3282 default qualifying domain. However, if you have set up (for example)
3283 routers whose behaviour depends on the contents of an incoming message, you
3284 cannot test those conditions using -bt. The -N option provides a possible
3285 way of doing such tests.
3286
3287 -bV
3288
3289 This option causes Exim to write the current version number, compilation
3290 number, and compilation date of the exim binary to the standard output. It
3291 also lists the DBM library that is being used, the optional modules (such
3292 as specific lookup types), the drivers that are included in the binary, and
3293 the name of the run time configuration file that is in use.
3294
3295 As part of its operation, -bV causes Exim to read and syntax check its
3296 configuration file. However, this is a static check only. It cannot check
3297 values that are to be expanded. For example, although a misspelt ACL verb
3298 is detected, an error in the verb's arguments is not. You cannot rely on
3299 -bV alone to discover (for example) all the typos in the configuration;
3300 some realistic testing is needed. The -bh and -N options provide more
3301 dynamic testing facilities.
3302
3303 -bv
3304
3305 This option runs Exim in address verification mode, in which each argument
3306 is taken as a recipient address to be verified by the routers. (This does
3307 not involve any verification callouts). During normal operation,
3308 verification happens mostly as a consequence processing a verify condition
3309 in an ACL (see chapter 43). If you want to test an entire ACL, possibly
3310 including callouts, see the -bh and -bhc options.
3311
3312 If verification fails, and the caller is not an admin user, no details of
3313 the failure are output, because these might contain sensitive information
3314 such as usernames and passwords for database lookups.
3315
3316 If no arguments are given, Exim runs in an interactive manner, prompting
3317 with a right angle bracket for addresses to be verified.
3318
3319 Unlike the -be test option, you cannot arrange for Exim to use the readline
3320 () function, because it is running as exim and there are security issues.
3321
3322 Verification differs from address testing (the -bt option) in that routers
3323 that have no_verify set are skipped, and if the address is accepted by a
3324 router that has fail_verify set, verification fails. The address is
3325 verified as a recipient if -bv is used; to test verification for a sender
3326 address, -bvs should be used.
3327
3328 If the -v option is not set, the output consists of a single line for each
3329 address, stating whether it was verified or not, and giving a reason in the
3330 latter case. Without -v, generating more than one address by redirection
3331 causes verification to end successfully, without considering the generated
3332 addresses. However, if just one address is generated, processing continues,
3333 and the generated address must verify successfully for the overall
3334 verification to succeed.
3335
3336 When -v is set, more details are given of how the address has been handled,
3337 and in the case of address redirection, all the generated addresses are
3338 also considered. Verification may succeed for some and fail for others.
3339
3340 The return code is 2 if any address failed outright; it is 1 if no address
3341 failed outright but at least one could not be resolved for some reason.
3342 Return code 0 is given only when all addresses succeed.
3343
3344 If any of the routers in the configuration makes any tests on the sender
3345 address of a message, you should use the -f option to set an appropriate
3346 sender when running -bv tests. Without it, the sender is assumed to be the
3347 calling user at the default qualifying domain.
3348
3349 -bvs
3350
3351 This option acts like -bv, but verifies the address as a sender rather than
3352 a recipient address. This affects any rewriting and qualification that
3353 might happen.
3354
3355 -bw
3356
3357 This option runs Exim as a daemon, awaiting incoming SMTP connections,
3358 similarly to the -bd option. All port specifications on the command-line
3359 and in the configuration file are ignored. Queue-running may not be
3360 specified.
3361
3362 In this mode, Exim expects to be passed a socket as fd 0 (stdin) which is
3363 listening for connections. This permits the system to start up and have
3364 inetd (or equivalent) listen on the SMTP ports, starting an Exim daemon for
3365 each port only when the first connection is received.
3366
3367 If the option is given as -bw<time> then the time is a timeout, after which
3368 the daemon will exit, which should cause inetd to listen once more.
3369
3370 -C <filelist>
3371
3372 This option causes Exim to find the run time configuration file from the
3373 given list instead of from the list specified by the CONFIGURE_FILE
3374 compile-time setting. Usually, the list will consist of just a single file
3375 name, but it can be a colon-separated list of names. In this case, the
3376 first file that exists is used. Failure to open an existing file stops Exim
3377 from proceeding any further along the list, and an error is generated.
3378
3379 When this option is used by a caller other than root, and the list is
3380 different from the compiled-in list, Exim gives up its root privilege
3381 immediately, and runs with the real and effective uid and gid set to those
3382 of the caller. However, if a TRUSTED_CONFIG_LIST file is defined in Local/
3383 Makefile, that file contains a list of full pathnames, one per line, for
3384 configuration files which are trusted. Root privilege is retained for any
3385 configuration file so listed, as long as the caller is the Exim user (or
3386 the user specified in the CONFIGURE_OWNER option, if any), and as long as
3387 the configuration file is not writeable by inappropriate users or groups.
3388
3389 Leaving TRUSTED_CONFIG_LIST unset precludes the possibility of testing a
3390 configuration using -C right through message reception and delivery, even
3391 if the caller is root. The reception works, but by that time, Exim is
3392 running as the Exim user, so when it re-executes to regain privilege for
3393 the delivery, the use of -C causes privilege to be lost. However, root can
3394 test reception and delivery using two separate commands (one to put a
3395 message on the queue, using -odq, and another to do the delivery, using -M
3396 ).
3397
3398 If ALT_CONFIG_PREFIX is defined in Local/Makefile, it specifies a prefix
3399 string with which any file named in a -C command line option must start. In
3400 addition, the file name must not contain the sequence "/../". However, if
3401 the value of the -C option is identical to the value of CONFIGURE_FILE in
3402 Local/Makefile, Exim ignores -C and proceeds as usual. There is no default
3403 setting for ALT_CONFIG_PREFIX; when it is unset, any file name can be used
3404 with -C.
3405
3406 ALT_CONFIG_PREFIX can be used to confine alternative configuration files to
3407 a directory to which only root has access. This prevents someone who has
3408 broken into the Exim account from running a privileged Exim with an
3409 arbitrary configuration file.
3410
3411 The -C facility is useful for ensuring that configuration files are
3412 syntactically correct, but cannot be used for test deliveries, unless the
3413 caller is privileged, or unless it is an exotic configuration that does not
3414 require privilege. No check is made on the owner or group of the files
3415 specified by this option.
3416
3417 -D<macro>=<value>
3418
3419 This option can be used to override macro definitions in the configuration
3420 file (see section 6.4). However, like -C, if it is used by an unprivileged
3421 caller, it causes Exim to give up its root privilege. If DISABLE_D_OPTION
3422 is defined in Local/Makefile, the use of -D is completely disabled, and its
3423 use causes an immediate error exit.
3424
3425 If WHITELIST_D_MACROS is defined in Local/Makefile then it should be a
3426 colon-separated list of macros which are considered safe and, if -D only
3427 supplies macros from this list, and the values are acceptable, then Exim
3428 will not give up root privilege if the caller is root, the Exim run-time
3429 user, or the CONFIGURE_OWNER, if set. This is a transition mechanism and is
3430 expected to be removed in the future. Acceptable values for the macros
3431 satisfy the regexp: "^[A-Za-z0-9_/.-]*$"
3432
3433 The entire option (including equals sign if present) must all be within one
3434 command line item. -D can be used to set the value of a macro to the empty
3435 string, in which case the equals sign is optional. These two commands are
3436 synonymous:
3437
3438 exim -DABC ...
3439 exim -DABC= ...
3440
3441 To include spaces in a macro definition item, quotes must be used. If you
3442 use quotes, spaces are permitted around the macro name and the equals sign.
3443 For example:
3444
3445 exim '-D ABC = something' ...
3446
3447 -D may be repeated up to 10 times on a command line. Only macro names up to
3448 22 letters long can be set.
3449
3450 -d<debug options>
3451
3452 This option causes debugging information to be written to the standard
3453 error stream. It is restricted to admin users because debugging output may
3454 show database queries that contain password information. Also, the details
3455 of users' filter files should be protected. If a non-admin user uses -d,
3456 Exim writes an error message to the standard error stream and exits with a
3457 non-zero return code.
3458
3459 When -d is used, -v is assumed. If -d is given on its own, a lot of
3460 standard debugging data is output. This can be reduced, or increased to
3461 include some more rarely needed information, by directly following -d with
3462 a string made up of names preceded by plus or minus characters. These add
3463 or remove sets of debugging data, respectively. For example, -d+filter adds
3464 filter debugging, whereas -d-all+filter selects only filter debugging. Note
3465 that no spaces are allowed in the debug setting. The available debugging
3466 categories are:
3467
3468 acl ACL interpretation
3469 auth authenticators
3470 deliver general delivery logic
3471 dns DNS lookups (see also resolver)
3472 dnsbl DNS black list (aka RBL) code
3473 exec arguments for execv() calls
3474 expand detailed debugging for string expansions
3475 filter filter handling
3476 hints_lookup hints data lookups
3477 host_lookup all types of name-to-IP address handling
3478 ident ident lookup
3479 interface lists of local interfaces
3480 lists matching things in lists
3481 load system load checks
3482 local_scan can be used by local_scan() (see chapter 45)
3483 lookup general lookup code and all lookups
3484 memory memory handling
3485 pid add pid to debug output lines
3486 process_info setting info for the process log
3487 queue_run queue runs
3488 receive general message reception logic
3489 resolver turn on the DNS resolver's debugging output
3490 retry retry handling
3491 rewrite address rewriting
3492 route address routing
3493 timestamp add timestamp to debug output lines
3494 tls TLS logic
3495 transport transports
3496 uid changes of uid/gid and looking up uid/gid
3497 verify address verification logic
3498 all almost all of the above (see below), and also -v
3499
3500 The "all" option excludes "memory" when used as "+all", but includes it for
3501 "-all". The reason for this is that "+all" is something that people tend to
3502 use when generating debug output for Exim maintainers. If "+memory" is
3503 included, an awful lot of output that is very rarely of interest is
3504 generated, so it now has to be explicitly requested. However, "-all" does
3505 turn everything off.
3506
3507 The "resolver" option produces output only if the DNS resolver was compiled
3508 with DEBUG enabled. This is not the case in some operating systems. Also,
3509 unfortunately, debugging output from the DNS resolver is written to stdout
3510 rather than stderr.
3511
3512 The default (-d with no argument) omits "expand", "filter", "interface",
3513 "load", "memory", "pid", "resolver", and "timestamp". However, the "pid"
3514 selector is forced when debugging is turned on for a daemon, which then
3515 passes it on to any re-executed Exims. Exim also automatically adds the pid
3516 to debug lines when several remote deliveries are run in parallel.
3517
3518 The "timestamp" selector causes the current time to be inserted at the
3519 start of all debug output lines. This can be useful when trying to track
3520 down delays in processing.
3521
3522 If the debug_print option is set in any driver, it produces output whenever
3523 any debugging is selected, or if -v is used.
3524
3525 -dd<debug options>
3526
3527 This option behaves exactly like -d except when used on a command that
3528 starts a daemon process. In that case, debugging is turned off for the
3529 subprocesses that the daemon creates. Thus, it is useful for monitoring the
3530 behaviour of the daemon without creating as much output as full debugging
3531 does.
3532
3533 -dropcr
3534
3535 This is an obsolete option that is now a no-op. It used to affect the way
3536 Exim handled CR and LF characters in incoming messages. What happens now is
3537 described in section 47.2.
3538
3539 -E
3540
3541 This option specifies that an incoming message is a locally-generated
3542 delivery failure report. It is used internally by Exim when handling
3543 delivery failures and is not intended for external use. Its only effect is
3544 to stop Exim generating certain messages to the postmaster, as otherwise
3545 message cascades could occur in some situations. As part of the same
3546 option, a message id may follow the characters -E. If it does, the log
3547 entry for the receipt of the new message contains the id, following "R=",
3548 as a cross-reference.
3549
3550 -ex
3551
3552 There are a number of Sendmail options starting with -oe which seem to be
3553 called by various programs without the leading o in the option. For
3554 example, the vacation program uses -eq. Exim treats all options of the form
3555 -ex as synonymous with the corresponding -oex options.
3556
3557 -F <string>
3558
3559 This option sets the sender's full name for use when a locally-generated
3560 message is being accepted. In the absence of this option, the user's gecos
3561 entry from the password data is used. As users are generally permitted to
3562 alter their gecos entries, no security considerations are involved. White
3563 space between -F and the <string> is optional.
3564
3565 -f <address>
3566
3567 This option sets the address of the envelope sender of a locally-generated
3568 message (also known as the return path). The option can normally be used
3569 only by a trusted user, but untrusted_set_sender can be set to allow
3570 untrusted users to use it.
3571
3572 Processes running as root or the Exim user are always trusted. Other
3573 trusted users are defined by the trusted_users or trusted_groups options.
3574 In the absence of -f, or if the caller is not trusted, the sender of a
3575 local message is set to the caller's login name at the default qualify
3576 domain.
3577
3578 There is one exception to the restriction on the use of -f: an empty sender
3579 can be specified by any user, trusted or not, to create a message that can
3580 never provoke a bounce. An empty sender can be specified either as an empty
3581 string, or as a pair of angle brackets with nothing between them, as in
3582 these examples of shell commands:
3583
3584 exim -f '<>' user@domain
3585 exim -f "" user@domain
3586
3587 In addition, the use of -f is not restricted when testing a filter file
3588 with -bf or when testing or verifying addresses using the -bt or -bv
3589 options.
3590
3591 Allowing untrusted users to change the sender address does not of itself
3592 make it possible to send anonymous mail. Exim still checks that the From:
3593 header refers to the local user, and if it does not, it adds a Sender:
3594 header, though this can be overridden by setting no_local_from_check.
3595
3596 White space between -f and the <address> is optional (that is, they can be
3597 given as two arguments or one combined argument). The sender of a
3598 locally-generated message can also be set (when permitted) by an initial
3599 "From " line in the message - see the description of -bm above - but if -f
3600 is also present, it overrides "From ".
3601
3602 -G
3603
3604 This option is equivalent to an ACL applying:
3605
3606 control = suppress_local_fixups
3607
3608 for every message received. Note that Sendmail will complain about such bad
3609 formatting, where Exim silently just does not fix it up. This may change in
3610 future.
3611
3612 As this affects audit information, the caller must be a trusted user to use
3613 this option.
3614
3615 -h <number>
3616
3617 This option is accepted for compatibility with Sendmail, but has no effect.
3618 (In Sendmail it overrides the "hop count" obtained by counting Received:
3619 headers.)
3620
3621 -i
3622
3623 This option, which has the same effect as -oi, specifies that a dot on a
3624 line by itself should not terminate an incoming, non-SMTP message. I can
3625 find no documentation for this option in Solaris 2.4 Sendmail, but the
3626 mailx command in Solaris 2.4 uses it. See also -ti.
3627
3628 -L <tag>
3629
3630 This option is equivalent to setting syslog_processname in the config file
3631 and setting log_file_path to "syslog". Its use is restricted to
3632 administrators. The configuration file has to be read and parsed, to
3633 determine access rights, before this is set and takes effect, so early
3634 configuration file errors will not honour this flag.
3635
3636 The tag should not be longer than 32 characters.
3637
3638 -M <message id> <message id> ...
3639
3640 This option requests Exim to run a delivery attempt on each message in
3641 turn. If any of the messages are frozen, they are automatically thawed
3642 before the delivery attempt. The settings of queue_domains,
3643 queue_smtp_domains, and hold_domains are ignored.
3644
3645 Retry hints for any of the addresses are overridden - Exim tries to deliver
3646 even if the normal retry time has not yet been reached. This option
3647 requires the caller to be an admin user. However, there is an option called
3648 prod_requires_admin which can be set false to relax this restriction (and
3649 also the same requirement for the -q, -R, and -S options).
3650
3651 The deliveries happen synchronously, that is, the original Exim process
3652 does not terminate until all the delivery attempts have finished. No output
3653 is produced unless there is a serious error. If you want to see what is
3654 happening, use the -v option as well, or inspect Exim's main log.
3655
3656 -Mar <message id> <address> <address> ...
3657
3658 This option requests Exim to add the addresses to the list of recipients of
3659 the message ("ar" for "add recipients"). The first argument must be a
3660 message id, and the remaining ones must be email addresses. However, if the
3661 message is active (in the middle of a delivery attempt), it is not altered.
3662 This option can be used only by an admin user.
3663
3664 -MC <transport> <hostname> <sequence number> <message id>
3665
3666 This option is not intended for use by external callers. It is used
3667 internally by Exim to invoke another instance of itself to deliver a
3668 waiting message using an existing SMTP connection, which is passed as the
3669 standard input. Details are given in chapter 48. This must be the final
3670 option, and the caller must be root or the Exim user in order to use it.
3671
3672 -MCA
3673
3674 This option is not intended for use by external callers. It is used
3675 internally by Exim in conjunction with the -MC option. It signifies that
3676 the connection to the remote host has been authenticated.
3677
3678 -MCD
3679
3680 This option is not intended for use by external callers. It is used
3681 internally by Exim in conjunction with the -MC option. It signifies that
3682 the remote host supports the ESMTP DSN extension.
3683
3684 -MCG
3685
3686 This option is not intended for use by external callers. It is used
3687 internally by Exim in conjunction with the -MC option. It signifies that an
3688 alternate queue is used, named by the following option.
3689
3690 -MCP
3691
3692 This option is not intended for use by external callers. It is used
3693 internally by Exim in conjunction with the -MC option. It signifies that
3694 the server to which Exim is connected supports pipelining.
3695
3696 -MCQ <process id> <pipe fd>
3697
3698 This option is not intended for use by external callers. It is used
3699 internally by Exim in conjunction with the -MC option when the original
3700 delivery was started by a queue runner. It passes on the process id of the
3701 queue runner, together with the file descriptor number of an open pipe.
3702 Closure of the pipe signals the final completion of the sequence of
3703 processes that are passing messages through the same SMTP connection.
3704
3705 -MCS
3706
3707 This option is not intended for use by external callers. It is used
3708 internally by Exim in conjunction with the -MC option, and passes on the
3709 fact that the SMTP SIZE option should be used on messages delivered down
3710 the existing connection.
3711
3712 -MCT
3713
3714 This option is not intended for use by external callers. It is used
3715 internally by Exim in conjunction with the -MC option, and passes on the
3716 fact that the host to which Exim is connected supports TLS encryption.
3717
3718 -Mc <message id> <message id> ...
3719
3720 This option requests Exim to run a delivery attempt on each message in
3721 turn, but unlike the -M option, it does check for retry hints, and respects
3722 any that are found. This option is not very useful to external callers. It
3723 is provided mainly for internal use by Exim when it needs to re-invoke
3724 itself in order to regain root privilege for a delivery (see chapter 55).
3725 However, -Mc can be useful when testing, in order to run a delivery that
3726 respects retry times and other options such as hold_domains that are
3727 overridden when -M is used. Such a delivery does not count as a queue run.
3728 If you want to run a specific delivery as if in a queue run, you should use
3729 -q with a message id argument. A distinction between queue run deliveries
3730 and other deliveries is made in one or two places.
3731
3732 -Mes <message id> <address>
3733
3734 This option requests Exim to change the sender address in the message to
3735 the given address, which must be a fully qualified address or "<>" ("es"
3736 for "edit sender"). There must be exactly two arguments. The first argument
3737 must be a message id, and the second one an email address. However, if the
3738 message is active (in the middle of a delivery attempt), its status is not
3739 altered. This option can be used only by an admin user.
3740
3741 -Mf <message id> <message id> ...
3742
3743 This option requests Exim to mark each listed message as "frozen". This
3744 prevents any delivery attempts taking place until the message is "thawed",
3745 either manually or as a result of the auto_thaw configuration option.
3746 However, if any of the messages are active (in the middle of a delivery
3747 attempt), their status is not altered. This option can be used only by an
3748 admin user.
3749
3750 -Mg <message id> <message id> ...
3751
3752 This option requests Exim to give up trying to deliver the listed messages,
3753 including any that are frozen. However, if any of the messages are active,
3754 their status is not altered. For non-bounce messages, a delivery error
3755 message is sent to the sender, containing the text "cancelled by
3756 administrator". Bounce messages are just discarded. This option can be used
3757 only by an admin user.
3758
3759 -Mmad <message id> <message id> ...
3760
3761 This option requests Exim to mark all the recipient addresses in the
3762 messages as already delivered ("mad" for "mark all delivered"). However, if
3763 any message is active (in the middle of a delivery attempt), its status is
3764 not altered. This option can be used only by an admin user.
3765
3766 -Mmd <message id> <address> <address> ...
3767
3768 This option requests Exim to mark the given addresses as already delivered
3769 ("md" for "mark delivered"). The first argument must be a message id, and
3770 the remaining ones must be email addresses. These are matched to recipient
3771 addresses in the message in a case-sensitive manner. If the message is
3772 active (in the middle of a delivery attempt), its status is not altered.
3773 This option can be used only by an admin user.
3774
3775 -Mrm <message id> <message id> ...
3776
3777 This option requests Exim to remove the given messages from the queue. No
3778 bounce messages are sent; each message is simply forgotten. However, if any
3779 of the messages are active, their status is not altered. This option can be
3780 used only by an admin user or by the user who originally caused the message
3781 to be placed on the queue.
3782
3783 -Mset <message id>
3784
3785 This option is useful only in conjunction with -be (that is, when testing
3786 string expansions). Exim loads the given message from its spool before
3787 doing the test expansions, thus setting message-specific variables such as
3788 $message_size and the header variables. The $recipients variable is made
3789 available. This feature is provided to make it easier to test expansions
3790 that make use of these variables. However, this option can be used only by
3791 an admin user. See also -bem.
3792
3793 -Mt <message id> <message id> ...
3794
3795 This option requests Exim to "thaw" any of the listed messages that are
3796 "frozen", so that delivery attempts can resume. However, if any of the
3797 messages are active, their status is not altered. This option can be used
3798 only by an admin user.
3799
3800 -Mvb <message id>
3801
3802 This option causes the contents of the message body (-D) spool file to be
3803 written to the standard output. This option can be used only by an admin
3804 user.
3805
3806 -Mvc <message id>
3807
3808 This option causes a copy of the complete message (header lines plus body)
3809 to be written to the standard output in RFC 2822 format. This option can be
3810 used only by an admin user.
3811
3812 -Mvh <message id>
3813
3814 This option causes the contents of the message headers (-H) spool file to
3815 be written to the standard output. This option can be used only by an admin
3816 user.
3817
3818 -Mvl <message id>
3819
3820 This option causes the contents of the message log spool file to be written
3821 to the standard output. This option can be used only by an admin user.
3822
3823 -m
3824
3825 This is apparently a synonym for -om that is accepted by Sendmail, so Exim
3826 treats it that way too.
3827
3828 -N
3829
3830 This is a debugging option that inhibits delivery of a message at the
3831 transport level. It implies -v. Exim goes through many of the motions of
3832 delivery - it just doesn't actually transport the message, but instead
3833 behaves as if it had successfully done so. However, it does not make any
3834 updates to the retry database, and the log entries for deliveries are
3835 flagged with "*>" rather than "=>".
3836
3837 Because -N discards any message to which it applies, only root or the Exim
3838 user are allowed to use it with -bd, -q, -R or -M. In other words, an
3839 ordinary user can use it only when supplying an incoming message to which
3840 it will apply. Although transportation never fails when -N is set, an
3841 address may be deferred because of a configuration problem on a transport,
3842 or a routing problem. Once -N has been used for a delivery attempt, it
3843 sticks to the message, and applies to any subsequent delivery attempts that
3844 may happen for that message.
3845
3846 -n
3847
3848 This option is interpreted by Sendmail to mean "no aliasing". For normal
3849 modes of operation, it is ignored by Exim. When combined with -bP it makes
3850 the output more terse (suppresses option names, environment values and
3851 config pretty printing).
3852
3853 -O <data>
3854
3855 This option is interpreted by Sendmail to mean "set option". It is ignored
3856 by Exim.
3857
3858 -oA <file name>
3859
3860 This option is used by Sendmail in conjunction with -bi to specify an
3861 alternative alias file name. Exim handles -bi differently; see the
3862 description above.
3863
3864 -oB <n>
3865
3866 This is a debugging option which limits the maximum number of messages that
3867 can be delivered down one SMTP connection, overriding the value set in any
3868 smtp transport. If <n> is omitted, the limit is set to 1.
3869
3870 -odb
3871
3872 This option applies to all modes in which Exim accepts incoming messages,
3873 including the listening daemon. It requests "background" delivery of such
3874 messages, which means that the accepting process automatically starts a
3875 delivery process for each message received, but does not wait for the
3876 delivery processes to finish.
3877
3878 When all the messages have been received, the reception process exits,
3879 leaving the delivery processes to finish in their own time. The standard
3880 output and error streams are closed at the start of each delivery process.
3881 This is the default action if none of the -od options are present.
3882
3883 If one of the queueing options in the configuration file (queue_only or
3884 queue_only_file, for example) is in effect, -odb overrides it if
3885 queue_only_override is set true, which is the default setting. If
3886 queue_only_override is set false, -odb has no effect.
3887
3888 -odf
3889
3890 This option requests "foreground" (synchronous) delivery when Exim has
3891 accepted a locally-generated message. (For the daemon it is exactly the
3892 same as -odb.) A delivery process is automatically started to deliver the
3893 message, and Exim waits for it to complete before proceeding.
3894
3895 The original Exim reception process does not finish until the delivery
3896 process for the final message has ended. The standard error stream is left
3897 open during deliveries.
3898
3899 However, like -odb, this option has no effect if queue_only_override is
3900 false and one of the queueing options in the configuration file is in
3901 effect.
3902
3903 If there is a temporary delivery error during foreground delivery, the
3904 message is left on the queue for later delivery, and the original reception
3905 process exits. See chapter 51 for a way of setting up a restricted
3906 configuration that never queues messages.
3907
3908 -odi
3909
3910 This option is synonymous with -odf. It is provided for compatibility with
3911 Sendmail.
3912
3913 -odq
3914
3915 This option applies to all modes in which Exim accepts incoming messages,
3916 including the listening daemon. It specifies that the accepting process
3917 should not automatically start a delivery process for each message
3918 received. Messages are placed on the queue, and remain there until a
3919 subsequent queue runner process encounters them. There are several
3920 configuration options (such as queue_only) that can be used to queue
3921 incoming messages under certain conditions. This option overrides all of
3922 them and also -odqs. It always forces queueing.
3923
3924 -odqs
3925
3926 This option is a hybrid between -odb/-odi and -odq. However, like -odb and
3927 -odi, this option has no effect if queue_only_override is false and one of
3928 the queueing options in the configuration file is in effect.
3929
3930 When -odqs does operate, a delivery process is started for each incoming
3931 message, in the background by default, but in the foreground if -odi is
3932 also present. The recipient addresses are routed, and local deliveries are
3933 done in the normal way. However, if any SMTP deliveries are required, they
3934 are not done at this time, so the message remains on the queue until a
3935 subsequent queue runner process encounters it. Because routing was done,
3936 Exim knows which messages are waiting for which hosts, and so a number of
3937 messages for the same host can be sent in a single SMTP connection. The
3938 queue_smtp_domains configuration option has the same effect for specific
3939 domains. See also the -qq option.
3940
3941 -oee
3942
3943 If an error is detected while a non-SMTP message is being received (for
3944 example, a malformed address), the error is reported to the sender in a
3945 mail message.
3946
3947 Provided this error message is successfully sent, the Exim receiving
3948 process exits with a return code of zero. If not, the return code is 2 if
3949 the problem is that the original message has no recipients, or 1 for any
3950 other error. This is the default -oex option if Exim is called as rmail.
3951
3952 -oem
3953
3954 This is the same as -oee, except that Exim always exits with a non-zero
3955 return code, whether or not the error message was successfully sent. This
3956 is the default -oex option, unless Exim is called as rmail.
3957
3958 -oep
3959
3960 If an error is detected while a non-SMTP message is being received, the
3961 error is reported by writing a message to the standard error file (stderr).
3962 The return code is 1 for all errors.
3963
3964 -oeq
3965
3966 This option is supported for compatibility with Sendmail, but has the same
3967 effect as -oep.
3968
3969 -oew
3970
3971 This option is supported for compatibility with Sendmail, but has the same
3972 effect as -oem.
3973
3974 -oi
3975
3976 This option, which has the same effect as -i, specifies that a dot on a
3977 line by itself should not terminate an incoming, non-SMTP message.
3978 Otherwise, a single dot does terminate, though Exim does no special
3979 processing for other lines that start with a dot. This option is set by
3980 default if Exim is called as rmail. See also -ti.
3981
3982 -oitrue
3983
3984 This option is treated as synonymous with -oi.
3985
3986 -oMa <host address>
3987
3988 A number of options starting with -oM can be used to set values associated
3989 with remote hosts on locally-submitted messages (that is, messages not
3990 received over TCP/IP). These options can be used by any caller in
3991 conjunction with the -bh, -be, -bf, -bF, -bt, or -bv testing options. In
3992 other circumstances, they are ignored unless the caller is trusted.
3993
3994 The -oMa option sets the sender host address. This may include a port
3995 number at the end, after a full stop (period). For example:
3996
3997 exim -bs -oMa 10.9.8.7.1234
3998
3999 An alternative syntax is to enclose the IP address in square brackets,
4000 followed by a colon and the port number:
4001
4002 exim -bs -oMa [10.9.8.7]:1234
4003
4004 The IP address is placed in the $sender_host_address variable, and the
4005 port, if present, in $sender_host_port. If both -oMa and -bh are present on
4006 the command line, the sender host IP address is taken from whichever one is
4007 last.
4008
4009 -oMaa <name>
4010
4011 See -oMa above for general remarks about the -oM options. The -oMaa option
4012 sets the value of $sender_host_authenticated (the authenticator name). See
4013 chapter 33 for a discussion of SMTP authentication. This option can be used
4014 with -bh and -bs to set up an authenticated SMTP session without actually
4015 using the SMTP AUTH command.
4016
4017 -oMai <string>
4018
4019 See -oMa above for general remarks about the -oM options. The -oMai option
4020 sets the value of $authenticated_id (the id that was authenticated). This
4021 overrides the default value (the caller's login id, except with -bh, where
4022 there is no default) for messages from local sources. See chapter 33 for a
4023 discussion of authenticated ids.
4024
4025 -oMas <address>
4026
4027 See -oMa above for general remarks about the -oM options. The -oMas option
4028 sets the authenticated sender value in $authenticated_sender. It overrides
4029 the sender address that is created from the caller's login id for messages
4030 from local sources, except when -bh is used, when there is no default. For
4031 both -bh and -bs, an authenticated sender that is specified on a MAIL
4032 command overrides this value. See chapter 33 for a discussion of
4033 authenticated senders.
4034
4035 -oMi <interface address>
4036
4037 See -oMa above for general remarks about the -oM options. The -oMi option
4038 sets the IP interface address value. A port number may be included, using
4039 the same syntax as for -oMa. The interface address is placed in
4040 $received_ip_address and the port number, if present, in $received_port.
4041
4042 -oMm <message reference>
4043
4044 See -oMa above for general remarks about the -oM options. The -oMm option
4045 sets the message reference, e.g. message-id, and is logged during delivery.
4046 This is useful when some kind of audit trail is required to tie messages
4047 together. The format of the message reference is checked and will abort if
4048 the format is invalid. The option will only be accepted if exim is running
4049 in trusted mode, not as any regular user.
4050
4051 The best example of a message reference is when Exim sends a bounce
4052 message. The message reference is the message-id of the original message
4053 for which Exim is sending the bounce.
4054
4055 -oMr <protocol name>
4056
4057 See -oMa above for general remarks about the -oM options. The -oMr option
4058 sets the received protocol value that is stored in $received_protocol.
4059 However, it does not apply (and is ignored) when -bh or -bs is used. For
4060 -bh, the protocol is forced to one of the standard SMTP protocol names (see
4061 the description of $received_protocol in section 11.9). For -bs, the
4062 protocol is always "local-" followed by one of those same names. For -bS
4063 (batched SMTP) however, the protocol can be set by -oMr.
4064
4065 -oMs <host name>
4066
4067 See -oMa above for general remarks about the -oM options. The -oMs option
4068 sets the sender host name in $sender_host_name. When this option is
4069 present, Exim does not attempt to look up a host name from an IP address;
4070 it uses the name it is given.
4071
4072 -oMt <ident string>
4073
4074 See -oMa above for general remarks about the -oM options. The -oMt option
4075 sets the sender ident value in $sender_ident. The default setting for local
4076 callers is the login id of the calling process, except when -bh is used,
4077 when there is no default.
4078
4079 -om
4080
4081 In Sendmail, this option means "me too", indicating that the sender of a
4082 message should receive a copy of the message if the sender appears in an
4083 alias expansion. Exim always does this, so the option does nothing.
4084
4085 -oo
4086
4087 This option is ignored. In Sendmail it specifies "old style headers",
4088 whatever that means.
4089
4090 -oP <path>
4091
4092 This option is useful only in conjunction with -bd or -q with a time value.
4093 The option specifies the file to which the process id of the daemon is
4094 written. When -oX is used with -bd, or when -q with a time is used without
4095 -bd, this is the only way of causing Exim to write a pid file, because in
4096 those cases, the normal pid file is not used.
4097
4098 -or <time>
4099
4100 This option sets a timeout value for incoming non-SMTP messages. If it is
4101 not set, Exim will wait forever for the standard input. The value can also
4102 be set by the receive_timeout option. The format used for specifying times
4103 is described in section 6.16.
4104
4105 -os <time>
4106
4107 This option sets a timeout value for incoming SMTP messages. The timeout
4108 applies to each SMTP command and block of data. The value can also be set
4109 by the smtp_receive_timeout option; it defaults to 5 minutes. The format
4110 used for specifying times is described in section 6.16.
4111
4112 -ov
4113
4114 This option has exactly the same effect as -v.
4115
4116 -oX <number or string>
4117
4118 This option is relevant only when the -bd (start listening daemon) option
4119 is also given. It controls which ports and interfaces the daemon uses.
4120 Details of the syntax, and how it interacts with configuration file
4121 options, are given in chapter 13. When -oX is used to start a daemon, no
4122 pid file is written unless -oP is also present to specify a pid file name.
4123
4124 -pd
4125
4126 This option applies when an embedded Perl interpreter is linked with Exim
4127 (see chapter 12). It overrides the setting of the perl_at_start option,
4128 forcing the starting of the interpreter to be delayed until it is needed.
4129
4130 -ps
4131
4132 This option applies when an embedded Perl interpreter is linked with Exim
4133 (see chapter 12). It overrides the setting of the perl_at_start option,
4134 forcing the starting of the interpreter to occur as soon as Exim is
4135 started.
4136
4137 -p<rval>:<sval>
4138
4139 For compatibility with Sendmail, this option is equivalent to
4140
4141 -oMr <rval> -oMs <sval>
4142
4143 It sets the incoming protocol and host name (for trusted callers). The host
4144 name and its colon can be omitted when only the protocol is to be set. Note
4145 the Exim already has two private options, -pd and -ps, that refer to
4146 embedded Perl. It is therefore impossible to set a protocol value of "d" or
4147 "s" using this option (but that does not seem a real limitation).
4148
4149 -q
4150
4151 This option is normally restricted to admin users. However, there is a
4152 configuration option called prod_requires_admin which can be set false to
4153 relax this restriction (and also the same requirement for the -M, -R, and
4154 -S options).
4155
4156 If other commandline options do not specify an action, the -q option starts
4157 one queue runner process. This scans the queue of waiting messages, and
4158 runs a delivery process for each one in turn. It waits for each delivery
4159 process to finish before starting the next one. A delivery process may not
4160 actually do any deliveries if the retry times for the addresses have not
4161 been reached. Use -qf (see below) if you want to override this.
4162
4163 If the delivery process spawns other processes to deliver other messages
4164 down passed SMTP connections, the queue runner waits for these to finish
4165 before proceeding.
4166
4167 When all the queued messages have been considered, the original queue
4168 runner process terminates. In other words, a single pass is made over the
4169 waiting mail, one message at a time. Use -q with a time (see below) if you
4170 want this to be repeated periodically.
4171
4172 Exim processes the waiting messages in an unpredictable order. It isn't
4173 very random, but it is likely to be different each time, which is all that
4174 matters. If one particular message screws up a remote MTA, other messages
4175 to the same MTA have a chance of getting through if they get tried first.
4176
4177 It is possible to cause the messages to be processed in lexical message id
4178 order, which is essentially the order in which they arrived, by setting the
4179 queue_run_in_order option, but this is not recommended for normal use.
4180
4181 -q<qflags>
4182
4183 The -q option may be followed by one or more flag letters that change its
4184 behaviour. They are all optional, but if more than one is present, they
4185 must appear in the correct order. Each flag is described in a separate item
4186 below.
4187
4188 -qq...
4189
4190 An option starting with -qq requests a two-stage queue run. In the first
4191 stage, the queue is scanned as if the queue_smtp_domains option matched
4192 every domain. Addresses are routed, local deliveries happen, but no remote
4193 transports are run.
4194
4195 The hints database that remembers which messages are waiting for specific
4196 hosts is updated, as if delivery to those hosts had been deferred. After
4197 this is complete, a second, normal queue scan happens, with routing and
4198 delivery taking place as normal. Messages that are routed to the same host
4199 should mostly be delivered down a single SMTP connection because of the
4200 hints that were set up during the first queue scan. This option may be
4201 useful for hosts that are connected to the Internet intermittently.
4202
4203 -q[q]i...
4204
4205 If the i flag is present, the queue runner runs delivery processes only for
4206 those messages that haven't previously been tried. (i stands for "initial
4207 delivery".) This can be helpful if you are putting messages on the queue
4208 using -odq and want a queue runner just to process the new messages.
4209
4210 -q[q][i]f...
4211
4212 If one f flag is present, a delivery attempt is forced for each non-frozen
4213 message, whereas without f only those non-frozen addresses that have passed
4214 their retry times are tried.
4215
4216 -q[q][i]ff...
4217
4218 If ff is present, a delivery attempt is forced for every message, whether
4219 frozen or not.
4220
4221 -q[q][i][f[f]]l
4222
4223 The l (the letter "ell") flag specifies that only local deliveries are to
4224 be done. If a message requires any remote deliveries, it remains on the
4225 queue for later delivery.
4226
4227 -q[q][i][f[f]][l][G<name>[/<time>]]]
4228
4229 If the G flag and a name is present, the queue runner operates on the queue
4230 with the given name rather than the default queue. The name should not
4231 contain a / character. For a periodic queue run (see below) append to the
4232 name a slash and a time value.
4233
4234 If other commandline options specify an action, a -qG<name> option will
4235 specify a queue to operate on. For example:
4236
4237 exim -bp -qGquarantine
4238 mailq -qGquarantine
4239 exim -qGoffpeak -Rf @special.domain.example
4240
4241 -q<qflags> <start id> <end id>
4242
4243 When scanning the queue, Exim can be made to skip over messages whose ids
4244 are lexically less than a given value by following the -q option with a
4245 starting message id. For example:
4246
4247 exim -q 0t5C6f-0000c8-00
4248
4249 Messages that arrived earlier than "0t5C6f-0000c8-00" are not inspected. If
4250 a second message id is given, messages whose ids are lexically greater than
4251 it are also skipped. If the same id is given twice, for example,
4252
4253 exim -q 0t5C6f-0000c8-00 0t5C6f-0000c8-00
4254
4255 just one delivery process is started, for that message. This differs from
4256 -M in that retry data is respected, and it also differs from -Mc in that it
4257 counts as a delivery from a queue run. Note that the selection mechanism
4258 does not affect the order in which the messages are scanned. There are also
4259 other ways of selecting specific sets of messages for delivery in a queue
4260 run - see -R and -S.
4261
4262 -q<qflags><time>
4263
4264 When a time value is present, the -q option causes Exim to run as a daemon,
4265 starting a queue runner process at intervals specified by the given time
4266 value (whose format is described in section 6.16). This form of the -q
4267 option is commonly combined with the -bd option, in which case a single
4268 daemon process handles both functions. A common way of starting up a
4269 combined daemon at system boot time is to use a command such as
4270
4271 /usr/exim/bin/exim -bd -q30m
4272
4273 Such a daemon listens for incoming SMTP calls, and also starts a queue
4274 runner process every 30 minutes.
4275
4276 When a daemon is started by -q with a time value, but without -bd, no pid
4277 file is written unless one is explicitly requested by the -oP option.
4278
4279 -qR<rsflags> <string>
4280
4281 This option is synonymous with -R. It is provided for Sendmail
4282 compatibility.
4283
4284 -qS<rsflags> <string>
4285
4286 This option is synonymous with -S.
4287
4288 -R<rsflags> <string>
4289
4290 The <rsflags> may be empty, in which case the white space before the string
4291 is optional, unless the string is f, ff, r, rf, or rff, which are the
4292 possible values for <rsflags>. White space is required if <rsflags> is not
4293 empty.
4294
4295 This option is similar to -q with no time value, that is, it causes Exim to
4296 perform a single queue run, except that, when scanning the messages on the
4297 queue, Exim processes only those that have at least one undelivered
4298 recipient address containing the given string, which is checked in a
4299 case-independent way. If the <rsflags> start with r, <string> is
4300 interpreted as a regular expression; otherwise it is a literal string.
4301
4302 If you want to do periodic queue runs for messages with specific
4303 recipients, you can combine -R with -q and a time value. For example:
4304
4305 exim -q25m -R @special.domain.example
4306
4307 This example does a queue run for messages with recipients in the given
4308 domain every 25 minutes. Any additional flags that are specified with -q
4309 are applied to each queue run.
4310
4311 Once a message is selected for delivery by this mechanism, all its
4312 addresses are processed. For the first selected message, Exim overrides any
4313 retry information and forces a delivery attempt for each undelivered
4314 address. This means that if delivery of any address in the first message is
4315 successful, any existing retry information is deleted, and so delivery
4316 attempts for that address in subsequently selected messages (which are
4317 processed without forcing) will run. However, if delivery of any address
4318 does not succeed, the retry information is updated, and in subsequently
4319 selected messages, the failing address will be skipped.
4320
4321 If the <rsflags> contain f or ff, the delivery forcing applies to all
4322 selected messages, not just the first; frozen messages are included when ff
4323 is present.
4324
4325 The -R option makes it straightforward to initiate delivery of all messages
4326 to a given domain after a host has been down for some time. When the SMTP
4327 command ETRN is accepted by its ACL (see chapter 43), its default effect is
4328 to run Exim with the -R option, but it can be configured to run an
4329 arbitrary command instead.
4330
4331 -r
4332
4333 This is a documented (for Sendmail) obsolete alternative name for -f.
4334
4335 -S<rsflags> <string>
4336
4337 This option acts like -R except that it checks the string against each
4338 message's sender instead of against the recipients. If -R is also set, both
4339 conditions must be met for a message to be selected. If either of the
4340 options has f or ff in its flags, the associated action is taken.
4341
4342 -Tqt <times>
4343
4344 This is an option that is exclusively for use by the Exim testing suite. It
4345 is not recognized when Exim is run normally. It allows for the setting up
4346 of explicit "queue times" so that various warning/retry features can be
4347 tested.
4348
4349 -t
4350
4351 When Exim is receiving a locally-generated, non-SMTP message on its
4352 standard input, the -t option causes the recipients of the message to be
4353 obtained from the To:, Cc:, and Bcc: header lines in the message instead of
4354 from the command arguments. The addresses are extracted before any
4355 rewriting takes place and the Bcc: header line, if present, is then
4356 removed.
4357
4358 If the command has any arguments, they specify addresses to which the
4359 message is not to be delivered. That is, the argument addresses are removed
4360 from the recipients list obtained from the headers. This is compatible with
4361 Smail 3 and in accordance with the documented behaviour of several versions
4362 of Sendmail, as described in man pages on a number of operating systems
4363 (e.g. Solaris 8, IRIX 6.5, HP-UX 11). However, some versions of Sendmail
4364 add argument addresses to those obtained from the headers, and the O'Reilly
4365 Sendmail book documents it that way. Exim can be made to add argument
4366 addresses instead of subtracting them by setting the option
4367 extract_addresses_remove_arguments false.
4368
4369 If there are any Resent- header lines in the message, Exim extracts
4370 recipients from all Resent-To:, Resent-Cc:, and Resent-Bcc: header lines
4371 instead of from To:, Cc:, and Bcc:. This is for compatibility with Sendmail
4372 and other MTAs. (Prior to release 4.20, Exim gave an error if -t was used
4373 in conjunction with Resent- header lines.)
4374
4375 RFC 2822 talks about different sets of Resent- header lines (for when a
4376 message is resent several times). The RFC also specifies that they should
4377 be added at the front of the message, and separated by Received: lines. It
4378 is not at all clear how -t should operate in the present of multiple sets,
4379 nor indeed exactly what constitutes a "set". In practice, it seems that
4380 MUAs do not follow the RFC. The Resent- lines are often added at the end of
4381 the header, and if a message is resent more than once, it is common for the
4382 original set of Resent- headers to be renamed as X-Resent- when a new set
4383 is added. This removes any possible ambiguity.
4384
4385 -ti
4386
4387 This option is exactly equivalent to -t -i. It is provided for
4388 compatibility with Sendmail.
4389
4390 -tls-on-connect
4391
4392 This option is available when Exim is compiled with TLS support. It forces
4393 all incoming SMTP connections to behave as if the incoming port is listed
4394 in the tls_on_connect_ports option. See section 13.4 and chapter 42 for
4395 further details.
4396
4397 -U
4398
4399 Sendmail uses this option for "initial message submission", and its
4400 documentation states that in future releases, it may complain about
4401 syntactically invalid messages rather than fixing them when this flag is
4402 not set. Exim ignores this option.
4403
4404 -v
4405
4406 This option causes Exim to write information to the standard error stream,
4407 describing what it is doing. In particular, it shows the log lines for
4408 receiving and delivering a message, and if an SMTP connection is made, the
4409 SMTP dialogue is shown. Some of the log lines shown may not actually be
4410 written to the log if the setting of log_selector discards them. Any
4411 relevant selectors are shown with each log line. If none are shown, the
4412 logging is unconditional.
4413
4414 -x
4415
4416 AIX uses -x for a private purpose ("mail from a local mail program has
4417 National Language Support extended characters in the body of the mail
4418 item"). It sets -x when calling the MTA from its mail command. Exim ignores
4419 this option.
4420
4421 -X <logfile>
4422
4423 This option is interpreted by Sendmail to cause debug information to be
4424 sent to the named file. It is ignored by Exim.
4425
4426 -z <log-line>
4427
4428 This option writes its argument to Exim's logfile. Use is restricted to
4429 administrators; the intent is for operational notes. Quotes should be used
4430 to maintain a multi-word item as a single argument, under most shells.
4431
4432
4433
4434 ===============================================================================
4435 6. THE EXIM RUN TIME CONFIGURATION FILE
4436
4437 Exim uses a single run time configuration file that is read whenever an Exim
4438 binary is executed. Note that in normal operation, this happens frequently,
4439 because Exim is designed to operate in a distributed manner, without central
4440 control.
4441
4442 If a syntax error is detected while reading the configuration file, Exim writes
4443 a message on the standard error, and exits with a non-zero return code. The
4444 message is also written to the panic log. Note: Only simple syntax errors can
4445 be detected at this time. The values of any expanded options are not checked
4446 until the expansion happens, even when the expansion does not actually alter
4447 the string.
4448
4449 The name of the configuration file is compiled into the binary for security
4450 reasons, and is specified by the CONFIGURE_FILE compilation option. In most
4451 configurations, this specifies a single file. However, it is permitted to give
4452 a colon-separated list of file names, in which case Exim uses the first
4453 existing file in the list.
4454
4455 The run time configuration file must be owned by root or by the user that is
4456 specified at compile time by the CONFIGURE_OWNER option (if set). The
4457 configuration file must not be world-writeable, or group-writeable unless its
4458 group is the root group or the one specified at compile time by the
4459 CONFIGURE_GROUP option.
4460
4461 Warning: In a conventional configuration, where the Exim binary is setuid to
4462 root, anybody who is able to edit the run time configuration file has an easy
4463 way to run commands as root. If you specify a user or group in the
4464 CONFIGURE_OWNER or CONFIGURE_GROUP options, then that user and/or any users who
4465 are members of that group will trivially be able to obtain root privileges.
4466
4467 Up to Exim version 4.72, the run time configuration file was also permitted to
4468 be writeable by the Exim user and/or group. That has been changed in Exim 4.73
4469 since it offered a simple privilege escalation for any attacker who managed to
4470 compromise the Exim user account.
4471
4472 A default configuration file, which will work correctly in simple situations,
4473 is provided in the file src/configure.default. If CONFIGURE_FILE defines just
4474 one file name, the installation process copies the default configuration to a
4475 new file of that name if it did not previously exist. If CONFIGURE_FILE is a
4476 list, no default is automatically installed. Chapter 7 is a "walk-through"
4477 discussion of the default configuration.
4478
4479
4480 6.1 Using a different configuration file
4481 ----------------------------------------
4482
4483 A one-off alternate configuration can be specified by the -C command line
4484 option, which may specify a single file or a list of files. However, when -C is
4485 used, Exim gives up its root privilege, unless called by root (or unless the
4486 argument for -C is identical to the built-in value from CONFIGURE_FILE), or is
4487 listed in the TRUSTED_CONFIG_LIST file and the caller is the Exim user or the
4488 user specified in the CONFIGURE_OWNER setting. -C is useful mainly for checking
4489 the syntax of configuration files before installing them. No owner or group
4490 checks are done on a configuration file specified by -C, if root privilege has
4491 been dropped.
4492
4493 Even the Exim user is not trusted to specify an arbitrary configuration file
4494 with the -C option to be used with root privileges, unless that file is listed
4495 in the TRUSTED_CONFIG_LIST file. This locks out the possibility of testing a
4496 configuration using -C right through message reception and delivery, even if
4497 the caller is root. The reception works, but by that time, Exim is running as
4498 the Exim user, so when it re-execs to regain privilege for the delivery, the
4499 use of -C causes privilege to be lost. However, root can test reception and
4500 delivery using two separate commands (one to put a message on the queue, using
4501 -odq, and another to do the delivery, using -M).
4502
4503 If ALT_CONFIG_PREFIX is defined in Local/Makefile, it specifies a prefix string
4504 with which any file named in a -C command line option must start. In addition,
4505 the file name must not contain the sequence "/../". There is no default setting
4506 for ALT_CONFIG_PREFIX; when it is unset, any file name can be used with -C.
4507
4508 One-off changes to a configuration can be specified by the -D command line
4509 option, which defines and overrides values for macros used inside the
4510 configuration file. However, like -C, the use of this option by a
4511 non-privileged user causes Exim to discard its root privilege. If
4512 DISABLE_D_OPTION is defined in Local/Makefile, the use of -D is completely
4513 disabled, and its use causes an immediate error exit.
4514
4515 The WHITELIST_D_MACROS option in Local/Makefile permits the binary builder to
4516 declare certain macro names trusted, such that root privilege will not
4517 necessarily be discarded. WHITELIST_D_MACROS defines a colon-separated list of
4518 macros which are considered safe and, if -D only supplies macros from this
4519 list, and the values are acceptable, then Exim will not give up root privilege
4520 if the caller is root, the Exim run-time user, or the CONFIGURE_OWNER, if set.
4521 This is a transition mechanism and is expected to be removed in the future.
4522 Acceptable values for the macros satisfy the regexp: "^[A-Za-z0-9_/.-]*$"
4523
4524 Some sites may wish to use the same Exim binary on different machines that
4525 share a file system, but to use different configuration files on each machine.
4526 If CONFIGURE_FILE_USE_NODE is defined in Local/Makefile, Exim first looks for a
4527 file whose name is the configuration file name followed by a dot and the
4528 machine's node name, as obtained from the uname() function. If this file does
4529 not exist, the standard name is tried. This processing occurs for each file
4530 name in the list given by CONFIGURE_FILE or -C.
4531
4532 In some esoteric situations different versions of Exim may be run under
4533 different effective uids and the CONFIGURE_FILE_USE_EUID is defined to help
4534 with this. See the comments in src/EDITME for details.
4535
4536
4537 6.2 Configuration file format
4538 -----------------------------
4539
4540 Exim's configuration file is divided into a number of different parts. General
4541 option settings must always appear at the start of the file. The other parts
4542 are all optional, and may appear in any order. Each part other than the first
4543 is introduced by the word "begin" followed by at least one literal space, and
4544 the name of the part. The optional parts are:
4545
4546 * ACL: Access control lists for controlling incoming SMTP mail (see chapter
4547 43).
4548
4549 * authenticators: Configuration settings for the authenticator drivers. These
4550 are concerned with the SMTP AUTH command (see chapter 33).
4551
4552 * routers: Configuration settings for the router drivers. Routers process
4553 addresses and determine how the message is to be delivered (see chapters 15
4554 -22).
4555
4556 * transports: Configuration settings for the transport drivers. Transports
4557 define mechanisms for copying messages to destinations (see chapters 24-30
4558 ).
4559
4560 * retry: Retry rules, for use when a message cannot be delivered immediately.
4561 If there is no retry section, or if it is empty (that is, no retry rules
4562 are defined), Exim will not retry deliveries. In this situation, temporary
4563 errors are treated the same as permanent errors. Retry rules are discussed
4564 in chapter 32.
4565
4566 * rewrite: Global address rewriting rules, for use when a message arrives and
4567 when new addresses are generated during delivery. Rewriting is discussed in
4568 chapter 31.
4569
4570 * local_scan: Private options for the local_scan() function. If you want to
4571 use this feature, you must set
4572
4573 LOCAL_SCAN_HAS_OPTIONS=yes
4574
4575 in Local/Makefile before building Exim. Details of the local_scan()
4576 facility are given in chapter 45.
4577
4578 Leading and trailing white space in configuration lines is always ignored.
4579
4580 Blank lines in the file, and lines starting with a # character (ignoring
4581 leading white space) are treated as comments and are ignored. Note: A #
4582 character other than at the beginning of a line is not treated specially, and
4583 does not introduce a comment.
4584
4585 Any non-comment line can be continued by ending it with a backslash. Note that
4586 the general rule for white space means that trailing white space after the
4587 backslash and leading white space at the start of continuation lines is
4588 ignored. Comment lines beginning with # (but not empty lines) may appear in the
4589 middle of a sequence of continuation lines.
4590
4591 A convenient way to create a configuration file is to start from the default,
4592 which is supplied in src/configure.default, and add, delete, or change settings
4593 as required.
4594
4595 The ACLs, retry rules, and rewriting rules have their own syntax which is
4596 described in chapters 43, 32, and 31, respectively. The other parts of the
4597 configuration file have some syntactic items in common, and these are described
4598 below, from section 6.11 onwards. Before that, the inclusion, macro, and
4599 conditional facilities are described.
4600
4601
4602 6.3 File inclusions in the configuration file
4603 ---------------------------------------------
4604
4605 You can include other files inside Exim's run time configuration file by using
4606 this syntax:
4607
4608 .include <file name>
4609 .include_if_exists <file name>
4610
4611 on a line by itself. Double quotes round the file name are optional. If you use
4612 the first form, a configuration error occurs if the file does not exist; the
4613 second form does nothing for non-existent files.
4614
4615 The first form allows a relative name. It is resolved relative to the directory
4616 of the including file. For the second form an absolute file name is required.
4617
4618 Includes may be nested to any depth, but remember that Exim reads its
4619 configuration file often, so it is a good idea to keep them to a minimum. If
4620 you change the contents of an included file, you must HUP the daemon, because
4621 an included file is read only when the configuration itself is read.
4622
4623 The processing of inclusions happens early, at a physical line level, so, like
4624 comment lines, an inclusion can be used in the middle of an option setting, for
4625 example:
4626
4627 hosts_lookup = a.b.c \
4628 .include /some/file
4629
4630 Include processing happens after macro processing (see below). Its effect is to
4631 process the lines of the included file as if they occurred inline where the
4632 inclusion appears.
4633
4634
4635 6.4 Macros in the configuration file
4636 ------------------------------------
4637
4638 If a line in the main part of the configuration (that is, before the first
4639 "begin" line) begins with an upper case letter, it is taken as a macro
4640 definition, and must be of the form
4641
4642 <name> = <rest of line>
4643
4644 The name must consist of letters, digits, and underscores, and need not all be
4645 in upper case, though that is recommended. The rest of the line, including any
4646 continuations, is the replacement text, and has leading and trailing white
4647 space removed. Quotes are not removed. The replacement text can never end with
4648 a backslash character, but this doesn't seem to be a serious limitation.
4649
4650 Macros may also be defined between router, transport, authenticator, or ACL
4651 definitions. They may not, however, be defined within an individual driver or
4652 ACL, or in the local_scan, retry, or rewrite sections of the configuration.
4653
4654
4655 6.5 Macro substitution
4656 ----------------------
4657
4658 Once a macro is defined, all subsequent lines in the file (and any included
4659 files) are scanned for the macro name; if there are several macros, the line is
4660 scanned for each in turn, in the order in which the macros are defined. The
4661 replacement text is not re-scanned for the current macro, though it is scanned
4662 for subsequently defined macros. For this reason, a macro name may not contain
4663 the name of a previously defined macro as a substring. You could, for example,
4664 define
4665
4666 ABCD_XYZ = <something>
4667 ABCD = <something else>
4668
4669 but putting the definitions in the opposite order would provoke a configuration
4670 error. Macro expansion is applied to individual physical lines from the file,
4671 before checking for line continuation or file inclusion (see above). If a line
4672 consists solely of a macro name, and the expansion of the macro is empty, the
4673 line is ignored. A macro at the start of a line may turn the line into a
4674 comment line or a ".include" line.
4675
4676
4677 6.6 Redefining macros
4678 ---------------------
4679
4680 Once defined, the value of a macro can be redefined later in the configuration
4681 (or in an included file). Redefinition is specified by using == instead of =.
4682 For example:
4683
4684 MAC = initial value
4685 ...
4686 MAC == updated value
4687
4688 Redefinition does not alter the order in which the macros are applied to the
4689 subsequent lines of the configuration file. It is still the same order in which
4690 the macros were originally defined. All that changes is the macro's value.
4691 Redefinition makes it possible to accumulate values. For example:
4692
4693 MAC = initial value
4694 ...
4695 MAC == MAC and something added
4696
4697 This can be helpful in situations where the configuration file is built from a
4698 number of other files.
4699
4700
4701 6.7 Overriding macro values
4702 ---------------------------
4703
4704 The values set for macros in the configuration file can be overridden by the -D
4705 command line option, but Exim gives up its root privilege when -D is used,
4706 unless called by root or the Exim user. A definition on the command line using
4707 the -D option causes all definitions and redefinitions within the file to be
4708 ignored.
4709
4710
4711 6.8 Example of macro usage
4712 --------------------------
4713
4714 As an example of macro usage, consider a configuration where aliases are looked
4715 up in a MySQL database. It helps to keep the file less cluttered if long
4716 strings such as SQL statements are defined separately as macros, for example:
4717
4718 ALIAS_QUERY = select mailbox from user where \
4719 login='${quote_mysql:$local_part}';
4720
4721 This can then be used in a redirect router setting like this:
4722
4723 data = ${lookup mysql{ALIAS_QUERY}}
4724
4725 In earlier versions of Exim macros were sometimes used for domain, host, or
4726 address lists. In Exim 4 these are handled better by named lists - see section
4727 10.5.
4728
4729
4730 6.9 Builtin macros
4731 ------------------
4732
4733 Exim defines some macros depending on facilities available, which may differ
4734 due to build-time definitions and from one release to another. All of these
4735 macros start with an underscore. They can be used to conditionally include
4736 parts of a configuration (see below).
4737
4738 The following classes of macros are defined:
4739
4740 _HAVE_* build-time defines
4741 _DRIVER_ROUTER_* router drivers
4742 _DRIVER_TRANSPORT_* transport drivers
4743 _DRIVER_AUTHENTICATOR_* authenticator drivers
4744 _OPT_MAIN_* main config options
4745 _OPT_ROUTERS_* generic router options
4746 _OPT_TRANSPORTS_* generic transport options
4747 _OPT_AUTHENTICATORS_* generic authenticator options
4748 _OPT_ROUTER_*_* private router options
4749 _OPT_TRANSPORT_*_* private transport options
4750 _OPT_AUTHENTICATOR_*_* private authenticator options
4751
4752 Use an "exim -bP macros" command to get the list of macros.
4753
4754
4755 6.10 Conditional skips in the configuration file
4756 ------------------------------------------------
4757
4758 You can use the directives ".ifdef", ".ifndef", ".elifdef", ".elifndef",
4759 ".else", and ".endif" to dynamically include or exclude portions of the
4760 configuration file. The processing happens whenever the file is read (that is,
4761 when an Exim binary starts to run).
4762
4763 The implementation is very simple. Instances of the first four directives must
4764 be followed by text that includes the names of one or macros. The condition
4765 that is tested is whether or not any macro substitution has taken place in the
4766 line. Thus:
4767
4768 .ifdef AAA
4769 message_size_limit = 50M
4770 .else
4771 message_size_limit = 100M
4772 .endif
4773
4774 sets a message size limit of 50M if the macro "AAA" is defined (or "A" or
4775 "AA"), and 100M otherwise. If there is more than one macro named on the line,
4776 the condition is true if any of them are defined. That is, it is an "or"
4777 condition. To obtain an "and" condition, you need to use nested ".ifdef"s.
4778
4779 Although you can use a macro expansion to generate one of these directives, it
4780 is not very useful, because the condition "there was a macro substitution in
4781 this line" will always be true.
4782
4783 Text following ".else" and ".endif" is ignored, and can be used as comment to
4784 clarify complicated nestings.
4785
4786
4787 6.11 Common option syntax
4788 -------------------------
4789
4790 For the main set of options, driver options, and local_scan() options, each
4791 setting is on a line by itself, and starts with a name consisting of lower-case
4792 letters and underscores. Many options require a data value, and in these cases
4793 the name must be followed by an equals sign (with optional white space) and
4794 then the value. For example:
4795
4796 qualify_domain = mydomain.example.com
4797
4798 Some option settings may contain sensitive data, for example, passwords for
4799 accessing databases. To stop non-admin users from using the -bP command line
4800 option to read these values, you can precede the option settings with the word
4801 "hide". For example:
4802
4803 hide mysql_servers = localhost/users/admin/secret-password
4804
4805 For non-admin users, such options are displayed like this:
4806
4807 mysql_servers = <value not displayable>
4808
4809 If "hide" is used on a driver option, it hides the value of that option on all
4810 instances of the same driver.
4811
4812 The following sections describe the syntax used for the different data types
4813 that are found in option settings.
4814
4815
4816 6.12 Boolean options
4817 --------------------
4818
4819 Options whose type is given as boolean are on/off switches. There are two
4820 different ways of specifying such options: with and without a data value. If
4821 the option name is specified on its own without data, the switch is turned on;
4822 if it is preceded by "no_" or "not_" the switch is turned off. However, boolean
4823 options may be followed by an equals sign and one of the words "true", "false",
4824 "yes", or "no", as an alternative syntax. For example, the following two
4825 settings have exactly the same effect:
4826
4827 queue_only
4828 queue_only = true
4829
4830 The following two lines also have the same (opposite) effect:
4831
4832 no_queue_only
4833 queue_only = false
4834
4835 You can use whichever syntax you prefer.
4836
4837
4838 6.13 Integer values
4839 -------------------
4840
4841 If an option's type is given as "integer", the value can be given in decimal,
4842 hexadecimal, or octal. If it starts with a digit greater than zero, a decimal
4843 number is assumed. Otherwise, it is treated as an octal number unless it starts
4844 with the characters "0x", in which case the remainder is interpreted as a
4845 hexadecimal number.
4846
4847 If an integer value is followed by the letter K, it is multiplied by 1024; if
4848 it is followed by the letter M, it is multiplied by 1024x1024; if by the letter
4849 G, 1024x1024x1024. When the values of integer option settings are output,
4850 values which are an exact multiple of 1024 or 1024x1024 are sometimes, but not
4851 always, printed using the letters K and M. The printing style is independent of
4852 the actual input format that was used.
4853
4854
4855 6.14 Octal integer values
4856 -------------------------
4857
4858 If an option's type is given as "octal integer", its value is always
4859 interpreted as an octal number, whether or not it starts with the digit zero.
4860 Such options are always output in octal.
4861
4862
4863 6.15 Fixed point numbers
4864 ------------------------
4865
4866 If an option's type is given as "fixed-point", its value must be a decimal
4867 integer, optionally followed by a decimal point and up to three further digits.
4868
4869
4870 6.16 Time intervals
4871 -------------------
4872
4873 A time interval is specified as a sequence of numbers, each followed by one of
4874 the following letters, with no intervening white space:
4875
4876 s seconds
4877 m minutes
4878 h hours
4879 d days
4880 w weeks
4881
4882 For example, "3h50m" specifies 3 hours and 50 minutes. The values of time
4883 intervals are output in the same format. Exim does not restrict the values; it
4884 is perfectly acceptable, for example, to specify "90m" instead of "1h30m".
4885
4886
4887 6.17 String values
4888 ------------------
4889
4890 If an option's type is specified as "string", the value can be specified with
4891 or without double-quotes. If it does not start with a double-quote, the value
4892 consists of the remainder of the line plus any continuation lines, starting at
4893 the first character after any leading white space, with trailing white space
4894 removed, and with no interpretation of the characters in the string. Because
4895 Exim removes comment lines (those beginning with #) at an early stage, they can
4896 appear in the middle of a multi-line string. The following two settings are
4897 therefore equivalent:
4898
4899 trusted_users = uucp:mail
4900 trusted_users = uucp:\
4901 # This comment line is ignored
4902 mail
4903
4904 If a string does start with a double-quote, it must end with a closing
4905 double-quote, and any backslash characters other than those used for line
4906 continuation are interpreted as escape characters, as follows:
4907
4908 "\\" single backslash
4909 "\n" newline
4910 "\r" carriage return
4911 "\t" tab
4912 "\"<octal digits> up to 3 octal digits specify one character
4913 "\x"<hex digits> up to 2 hexadecimal digits specify one character
4914
4915 If a backslash is followed by some other character, including a double-quote
4916 character, that character replaces the pair.
4917
4918 Quoting is necessary only if you want to make use of the backslash escapes to
4919 insert special characters, or if you need to specify a value with leading or
4920 trailing spaces. These cases are rare, so quoting is almost never needed in
4921 current versions of Exim. In versions of Exim before 3.14, quoting was required
4922 in order to continue lines, so you may come across older configuration files
4923 and examples that apparently quote unnecessarily.
4924
4925
4926 6.18 Expanded strings
4927 ---------------------
4928
4929 Some strings in the configuration file are subjected to string expansion, by
4930 which means various parts of the string may be changed according to the
4931 circumstances (see chapter 11). The input syntax for such strings is as just
4932 described; in particular, the handling of backslashes in quoted strings is done
4933 as part of the input process, before expansion takes place. However, backslash
4934 is also an escape character for the expander, so any backslashes that are
4935 required for that reason must be doubled if they are within a quoted
4936 configuration string.
4937
4938
4939 6.19 User and group names
4940 -------------------------
4941
4942 User and group names are specified as strings, using the syntax described
4943 above, but the strings are interpreted specially. A user or group name must
4944 either consist entirely of digits, or be a name that can be looked up using the
4945 getpwnam() or getgrnam() function, as appropriate.
4946
4947
4948 6.20 List construction
4949 ----------------------
4950
4951 The data for some configuration options is a list of items, with colon as the
4952 default separator. Many of these options are shown with type "string list" in
4953 the descriptions later in this document. Others are listed as "domain list",
4954 "host list", "address list", or "local part list". Syntactically, they are all
4955 the same; however, those other than "string list" are subject to particular
4956 kinds of interpretation, as described in chapter 10.
4957
4958 In all these cases, the entire list is treated as a single string as far as the
4959 input syntax is concerned. The trusted_users setting in section 6.17 above is
4960 an example. If a colon is actually needed in an item in a list, it must be
4961 entered as two colons. Leading and trailing white space on each item in a list
4962 is ignored. This makes it possible to include items that start with a colon,
4963 and in particular, certain forms of IPv6 address. For example, the list
4964
4965 local_interfaces = 127.0.0.1 : ::::1
4966
4967 contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address ::1.
4968
4969 Note: Although leading and trailing white space is ignored in individual list
4970 items, it is not ignored when parsing the list. The space after the first colon
4971 in the example above is necessary. If it were not there, the list would be
4972 interpreted as the two items 127.0.0.1:: and 1.
4973
4974
4975 6.21 Changing list separators
4976 -----------------------------
4977
4978 Doubling colons in IPv6 addresses is an unwelcome chore, so a mechanism was
4979 introduced to allow the separator character to be changed. If a list begins
4980 with a left angle bracket, followed by any punctuation character, that
4981 character is used instead of colon as the list separator. For example, the list
4982 above can be rewritten to use a semicolon separator like this:
4983
4984 local_interfaces = <; 127.0.0.1 ; ::1
4985
4986 This facility applies to all lists, with the exception of the list in
4987 log_file_path. It is recommended that the use of non-colon separators be
4988 confined to circumstances where they really are needed.
4989
4990 It is also possible to use newline and other control characters (those with
4991 code values less than 32, plus DEL) as separators in lists. Such separators
4992 must be provided literally at the time the list is processed. For options that
4993 are string-expanded, you can write the separator using a normal escape
4994 sequence. This will be processed by the expander before the string is
4995 interpreted as a list. For example, if a newline-separated list of domains is
4996 generated by a lookup, you can process it directly by a line such as this:
4997
4998 domains = <\n ${lookup mysql{.....}}
4999
5000 This avoids having to change the list separator in such data. You are unlikely
5001 to want to use a control character as a separator in an option that is not
5002 expanded, because the value is literal text. However, it can be done by giving
5003 the value in quotes. For example:
5004
5005 local_interfaces = "<\n 127.0.0.1 \n ::1"
5006
5007 Unlike printing character separators, which can be included in list items by
5008 doubling, it is not possible to include a control character as data when it is
5009 set as the separator. Two such characters in succession are interpreted as
5010 enclosing an empty list item.
5011
5012
5013 6.22 Empty items in lists
5014 -------------------------
5015
5016 An empty item at the end of a list is always ignored. In other words, trailing
5017 separator characters are ignored. Thus, the list in
5018
5019 senders = user@domain :
5020
5021 contains only a single item. If you want to include an empty string as one item
5022 in a list, it must not be the last item. For example, this list contains three
5023 items, the second of which is empty:
5024
5025 senders = user1@domain : : user2@domain
5026
5027 Note: There must be white space between the two colons, as otherwise they are
5028 interpreted as representing a single colon data character (and the list would
5029 then contain just one item). If you want to specify a list that contains just
5030 one, empty item, you can do it as in this example:
5031
5032 senders = :
5033
5034 In this case, the first item is empty, and the second is discarded because it
5035 is at the end of the list.
5036
5037
5038 6.23 Format of driver configurations
5039 ------------------------------------
5040
5041 There are separate parts in the configuration for defining routers, transports,
5042 and authenticators. In each part, you are defining a number of driver
5043 instances, each with its own set of options. Each driver instance is defined by
5044 a sequence of lines like this:
5045
5046 <instance name>:
5047 <option>
5048 ...
5049 <option>
5050
5051 In the following example, the instance name is localuser, and it is followed by
5052 three options settings:
5053
5054 localuser:
5055 driver = accept
5056 check_local_user
5057 transport = local_delivery
5058
5059 For each driver instance, you specify which Exim code module it uses - by the
5060 setting of the driver option - and (optionally) some configuration settings.
5061 For example, in the case of transports, if you want a transport to deliver with
5062 SMTP you would use the smtp driver; if you want to deliver to a local file you
5063 would use the appendfile driver. Each of the drivers is described in detail in
5064 its own separate chapter later in this manual.
5065
5066 You can have several routers, transports, or authenticators that are based on
5067 the same underlying driver (each must have a different instance name).
5068
5069 The order in which routers are defined is important, because addresses are
5070 passed to individual routers one by one, in order. The order in which
5071 transports are defined does not matter at all. The order in which
5072 authenticators are defined is used only when Exim, as a client, is searching
5073 them to find one that matches an authentication mechanism offered by the
5074 server.
5075
5076 Within a driver instance definition, there are two kinds of option: generic and
5077 private. The generic options are those that apply to all drivers of the same
5078 type (that is, all routers, all transports or all authenticators). The driver
5079 option is a generic option that must appear in every definition. The private
5080 options are special for each driver, and none need appear, because they all
5081 have default values.
5082
5083 The options may appear in any order, except that the driver option must precede
5084 any private options, since these depend on the particular driver. For this
5085 reason, it is recommended that driver always be the first option.
5086
5087 Driver instance names, which are used for reference in log entries and
5088 elsewhere, can be any sequence of letters, digits, and underscores (starting
5089 with a letter) and must be unique among drivers of the same type. A router and
5090 a transport (for example) can each have the same name, but no two router
5091 instances can have the same name. The name of a driver instance should not be
5092 confused with the name of the underlying driver module. For example, the
5093 configuration lines:
5094
5095 remote_smtp:
5096 driver = smtp
5097
5098 create an instance of the smtp transport driver whose name is remote_smtp. The
5099 same driver code can be used more than once, with different instance names and
5100 different option settings each time. A second instance of the smtp transport,
5101 with different options, might be defined thus:
5102
5103 special_smtp:
5104 driver = smtp
5105 port = 1234
5106 command_timeout = 10s
5107
5108 The names remote_smtp and special_smtp would be used to reference these
5109 transport instances from routers, and these names would appear in log lines.
5110
5111 Comment lines may be present in the middle of driver specifications. The full
5112 list of option settings for any particular driver instance, including all the
5113 defaulted values, can be extracted by making use of the -bP command line
5114 option.
5115
5116
5117
5118 ===============================================================================
5119 7. THE DEFAULT CONFIGURATION FILE
5120
5121 The default configuration file supplied with Exim as src/configure.default is
5122 sufficient for a host with simple mail requirements. As an introduction to the
5123 way Exim is configured, this chapter "walks through" the default configuration,
5124 giving brief explanations of the settings. Detailed descriptions of the options
5125 are given in subsequent chapters. The default configuration file itself
5126 contains extensive comments about ways you might want to modify the initial
5127 settings. However, note that there are many options that are not mentioned at
5128 all in the default configuration.
5129
5130