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