
              UNIVERSITY OF CAMBRIDGE COMPUTING SERVICE

            SPECIFICATION OF THE EXIM MAIL TRANSFER AGENT

                                  by

                             Philip Hazel
                                   
                      MODIFIED FOR EXIM FOR OS/2

                                  by

                            Alistair Young

Computer Laboratory                       Arkane Systems Ltd.
New Museums Site                          20 Bede Road
Pembroke Street                           Barnard Castle
Cambridge CB2 3QG                         Co. Durham DL12 8HD
United Kingdom                            United Kingdom

phone:  +44 1223 334600                   phone: +44 1833 638233
fax:    +44 1223 334679
email:  P.Hazel@ucs.cam.ac.uk             email: avatar-exim@arkane.demon.co.uk

Edition for Exim for OS/2, December 1997

The original of this document, found in the main Exim distribution, is
copyright (c) University of Cambridge 1997; it has been modified to be
specific to Exim for OS/2, and those modifications are copyright (c)
1997 Arkane Systems Ltd. Copying permission is granted to all.


                           CONTENTS


1. Introduction
  1.1 Mailing list and Web site
  1.2 Availability
  1.3 Limitations
  1.4 Features
  1.6 Interface
  1.7 Terminology

2. Incorporated code

3. How Exim delivers mail
  3.1 Philosophy
  3.2 Message reception
  3.3 Life of a message
  3.4 Drivers
  3.5 Delivery in detail

4. Building and installing Exim
  4.1 Unpacking
  4.2 Directories & environment variables
  4.3 Configuration file
  4.12 Setting up the spool directory
  4.13 Testing
  4.14 Switching Exim on

5. The Exim command line
  5.1 Setting options by program name
  5.3 Command line options

6. File and database lookups
  6.1 Single-key lookup types
  6.2 Query-style lookup types
  6.3 Use of data lookups
  6.4 Partial matching in file lookups

7. The Exim configuration file
  7.1 Configuration file format
  7.2 Macros in the configuration file
  7.3 Common option syntax
  7.4 Integer
  7.5 Fixed point number
  7.6 Time interval
  7.7 String
  7.8 Expanded strings
  7.10 String lists
  7.11 Domain lists
  7.12 Partial matching in domain lists
  7.13 Address lists
  7.14 Host lists
  7.15 Net lists

8. Regular expressions

9. String expansions
  9.1 Expansion items
  9.2 Expansion operators
  9.3 Expansion conditions
  9.4 Expansion variables
  9.5 Expansion string examples

10. Main configuration

11. Driver specifications

12. Environment for running local transports
  12.2 Current and home directories

13. Generic options for transports

14. The appendfile transport
  14.1 Private options for appendfile
  14.2 Operational details for appending
  14.3 Operational details for delivery to a new file

15. The autoreply transport
  15.1 Private options for autoreply

16. The debug transport

17. The pipe transport
  17.1 Returned status and data
  17.2 How the command is run
  17.3 Environment variables
  17.4 Private options for pipe
  17.5 Using an external local delivery agent

18. The smtp transport

19. Common generic options for directors and routers

20. Default transports

21. Additional generic options for directors
  21.1 Skipping directors

22. The aliasfile director
  22.1 Alias file format
  22.2 Types of alias item
  22.3 Duplicate addresses
  22.4 Errors in alias files
  22.5 Specifying a transport
  22.6 Aliasfile private options

23. The forwardfile director
  23.1 Forward file items
  23.2 Errors in forward files
  23.3 Filter files
  23.4 The home directory
  23.5 Forwardfile private options

24. The localuser director

25. The smartuser director

26. Additional generic options for routers
  26.1 Skipping routers

27. The domainlist router
  27.1 Routing rules
  27.2 Host list format
  27.3 Options format
  27.4 Application of routing rules
  27.5 Domainlist examples

28. The ipliteral router

29. The iplookup router

30. The lookuphost router

31. The queryprogram router

32. Retry configuration
  32.1 Long-term failures

33. Address rewriting
  33.1 Rewriting patterns
  33.2 Rewriting replacements
  33.3 Rewriting flags
  33.4 Rewriting examples

34. The default configuration file
  34.1 Main configuration settings
  34.2 Transport configuration settings
  34.3 Director configuration settings
  34.4 Router configuration settings
  34.5 Retry rules
  34.6 Rewriting configuration

35. Multiple user mailboxes

36. Using Exim to handle mailing lists
  36.1 Closed mailing lists

37. Virtual domains
  37.1 All mail to a given host
  37.2 Virtual domain not preserving envelope
  37.3 Virtual domain preserving envelope

38. Intermittently connected hosts

39. Verification of incoming mail
  39.1 Host verification
  39.2 Sender verification
  39.3 Header verification
  39.4 Receiver verification

40. Other policy controls on incoming mail
  40.1 Host checking using RBL
  40.2 Other host checking
  40.3 Sender checking
  40.4 Control of relaying
  40.5 Prohibition messages

41. System-wide message filtering

42. SMTP processing
  42.1 Outgoing SMTP over TCP/IP
  42.2 Incoming SMTP over TCP/IP
  42.3 Outgoing batched SMTP
  42.4 Incoming batched SMTP

43. Message processing
  43.1 Unqualified addresses
  43.2 The Bcc header
  43.3 The Date header
  43.4 The Delivery-date header
  43.5 The Envelope-to header
  43.6 The From header
  43.7 The Message-id header
  43.8 The Received header
  43.9 The Return-path header
  43.10 The Sender header
  43.11 The To header
  43.12 Constructed addresses
  43.13 Case of local parts
  43.14 Rewriting addresses

44. Automatic mail processing
  44.1 System-wide automatic processing
  44.2 Automatic processing by users
  44.3 Simplified vacation processing

45. Log files
  45.1 Logging message reception
  45.2 Logging Deliveries
  45.3 Deferred deliveries
  45.4 Delivery failures
  45.5 Completion
  45.6 Log level
  45.7 Message log

46. Day-to-day management
  46.1 The panic log
  46.2 The reject log
  46.4 Statistics
  46.5 What is Exim doing?
  46.6 Changing the configuration
  46.7 Watching the queue
  46.8 Holding domains

47. Exim utilities
  47.1 Querying Exim processes
  47.2 Summarising the queue
  47.3 Extracting log information
  47.5 Making DBM files
  47.6 Individual retry times
  47.7 Database maintenance
  47.8 Mail statistics

49. Security considerations
  49.2 Reading forward files
  49.3 Delivering to local files
  49.4 IPv4 source routing
  49.5 The VRFY, EXPN, and ETRN commands in SMTP
  49.8 Use of argv[0]
  49.9 Use of %f formatting
  49.11 Use of sprintf()
  49.12 Use of debug_printf() and log_write()
  49.13 Use of strcat() and strcpy()

50. Format of spool files

51. Adding new drivers to Exim



                              1. INTRODUCTION


  "If I have seen further it is by standing on the shoulders of giants."
                                                             (Isaac Newton)


Exim is a mail transfer agent (MTA) for systems connected to the
Internet. This version is intended for use under the OS/2 operating
system; the original version was for Unix systems, for which it is
necessary to fetch the main distribution.

The terms and conditions for the use and distribution of Exim are contained
in the file NOTICE. Exim is distributed under the terms of the GNU General
Public Licence, a copy of which may be found in the file LICENCE.

Exim owes a great deal to Smail 3 and its author, Ron Karr. Without
the experience of running and working on the Smail 3 code, I [Philip
Hazel] could never have contemplated starting to write a new
mailer. Many of the ideas and user interfaces are taken from Smail 3,
though the actual code of Exim is entirely new.

I am indebted to my colleague Piete Brooks for suggesting and implementing
the scheme for building Exim for multiple architectures and operating
systems, for porting Exim to several different versions of Unix, and for
numerous suggestions. Many other people, both in Cambridge and around the
world, have contributed to the development and the testing of Exim, and to
porting it to various operating systems. I am grateful to them all.

This edition of the Exim specification applies to version 1.80 of Exim.
Substantive changes from the 1.70 edition are marked by bars in the right
margin, except in the Texinfo version of the documentation, because Texinfo
doesn't support change bars. Minor corrections and rewordings are not so
marked.

As the program is still developing, there may be features in later versions
of the program that have not yet made it into this document, which is
updated only when there is a reasonable batch of changes to make. However,
all changes are noted briefly in the distributed file called doc/ChangeLog,
and specifications of new features that are not in this manual are placed
in doc/NewStuff.


1.1 Mailing list and Web site

There is a mailing list for users of Exim called exim-users@exim.org, and a
web site at http://www.exim.org, courtesy of Planet Online Ltd. Requests to
be added to or deleted from the mailing list should be sent to exim-users-
request@exim.org. By courtesy of Martin Hamilton, there is an archive of
this list in plain text form at http://www.roads.lut.ac.uk/lists/exim-
users/exim-users.archive and in HTML via Hypermail at
http://www.roads.lut.ac.uk/lists/exim-users/.

There is also a mailing list specific to users of the OS/2 version of
exim at list-exim@arkane.demon.co.uk. Requests to be added to or
deleted from the mailing list should be sent to
request-exim@arkane.demon.co.uk.

An Exim for OS/2 specific web site is under development at
http://www.arkane.demon.co.uk/exim/ at the present time.


1.2 Availability

The current distribution of Exim for OS/2 is available from

http://www.arkane.demon.co.uk/Files/exim.zip

The current Unix release of Exim is always to be found in

  ftp://ftp.cus.cam.ac.uk/pub/software/programs/exim/exim-n.nn.tar.gz

where n.nn is the highest such version number in the directory. When there
is only a small amount of change from one version to the next, a patch file
may be provided, with a final component name of the form

  exim-patch-n.nn-m.mm.gz

The main distribution contains ASCII versions of this specification and
other documentation; other formats of the documents are available in
separate files:

ftp://ftp.cus.cam.ac.uk/pub/software/programs/exim/exim-postscript-n.nn.tar.gz
ftp://ftp.cus.cam.ac.uk/pub/software/programs/exim/exim-texinfo-n.nn.tar.gz

These tar files contain only the /doc directory, not the complete distri-
bution. The documentation is also available online at the web site.

This non-ASCII documentation is for the non-OS/2 versions only.

There are a number of sites that maintain mirrors of the Exim distribution.
Those that I know about are listed in the file called Mirrors in the ftp
directory.


1.3 Limitations

 .   Exim uses file names that are longer than 14 characters.

 .   Exim uses the Emx compiler, and so requires the Emx 0.9c or later
     libraries to be installed.

 .   Exim is intended for use as an Internet mailer, and therefore handles
     addresses in RFC 822 domain format only. It cannot handle 'bang
     paths', though simple two-component bang paths can be converted by a
     straightforward rewriting configuration.

 .   Exim insists that every address it handles has a domain attached. For
     incoming local messages, domainless addresses are automatically quali-
     fied with a configured domain value. Configuration options specify
     from which remote systems unqualified addresses are acceptable.

 .   The only external transport currently implemented is an SMTP transport
     over a TCP/IP network (using sockets). However, a pipe transport
     is available, and there are facilities for writing messages to
     files and pipes, optionally in "batched SMTP" format; these
     facilities can be used to send messages to some other transport
     mechanism such as UUCP. Batched SMTP input is also catered for.


1.4 Features

These are some of the main features of Exim:

 .   Exim follows the same general approach of decentralized control that
     Smail does. There is no central process doing overall management of
     mail delivery. However, unlike Smail, the independent delivery pro-
     cesses share data in the form of 'hints', which makes delivery more
     efficient in some cases.

 .   Exim has flexible retry algorithms, applicable to directing and
     routing addresses as well as to delivery.

 .   Exim contains header and envelope rewriting facilities.

 .   Unqualified addresses are accepted only from specified hosts or
     networks.

 .   Exim can perform multiple deliveries down the same SMTP channel after
     deliveries have been delayed.

 .   Exim can be configured to do local deliveries immediately but to leave
     remote (SMTP) deliveries until the message is picked up by a queue-
     runner process. This increases the likelihood of multiple messages
     being sent down a single SMTP connection.

 .   Remote deliveries of the same message to different hosts can option-
     ally be done in parallel.

 .   Incoming SMTP messages start delivery as soon as they are received,
     without waiting for the SMTP call to close.

 .   Regular expressions are available in a number of configuration
     parameters.

 .   Domain lists can include file lookups, making it possible to support
     very large numbers of local domains.

 .   Exim supports optional checking of incoming return path (sender) and
     receiver addresses as they are received by SMTP.

 .   SMTP calls from specific machines, optionally from specific idents,
     can be locked out, and incoming SMTP messages from specific senders
     can also be locked out. Exim also supports the use of the Realtime      |
     Blocking List (RBL).                                                    |

 .   Hosts that are permitted to relay mail through a machine to another
     external domain can be controlled by IP number or IP network number.

 .   Messages on the queue can be 'frozen' and 'thawed' by the
     administrator.

 .   Exim can handle a number of independent local domains on the same
     machine; each domain can have its own alias files, etc. This facility
     is sometimes known as 'virtual domains'.

 .   Exim stats a user's home directory before looking for a .forward file,
     in order to detect the case of a missing NFS mount. Delivery is
     delayed if the directory is unavailable.

 .   Exim contains an optional built-in mail filtering facility. This can
     be configured to allow users to provide personal filter files, and it
     is also possible for a system-wide filter file to be applied to every
     message.

 .   Periodic warnings are automatically sent to messages' senders when
     delivery is delayed - the time between warnings is configurable.

 .   A queue run can be manually started to deliver just a particular
     portion of the queue, or those messages with a recipient whose address
     contains a given string.

 .   I have tried to make the wording of delivery failure messages clearer
     and simpler, for the benefit of those less-experienced people who are
     now using email.


1.6 Interface

Like many MTAs, Exim has adopted the Sendmail interface so that it can be a
straight replacement for OS/2 sendmail. All the relevant Sendmail
options are implemented, with one reservation. There are also some
additional options that are compatible with Smail 3, and some further
options that are new to Exim.

Sendmail uses the -bi option as a request to rebuild the alias file. As
Exim does not have the concept of a single alias file, it cannot mimic this
behaviour. It can be configured to run a particular script when this option
is received; otherwise the option is ignored.

The configuration interface is via a single text file which is divided into
a number of sections. The entries in this file consist of keywords and
values, in the style of Smail 3 configuration files. A default configur-
ation file which is suitable for simple installations is provided.

Control of messages on the queue can be done via certain command line
options.


1.7 Terminology

The term "local part", which is taken from RFC 822, is used to refer to
that part of an email address that precedes the @ sign. The part that
follows the @ sign is called the "domain" or "mail domain".

The word "domain" is sometimes used to mean all but the first component of
a machine's name. It is not used in that sense here, where it normally
refers to the part of an email address following the @ sign.

"Local domains" are mail domains for which the current host is responsible;
in other words, it has special knowledge of what to do with messages sent
to such domains, and normally that means either delivering them on the
local host or transforming them using alias files or something similar. All
other domains are "remote domains", which normally cause the message to be
transmitted to some other host.

The distinction is not always entirely clear-cut since a host can have
special knowledge about routing for remote domains, and messages for local
domains may under some circumstances be passed to other hosts.

The terms "local delivery" and "remote delivery" are used to distinguish
delivery to a file or a pipe on the local machine from delivery by SMTP to
some remote machine. The type of delivery does not necessarily correspond
to the type of address. Mail for a local domain may get passed on to some
other host, while mail for a remote domain might get delivered locally to a
file or pipe for onward transmission by some other means. However, these
are special cases.

The term "mailmaster" is used to refer to the person in charge of
maintaining the mail software on a given computer. Commonly this will be
the same person who fulfils the postmaster role, but this may not always be
the case.

The term "queue" is used to refer to the set of messages awaiting delivery,
because this term is in widespread use in the context of MTAs. However, in
Exim's case the reality is more like a pool than a queue, because there is
no ordering of waiting messages.

The term "queue-runner" is used to describe a process that scans the queue
and attempts to deliver those messages whose retry times have come. This
term is used by other MTAs, and also relates to the command runq, but in
Exim the waiting messages are normally processed in an unpredictable order.


                            2. INCORPORATED CODE


Two pieces of external code are included in the Exim distribution.

 .   Regular expressions are supported in the main Exim program and in the   |
     Exim monitor using the freely-distributable PCRE library, copyright     |
     (c) 1997 University of Cambridge. The source is distributed in the      |
     directory src/pcre.                                                     |

 .   RFC 1413 callbacks are supported in the main Exim program using the
     libident library made freely available by Peter Eriksson at
     ftp.lysator.liu.se. Some modifications have been made in order to
     support IPv6. The source is distributed in the directory called
     src/libident.



                         3. HOW EXIM DELIVERS MAIL


3.1 Philosophy

Exim is designed to work efficiently on systems that are permanently
connected to the Internet and are handling a general mix of mail. In such
circumstances, most messages can be delivered immediately. Consequently,
Exim does not maintain independent queues of messages for specific domains
or hosts, though it does try to send several messages in a single SMTP
connection after a host has been down, and it also maintains per-host retry
information.


3.2 Message reception

When Exim receives a message, it writes two files in its spool directory.
The first contains the "envelope" information, the current status of the
message, and the headers, while the second contains the body of the
message.

The envelope information consists of the address of the message's sender
and the address(es) of the recipient(s). This information is entirely
separate from any addresses contained in the headers. The status of the
message includes a list of recipients who have already received the
message. The format of the first spool file is described in chapter 50.

Any header rewriting that is specified in the configuration (see chapter
33) is done once and for all as the message is received. It is also
possible to specify the addition or removal of certain headers at the time
the message is written out (see chapter 13).

Every message handled by Exim is given a "message id" which is 16
characters long. It is divided into three parts, separated by hyphens. Each
part is a number, expressed in base 62:

     The first six characters are the time the message was received, as a
     number in seconds - the normal Unix way of representing a time of day.

     After the first hyphen, the next six characters are the id of the
     process that received the message.

     The final two characters, after the second hyphen, are used to ensure
     the id is unique, and are 00 except when a process receives more than
     one message in a single second.

The names of the two spool files consist of the message id, followed by -H
for the file containing the envelope and headers, and -D for the data file.

By default all these spool files are held in a single directory called
"input" inside the general exim spool directory. Some operating systems do
not perform very well if the number of files in a directory gets very
large; to improve performance in such cases there is an option that causes
Exim to split up the input files into 62 sub-directories whose names are
single letters or digits.


3.3 Life of a message

A message remains in the spool directory until it is completely delivered
to its recipients or to an error address, or until it is deleted by an
administrator or by the user who originally created it. In cases when
delivery cannot proceed - for example, when a message can neither be
delivered to its recipients nor returned to its sender, the message is
marked 'frozen' on the spool, and no more deliveries are attempted.

An administrator can thaw such messages when the problem has been correc-
ted, and can also freeze individual messages by hand if necessary. In
addition, an administrator can force a delivery error, causing an error
message to be sent.

As delivery proceeds, Exim writes timestamped information about each
address to a per-message log file; this includes any delivery error
messages. This log is solely for the benefit of the administrator, and is
normally deleted with the spool files when processing of a message is
complete. However, Exim can be configured to retain it (a dangerous option,
as the files can accumulate rapidly on a busy system). Exim also writes
delivery messages to its main log file, whose contents are described in
chapter 45.

All the information Exim itself needs to set up a delivery is kept in the
first spool file with the headers. When a successful delivery occurs, the
address is immediately written at the end of a journal file, whose name is
the message id followed by -J. At the end of a delivery run, if there are
some addresses left to be tried again later, the first spool file is
updated to indicate which these are, and the journal file is then deleted.
Updating the spool file is done by writing a new file and renaming it, to
minimize the possibility of data loss.

Should the system or the program crash after a successful delivery but
before the spool file has been updated, the journal is left lying around.
The next time Exim attempts to deliver the message it reads the journal
file and updates the spool file before proceeding. This minimizes the
chances of double deliveries caused by crashes.


3.4 Drivers

The main delivery processing elements of Exim are called directors,
routers, and transports, and collectively these are known as
drivers. Code for a number of them is included in the binary (as OS/2
programs are normally distributed in binary form, compile-time options
are not used), and runtime options specify which ones are actually
used.

A transport is a driver that transmits a copy of the message from Exim's     |
spool to some destination. There are two kinds of transport: for a local     |
transport, the destination is a file or a pipe on the local host, while for  |
a remote transport the destination is some other host. A message is passed   |
to a specific transport as a result of successful directing or routing. If   |
a message contains several addresses, it may be passed to a number of        |
different transports.                                                        |
                                                                             |
A director is a driver that operates on a local address, either determining  |
how its delivery should happen, or converting the address into one or more   |
new addresses (for example, via an alias file). A local address is one       |
whose domain matches an entry in the list given in the local_domains option  |
(except in one special case - see below). The fact that an address is local  |
does not imply that the message has to be delivered locally; it can be       |
directed to a local or to a remote transport.                                |
                                                                             |
A router is a driver that operates on a remote address, that is an address   |
whose domain does not match anything in the list given in local_domains.     |
When a router succeeds it can route an address to either a local or a        |
remote transport, or it can change the domain, and pass the address on to    |
subsequent routers. In exceptional cases, a router may determine that an     |
address is local after all, and cause it to be passed to the directors.      |
This happens automatically if a host lookup expands an abbreviated domain    |
into one that is local; it can also be made to happen if an MX record        |
points to the local host. This is the one case in which the directors are    |
used to process an address that may not match anything in local_domains.     |
The diagram below illustrates the relationship between the three kinds of    |
driver.                                                                      |
                                                                             |
                           address                                           |
                              |                                              |
                              |<---------- new address --------              |
                              V                               |              |
                      -----------------                       |              |
                      |    matches    |                       |              |
       ------- no ----| local_domains |--- yes -------        |              |
       |              |    option?    |              |        |              |
       V              -----------------              V        |              |
  -----------                                   ------------  |              |
  | routers |--- local after all ------------->| directors |---              |
  -----------                                  -------------                 |
       |                --------------               |                       |
       ---------------->| transports |<---------------                       |
                        --------------                                       |
                                                                             |
As new features have been added to Exim, the distinction between routers     |
and directors has become less clear-cut than it once was. However, since a   |
typical configuration has a number of directors and routers, checking the    |
domain against local_domains once at the start does use fewer resources      |
than checking it for each of them.                                           |


3.5 Delivery in detail

When a message is to be delivered, the sequence of events is roughly as
follows:

 .   If a system-wide filter file is specified, the message is passed to
     it. The filter may add recipients to the message, replace the
     recipients, discard the message, cause a new message to be generated,
     or cause the message delivery to fail. This facility is intended as a
     weapon against mail bombs and unsolicited mail. The format of the
     filter file is the same as for user filter files, described in the
     separate document entitled "Exim's User interface to mail filtering".
     Some additional features are available in systems filters - see
     chapter 41 for details. Note that a message is passed to the system
     filter only once, however many recipients it has.

 .   Each address is parsed and a check is made to see if it is local or
     not, by comparing the domain with the list in the local_domains
     option. This can contain wild cards and file lookups if necessary.

 .   If an address is local, it is passed to each configured director in
     turn until one is able to handle it. If none can, the address is
     failed. Directors can be targeted at particular local domains, so
     several local domains can be processed entirely independently of each
     other.

 .   A director that accepts an address may set up a local or a remote
     transport for it, or it may generate one or more new addresses
     (typically from alias, forward, or filter files). New addresses are
     fed back into this process from the top, but in order to avoid loops,
     a director ignores any address which has an identically-named ancestor
     that was processed by itself.

 .   If an address is not local, it is passed to each router in turn until
     one is able to handle it. If none can, the address is failed.

 .   A router that accepts an address may set up a transport for it, or may
     pass an altered address to subsequent routers, or it may discover that
     the address is a local address after all. This typically happens when
     a partial domain name is used and (for example) the DNS lookup is
     configured to try to extend such names. In this case, the address is
     passed to the directors. Exim can be configured to do this for any      |
     domain whose lowest MX record points to the local host.                 |

 .   Routers normally set up remote transports for messages that are to be
     delivered to other machines. However, a router can pass a message to a
     local transport, and by this means such messages can be routed to
     other transport mechanisms via pipes or files.

 .   When all the directing and routing is done, addresses that have been
     successfully handled are passed to their assigned transports. When
     local transports are doing real local deliveries, they handle only one
     address at a time, but if a local transport is being used as a pseudo-
     remote transport (for example, to collect batched SMTP messages for
     transmission by some other means) multiple addresses can be handled.
     Remote transports can always handle more than one address at once, but
     can be configured not to do so, or to restrict multiple addresses to
     the same domain.

 .   Each local delivery runs in a separate process, and they are run
     in sequence. By default the remote deliveries run one at a time in
     the main Exim process, but a configuration option is available to
     allow multiple remote deliveries for a single message to be run
     simultaneously, each in its own sub-process.

 .   Before running any local transport, Exim checks its retry database to
     see if there has been a previous temporary delivery failure for the
     address. If so, it does not attempt a new delivery until the retry
     time for the address is reached. Remote transports do their own retry
     handling, since an address may be deliverable to one of a number of
     hosts, each of which may have a different retry time. If there have
     been previous failures and no host has reached its retry time, no
     delivery is attempted. See chapter 32 for details of retry strategies.

 .   If there were any errors, a message is returned to an appropriate
     address (the sender in the common case), with details of the error for
     each failing address. Exim can be configured to send copies of error
     messages to other addresses.

 .   If one or more addresses suffered a temporary failure, the message is
     left on the queue, to be tried again later. Otherwise the spool files
     and message log are deleted, though the message log can optionally be
     preserved if required.

Delivery is said to be "deferred" when the message remains on the queue for
a subsequent delivery attempt after a temporary failure. Such messages get
processed again by queue-runner processes that are periodically started,
either by an Exim daemon or via cron.

Temporary failures may be detected during routing and directing as well as
during the transport stage. Exim uses a set of configured rules to
determine when next to process the failing address (see chapter 32). These
rules also specify when Exim should give up trying to deliver to the
address, at which point it generates a failure report.

When a message cannot be delivered to some or all of its intended
recipients, a delivery failure report is generated. All the addresses that
failed in a given delivery attempt are listed in a single failure report.
If a message has many recipients, it is possible for some addresses to fail
in one delivery attempt and others to fail subsequently, giving rise to
more than one failure report for a single message.

A failure report is normally sent to the sender of the original message, as
obtained from the message's envelope. For incoming SMTP messages, this is
the address given in the MAIL FROM command. However, when an address is
expanded via a forward or alias file, an alternative address can be
specified for delivery failures of the generated addresses. For a mailing
list expansion (see chapter 36) it is common to direct failure reports to
the manager of the list.

If a failure report (either locally generated or received from a remote
host) itself suffers a delivery failure, the message is left on the queue,
but is 'frozen', awaiting the attention of an administrator. However, there  |
are options which can be used to make Exim discard such failure reports, or  |
to keep them for only a short time.                                          |

There are many reasons why a message may not be immediately deliverable to
a particular address. Failure to connect to a remote machine (because it,
or the connection to it, is down) is one of the most common. Local
deliveries may also be delayed if NFS files are unavailable, or if a
mailbox is on a filing system where the user is over quota. Exim can be
configured to impose its own quotas on local mailboxes; where system quotas
are set they will also apply.

A machine that is connected to the Internet can normally deliver most mail
straight away (the usual figure for Cambridge is 98%). In its default
configuration, Exim starts a delivery process whenever it receives a
message, and usually this completes the entire delivery. This is a
lightweight approach, avoiding the need for any centralized queue managing
software. There are those who argue that a central message manager would be
able to batch up messages for the same host and send them in a single SMTP
call. I do not myself believe this would occur much in general, unless
messages were significantly delayed in order to create a batch.

However, if a host is unreachable for a period of time, a number of
messages may be waiting for it by the time it recovers, and sending them in
a single SMTP connection is clearly beneficial. Whenever a delivery to a
remote host is deferred, Exim makes a note in its hints database, and
whenever a successful SMTP delivery has happened, it looks to see if any
other messages are waiting for the same host. If any are found, they are
sent over the same SMTP connection, subject to a configuration limit as to
the maximum number in any one connection.

Exim can be configured not to start a delivery process automatically when a
message is received; this can be unconditional, or depend on the number of
incoming SMTP connections or the system load (where available). In these
situations, new messages wait on the queue until a queue-runner process
picks them up.



                      4. BUILDING AND INSTALLING EXIM


4.1 Unpacking

Exim is distributed as a zip file which, when unpacked, creates a
directory named exim into which the following files are placed:

NOTICE              notice about conditions of use
README              this file
configure.default   an example configuration file
exim.exe            Exim itself
exim_dbmbuild.exe   \
exim_dumpdb.exe     |
exim_fixdb.exe      |
exim_tidydb.exe     > various utilities and scripts
Exigrep.pl          |
Eximstats.pl        |
Exiqsumm.pl         /

It also creates the following subdirectories:

doc/                directory of documentation files
exim-src/           directory of the source files for Exim itself
util-src/           directory of the source files for the independent utilities

(Limitation: At present, exim expects the 'exim' directory to exist in
the root directory of the chosen drive. This will hopefully be
resolved in a future version of Exim for OS/2.)


4.2. Directories and environment variables

Exim for OS/2 requires the following three environment variables set
for proper operation, preferably in CONFIG.SYS. However, it can be
useful to change them for individual invocations of Exim:

USER            Contains the 'login name' of the current user, unless
                overridden with the -f switch.
USERFULLNAME    Contains the full name of the current user, unless
                overridden with the -F switch.
EDITOR          Contains the name of an editor to be used for editing
                e-mail on the queue.

Example:

SET USER=jruser
SET USERFULLNAME=J. Random User
SET EDITOR=/os2/e.exe

(Note that slashes, not backslashes, are used in pathnames.)

EXIM FOR OS/2 REQUIRES THE FOLLOWING SETTINGS TO BE MADE! NO LOCAL
DELIVERIES WILL WORK WITHOUT THEM!

As OS/2 itself does not support multiple users, a method for emulating
them had to be chosen in order for local deliveries to work correctly.

Rather than reimplement the excessive Unix-style passwd file, a
simpler method was chosen. A selected directory would be the 'base'
directory for the home directories of users; every directory under
this would be the home directory of a user. The existence of a
directory under the base would be taken to indicate the existence of a
user with the same name, and their .forward file, etc. would be read
from that directory.

The name of the 'base' directory must be set in the HOMEBASE
environment variable, terminated by a slash. It should not include a
drive letter, if you plan to forward mail to files. This limitation
should hopefully be corrected in a future release of Exim for OS/2.

Example:

I have a machine used by three users, foo, bar and baz, all of whom
wish to receive mail through Exim.

Therefore, I create a directory called 'home' off the root of my Exim
drive (d:), and add the following statement to my CONFIG.SYS file:

SET HOMEBASE=/home/

Under the d:\home directory, I create three more directories, foo, bar
and baz.

Now, mail addressed to any of these three users will be delivered
normally by the localuser transport. Mail addressed to other usernames
will be rejected by it.

If baz wished to have her mail forwarded to another machine, she
should create a normal .forward file, with the name:

d:/home/baz/.forward

(Limitation: For the moment, the home directories must exist on the
same drive as that which Exim is installed on. This will hopefully be
corrected in a future version of Exim for OS/2.)


4.3 Configuration file

A default configuration file is supplied under the name
configure.default. It will be necessary either to create your own, or
rename than one, to either simply 'configure', or 'configure.hostname'
if you are planning to use share the one copy of exim between multiple
machines.

If you use the default, 'minimal' configuration file, you will need to
edit it and change the line:

primary_hostname = put.your.hostname.here

to include the actual, fully qualified name of your machine.

Bear in mind that the default configuration will try to deliver mail
into Unix-style mailboxes in the directory /var/mail, and will look
for an aliases file in /etc - it is likely that you will want to
change this.


4.12 Setting up the spool directory

When it starts up, Exim tries to create its spool directory if it does
not exist. Sub-directories are automatically created in the spool
directory as necessary.


4.13 Testing

Having installed Exim and set up its runtime configuration file, some
simple tests can be done by using the address testing option. For
example,

  exim -v -bt <local username>

should verify that it recognizes a local mailbox, and

  exim -v -bt <remote address>

a remote one. Then try getting it to deliver mail, both locally and
remotely.

One thing that cannot be tested on a system that is already running a
mailer is the receipt of incoming SMTP mail on the standard SMTP port.
However, the -oX option can be used to run an Exim daemon that listens on
some other port, or inetd can be used to do this.

For debugging purposes, code for a transport called debug is included
in the binary. On Unix systems, it is recommended that this never be
included as a matter of course, because it makes it possible to
subvert mail deliveries. However, as all users under OS/2 possess the
equivalent of root privilege, I feel that including it poses no
additional security problem to include it, and it will make life
easier for those who need to debug but don't want to have to go
looking for compilers, etc. When this code is available, the
debug_transport runtime configuration option can be set, and this
suppresses normal mail delivery.  Instead, information about each
delivery is written to a file named by the debug_transport
option. Further details are given in chapter 17.


4.14 Switching Exim on

Installing Exim does not of itself put it in general use.

To make exim a drop-in replacement for OS/2 sendmail, simply make a
copy of exim in the exim directory named sendmail.exe. It is easiest
to simply place the 'exim' directory on the PATH statement in
CONFIG.SYS (if you have not already done so), and then rename the
sendmail.exe file in the \tcpip\bin directory to sendmail.not_in_use.

This will cause Exim to be invoked rather than sendmail by all
programs which use it. It is probably better to reconfigure programs
to call Exim instead where this is possible, but some programs seem to
have calls to sendmail hardcoded.

I have found the following 4OS/2 aliases useful in using Exim
locally. I offer them here for anyone who might find them useful, as
aliases or as .cmd files:

mailsend    exim -q
mail        exim -bm -t
queue       exim -bpa
smtp        exim -bs -d1


                          5. THE EXIM COMMAND LINE


Exim's command line takes the standard Unix form of a sequence of options,
each starting with a hyphen character, followed by a number of arguments.
The options are compatible with the main options of Sendmail, and there are
also some additional options, some of which are compatible with Smail 3.
Certain combinations of options do not make sense, and provoke an error if
used. The form of the arguments depends on which options are set.


5.1 Setting options by program name

If Exim is called under the name mailq, it behaves as if the option -bp
were present before any other options. This is for compatibility with some
systems that contain a command of that name in one of the standard
libraries.

If Exim is called under the name rsmtp it behaves as if the option -bS were
present before any other options, for compatibility with smail. The -bS
option is used for reading in a number of messages in batched SMTP format.

If Exim is called under the name rmail it behaves as if the option -i were
present before any other options, for compatibility with smail. The -i
option is used for reading a message that should not be terminated by a dot
on a line by itself. The name rmail is used as an interface by some UUCP
systems.

If Exim is called under the name runq it behaves as if the option -q were
present before any other options, for compatibility with smail. The -q
option causes a single queue-runner process to be started.


5.3 Command line options

The command options are described in alphabetical order below.

-bd    Run Exim as a daemon, awaiting incoming SMTP connections. By
       default, Exim listens for incoming connections on all
       the host's interfaces, but it can be restricted to specific inter-
       faces by setting the local_interfaces option in the configuration
       file. The standard SMTP port is used, but this can be varied by
       means of the daemon_smtp_service configuration option or the -oX      |
       command line option. Most commonly, the -bd option is combined with   |
       the -q<time> option, to cause periodic queue runs to happen as well.

       Note: Under OS/2, the daemon cannot detach itself from an OS/2
       session. At present, it also cannot be detached using the
       DETACH command - it becomes unable to start subprocesses -
       which I believe to be a compiler limitation.

       It is suggested that Exim be run in a minimised OS/2 window.

       The process id of a daemon that is both listening and starting queue
       runners is written to a file called exim-daemon.pid in Exim's spool
       directory, unless the -oX option is used, in which case the file
       name is exim-daemon.<port-number>.pid. If a daemon is run with only
       one of -bd and -q<time>, then that option is added on to the end of
       the file name, allowing sites that run two separate daemons to
       distinguish them.

       The SIGHUP signal can be used to cause the daemon to re-exec itself.
       This should be done whenever Exim's configuration file is changed,
       or a new version of Exim is installed. It is not necessary to do
       this when other files (e.g. alias files) are changed.

-bf <filename>
       Run Exim in filter testing mode; the file is the filter file to be
       tested, and a test message must be supplied on the standard input.
       If there are no message-dependent tests in the filter, an empty file
       can be supplied. If the test file does not begin with the special
       line

         # Exim filter

       then it is taken to be a normal .forward file, and is tested for
       validity under that interpretation. The result of this command,
       provided no errors are detected, is a list of the actions that Exim
       would try to take if presented with the message for real. More
       details of filter testing are given in the separate document
       entitled "Exim's User interface to mail filtering".

       When testing a filter file, various parameters that would normally
       be taken from the envelope recipient address of a message can be set
       by means of additional command line options. These are:

         -bfd  <domain>            default is the qualify domain
         -bfl  <local_part>        default is the logged in user
         -bfp  <local_part_prefix> default is null
         -bfs  <local_part_suffix> default is null

       The local part should always be set to the incoming address with any
       prefix or suffix stripped, because that is how it appears when a
       message is actually being delivered.

-bi    Sendmail interprets the -bi option as a request to rebuild its alias
       file. Exim does not have the concept of a single alias file, and so
       it cannot mimic this behaviour. However, calls to /usr/lib/sendmail
       -bi tend to appear in various scripts such as NIS make files, so the
       option must be recognized.

       If -bi is encountered, the command specified by the bi_command
       configuration option is run. If the -oA option is used, its
       value is passed to the command as an argument. The command set
       by bi_command may not contain arguments. The command can use
       the exim_dbmbuild utility, or some other means, to rebuild
       alias files if this is required. If the bi_command option is
       not set, then calling Exim with -bi is a no-op.

       (Note: you can't yet call scripts with this facility, but this
        is planned for a future release of Exim for OS/2.)

-bm    Accept an incoming, locally-generated message on the current input,
       and deliver it to the addresses given as the command arguments
       (except when -t is also given - see below). Each argument can be a
       comma-separated list of RFC 822 addresses. This is the default
       option, and is assumed if no other conflicting option is present.

       The format of the message must be as defined in RFC 822, except       |
       that, for compatibility with sendmail and smail, a line in one of     |
       the forms                                                             |
                                                                             |
         From sender Fri Jan  5 12:55 GMT 1996                               |
         From sender Fri, 5 Jan 97 12:55:01                                  |
                                                                             |
       (possibly with additional text after the date) is permitted to        |
       appear at the start of the message. There appears to be no            |
       authoritative specification of the format of this line. Exim          |
       recognizes it by matching against the regular expression defined by   |
       the uucp_from_pattern option, which can be changed if necessary. The  |
       specified sender is treated as if it were given as the argument to    |
       the -f option, but if a -f option is also present, its argument is    |
       used in preference to the address taken from the message.             |

-bp    List the contents of the mail queue on the current output. Each
       message on the queue is displayed as in the following example:

         25m  2.9K 0t5C6f-0000c8-00 <alice@wonderland.fict.book>
                   red.king@looking-glass.fict.book
                   <other addresses>

       The first line contains the amount of time the message has been on
       the queue (in this case 25 minutes), the size of the message (2.9K),
       the unique local identifier for the message, and the message sender,
       as contained in the envelope. If the message is a delivery error
       message, the sender address is empty, and appears as <>. If the
       message is frozen (attempts to deliver it are suspended) then the
       text '*** frozen ***' is displayed at the end of this line.

       The recipients of the message (taken from the envelope, not the
       headers) are displayed on subsequent lines. Those addresses to which
       the message has already been delivered are marked with the letter D.
       If an original address gets expanded into several addresses via an
       alias or forward file, the original is displayed with a 'D' when
       deliveries for all of its child addresses are completed.

       If the -bp option is followed by a list of message ids, then just
       those messages are listed.

-bpa   This option operates like -bp, but in addition it shows delivered
       addresses that were generated from the original toplevel address(es)
       in each message by alias or forwarding operations. These addresses
       are flagged with '+D' instead of just 'D'.

-bpu   This option operates like -bp but shows only undelivered addresses
       for each message displayed.

-bP    If this option is given with no arguments, it causes the values of
       all Exim's main configuration options to be written to the standard
       output. The values of one or more specific options can be requested
       by giving their names as arguments, for example:

         exim -bP qualify_domain local_domains

       If configure_file is given, the name of the runtime configuration
       file is output. If log_file_path or pid_file_path are given, the
       names of the directories where log files and daemon pid files are
       written are output, respectively. If these values are unset, log
       files are written in a subdirectory of the spool directory called
       log, and pid files are written directly into the spool directory.

       If one of the words director, router, or transport is given,
       followed by the name of an appropriate driver instance, the option
       settings for that driver are output. For example:

         exim -bP transport local_delivery

       The generic driver options are output first, followed by the
       driver's private options. A list of the names of drivers of a
       particular type can be obtained by using one of the words
       director_list, router_list, or transport_list, and a complete list
       of all drivers with their option settings can be obtained by using
       directors, routers, or transports.

-brt   This option is for testing retry rules, and it must be followed by
       up to three arguments. It causes Exim to look for a retry rule that
       matches the values and to output it on the standard output. For
       example:

         exim -brt bach.comp.mus
         Retry rule: *.comp.mus  F,2h,15m; FG,4d,30m;

       See chapter 32 for a description of Exim's retry rules. The first
       argument, which is required, can be a complete address in the form
       local_part@domain, or it can be just a domain name. The second
       argument is an optional second domain name; if no retry rule is
       found for the first argument, the second is tried. This ties in with
       Exim's behaviour when looking for retry rules for remote hosts - if
       no rule is found that matches the host, one that matches the mail
       domain is sought. The final argument is the name of a specific
       delivery error, as used in setting up retry rules, for example
       'quota_3d'.

-brw   This option is for testing address rewriting rules, and it must be
       followed by a single argument, consisting of either a local part
       without a domain, or a complete address with a fully-qualified
       domain. Exim outputs how this address would be rewritten for each
       possible place it might appear.

-bS    This option is used for batched SMTP input, where messages have been
       received from some external source by an alternative transport
       mechanism. It causes Exim to accept one or more messages by reading
       SMTP on the standard input, but to generate no responses. All errors
       are reported by sending mail. The senders in the MAIL FROM
       commands are believed. Unqualified senders and receivers are
       not rejected (there seems little point) but instead just get
       qualified. Receiver verification and administrative rejection is not
       done, even if configured. HELO and EHLO act as RSET; VRFY, EXPN,
       ETRN, HELP, and DEBUG act as NOOP; QUIT quits.

-bs    This option causes Exim to accept one or more messages by reading
       SMTP commands on the standard input, and producing SMTP replies on
       the standard output. Some user agents use this interface as a way of
       passing locally-generated messages to the MTA. The option can also
       be used to run Exim from inetd, as an alternative to using a
       listening daemon, in which case the standard input is the connected
       socket. Exim distinguishes between the two cases by attempting to
       read the IP address of the peer connected to the standard input. If
       it is not a socket, the call to getpeername() fails, and Exim
       assumes it is dealing with a local message.

       The senders of messages are taken from the SMTP MAIL FROM commands.

-bt    Run in address testing mode, in which each argument is taken as an
       address to be tested. The results are written to the standard
       output. If no arguments are given, Exim runs in an interactive
       manner, prompting with > for addresses to be tested. Each address is
       handled as if it were the recipient address on a message and passed
       to the appropriate directors or routers (compare the -bv option);
       the result is written to the standard output. The return code is 2
       if any address failed outright; it is 1 if no address failed
       outright but at least one could not be resolved for some reason.
       Return code 0 is given only when all addresses succeed.

-bV    Write the current version number, compilation number, and compi-
       lation date of the exim binary to the standard output.

-bv    Verify the addresses that are given as the arguments to the command,
       and write the results to the standard output. Verification differs
       from address testing (the -bt option) in that directors and routers
       that have no_verify set are skipped, and if the address is accepted
       by a director or router that has fail_verify set, verification
       fails. This is the same logic that is used when verifying addresses
       on incoming messages (see the sender_verify and receiver_verify
       options).

       If the -v (or -d) option is not set, the output consists of a single
       line for each address, stating whether it was verified or not, and
       giving a reason in the latter case. Otherwise, more details are
       given of how the address has been handled, and in the case of
       aliases or forwarding, the generated addresses are also considered.

       The return code is 2 if any address failed outright; it is 1 if no
       address failed outright but at least one could not be resolved for
       some reason. Return code 0 is given only when all addresses succeed.

-C <filename>
       Read the runtime configuration from the given file instead of from
       the default file 'configure' or 'configure.hostname'.

-D<macro>=<value>                                                            |
       This option can be used to override macro definitions in the          |
       configuration file.                                                   |

-d<number>
       Sets a debug level, causing debugging information to be written to
       the standard error file. Whitespace between -d and the number is
       optional. If no number is given, 1 is assumed, and the higher the
       number, the more output is produced. A value of zero turns debugging
       output off and is the default. A value of 9 gives the maximum amount
       of general information, 10 gives in addition details of the
       interpretation of filter files, and 11 or higher also turns on the
       debugging option for DNS lookups.

-df    If this option is set, debugging information is written to the
       file '/exim/stderr' instead of to the standard error file. This
       option provides a way of obtaining debugging information when
       Exim is run from inetd.

-dm    This option causes information about memory allocation and freeing
       operations to be written to the standard error file.

-dropcrAt least one MUA (dtmail) that calls an MTA via the command line is
       broken in that it terminates each line with CRLF, instead of just
       LF, which is the usual Unix convention, and although this bug has
       been admitted, it apparently won't get fixed. There is also some
       UUCP software which leaves CR at the ends of lines in messages. As a
       slight pander to these programs, the -dropcr option causes Exim to
       drop all CR characters in an incoming non-SMTP message.

-E     This option specifies that an incoming message is a locally-
       generated delivery failure message. It is used internally by Exim
       when handling delivery failures and is not intended for external
       use. Its only effect is to stop Exim generating certain messages to
       the mailmaster, as otherwise message cascades could occur in some
       situations. As part of the same option, a message id may follow the
       characters -E. If it does, the log entry for the receipt of the new
       message contains the id, following 'R=', as a cross reference.

-ex    There are a number of sendmail options starting with -oe which seem
       to be called by various programs without the leading o in the
       option. For example, the vacation program uses -eq. Exim treats all
       options of the form -ex as synonymous with the corresponding -oex
       options.

-F <string>
       Set the sender's full name for use when a locally-generated message
       is being accepted. In the absence of this option, the USERFULLNAME
       environment variable is used. White space between -F and the <string>
       is optional.

-f <address>
       Set the address of the sender of a locally-generated message.

       White space between -f and the <string> is optional. The sender of a
       locally-generated message can also be set by an initial 'From_' line
       in the message - see the description of -bm above, but if -f is also
       present, it overrides 'From_'.

-h <number>
       This option is accepted for compatibility with sendmail, but at
       present has no effect. (In sendmail it overrides the 'hop count'
       obtained by counting Received headers.)

-i     This option, which has the same effect as -oi, specifies that a dot
       on a line by itself should not terminate an incoming, non-SMTP
       message. I can find no documentation for this option in Solaris 2.4
       sendmail, but the mailx command in Solaris 2.4 uses it.

-M     The arguments are interpreted as a list of message ids, and Exim
       runs a delivery attempt on each message in turn. Retry hints for any
       of the addresses are overridden - this option forces Exim to try to
       deliver even if the normal retry time has not yet been reached.

       If any of the messages is frozen, it is automatically thawed before
       the delivery attempt, provided that the caller is an admin user.

-Mar <message-id> <address> <address> ...
       The first argument must be a message id, and the remaining ones must
       be email addresses. Exim adds the addresses to the list of recipi-
       ents of the message. However, if the message is active (in the
       middle of a delivery attempt), its status is not altered. This
       option can be used only by an admin user.

-Meb <message-id>
       This runs, under cmd.exe, the command defined in the environment
       variable EDITOR on a copy of the spool file containing the body
       of message (eb = Edit Body). If the editor exits normally, then
       the result of editing replaces the spool file. The message is locked
       during this process, so no delivery attempts can occur. Note that
       the first line of the spool file is its own name; care should be
       taken not to disturb this. The thinking behind providing this
       feature is that an administrator who has had to mess around with the
       addresses to get a message delivered might want to add some
       (grumbly) comment at the start of the message text.
       
-Mes <message-id> <address>
       There must be exactly two arguments. The first argument must be a
       message id, and the second one an email address. Exim changes the
       sender address in the message to the given address, which must be a
       fully qualified address, or '<>'. However, if the message is active
       (in the middle of a delivery attempt), its status is not altered.

-Mmad <message-id>
       Exim marks the all recipient addresses in the message as already
       delivered. However, if the message is active (in the middle of a
       delivery attempt), its status is not altered.

-Mmd <message-id> <address> <address> ...
       The first argument must be a message id, and the remaining ones must
       be email addresses. Exim marks the given addresses as already
       delivered. However, if the message is active (in the middle of a
       delivery attempt), its status is not altered.

-MC <transport> <hostname> <sequence number> <message id>
       This option is not intended for use by outside callers. It is used
       internally by Exim to invoke another instance of itself to deliver a
       waiting message using an existing SMTP channel, which is passed as
       the standard input and output. Details are given in chapter 42. This
       must be the final option.

-Mc    The arguments are interpreted as a list of message ids, and Exim
       runs a delivery attempt on each message in turn, but unlike the -M
       option, it does check for retry hints, and respects any that are
       found. This option is not very useful to external callers (except
       for testing). It is provided for internal use by Exim.

-Mf    The arguments are interpreted as a list of message ids, and each
       message is marked 'frozen'. This prevents any delivery attempts
       taking place until the message is 'thawed', either manually or as a
       result of the auto_thaw configuration option. However, if any of the
       messages is active (in the middle of a delivery attempt), its status
       is not altered.

-Mg    The arguments are interpreted as a list of message ids, and Exim
       gives up trying to deliver those messages. A delivery error message
       is sent, containing the text 'cancelled by administrator'. However,
       if any of the messages is active, its status is not altered.

-Mt    The arguments are interpreted as a list of message ids, and each
       message that was 'frozen' is now 'thawed', so that delivery attempts
       can resume. However, if any of the messages is active, its status is
       not altered.

-Mrm   The arguments are interpreted as a list of message ids, and each
       message is completely removed from Exim's queue, and forgotten.
       However, if any of the messages is active, its status is not
       altered.

-m     This is apparently a synonym for -om that is accepted by sendmail,
       so Exim treats it that way too.

-N     This is a debugging option that inhibits delivery of a message at
       the transport level. It implies at least -d1. Exim goes through many
       of the motions of delivery - it just doesn't actually transport the
       message, but instead behaves as if it had successfully done so.       |
       However, it does not make any updates to the retry database, and the  |
       log entries for deliveries are flagged with '*>' rather than '=>'.    |

-oA <file name>
       This option is used by Sendmail in conjunction with -bi to specify
       an alternative alias file name. Exim handles -bi differently; see
       the description above.

-oB <n>This is a debugging option which limits the maximum number of SMTP
       deliveries down one channel to <n>, overriding the value set in the
       smtp transport. If <n> is omitted, the limit is set to 1 (no
       batching).

-odb   This option applies to all modes in which Exim accepts incoming
       messages, including the listening daemon. It requests 'background'
       delivery of such messages, which means that the accepting process
       automatically starts another delivery process for each message
       received. Exim does not wait for such processes to complete (it can
       take some time to perform SMTP deliveries). This is the default
       action if none of the -od options are present.

-odf   This option (compatible with smail) requests 'foreground' (syn-
       chronous) delivery when Exim has accepted a locally-generated mess-
       age. For the daemon it is exactly the same as -odb. For a single
       message received on the standard input, if the protection regime
       permits it (see chapter 49), Exim converts the reception process
       into a delivery process. In other cases, it creates a new delivery
       process, and then waits for it to complete before proceeding.

-odi   This option is synonymous with -odf. It is provided for compati-
       bility with sendmail.

-odq   This option applies to all modes in which Exim accepts incoming
       messages, including the listening daemon. It specifies that the
       accepting process should not automatically start a delivery attempt
       for each message received. Messages are placed on the queue, and
       remain there until a subsequent queue-running process encounters
       them. The queue_only configuration option has the same effect.

-odqr  This option applies to all modes in which Exim accepts incoming
       messages, including the listening daemon. It causes Exim to process
       local addresses when a message is received, but not even to try
       routing remote addresses. Contrast with -odqs below, which does the
       routing, but not the delivery. The remote addresses will be picked
       up by the next queue runner. The queue_remote configuration option
       has the same effect.

-odqs  This option is a hybrid between -odb and -odq. A delivery process is
       started for each incoming message, the addresses are all processed,
       and local deliveries are done in the normal way. However, if any
       SMTP deliveries are required, they are not done at this time. Such
       messages remain on the queue until a subsequent queue-running
       process encounters them. Because routing was done, Exim knows which
       messages are waiting for which hosts, and so a number of messages
       for the same host will get sent in a single SMTP connection. The
       queue_smtp configuration option has the same effect.

-oee   If an error is detected while a non-SMTP message is being received
       (e.g. a malformed address), the error is reported to the sender in a
       mail message. Provided the message is successfully sent, Exim exits
       with a return code of zero.

-oem   If an error is detected while a non-SMTP message is being received
       (e.g. a malformed address), the error is reported to the sender in a
       mail message. Exim then exits with a non-zero return code. This is
       the default option.

-oep   If an error is detected while a non-SMTP message is being received,
       the error is reported by writing a message to the standard error
       file (stderr).

-oeq   This option is supported for compatibility with sendmail, but has
       the same effect as -oep.

-oew   This option is supported for compatibility with sendmail, but has
       the same effect as -oem.

-oi    This option, which has the same effect as -i, specifies that a dot
       on a line by itself should not terminate an incoming, non-SMTP
       message.

-oMa <host address>
       This option sets the sender host address value, and can be used only
       by a trusted caller. The value is used in log entries and can appear
       in Received headers. The option is intended for use when handing to
       Exim messages received by other means.

-oMr <protocol name>
       This option sets the received protocol value, and can be used only
       by a trusted caller. The value is used in log entries and can appear
       in Received headers. The option is intended for use when handing to
       Exim messages received by other means.

-oMs <host name>
       This option sets the sender host name value, and can be used only by
       a trusted caller. The value is used in log entries and can appear in
       Received headers. The option is intended for use when handing to
       Exim messages received by other means.

-oMt <ident string>
       This option sets the sender ident value, and can be used only by a
       trusted caller. The value is used in log entries and can appear in
       Received headers. The option is intended for use when handing to
       Exim messages received by other means.

-om    In sendmail, this option means 'me too', indicating that the sender
       of a message should receive a copy of the message if the sender
       appears in an alias expansion. Exim always does this, so the option
       does nothing.

-or <time>
       This option sets a timeout value for incoming non-SMTP messages. If
       it is not set, Exim will wait forever for the standard input. The
       value can also be set using the accept_timeout configuration vari-
       able. The format used for specifying times is described in section
       7.6.

-ov    This option has exactly the same effect as -v.

-oX <number>
       This option is relevant only when the -bd option is also given. It    |
       overrides any setting of the daemon_smtp_service option, and          |
       specifies an alternative TCP/IP port number for the listening
       daemon. When used, the process number of the daemon is written to a
       file whose name is exim-daemon.<number>.pid in Exim's spool
       directory.

-q     If the -q option is not followed by a time value, it requests a
       single queue run operation.

       Exim starts up a delivery process for each (inactive) message on the
       queue in turn, and waits for it to finish before starting the next
       one. When all the queued messages have been considered, the original
       process terminates. In other words, a single pass is made over the
       waiting mail. Use -q with a time (see below) if you want this to be
       repeated periodically.

       Exim processes the waiting messages in an unpredictable order. It
       isn't very random, but it is likely to be different each time, which
       is all that matters. If one particular message screws up a remote
       MTA, other messages to the same MTA have a chance of getting through
       if they get tried first.

       However, it is possible to cause the messages to be processed in
       lexical id order, which is essentially the order in which they
       arrived, and to start this operation at a particular point by
       following the -q option with a starting message id. For example:

         exim -q 0t5C6f-0000c8-00

       This causes Exim to skip any messages whose ids are lexically less
       than the given id. A second id can also be given to stop the queue
       run before the end. See also the -R option.

-q <time>
       This version of the -q option causes Exim to run as a daemon,
       starting a queue-running process at intervals specified by the
       given time value (whose format is described in section
        7.6). This form of the -q option is commonly combined with the
       -bd option, in which case a single daemon process handles both
       functions. A common way of starting up a combined daemon at
       system boot time is to use a command such as

         exim -bd -q30m

       Such a daemon listens for incoming SMTP calls, and also fires up a
       queue-runner process every 30 minutes. The process id of such a
       daemon is written to a file called exim-daemon.pid in Exim's spool
       directory, unless the -oX option has been used, in which case the
       file is called exim-daemon.<port-number>.pid. If a daemon is
       started without -bd then the -q option used to start it is
       added to the pid file name.

-qf    This option operates like -q, and may appear with or without a
       following time. The difference is that a delivery attempt is forced
       for each message, and any frozen messages are automatically thawed,
       whereas with -q only those addresses that have passed their retry
       times are tried.

-qfl   This option operates like -ql, and may appear with or without a
       following time. The difference is that a delivery attempt is forced
       for each message, and any frozen messages are automatically thawed,
       whereas with -ql only those local addresses that have passed their
       retry times are tried.

-ql    This option operates like -q, and may appear with or without a
       following time. The difference is that only local addresses are
       considered for delivery. Note that -ql cannot detect apparently
       remote addresses that actually turn out to be local when their
       domains get fully qualified.

-qR<string>                                                                  |
       This option is synonymous with -R. It is provided for sendmail        |
       compatibility.                                                        |
                                                                             |
-qRf<string>                                                                 |
       This option is synonymous with -Rf.                                   |

-R <string>
       This option is similar to -q with no time value, except that, when
       scanning the messages on the queue, Exim processes only those that
       have at least one undelivered address containing the given string,
       which is checked in a case-independent way. However, once a message
       is selected, all its addresses are processed. For the first message
       containing a matching address, Exim overrides any retry information
       and forces a delivery attempt. This makes it straightforward to
       initiate delivery for all messages to a given domain after a host
       has been down for some time. When the SMTP command ETRN is permitted
       (see the smtp_etrn options), its effect is to run Exim with the -R
       option.

-Rf <string>
       This option acts like -R, but forces a delivery for every matching
       message, not just the first one.

-r     This is a documented (for sendmail) obsolete alternative name for
       -f.

-t     When Exim is receiving a locally-generated, non-SMTP message on the
       current input, the -t option causes the recipients of the message to
       be obtained from the To, Cc, and Bcc headers in the message instead
       of from the command arguments. If there are any arguments, they
       specify addresses to which the message is not to be delivered. That
       is, the argument addresses are removed from the recipients list
       obtained from the headers. If a Bcc header is present, it is removed
       from the message unless there is no To or Cc header, in which case a
       Bcc header with no data is created, in accordance with RFC 822.

-v     This option has exactly the same effect as -d1; it causes Exim to be
       'verbose' and produce some output describing what it is doing on the
       standard error file. In particular, if an SMTP connection is made,
       the SMTP dialogue is shown.

-x     AIX uses -x for a private purpose ('mail from a local mail program
       has National Language Support extended characters in the body of the
       mail item'). It sets -x when calling the MTA from its mail command.
       Exim ignores this option.



                        6. FILE AND DATABASE LOOKUPS


Exim can be configured to look up data in files or databases in a number of
different circumstances. This chapter discusses some of the common features
of the data lookup facilities; particular cases are covered in more detail
in subsequent chapters.

Two different styles of data lookup are implemented:

 .   The "single-key" style requires the specification of a file in which
     to look, and a single key to search for.

 .   The "query" style accepts a generalized query, which may contain one
     or more keys.


6.1 Single-key lookup types

The following single-key lookup types are implemented:

 .   lsearch: Data are looked up by searching the given file linearly for a
     line beginning with the single key, terminated by a colon if there is
     following data. This is the traditional textual format of textual
     alias files.

 .   dbm: Calls to DBM library functions are used to extract data from the
     given DBM file by key.

NIS lookups are not implemented under OS/2.

If '*' is added to a single-key lookup type (for example, 'lsearch*'), then
if the initial lookup fails, the key '*' is looked up in the file to
provide a default value. See also the section on partial matching below.

There has been some confusion over the way lsearch lookups work. The fact    |
that the file is searched linearly does not make this kind of search any     |
different from the other single-key lookup types. Its implementation is      |
just one of several 'black boxes' which, given a key, yield a data value.    |
Thus the keys in the file are literal strings and are not interpreted in     |
any way.                                                                     |


6.2 Query-style lookup types

There are no query-style lookups implemented currently under OS/2
(i.e., no NIS+).


6.3 Use of data lookups

There are three different types of configuration item in which data lookups
can be specified:

(1)  Any string that is to be expanded may contain explicit lookup
     requests. String expansions are described in chapter 9.

(2)  Lists of domains and other items can contain lookup requests as a way
     of avoiding excessively long linear lists. See section 7.11 for a full
     description.

(3)  Some drivers can be configured look up data in files.

In a string expansion, all the parameters of the lookup are specified
explicitly, while for the other types there is always one implicit key
involved. For example, the local_domains option contains a list of local
domains; when it is being searched there is some domain name that is an
implicit key.

This is not a problem for single-key lookups; the relevant file name is
specified, and the key is implicit. For example, the list of local domains
could be given as

  local_domains = dbm;/local/domain/list

However, for query-style lookups the entire query has to be specified, and
to do this, some means of including the implicit key is required. The
special expansion variable $key is provided for this purpose. NIS+ could be
used to look up local domains by a setting such as

  local_domains = nisplus;[domain=$key],domains.org_dir

In the cases where drivers specify file lookups, there are always two
alternative configuration options: file is specified for single-key
lookups, using an implicit key, or query is specified for query-style
lookups. In the latter case the query is an expanded string, and the
relevant key is always available as one of the normal expansion variables.


6.4 Partial matching in file lookups

The normal operation of a single-key lookup is to search the file for an
exact match with the given key. However, in a number of situations where
domains are being looked up, it is possible to request partial matching. In
this case, information in the file that has a key starting with '*.'
matches any domain that ends with the components that follow the fullstop.
For example, if a key in a DBM file is

  *.dates.fict.book

then this matches the keys 2001.dates.fict.book and 1984.dates.fict.book
when partial matching is requested. It also matches the key
dates.fict.book, if that key does not itself appear in the file.

Partial matching is requested by adding the string 'partial-' at the front
of the name of a search type, for example, 'partial-dbm'. The key is first
looked up verbatim; if that fails, then '*.' is added to the start of the
key and it is looked up again. If that fails, then further lookups are
tried with dot-separated components removed from the start of the key, one-
by-one, and '*.' added on the front, until there are fewer than two non-*
components left.

In fact, the minimum number of non-* components can be adjusted by
including a number before the hyphen in the search type. For example,
'partial3-lsearch' specifies a minimum of three non-* components in the
key. If 'partial0' is used, the original key gets shortened right down to
the null string, and the final lookup is for '*' on its own.

If the search type ends in '*', then the search for a default that that
causes happens after all partial lookups have failed. If 'partial0' is
specified, adding '*' to the search type has no effect, because the '*' key
is already included in the sequence of partial lookups.


                       7. THE EXIM CONFIGURATION FILE


Exim uses a single runtime configuration file which it reads when it is
starting up. The name of the file is compiled into the binary for security
reasons, and is by default 'configure'.

Some sites may wish to use the same Exim binary on different machines
that share a filing system, but to use different configuration files
on each machine. Exim first looks for a file whose name is the
configuration file name followed by a dot and the machine's node name,
as obtained from the uname() function. If this file does not exist,
the standard name is tried.

A one-off alternative configuration file can be specified by the -C command
line option.

A default configuration file, which will work correctly in simple situ-
ations, is provided in the file configure.default.

If a syntax error is detected while reading the configuration file, Exim
writes a message on the standard error, and exists with a non-zero return
code. The message is also written to the panic log.


7.1 Configuration file format

Exim's configuration file is in six parts, which must appear in the correct
order in the file, separated by a line containing just the word 'end'.
These parts contain:

 .   Main configuration settings.

 .   Configuration settings for the transport drivers. Transports define
     mechanisms for copying messages to destinations.

 .   Configuration settings for the director drivers. Directors process
     local addresses, that is, those with domains that match local_domains.
     These are typically (but not necessarily) delivered on the local host.

 .   Configuration settings for the router drivers. Routers process remote
     addresses, that is, those with domains that do not match
     local_domains.

 .   Retry rules, for use when a message cannot be immediately delivered.

 .   Header re-writing rules.

Blank lines in the file are ignored, and lines starting with a # character
are treated as comments and are also ignored. Note that an # character       |
other than at the beginning of a line is not treated specially, and does     |
not introduce a comment. A convenient way to create a configuration file is  |
to start from the default, which is supplied in configure.default, and
add, delete, or change settings as required.

The configuration settings for the various drivers are described in
chapters 11 - 31. The retry and rewriting rules have their own syntax which
is described in chapters 32 and 33. The remaining parts have some syntactic
items in common, and these are described in sections 7.3 onwards. Before
that, the simple macro facility is described.


7.2 Macros in the configuration file

If a line in the main part of the configuration (that is, before the first
'end' line) begins with an upper case letter, it is taken as a macro
definition, of the form

  <name> = <rest of line>

The name must consist of letters, digits, and underscores, and need not all
be in upper case, though that is recommended. The rest of the line is the
replacement text, and has leading and trailing white space removed. If the
line ends with the character \ after trailing space is removed, then the
next line is concatenated with it, with the \ character and any leading
space on the following line omitted. This continues for as long as lines
end in \. Thus a replacement text can never end with a \ character, but
this doesn't seem to me to be a serious limitation.

Once a macro is defined, all subsequent lines in the file are scanned for
the macro name; if there are several macros, the line is scanned for each
in turn, in the order in which they are defined. The replacement text is
not re-scanned for the current macro, though it will be for subsequently
defined macros.

For example, suppose you have lots of local domains, but they fall into
three different types. You could set up

  LOCAL1 = domain1:\
           domain2
  LOCAL2 = domain3:domain4
  LOCAL3 = dbm;/list/of/other/domains

  local_domains = LOCAL1:LOCAL2:LOCAL3

and then use the domains option on appropriate directors to handle each set
of domains differently. This avoids having to list each domain in more than
one place.


7.3 Common option syntax

For the main set of options and for driver options, each option setting is
on a line by itself, and starts with a name consisting of lower case
letters and underscores. Many options require a data value, and in these
cases the name must be followed by an equals sign (with optional white
space) and then the value. For example:

  primary_hostname = put.your.hostname.here

Options whose type is given as boolean are on/off switches that are not
always followed by a data value. If the option name is specified on its
own, the switch is turned on; if it is preceded by 'no_' or 'not_' then the
switch is turned off. However, boolean options may alternatively be
followed by an equals sign and one of the words 'true', 'false', 'yes', or
'no'. For example:

  sender_verify
  no_smtp_verify
  queue_only = true

The types of data that may be required by non-boolean options are described
in the following sections.


7.4 Integer

If a numerical data item starts with the characters '0x', the remainder of
it is interpreted as a hexadecimal number. Otherwise, it is treated as
octal if it starts with the digit 0, and decimal if not. No negative values
are involved. If an integer value is followed by the letter K, it is
multiplied by 1024; if it is followed by the letter M, it is multiplied by
1024x1024.

When the values of option settings are output, some are always shown in
octal, and for others, values which are an exact multiple of 1024 or
1024x1024 are printed using the letters K and M. The printing style is
independent of the actual input format that was used.


7.5 Fixed point number

A fixed point number consists of a decimal integer, optionally followed by
a decimal point and up to three further digits.


7.6 Time interval

A time interval is specified as a sequence of numbers, each followed by one
of the following letters, with no intervening white space:

  s   seconds
  m   minutes
  h   hours
  d   days
  w   weeks

For example, '3h50m' specifies 3 hours and 50 minutes. The values of time
options are output in the same format.


7.7 String

If a string data item does not start with a double-quote character, then it
is taken as consisting of the remainder of the line, starting at the first
non-whitespace character, with trailing whitespace characters removed, and
with no interpretation of the characters therein.

If a string does start with a double-quote, then it continues to a closing
double-quote, with the backslash character (\) being interpreted as an
escape character. If a backslash occurs at the end of an input line, the
string is continued on the following line, with any leading whitespace
being removed. Because Exim removes comment lines (those beginning with #)
at an early stage, they can appear in the middle of a multi-line string.

The following two settings are equivalent:

  local_domains = "arkane.net:\
                   arkane.co.uk"

  local_domains = arkane.net:arkane.co.uk

If a backslash occurs in the middle of a line, the following escapes are
recognized:

  \\               single backslash
  \n               newline
  \r               carriage return
  \t               tab
  \<octal digits>  up to 3 octal digits specify one character
  \x<hex digits>   up to 2 hexadecimal digits specify one character

If a backslash is followed by some other character, including a double-
quote character, then that character replaces the pair.


7.8 Expanded strings

Some strings in the configuration file subjected to "string expansion", by
which means various parts of the string may be changed according to the
circumstances. The input syntax for such strings is as just described; the
expansion process is described in chapter 9.


7.10 String lists

Some configuration settings accept a colon-separated list of strings. In
these cases the entire list is treated as a single string as far as the
input syntax is concerned. The local_domains setting in section 7.7 above
is an example. There is a limit of 1023 on the number of characters in an
item in a string list. If a colon is actually needed in an item in a string
list, it can be entered as two colons.

Leading and trailing whitespace on each item in a string list is ignored.
This makes it possible to include items that start with a colon.


7.11 Domain lists

Domain lists are colon-separated string lists containing a number of domain
patterns that are to be matched against a domain given in a mail address.
Several different kinds of matching are provided:

 .   If a pattern consists of a single @ character, it matches the local
     host name, as set in the primary_hostname option. This makes it
     possible to use the same configuration file on several different hosts
     that differ only in their names.

 .   If the pattern starts with an asterisk, then the remaining characters
     of the pattern are compared with the terminating characters of the
     domain.

 .   If the pattern starts with a circumflex character, then it is treated
     as a regular expression, and matched against the domain using a
     regular expression matching function. The circumflex is treated as
     part of the regular expression. The syntax of regular expressions is
     described in chapter 8, but note that if a backslash is required in
     the regular expression, it must be given as two backslashes in the
     string if the string is in quotes.

 .   If the pattern starts with one of the strings 'dbm;' or 'lsearch;'
     then the remainder of the pattern must be an absolute file name. In
     the first case, a DBM lookup is done on the file using the domain name
     as the key; in the second case a linear search is performed for a line
     starting with the domain name, which must be followed by a colon if
     there is other data on the line (i.e. it is in the format of an alias
     file). The data from a DBM lookup or the rest of a linear search line
     is available in some cases via the expansion variable $domain_data.     |

 .   Any of the two lookup types just mentioned may be preceded by
     'partial<n>-', where the <n> is optional, for example,

       partial-dbm;/partial/domains

     This causes partial matching logic to be invoked; a description of how
     this works is given in the next section.

 .   Also, any of the four lookup types may be followed by an asterisk.      |
     This causes a default lookup for a key consisting of a single asterisk  |
     to be done when a lookup fails. This is not a useful feature when       |
     using a domain list to select particular domains (because anything can  |
     be matched), but it might have value if the result of the lookup is     |
     being used via the $domain_data expansion variable.                     |

 .   If none of the above cases apply, a straight textual comparison is
     made between the pattern and the domain.

Here is an example which uses all four kinds of pattern:

  local_domains = "lib.unseen.edu:\
                   *.foundation.fict.book:\
                   ^[1-2]\\d{3}\\.fict\\.book$:\
                   dbm;/opt/data/penguin/book"

There are obvious processing trade-offs among the various matching modes.
Using an asterisk is faster than a regular expression, and listing a few
names explicitly probably is too. The use of a file or database lookup is
expensive, but may be the only option if hundreds of names are required.
The patterns are tested in order, so it makes sense to put the most
commonly matched patterns earlier in the string.


7.12 Partial matching in domain lists

When one of the single-key lookup types is preceded by 'partial-' then
matching proceeds as follows: First the subject text is looked up verbatim;
if that fails, '*.' is added to the front of the subject and another lookup
is tried. If that fails, domains are chopped off and replaced by '*.' until
there are fewer than two left. For example, if the file contains

  *.neverwhere.tvs

then domains such as market.neverwhere.tvs and downst.neverwhere.tvs match
it, as does neverwhere.tvs itself, provided there isn't a separate entry
for it in the file. A different minimum number of components can be imposed
by supplying a number after 'partial', for example, 'partial3-dbm'.


7.13 Address lists

An address list is a string list in which each item is a pattern to be
matched against a mail address. There are several alternative formats:

 .   If a pattern starts with ^ then a regular expression match is done
     against the complete address.

 .   If there is no @ in the pattern, it is first matched against the
     domain part of the subject address, the local part being ignored. This
     match is done exactly as for an entry in a domain list, so, for         |
     example, the item may begin with * or it may be a lookup (see section   |
     7.11). If there is no match, and the pattern consists of a single file  |
     lookup, then the entire subject address is looked up in the file, with
     partial matching disabled. This means that an item such as

       sender_reject_recipients = partial-dbm;/black/list

     can reference a single file containing a mixture of complete domains,
     partial domains, and individual mail addresses.

 .   If the pattern starts with '@@<lookup-item>' (for example,
     '@@lsearch;/some/file'), the address that is being checked is split
     into a local part and a domain. The domain is looked up in the file.
     If it is not found, there is no match. If it is found, the data that
     is looked up from the file is treated as a colon-separated list of
     local part patterns, each of which is matched against the subject
     local part in turn.

     The lookup may be a partial one, and/or one involving a search for a
     default keyed by '*'. The local part patterns that are looked up can
     be regular expressions or begin with '*', or even be further lookups.
     In lsearch files, an entry may be split over several lines by
     indentating the second and subsequent lines, but the separating colon
     must still be included at line breaks. White space surrounding the
     colons is ignored. For example:

       aol.com:  spammer1 : spammer2 : ^[0-9]+$ :
                 spammer3 : spammer4

     As in all colon-separated lists in Exim, a colon can be included in an
     item by doubling.

     If the last item in the list starts with the character '>', then the
     remainder of the item is taken as a new key to look up for a
     continuation list of local parts. The new key can be any sequence of
     characters. Thus one might have entries like

       aol.com: spammer1 : spammer 2 : >*
       xyz.com: spammer3 : >*
       *:       ^\d{8}$

     in a file that was searched with lsearch*, to produce a match for
     8-digit local parts for all domains. Of course, using this feature
     costs another lookup each time a chain is followed, but the effort
     needed to maintain the data is reduced. It is possible to construct
     loops using this facility, and in order to catch them, the chains may
     be no more than 50 long.

 .   If none of the above cases apply, the local part of the subject
     address is compared with the local part of the pattern, which may
     start with an asterisk. If the local parts match, then the domains are
     compared in exactly the same way as entries in a domain list, except    |
     that a regular expression is not permitted for a domain only. However,  |
     file lookups are permitted. For example:

       sender_reject = "*@*.spamming.site:\
                        bozo@partial-lsearch;/list/of/dodgy/sites"

     The domain may be given as a single '@' character, as in a domain
     list, standing for the local host name, leading to items of the form
     'user@@'.


7.14 Host lists

Host lists are used to control what remote hosts are allowed to do (for      |
example, use the local host as a relay) and are in the same form as domain   |
lists, with some extensions. IP literal addresses are permitted, and any     |
item can optionally be preceded by                                           |
                                                                             |
  <ident>@                                                                   |
  or                                                                         |
  !<ident>@                                                                  |
                                                                             |
where <ident> is an RFC 1413 identification string. For example,             |
                                                                             |
  sender_host_accept = exim@my.mail.gate                                     |
  sender_host_reject = 111.111.111.111:!root@public.host                     |
                                                                             |
If an <ident> string is present, then it must match the RFC 1413             |
identification sent by the remote host, unless it is preceded by an          |
exclamation mark, in which case it must not match. Such entries may be       |
freely mixed with other types, and address literals can be IPv4 or IPv6      |
addresses (once IPv6 support is compiled into Exim).                         |
                                                                             |
When a host list contains a wildcarded entry, Exim has to use the remote     |
host's IP address to look up its name (using gethostbyaddr()) in order to    |
match it against the wildcard. If the lookup fails, Exim takes a hard line   |
by default: if the host list is of the 'accept' type, it behaves as if the   |
remote host does not match the entry, whereas if it is of the 'reject'       |
type, it behaves as if it does. In some situations this may be too harsh.    |
If an entry in a host list is the string '+allow_unknown', then if a         |
reverse lookup is necessary for checking any subsequent items in the list,   |
and the lookup fails, the opposite action to the default happens. That is,   |
for an 'accept' list the host is deemed to be in the list, and for a         |
'reject' list it is deemed not to be in the list.                            |


7.15 Net lists

Net lists are colon-separated string lists in which each item identifies an
IP network (that is, a set of IP addresses) or is the name of a file
containing a list of such items. Each item consists of an IP network number
and a net mask, separated by a slash.

IPv4 addresses are given in the normal 'dotted-quad' notation, and the mask  |
for an IPv4 address can also be given in this form, a syntax which is        |
retained for compatibility, but which is no longer recommended. The          |
preferred mask specification is a single number, specifying the number of 1  |
bits, starting at the most significant end.                                  |
                                                                             |
This example shows both kinds of address:                                    |
                                                                             |
  receiver_unqualified_nets = "123.123.0.0/16: \                             |
                               5f03::1200::836f::::/48"                      |
                                                                             |
When a netlist is used for checking a host, its IP address is compared with
the network number using the given mask.

When a netlist item is a file name, each line in the file must be a netlist
item, complete with mask. Blank lines and lines starting with # are
ignored. In fact, a # character anywhere in a line causes the rest of the
line to be ignored in a netlist file (this is not true of Exim configur-     |
ation files in general). For example, if the file /opt/exim/unqualnets       |
contained

  123.123.0.0/16
  5f03:1200:836f::/48

then specifying

  receiver_unqualified_nets = /opt/exim/unqualnets

has exactly the same effect as the previous example above. Note that there
are no colon separators or backslash continuations, and that colons in IPv6
addresses are not doubled.


                           8. REGULAR EXPRESSIONS


Exim uses the PCRE regular expression library; this provides regular         |
expression matching that is compatible with Perl 5. The format of these      |
regular expressions is described in many Perl reference books, and also in   |
Jeffrey Friedl's Mastering Regular Expressions (O'Reilly, ISBN               |
1-56592-257-3).                                                              |
                                                                             |
The PCRE distribution files, which are included in the directory             |
exim-src/pcre in the Exim distribution, contain a man page for PCRE which    |
describes exactly what it supports, so no further description is included    |
here. The PCRE functions are called from Exim using the default option       |
settings, except when processing the 'matches' action in an Exim filter,     |
where PCRE_CASELESS is set to cause matching to be independent of the case of|
letters.                                                                     |



                            9. STRING EXPANSIONS


A number of configuration strings are expanded before use. Some of them are
expanded every time they are used; others are expanded only once.

Expanded strings are copied verbatim except when a dollar or backslash
character is encountered. A dollar specifies the start of a portion of the
string which is interpreted and replaced as described below.

An uninterpreted dollar can be included in the string by putting a
backslash in front of it - if the string appears in quotes, two backslashes
are required because the quotes themselves cause some interpretation when
the string is read in. A backslash can in fact be used to prevent any
character being treated specially in an expansion, including itself.


9.1 Expansion items

The following items are recognized in expanded strings. White space may be
used between sub-items that are keywords or sub-strings enclosed in braces
inside an outer set of braces, to improve readability.

$<variable name> or ${<variable name>}

   Substitute the contents of the named variable; the latter form can be
   used to separate the name from subsequent alphameric characters. The
   names of the variables are given in section 9.4 below. If the name of a
   non-existent variable is given, the expansion fails.

$header_<header name>: or $h_<header name>:

   Substitute the contents of the named message header, for example

     $header_reply-to:

   This particular expansion is intended mainly for use in filter files.
   The header names follow the syntax of RFC 822, which states that they
   may contain any printing characters except space and colon.
   Consequently, curly brackets do not terminate header names. Upper and
   lower case letters are synonymous in header names. If the following
   character is white space, the terminating colon may be omitted. The
   white space is included in the expanded string. If the message does not
   contain the given header, the expansion item is replaced by an empty
   string. If there is more than one header with the same name, they are
   all concatenated to form the substitution string, with a newline
   character between each of them.

${<op>:<string>}

   The string is first itself expanded, and then the operation specified by
   <op> is applied to it. A list of operators is given in section 9.2
   below. The string starts with the first character after the colon, which
   may be leading white space.

${if <condition> {<string1>}{<string2>}}

   If <condition> is true, <string1> is expanded and replaces the whole
   item; otherwise <string2> is used. The second string need not be
   present; if it is not and the condition is not true, the item is
   replaced with nothing. Alternatively, the word 'fail' may be present
   instead of the second string (without any curly brackets). In this case,
   the expansion fails if the condition is not true. The available
   conditions are described in section 9.3 below.

${lookup{<key>} <search type> {<file>} {<string1>} {<string2>}}

${lookup <search type> {<query>} {<string1>} {<string2>}}

   These items specify data lookups in files and databases, as discussed in
   chapter 6. The first form is used for single-key lookups, and the second
   is used for query-style lookups.

   If the lookup succeeds, then <string1> is expanded and replaces the
   entire item. During its expansion, a variable called $value is avail-
   able, containing the data returned by the file lookup. If the lookup
   fails, <string2> is expanded and replaces the entire item. It may be
   omitted, in which case the replacement is null.

   For single-key lookups, the string 'partial-' is permitted to precede     |
   the search type in order to do partial matching, and * may follow a       |
   search type to request a default lookup if the key does not match (see    |
   section 6.4).                                                             |

   If a partial search was used, the variables $1 and $2 contain the wild
   and non-wild parts of the key during the expansion of the replacement
   text. They return to their previous values at the end of the lookup
   item.

   Instead of {<string2>} the word 'fail' can appear, and in this case, if
   the lookup fails, the entire string expansion fails in a way that can be
   detected by the caller. The consequences of this depend on the
   circumstances.

   The <key>, <file>, and <query> strings are expanded before use. For
   single-key lookups the search type must be one of

     dbm       do a DBM lookup
     lsearch   do a linear search

   For a linear search, a line beginning with the key followed by a colon
   is searched for, and the data is the remainder of the line and any
   continuations, in the format of an alias file.

${lookup{<key:subkey>} <search type> {<file>} {<string1>} {<string2>}}

   This searches for <key> in the file as described above for single-key
   lookups; if it succeeds, it extracts from the data a subfield which is
   identified by the <subkey>. The data related to the main key must be of
   the form:

     <subkey1> = <value1>  <subkey2> = <value2> ...

   where the equals signs are optional. If any of the values contain white
   space, they must be enclosed in double quotes, and any values that are
   enclosed in double quotes are subject to escape processing as described
   in section 7.7. For example, if a line in a linearly searched file
   contains

     alice: uid=1984 gid=2001

   then expanding the string

     ${lookup{alice:uid}lsearch{<file name>}{$value}}

   yields the string '1984'. If the subkey is not found in <string1>, then
   <string2>, if present, is expanded and replaces the entire item.
   Otherwise the replacement is null.

${extract{<key>}{<string>}}

   The key and the string are first expanded. Then the subfield identified
   by the key is extracted from the string, exactly as just described for
   lookup items with subkeys. If the key is not found in the string, the
   item is replaced by nothing.


9.2 Expansion operators

A string can be forced into lower case by the lc operator, for example

  ${lc:$local_part}

The length operator can be used to extract the initial portion of a string.
It is followed by an underscore and the number of characters required. For
example

  ${length_50:$message_body}

The result of this operator is either the first n characters or the whole
string, whichever is the shorter. The abbreviation l can be used instead of
length.

The substr operator can be used to extract more general substrings. It is
followed by an underscore and the starting offset, then a second underscore
and the length required. For example

  ${substr_3_2:$local_part}

If the starting offset is greater than the string length the result is the
null string; if the length plus starting offset is greater than the string
length, the result is the right-hand part of the string, starting from the
given offset. The first character in the string has offset 0. The
abbreviation s can be used instead of substr.

The substr expansion operator can take negative offset values to count from
the righthand end of its operand. The last character is offset -1, the
second-last is offset -2, and so on. Thus, for example,

  ${substr_-5_2:1234567}

yields '34'. If the absolute value of a negative offset is greater than the
length of the string, the substring starts at the beginning of the string,
and the length is reduced by the amount of overshoot. Thus, for example,

  ${substr_-5_2:12}

yields an empty string, but

  ${substr_-3_2:12}

yields '1'.

If the second number is omitted from substr, the remainder of the string is
taken, if the offset was positive. If it was negative, all characters in
the string preceding the offset point are taken. For example, an offset of
-1 and no length yields all but the last character of the string.

The quote operator puts its argument into double quotes if it contains       |
anything other than letters, digits, underscores, and hyphens. Any occur-    |
rences of double quotes and backslashes are escaped with a backslash. For    |
example                                                                      |
                                                                             |
  ${quote:ab*d}                                                              |
                                                                             |
becomes                                                                      |
                                                                             |
  "ab*cd"                                                                    |
                                                                             |
The place where this is useful is when the argument is a substitution from   |
a variable or a message header.                                              |
                                                                             |
The rxquote operator inserts a backslash before any non-alphanumeric         |
characters in its argument. This is useful when substituting the values of   |
variables or headers inside regular expressions.                             |

The expand operator causes a string to be expanded for a second time. For
example,

  ${expand:${lookup{$domain}dbm{/some/file}{$value}}}

first looks up a string in a file while expanding the operand for expand,
and then re-expands what it has found.


9.3 Expansion conditions

The following conditions are available for testing while expanding strings:

  !<condition>

This negates the result of the condition.

  def:<variable>

This condition is true if the named expansion variable does not contain the
empty string, for example                                                    |
                                                                             |
  ${if def:sender_ident {from $sender_ident}}                                |
                                                                             |
Note that the variable name is given without a leading $ character. If the   |
variable does not exist, the expansion fails.                                |
                                                                             |
  def:header_<header name>  or  def:h_<header name>                          |
                                                                             |
This condition is true if a message is being processed and the named header  |
exists in the message. For example,                                          |
                                                                             |
  ${if def:header_reply-to {$h_reply-to:}{$h_from:}}                         |
                                                                             |
Note that no $ appears before header_ or h_ in the condition.                |

  exists{<file name>}

The substring is first expanded and then interpreted as an absolute path.
The condition is true if the named file (or directory) exists. The
existence test is done by calling the stat() function.

  eq {<string1>}{<string2>}

The two substrings are first expanded. The condition is true if the two
resulting strings are identical, including the case of letters.

  match {<string1>}{<string2>}

The two substrings are first expanded. The second is then treated as a
regular expression and applied to the first. Because of the pre-expansion,   |
if the regular expression contains dollar or backslash characters, they      |
must be escaped with backslashes. If the whole expansion string is in        |
double quotes, further escaping of backslashes is also required.             |

The condition is true if the regular expression match succeeds. At the
start of an "if" expansion the values of the numeric variable substitutions
$1 etc. are remembered. Obeying a "match" condition that succeeds causes
them to be reset to the substrings of that condition and they will have
these values during the expansion of the success string. At the end of the
"if" expansion, the previous values are restored. After testing a combi-
nation of conditions using "or", the subsequent values of the numeric
variables are those of the condition that succeeded.

  or {{<cond1>}{<cond2>}...}

The sub-conditions are evaluated from left to right. The condition is true
if any one of the sub-conditions is true. When a true sub-condition is
found, the following ones are parsed but not evaluated. Thus if there are
several 'match' sub-conditions the values of the numeric variables are
taken from the first one that succeeds.

  and {{<cond1>}{<cond2>}...}

The sub-conditions are evaluated from left to right. The condition is true
if all of the sub-conditions are true. When a false sub-condition is found,
the following ones are parsed but not evaluated.


9.4 Expansion variables

The variable substitutions that are available for use in expansion strings
are:

$compile_date: The date on which the Exim binary was compiled.

$compile_number: The building process for Exim keeps a count of the number
of times it has been compiled. This serves to distinguish different
compilations of the same version of the program.

$domain: When an address is being directed, routed, or delivered on its
own, this variable contains the domain. In particular, it is set during      |
user filtering, but not during system filtering, since a message may have    |
many recipients and the system filter is called just once.                   |

For remote addresses, the domain can change as routing proceeds, as a
result of router actions. When a remote or local delivery is taking place,
if all the addresses that are being handled simultaneously contain the same
domain, it is placed in $domain. Otherwise this variable is empty.
Transports should be restricted to handling only one domain at once if its
value is required at transport time - this is the default for local
transports.

When a rewrite item is being processed (see chapter 33) $domain contains
the domain portion of the address that is being re-written; it can be used
in the expansion of the replacement address, for example, to rewrite
domains by file lookup.

$domain_data: When a director or a router has a setting of the domains       |
generic option, and that involves a file lookup, the data associated with    |
the key in the file is available during the running of the director or       |
router as $domain_data. In all other situations, this variable expands to    |
nothing.                                                                     |

$home: A home directory may be set during a local delivery, either by the
transport or by the director that handled the address. When this is the
case, $home contains its value and may be used in any expanded options for
the transport. The forwardfile director also makes use of the $home. Full
details are given in chapter 23. When interpreting a user's filter file,
Exim is normally configured so that $home contains the user's home
directory. When running a filter test via the -bf option, $home is set to
the value of the environment variable HOME.

$host: When a local transport is run as a result of routing a remote
address, the expansion variable $host is available to access the host name
that the router defined. A router may set up many hosts; in this case $host
refers to the first one. It is expected that this usage will be mainly via
the domainlist router, setting up a single host for batched SMTP output,
for example.

When used in a transport filter (see chapter 13), $host refers to the host
involved in the current connection.

$host_address: This variable is available only for use in transport filters
(see chapter 13).

$local_part: When an address is being directed, routed, or delivered on its
own, this variable contains the local part. If a local part prefix or
suffix has been recognized, it is not included in the value. When a number
of addresses are being delivered in a batch by a local or remote transport,
$local_part is not set.

When a rewrite item is being processed (see chapter 33) $local_part
contains the local-part portion of the address that is being re-written; it
can be used in the expansion of the replacement address, for example, to
rewrite local parts by file lookup.

$local_part_data: When a director or a router has a setting of the           |
local_parts generic option, and that involves a file lookup, the data        |
associated with the key in the file is available during the running of the   |
director or router as $local_part_data. In all other situations, this        |
variable expands to nothing.                                                 |

$local_part_prefix: When an address is being directed or delivered locally,
and a specific prefix for the local part was recognized, it is available in
this variable. Otherwise it is empty.

$local_part_suffix: When an address is being directed or delivered locally,
and a specific suffix for the local part was recognized, it is available in
this variable. Otherwise it is empty.

$key: When a domain list is being searched, this variable contains the
value of the key, so that it can be inserted into strings for query-style
lookups. See chapter 6 for details. In other circumstances this variable is
empty.

$message_body: This variable contains the initial portion of a message's
body while it is being delivered, and is intended mainly for use in filter
files. The maximum number of characters of the body that are used is set by
the message_body_visible configuration option; the default is 500. Newlines  |
are converted into spaces to make it easier to search for phrases that       |
might be split over a line break.                                            |

$message_headers: This variable contains a concatenation of all the header   |
lines when a message is being processed. They are separated by newline       |
characters.                                                                  |

$message_id: When a message is being received or delivered, this variable
contains the unique message id which is used by Exim to identify the
message.

$message_precedence: When a message is being delivered, the value of any
"Precedence" header is made available in this variable. If there is no such
header, the value is the null string.

$message_size: When a message is being received or delivered, this variable
contains its size in bytes. The size includes those headers that were        |
received with the message, but not those (such as Envelope-to) that are      |
added to individual deliveries.                                              |

$original_domain: When a top-level address is being processed for delivery,
this contains the same value as $domain. However, if an address generated
by an alias, forward, or filter file is being processed, this variable
contains the domain of the original address.

$original_local_part: When a top-level address is being processed for
delivery, this contains the same value as $local_part. However, if an
address generated by an alias, forward, or filter file is being processed,
this variable contains the local part of the original address.

$pipe_addresses: This is not an expansion variable, but is mentioned here
because the string $pipe_addresses is handled specially in the command
specification for the pipe transport and in transport filters. It cannot be  |
used in general expansion strings, and provokes an 'unknown variable' error
if encountered.

$primary_hostname: The value set in the configuration file, or read by the
uname() function.

$qualify_domain: The value set for this option in the configuration file.

$qualify_recipient: The value set for this option in the configuration
file, or if not set, the value of $qualify_domain.

$received_protocol: When a message is being processed, this variable
contains the name of the protocol by which it was received.

$recipients: This variable contains a list of envelope recipients for a
message, but is recognized only in the system filter file, to prevent
exposure of Bcc recipients to ordinary users. A comma and a space separate
the addresses in the replacement text.

$recipients_count: When a message is being processed, this variable con-
tains the number of envelope recipients that came with the message.
Duplicates are not excluded from the count.

$reply_address: When a message is being processed, this variable contains
the contents of the Reply-to: header if one exists, or otherwise the
contents of the From: header.

$return_path: When a message is being delivered, this variable contains the
return path - the sender field that is sent as part of the envelope. In
many cases, this has the same value as $sender_address, but if, for
example, an incoming message to a mailing list has been expanded by a
director which specifies a specific address for delivery error messages,
then $return_path contains the new errors address, while $sender_address
contains the original sender address that was received with the message.

$route_option: A router may set up an arbitrary string to be passed to a
transport via this variable. Currently, only the queryprogram router has
the ability to do so.

$self_hostname: The generic router option self can be set to the value       |
'local'. This causes the address to be passed over to the directors, as if   |
its domain were a local domain. While subsequently directing (and doing any  |
local deliveries) $self_hostname is set to the name of the local host that   |
the router encountered. In other circumstances its contents are null.        |

$sender_address: When a message is being processed, this variable contains
the sender's address that was received in the message's envelope.

$sender_address_domain: The domain portion of $sender_address.

$sender_address_local_part: The local part portion of $sender_address.

$sender_fullhost: When a message has been received from a remote host, this  |
variable contains the host name and IP address in a single string, which     |
always ends with the IP address in square brackets. The format of the rest   |
of the string depends on whether the host issued a HELO or EHLO SMTP         |
command, and whether the host name was verified by looking up its IP         |
address. (This is configurable via the host_lookup_nets option.) A plain     |
host name at the start of the string is a verified host name; if this is     |
not present, verification either failed or was not requested. A host name    |
in parentheses is the argument of a HELO or EHLO command. This is omitted    |
if it is identical to the verified host name.                                |
                                                                             |
$sender_helo_name: When a message has been received from a remote host that  |
has issued a HELO or EHLO command, the argument of that command is placed    |
in this variable.                                                            |
                                                                             |
$sender_host_address: When a message has been received from a remote host,   |
this variable contains the host's IP address.                                |
                                                                             |
$sender_host_name: When a message has been received from a remote host,      |
this variable contains the host's name as verified by looking up its IP      |
address. If verification failed, or was not requested, this variable         |
contains the empty string.                                                   |

$sender_ident: When a message has been received from a remote host, this
variable contains the identification received in response to an RFC 1413
request. When a message has been received locally, this variable contains
the login name of the user that called Exim.

$spool_directory: The name of Exim's spool directory.

$tod_bsdinbox: The time of day and date, in the format required for BSD-
style mailbox files, for example: Thu Oct 17 17:14:09 1995.

$tod_full: A full version of the time and date, for example: Wed, 18 Oct
1995 09:51:40 +0100. The timezone is always given as a numerical offset
from GMT.

$tod_log: The time and date in the format used for writing Exim's log
files, which is: 1995-10-12 15:32:29.

$value: This variable contains the result of an expansion lookup operation,
as described above. If used in other circumstances, its contents are null.

$version_number: The version number of Exim.


9.5 Expansion string examples

Typical settings for defining a local mailbox to the appendfile transport
are

  file = /var/spool/mail/${local_part}
  file = ${home}/inbox

The default setting for the Received header is as follows:

  received_header_text = "Received: \
       ${if def:sender_fullhost {from ${sender_fullhost} \
       ${if def:sender_ident {(${sender_ident})}}\n\t}\
       {${if def:sender_ident {from ${sender_ident} }}}}\
       by ${primary_hostname} \
       ${if def:received_protocol {with ${received_protocol}}} \
       (Exim ${version_number} #${compile_number})\n\t\
       id ${message_id}"



                           10. MAIN CONFIGURATION


The first part of the configuration file contains the main configuration
settings. Each setting occupies one line of the file, except that string
values can be continued onto multiple lines as described in section 7.7.
All macro definitions must be in this part of the file - they differ from
options settings by starting with an upper case letter. The available
options are as follows:

accept_8bitmime

    Type:    boolean
    Default: false

    This option causes Exim to send 8BITMIME in its response to an SMTP
    EHLO command, and to accept the BODY= parameter on MAIL FROM commands.
    However, Exim is not a protocol converter, and it takes no steps to do
    anything special with messages received by this route. Consequently,
    this option is turned off by default.

accept_timeout

    Type:    time
    Default: 0

    This sets the timeout for accepting a non-SMTP message, that is, the
    maximum time that Exim waits when reading a message on the standard
    input. If the value is zero, it will wait for ever. This setting is
    overridden by the -or command option.

address_directory_transport

    Type:    string
    Default: "address_directory"

    This sets the default name of the transport driver that is to be used
    when the expansion of the local part of an address by an aliasing or
    forwarding director results in a path ending in '/', implying delivery
    of each message into a separate file in some directory. This transport   |
    is used only if the director's own directory_transport option is not     |
    set.                                                                     |

address_directory2_transport

    Type:    string
    Default: "address_directory2"

    This sets the default name of the transport driver that is to be used
    when the expansion of the local part of an address by an aliasing or
    forwarding director results in a path ending in '//'. The reason for
    having both address_directory and address_directory2 is to allow for
    the rare circumstance in which both maildir and non-maildir format
    delivery is required. This transport is used only if the director's own  |
    directory2_transport option is not set.                                  |

address_file_transport

    Type:    string
    Default: "address_file"

    This sets the default name of the transport driver that is to be used
    when the expansion of the local part of an address by an aliasing or
    forwarding director results in a file name. This transport is used only  |
    if the director's own file_transport option is not set.                  |

address_pipe_transport

    Type:    string
    Default: "address_pipe"

    This sets the default name of the transport driver that is to be used
    when the expansion of the local part of an address by an aliasing or
    forwarding director results in a pipe command. This transport is used    |
    only if the director's own pipe_transport option is not set.             |

address_reply_transport

    Type:    string
    Default: "address_reply"

    This sets the default name of the transport driver that is to be used
    when the expansion of the local part of an address by a forwarding
    director results in the generation of an automatic reply. This trans-    |
    port is used only if the director's own reply_transport option is not    |
    set.                                                                     |

always_bcc

    Type:    boolean
    Default: false

    Exim adds a To header to messages whose recipients are given on the
    command line when there is no To, Cc, or Bcc in the message. In other
    cases of missing recipient headers, it just adds an empty Bcc header to
    make the message conform with RFC 822. Setting always_bcc causes it to
    add an empty Bcc in all cases. This can be helpful in conjunction with
    mailing list software that passes recipient addresses on the command
    line.

auto_thaw

    Type:    time
    Default: 0s

    If this option is set to a non-zero time, a new delivery is attempted
    on frozen messages if this much time has passed since the message was
    frozen.

bi_command

    Type:    string
    Default: unset

    This option supplies the name of a command that is run when Exim is
    called with the -bi option (see chapter 5). The string value is just
    the command name, it is not a complete command line. If an argument is
    required, it must come from the -oA command line option.

check_log_inodes

    Not implemented under OS/2.

check_log_space

    Type:    integer
    Default: 0

    See check_spool_space below.

check_spool_inodes

    Not implemented under OS/2.

check_spool_space

    Type:    integer
    Default: 0

    The check_... options allow for checking of disc resources before
    a message is accepted: check_spool_space checks the spool
    partition if the value is greater than zero, for example:

      check_spool_space = 10M

    check_log_space checks the partition in which log files are
    written. These should be set only if log_file_path is set to
    point to a different partition to the spool directory.

    If there is less space or fewer inodes than requested, Exim refuses to
    accept incoming mail. In the case of SMTP input this is done by giving
    a 452 temporary error response to the MAIL FROM command. For non-SMTP
    input and for batched SMTP input, the test is done at start-up; on
    failure a message is written to stderr and Exim exits with a non-zero
    code, as it obviously cannot send an error message of any kind.

collapse_source_routes

    Type:    boolean
    Default: false

    If this option is set, then source-routed mail addresses are stripped
    down to their final components.

daemon_smtp_service                                                          |
                                                                             |
    Type:    string                                                          |
    Default: unset                                                           |
                                                                             |
    This option specifies the numerical port number or the service name      |
    equivalent on which the daemon is to listen for incoming SMTP calls. It  |
    is overridden by -oX on the command line.                                |

debug_level

    Type:    integer
    Default: 0

    This option sets the debug level, thus enabling it to be set when
    calling Exim from an MUA, but it is overridden by the use of -d on the
    command line.

debug_transport

    Type:    string
    Default: unset

    This option causes all deliveries to be subverted by substituting
    a call to the debug transport. This appends information about the
    address, and a copy of the message, to the file whose name is specified
    by this option. No locking is used.

delay_warning                                                                |
                                                                             |
    Type:    time-list                                                       |
    Default: 24h                                                             |
                                                                             |
    When a message is delayed, Exim sends a warning message to the sender    |
    at intervals specified by this option. If it is set to a zero amount of  |
    time, no warnings are sent. The data is a colon-separated list of times  |
    after which to send warning messages. Up to 10 times may be given. If a  |
    message has been on the queue for longer than the last time, the last    |
    interval between the times is used to compute subsequent warning times.  |
    For example, with                                                        |
                                                                             |
      delay_warning = 4h:8h:24h                                              |
                                                                             |
    the first message is sent after 4 hours, the second after 8 hours, and   |
    subsequent ones every 16 hours thereafter. To stop warnings after a      |
    given time, set a huge subsequent time.                                  |

delay_warning_condition                                                      |
                                                                             |
    Type:    string                                                          |
    Default: unset                                                           |
                                                                             |
    The string is expanded at the time a warning message might be sent. If   |
    the result of the expansion is a forced failure, an empty string, or a   |
    string matching any of '0', 'no' or 'false' (the comparison being done   |
    caselessly) then the warning message is not sent. For example            |
                                                                             |
      delay_warning_condition = "\                                           |
        ${if match{$h_precedence:}{(?i)bulk|list}{no}{yes}}"                 |
                                                                             |
    suppresses the sending of warnings about messages that have 'bulk' or    |
    'list' in a Precedence header. Note that the colon to terminate the      |
    header name is necessary because } may legally occur in header names.    |

deliver_load_max

    Type:    fixed-point
    Default: unset

    When this option is set, no message deliveries are ever done if the
    system load average is greater than its value, except for deliveries
    forced with the -M option. If deliver_queue_load_max is not set and the
    load gets this high during a queue run, the run is abandoned. There
    is no means at present to measure the system load average under OS/2,
    so this option is non-functional; this limitation should be lifted in
    a future release of Exim for OS/2.

deliver_queue_load_max

    Type:    fixed-point
    Default: unset

    If this option is set, its value is used to determine whether to
    abandon a queue run, instead of the value of deliver_load_max.

delivery_date_remove

    Type:    boolean
    Default: true

    Exim's local transports (appendfile and pipe) have an option for adding
    a Delivery-date header to a message when it is delivered - in exactly
    the same way as Return-path is handled. Delivery-date records the
    actual time of delivery. Such headers should not be present in outgoing
    messages, and this option causes them to be removed, to avoid any
    problems that might occur when a delivered message is subsequently sent
    on to some other recipient.

dns_retrans

    Type:    time
    Default: 0

    The options dns_retrans and dns_retry can be used to set the
    retransmission and retry parameters for DNS lookups. Values of zero
    (the defaults) leave the system default settings unchanged. The first
    value is the time between retries, and the second is the number of
    retries. It isn't totally clear exactly how these settings affect the
    total time a DNS lookup may take. I haven't found any documentation
    about timeouts on DNS lookups; these parameter values are available in
    the external resolver interface structure, but nowhere does it seem to
    describe how they are used or what you might want to set in them.

dns_retry

    Type:    integer
    Default: 0

    See dns_retrans above.

envelope_to_remove

    Type:    boolean
    Default: true

    Exim's local transports (appendfile and pipe) have an option for adding
    an Envelope-to header to a message when it is delivered - in exactly
    the same way as Return-path is handled. Envelope-to records the
    original recipient address in the envelope that caused the delivery.
    Such headers should not be present in outgoing messages, and this
    option causes them to be removed, to avoid any problems that might
    occur when a delivered message is subsequently sent on to some other
    recipient.

errors_address

    Type:    string
    Default: "postmaster"

    The mail address to which Exim will send certain error reports. As the
    default is specified without a domain, it will be sent to the domain
    specified by the qualify_recipient option. If this address is specified
    with a domain, it must be a fully qualified domain.

errors_copy

    Type:    string-list
    Default: unset

    Setting this option causes Exim to send bcc copies of delivery failure
    reports to other addresses. The value is a colon-separated list of
    items; each item consists of a pattern and an address list, separated
    by white space. If the pattern matches the recipient of the delivery
    error report, the message is copied to the addresses on the list. The
    items are scanned in order, and once a matching one is found, no
    further items are examined. For example:

      errors_copy = "spqr@mydomain   postmaster@mydomain :\
                     rqps@mydomain   mailmaster@mydomain,\
                                     postmaster@mydomain"

    Each pattern can be a single regular expression, indicated by starting
    it with a ^ character; alternatively, either portion (local part,
    domain) can start with an asterisk, or the domain can be in any format
    that is acceptable as an item in a domain list, including a file
    lookup. A regular expression is matched against the entire (fully
    qualified) recipient; non-regular expressions must contain both a local
    part and domain, separated by @.

    The address list is a string which is expanded, and must end up as a
    comma-separated list of addresses. It is used to construct a Bcc header
    which is added to the error message. The expansion variables local_part
    and domain are set from the original recipient of the error message,
    and if there was any wildcard matching, the expansion variables $0, $1,
    etc. are set in the normal way.

errors_reply_to

    Type:    string
    Default: unset

    Exim's delivery error messages contain the header

      From: Mail Delivery System <Mailer-Daemon@${qualify_domain}>

    (where string expansion notation is used to show a variable substitu-
    tion). Experience shows that a large number of people reply to such
    messages. If the errors_reply_to option is set, a Reply-to header is
    added. The option must specify the complete header body.

exim_group

    Not implemented under OS/2.

exim_path

    Type:    string
    Default: see below

    This option specifies the path name of the Exim binary, which is used
    when Exim needs to re-exec itself. The default is set up to point to
    the file exim in the directory /exim. It is necessary to change
    exim_path if Exim is run from some other place.

exim_user

    Not implemented under OS/2.

finduser_retries

    Type:    integer
    Default: 0

    Implemented, but of doubtful value at the present time, under OS/2.

forbid_domain_literals

    Type:    boolean
    Default: false

    If this option is set, the RFC 822 domain literal format is not
    permitted in addresses.

freeze_tell_mailmaster

    Type:    boolean
    Default: false

    On encountering certain errors, Exim freezes a message, which means
    that no further delivery attempts take place until an administrator
    thaws it. If this option is set, a message is sent to errors_address
    every time a message is frozen, unless the message is itself a delivery
    error message. (Without this exception there is the possibility of
    looping.) If several of the message's addresses cause freezing, only a
    single message is sent to the mail administrator. The reason(s) for
    freezing will be found in the message log.

gecos_name

    Type:    string
    Default: unset

    Not implemented under OS/2.

gecos_pattern

    Type:    string
    Default: unset

    Not implemented under OS/2.

headers_check_syntax

    Type:    boolean
    Default: false

    This option causes Exim to check the syntax of all headers that can
    contain lists of addresses (Sender, From, Reply-to, To, Cc, and Bcc) on
    all incoming messages (both local and SMTP). This is a syntax check
    only, to catch real junk such as

      To: user@

    Like the headers_sender_verify options, the rejection happens after the
    end of the data, but it is also controlled by headers_checks_fail; if
    that is unset, the message is accepted and a warning is written to the
    reject log.

headers_checks_fail

    Type:    boolean
    Default: true

    If this option is true, failure of any header check (see below) causes
    the message to be rejected. If it is false, a warning message is
    written in the reject log.

headers_sender_verify

    Type:    boolean
    Default: false

    If this option is set with sender_verify, and the sending host does not  |
    match sender_verify_except_hosts or sender_verify_except_nets, Exim      |
    insists on there being a verifyable address in one of the Sender,
    Reply-to, or From headers (which are checked in that order) on all
    incoming SMTP messages. If one cannot be found, the message is
    rejected, unless headers_checks_fail is unset, in which case a warning
    entry is written in the reject log.

    Unfortunately, because it has to read the message before doing this
    check, the rejection happens after the end of the data, and it is known
    that some mailers do not treat hard (5xx) errors correctly at this
    point - they keep the message on their spools and try again later, but
    that is their problem, though it does waste some resources.

headers_sender_verify_errmsg

    Type:    boolean
    Default: false

    This option acts like headers_sender_verify, except that it applies
    only to messages whose envelope sender is '<>', that is, delivery error
    messages whose sender cannot be verified at time the SMTP MAIL FROM
    command is received.

helo_verify                                                                  |
                                                                             |
    Type:    boolean                                                         |
    Default: false                                                           |
                                                                             |
    The RFCs mandate that a server must not reject a message because it      |
    doesn't like the HELO or EHLO command, or indeed if there isn't a HELO   |
    or EHLO command at all. However, some sites like to be stricter. If      |
    helo_verify is set, Exim accepts an incoming SMTP call only if:          |
                                                                             |
     .   A HELO or EHLO command is received;                                 |
                                                                             |
    and                                                                      |
                                                                             |
     .   The host name given in that command either:                         |
                                                                             |
         (i)  is an IP literal matching the calling address of the host      |
              (the RFCs specifically allow this),                            |
                                                                             |
         or                                                                  |
                                                                             |
          .   matches the host name that Exim obtains by doing a reverse     |
              lookup of the calling host address,                            |
                                                                             |
         or                                                                  |
                                                                             |
          .   when looked up using gethostbyname() yields the calling host   |
              address.                                                       |
                                                                             |
    If no HELO or EHLO is given, MAIL FROM commands are rejected; if a bad   |
    HELO or EHLO is given, it is rejected with a 550 error. Rejections are   |
    logged in the main and reject logs.                                      |

helo_verify_nets                                                             |
                                                                             |
    Type:    net-list                                                        |
    Default: unset                                                           |
                                                                             |
    This option is an obsolete name for host_lookup_nets that is retained    |
    for backward compatibility.                                              |

hold_domains

    Type:    domain-list
    Default: unset

    This option, together with hold_domains_except, allows mail for par-
    ticular domains to be held on the queue manually. The options are
    overridden if a message delivery is forced with the -M or -qf options.
    Otherwise, if a domain matches an item in hold_domains and does not
    match any item in hold_domains_except, no routing or delivery for that
    address is done, and it is deferred every time the message is looked
    at. If hold_domains_except is set but hold_domains is unset, Exim acts
    as if hold_domains were set to '*', that is, all domains except those
    matching hold_domains_except are held.

    These options are intended as temporary operational measures for
    delaying the delivery of mail while some problem is being sorted out,
    or some new configuration tested. They do not override Exim's message
    clearing away code, which removes messages from the queue if they have
    been there longer than the longest retry time in any retry rule. If you
    want to hold messages for longer than the normal retry times, insert a
    dummy retry rule with a long retry time.

hold_domains_except

    Type:    domain-list
    Default: unset

    See hold_domains above.

host_lookup_nets                                                             |
                                                                             |
    Type:    net-list                                                        |
    Default: unset                                                           |
                                                                             |
    Exim does not look up the name of a calling host from its IP address     |
    unless it is required to compare against some host list, or the address  |
    matches one of the networks in this option. The default configuration    |
    file contains                                                            |
                                                                             |
      host_lookup_nets = 0.0.0.0/0                                           |
                                                                             |
    which causes a lookup to happen for all hosts. If the expense of these   |
    lookups is felt to be too great, the setting can be changed or removed.  |
    However, Exim always does a lookup if the domain name quoted in a HELO   |
    or EHLO command is the local host's own name or any of its local mail    |
    domains.                                                                 |

ignore_errmsg_errors

    Type:    boolean
    Default: false

    If this options is set, failed addresses in error messages (i.e.
    messages whose senders are '<>') are discarded (with a log entry). The
    default action is to freeze such messages for human attention.

ignore_errmsg_errors_after

    Type:    time
    Default: 0

    This option, if it is set to a non-zero time, acts as a delayed version
    of ignore_errmsg_errors, which must be unset for this option to take
    effect. If an error message is frozen because of delivery failure, then
    it is unfrozen at the next queue run after the given time, and if
    delivery fails again, the error message is discarded. This makes it
    possible to keep failed error messages around for a shorter time than
    the normal maximum retry time.

keep_malformed

    Type:    time
    Default: 4d

    This option specifies the length of time to keep messages whose spool
    files have been corrupted in some way. This should, of course, never
    happen. At the next attempt to deliver such a message, it gets removed.
    The incident is logged.

kill_ip_options

    Type:    boolean
    Default: true

    IP packets can contain options which are "source routing" data that
    enables one host to pretend to be another. (Don't confuse IP source
    routing with source-routed mail addresses, which are something entirely
    different.) IP source routing is an obvious security risk, and many
    sites lock out such packets in their routers. Also, some operating
    systems are able to disable IP source routing at the kernel level.

    This option is not yet functional under OS/2 - OS limitation.

local_domains

    Type:    domain-list
    Default: see below

    This specifies a list of domains which are recognized as 'local', that
    is, their final delivery (as far as the Internet is concerned) is
    handled by this MTA. If this option is not set, it defaults to the
    value of qualify_recipient.

    The name of the local host is not by default recognized as a local mail
    domain; either it must be included in local_domains, or the
    local_domains_include_host option must be set. If you want to accept
    mail addressed to your host in RFC 822 domain literal format, then
    local_host must also include the appropriate 'domains', consisting of
    IP addresses enclosed in square brackets. The
    local_domains_include_host_literals option can be set to add all IP
    addresses automatically.

    It is possible to specify no local domains by specifying no data for
    this option, for example,

      local_domains =

    If there are very many local domains, then they can be stored in a file
    and looked up whenever this string is searched. See the discussion of
    domain lists in section 7.11.

local_domains_include_host

    Type:    boolean
    Default: false

    If this option is set, the value of primary_hostname is added to the
    value of local_domains, unless it is already present. This makes it
    possible to use the same configuration file on a number of different
    hosts. This option is now obsolescent, as the same effect can be
    obtained by including the conventional item '@' (which matches the
    primary host name) in local_domains.

local_domains_include_host_literals

    Type:    boolean
    Default: false

    If this option is set and local_interfaces is unset, the IP addresses
    of all the interfaces on the local host, with the exception of
    127.0.0.1 (and ::1 on IPv6 systems), are added to the value of
    local_domains, in domain literal format, that is, as dotted quad
    strings enclosed in square brackets. If local_interfaces is set, then
    only those addresses it contains (again excluding 127.0.0.1 and ::1)
    are used.

local_interfaces

    Type:    string-list
    Default: unset

    The string must contain a list of IP addresses in dotted-quad format.
    These are used for two different purposes:

     .   When a daemon is started to listen for incoming SMTP calls, it
         listens only on the interfaces identified here. An error occurs if
         it is unable to set up a listening socket on any interface.

     .   Only the IP addresses listed here are taken as the local host's
         addresses when routing mail and checking for mail loops.

    If local_interfaces is unset, the daemon issues a generic listen() that
    accepts incoming calls from any interface, and it also gets a complete
    list of available interfaces and treats them all as local when routing
    mail. On most systems the default action is what is wanted. However,
    some systems set up large numbers of virtual interfaces in order to
    provide many different virtual web servers. In these cases
    local_interfaces can be used to restrict SMTP traffic to one or two
    interfaces only.

locally_caseless

    Type:    boolean
    Default: true

    For most Unix systems it is desirable that local parts of local mail
    addresses be treated in a case-independent manner, since most users
    expect that mail to OBailey and obailey, for example, will end up in
    the same mailbox. By default, Exim lower-cases local local parts at the
    start of processing them, on the assumption that account names in the    |
    password file are in lower case. For installations that want to draw     |
    case distinctions, this option is provided. When turned off, local
    local parts are handled verbatim.

    (Note: this is of limited use when used with the localuser director, as
     HPFS is not a case-sensitive filesystem.)

log_arguments

    Type:    boolean
    Default: false

    Setting this option causes Exim to write the arguments with which it
    was called to the main log. This is a debugging feature, added to make
    it easy to find out with what arguments certain MUAs call
    /usr/lib/sendmail. The logging does not happen if Exim has given up      |
    root privilege because it was called with the -C or -D options.          |

log_file_path

    Type:    string
    Default: /exim/%slog

    This option sets the path which is used to determine the names of
    Exim's log files. The string is expanded, so it can contain, for
    example, references to the host name. After expansion it must contain
    the string '%s' somewhere within it; this will be replaced with one of
    the strings 'main', 'panic', 'process' or 'reject' to form the final
    file name. For example,

      log_file_path = /var/log/${primary_hostname}/exim_%slog

    If no specific path is set for the log files, they are written in a
    subdirectory called log in Exim's spool directory.

log_ip_options

    Type:    boolean
    Default: true

    See kill_ip_options above.

log_level

    Type:    integer
    Default: 5

    This controls the amount of data written to the main log (see section
    45.6). The higher the number, the more is written. At present a value
    of 6 or higher causes all possible messages to appear.

log_received_recipients

    Type:    boolean
    Default: false

    When this option is set, the recipients of a message are listed on the
    main log as soon as the message is received. The list appears at the
    end of the log line that is written when a message is received,
    preceded by the word 'for'. The addresses are listed after they have
    been qualified, but before any rewriting has taken place.

log_received_sender                                                          |
                                                                             |
    Type:    boolean                                                         |
    Default: false                                                           |
                                                                             |
    If this option is set, the unrewritten original sender of a message is   |
    added to the end of the log line that records the message's arrival,     |
    after the word 'from' (before the recipients if log_received_recipients  |
    is also set).                                                            |

log_refused_recipients

    Type:    boolean
    Default: false

    If this option is set, an entry is written in the main and reject logs
    for each recipient that is refused for policy reasons. Otherwise cases
    where all recipients are to be refused just cause a single log entry
    for the message.

log_smtp_confirmation

    Type:    boolean
    Default: false

    This option causes the response to the final '.' in the SMTP dialog for
    outgoing messages to be added to delivery log lines in the form
    'C="<text>"'. A number of MTAs (including Exim from release 1.60)
    return an identifying string in this reponse, so logging this infor-
    mation allows messages to be tracked more easily. This global option
    applies to all SMTP transports.

log_subject

    Type:    boolean
    Default: false

    This option causes a message's subject to be included in the arrival
    log line, in the form 'T="<subject text>"'. T stands for 'topic' (S is
    already used for 'size').

message_body_visible

    Type:    integer
    Default: 500

    This option specifies how much of a message's body is to be included in
    the message_body expansion variable.

message_filter

    Type:    string
    Default: unset

    This option specifies a filter file which is applied to all messages
    before any routing or directing is done. This is called the 'system
    message filter'. Details of this facility are given in chapter 41.

message_filter_group

    Not implemented under OS/2.

message_filter_user

    Not implemented under OS/2.

message_id_header_text

    Type:    string
    Default: unset

    If this variable is set, the string is expanded and used to augment the
    text of the Message-id header that Exim creates if an incoming message
    does not have one. The text of this header is required by RFC 822 to
    take the form of an address. By default, Exim uses its internal message
    id as the local part, and the primary host name as the domain. If this
    option is set, it is expanded and inserted into the header immediately
    before the @, separated from the internal message id by a dot. Any
    characters that are illegal in an address are automatically converted
    into hyphens. This means that constructions like ${tod_log} can be
    used, as the spaces and colons will become hyphens.

message_size_limit

    Type:    integer
    Default: 0

    This option limits the maximum size of message that Exim will process.
    Zero means no limit. It should be set somewhat larger than
    return_size_limit if the latter is non-zero. Incoming SMTP messages are
    failed with a 552 error if the limit is exceeded; locally-generated
    messages either get a stderr message or a delivery failure message to
    the sender, depending on the -oe setting, in the normal way. Rejection
    of an oversized message is logged on both the main and the reject logs.

never_users

    Not implemented under OS/2.

nobody_group

    Not implemented under OS/2.

nobody_user

    Not implemented under OS/2.

percent_hack_domains

    Type:    domain-list
    Default: unset

    The 'percent hack' is the convention whereby a local part containing a
    percent sign is re-interpreted as a remote address, with the percent
    replaced by @. This is also known as 'source routing', though that term
    is also applied to RFC 822 addresses that begin with an @ character. If
    this option is set, Exim implements the percent facility for those
    local domains listed, but no others. The option can be set to '*' to
    allow the percent hack in all local domains.

pid_file_path

    Type:    string
    Default: compile-time configured (may be unset)

    This option sets the path which is used to determine the name of the
    file to which the Exim daemon writes its process id. The string is
    expanded, so it can contain, for example, references to the host name.
    After expansion it must contain the string '%s' somewhere within it;
    this will be replaced by the null string or a non-standard port number
    to form the final file name. For example,

      pid_file_path = /var/log/${primary_hostname}/exim%s.pid

    If no specific path is set for the file, it is written in Exim's spool
    directory.

preserve_message_logs

    Type:    boolean
    Default: false

    If this option is set, message log files are not deleted when messages
    are completed. Instead, they are moved to a subdirectory of the spool
    directory called msglog.OLD, where they remain available for statisti-
    cal or debugging purposes. This is a dangerous option to set on systems
    with any appreciable volume of mail. Use with care!

primary_hostname

    Type:    string
    Default: see below

    This specifies the name of the current host. This is used in the HELO
    command for outgoing SMTP messages, and as the default for
    qualify_domain. If it is not set, Exim calls uname() to find it. If
    this fails, Exim panics and dies. If the name returned by uname()
    contains only one component, Exim passes it to gethostbyname() in order
    to obtain the fully-qualified version.

prod_requires_admin

    Not implemented under OS/2.

prohibition_message                                                          |
                                                                             |
    Type:    string                                                          |
    Default: unset                                                           |
                                                                             |
    This option adds a site-specific message to the error response that is   |
    sent when an SMTP command fails for policy reasons, for example if the   |
    sending host is in a host reject list. Details of this facility are      |
    given in chapter 40.                                                     |

qualify_domain

    Type:    string
    Default: see below

    This specifies the domain name that is added to any sender addresses
    that do not have a domain qualification. It also applies to recipient
    addresses if qualify_recipient is not set. Such addresses are accepted
    by default only for locally-generated messages - messages from external
    sources must always contain fully qualified addresses, unless the
    sending host matches one of the receiver_unqualified or
    sender_unqualified options. If qualify_domain is not set, it defaults
    to the primary_hostname value.

qualify_recipient

    Type:    string
    Default: see below

    This specifies the domain name that is added to any recipient addresses
    that do not have a domain qualification. Such addresses are accepted by
    default only for locally-generated messages - messages from external
    sources must always contain fully qualified addresses, unless the
    sending host matches one of the receiver_unqualified or
    sender_unqualified options (see below). If qualify_recipient is not
    set, it defaults to the qualify_domain value.

queue_only

    Type:    boolean
    Default: false

    If queue_only is set (which is equivalent to the -odq command line
    option), a delivery process is not automatically started whenever a
    message has been received. Instead, the message waits on the queue for
    the next queue run. Even if queue_only is false, incoming SMTP messages
    may not get delivered immediately if a lot of them arrive at once - see
    the queue_only_load and smtp_accept_queue options.

queue_only_load

    Type:    fixed-point
    Default: unset

    If the system load average is higher than this value, all incoming
    messages are queued, and no automatic deliveries are started. If this
    happens during local or remote SMTP input, all subsequent messages on
    the same connection are queued. Deliveries will subsequently be per-
    formed by queue running processes, unless the load is higher than
    deliver_load_max. There are some operating systems for which Exim
    cannot determine the load average (see chapter 1); for these this
    option has no effect. See also smtp_accept_queue and smtp_load_reserve.

queue_remote

    Type:    boolean
    Default: false

    If this option (equivalent to the -odqr option) is set, a delivery
    process is started whenever a message is received, but only local
    addresses are handled, and only local deliveries take place, unless      |
    queue_remote_except is set, in which case addresses that contain         |
    matching remote domains are also handled. See also queue_smtp, which is  |
    subtly different.

queue_remote_except                                                          |
                                                                             |
    Type:    domain-list                                                     |
    Default: unset                                                           |
                                                                             |
    This option lists domains for which queue_remote does not apply. It is   |
    checked against the domains supplied in the incoming addresses, before   |
    any widening is done (because that is part of routing).                  |

queue_run_in_order

    Type:    boolean
    Default: false

    If this option is set, queue runs happen in order of message arrival
    instead of in an arbitrary order.

queue_run_max

    Type:    integer
    Default: 5

    This controls the maximum number of queue-running processes that the
    Exim daemon will run simultaneously. It does not, however, interlock
    with other processes, so additional queue-runners can be started by
    other means, or by killing and restarting the daemon.

queue_smtp

    Type:    boolean
    Default: false

    If queue_smtp is set (which is equivalent to the -odqs command line
    option), a delivery process is started whenever a message has been
    received, but only local deliveries take place. If any SMTP deliveries
    are required, the message waits on the queue for the next queue run.
    Since routing of the message has taken place, Exim knows to which
    remote hosts it must be delivered, and so when the queue run happens,
    multiple messages for the same host are delivered over a single SMTP
    connection. See also queue_remote, which is similar, but does not do
    the routing.

rbl_domains                                                                  |
                                                                             |
    Type:    domain-list                                                     |
    Default: unset                                                           |
                                                                             |
    This option is part of the support for Realtime Blocking Lists (RBL),    |
    details of which are given in chapter 40. It can be set to a colon-      |
    separated list of DNS RBL domains in which to look up the inverted IP    |
    address of a calling host. If any lookup succeeds, and                   |
    rbl_reject_recipients is set, mail from the host is blocked by refusing  |
    all recipients, except those listed in recipients_reject_except. If a    |
    lookup times out or otherwise fails to give a decisive answer, the mail  |
    is not blocked (by that entry in the list). When blocking occurs, an     |
    associated TXT record is looked up in the DNS, and if it exists, its     |
    contents are returned as part of the 550 rejection messages.             |
                                                                             |
rbl_except_nets                                                              |
                                                                             |
    Type:    net-list                                                        |
    Default: unset                                                           |
                                                                             |
    Networks and individual hosts can be excepted from RBL checking by       |
    setting rbl_except_nets.                                                 |
                                                                             |
rbl_reject_recipients                                                        |
                                                                             |
    Type:    boolean                                                         |
    Default: true                                                            |
                                                                             |
    If this option is turned off, then any hosts that are found by           |
    searching rbl_domains are just logged rather than causing recipients to  |
    be rejected.                                                             |
                                                                             |
rbl_warn_header                                                              |
                                                                             |
    Type:    boolean                                                         |
    Default: true                                                            |
                                                                             |
    When this option is set and rbl_reject_recipients is false, an X-RBL-    |
    Warning: header is added to any message whose sending host is in any     |
    RBL. The header contains the contents of the DNS TXT record, if one was  |
    found.                                                                   |

received_header_text

    Type:    string
    Default: see below

    This string defines the contents of the Received message header that is
    added to each message, except for the timestamp, which is automatically
    added on at the end, preceded by a semicolon. The string is expanded
    each time it is used, and the default is

      received_header_text = "Received: \
           ${if def:sender_fullhost {from ${sender_fullhost} \
           ${if def:sender_ident {(${sender_ident})}}\n\t}\
           {${if def:sender_ident {from ${sender_ident} }}}}\
           by ${primary_hostname} \
           ${if def:received_protocol {with ${received_protocol}}} \
           (Exim ${version_number} #${compile_number})\n\t\
           id ${message_id}"

    The use of conditional expansions ensures that this works for both
    locally generated messages and messages received from remote hosts,
    giving header lines such as the following:

      Received: from scrooge.carol.book [240.1.12.25] (root)
              by marley.carol.book with smtp (Exim 0.25 #9)
              id E0tS3Ga-0005C5-00; Mon, 25 Dec 1995 14:43:44 +0000
      Received: by scrooge.carol.book with local (Exim 0.25 #9)
              id E0tS3GW-0005C2-00; Mon, 25 Dec 1995 14:43:41 +0000

    Note the automatic addition of the date and time in the required
    format.

received_headers_max

    Type:    integer
    Default: 30

    When a message is to be delivered to a remote machine, the number of
    Received headers is counted, and if it is greater than this parameter,
    a mail loop is assumed to have occurred, the delivery is abandoned, and
    a delivery error message is generated.

receiver_try_verify

    Type:    boolean
    Default: false

    See receiver_verify.

receiver_unqualified_hosts

    Type:    host-list
    Default: unset

    This option lists those hosts from which Exim is prepared to accept
    unqualified receiver addresses. The addresses are made fully qualified
    by the addition of the qualify_recipient value. Typically the hosts are
    local ones, but if you want to imitate the behaviour of mailers that
    accept unqualified addresses from anywhere, specify

      receiver_unqualified_hosts = *

receiver_unqualified_nets

    Type:    net-list
    Default: unset

    This option lists those IP networks from any host on which Exim is
    prepared to accept unqualified receiver addresses. The addresses are
    made fully qualified by the addition of the qualify_domain. Typically
    local networks are specified. This is a more efficient option than
    using a wildcarded partial entry in receiver_unqualified_hosts, because
    no DNS lookup is required.

receiver_verify

    Type:    boolean
    Default: false

    When this option is set, the addresses of recipients received from a
    remote host are verified as they are received, unless the host matches
    an entry in either receiver_verify_except_hosts or
    receiver_verify_except_nets. If receiver_verify_addresses, is set, only
    those addresses that match are verified. If receiver_verify_senders, or
    receiver_verify_senders_except is set, verification happens only for
    messages whose senders meet the criteria.

    If an address is invalid, an incoming SMTP call gets an error response
    to the RCPT TO command. If an address cannot immediately be verified, a
    temporary error code is given. The receiver_try_verify option is less
    severe: it operates in the same way, except that an address is accepted
    if it cannot immediately be verified. Verification failures are logged.

receiver_verify_addresses

    Type:    address-list
    Default: unset

    This option restricts receiver verification to those addresses it
    matches. The option is inspected only if receiver_verify or
    receiver_try_verify is set.

receiver_verify_except_hosts

    Type:    host-list
    Default: unset

    See receiver_verify above.

receiver_verify_except_nets

    Type:    net-list
    Default: unset

    See receiver_verify above.

receiver_verify_senders

    Type:    address-list
    Default: unset

    This option, together with receiver_verify_senders_except, allows
    receiver verification to be conditional upon the sender. These options
    are inspected only if receiver_verify or receiver_try_verify is set. If
    receiver_verify_addresses is also set, then the address must also match
    verification to occur.

    Verification does not occur if the sender matches any item in
    receiver_verify_senders_except or if receiver_verify_senders is set and
    the sender address does not match any of its items.

    If the null sender is required in the list of addresses, then it must
    not be the last item, as a null last item in a list is ignored. It is
    best placed at the start of the list. For example, to restrict receiver
    verification to messages with null senders and senders in the .com and
    .org domains, you could have

      receiver_verify
      receiver_verify_senders = :*.com:*.org

    If the null sender is the only entry required, then the list should
    consist of a single colon.

receiver_verify_senders_except

    Type:    address-list
    Default: unset

    See receiver_verify_senders above.

recipients_max

    Type:    integer
    Default: 0

    If this is set greater than zero, it specifies the maximum number of
    recipients for any message. This applies to the original list of
    recipients supplied with the message. SMTP messages get a 421 response
    for all recipients over the limit; earlier recipients are delivered as
    normal. Non-SMTP messages with too many recipients are failed, and no
    deliveries are done.

recipients_max_reject

    Type:    boolean
    Default: false

    If this option is set true, then Exim rejects SMTP messages containing
    too many recipients by giving 550 errors to the surplus RCPT TO
    commands, and a 554 error to the eventual DATA command. Otherwise (the
    default) it gives a 421 error to the surplus RCPT TO commands and
    accepts the message on behalf of the initial set of recipients. The
    remote server should then re-send the message for the remaining
    recipients at a later time.

recipients_reject_except

    Type:    address-list
    Default: unset

    This option lists recipient addresses which are exceptions to any
    policy for recipient rejection, that is, as a result of
    sender_reject_recipients, etc. This option is entirely independent of    |
    any checks for unwanted message relaying. However, it does interact      |
    with the RBL options.                                                    |

refuse_ip_options

    Type:    boolean
    Default: true

    See kill_ip_options above.

relay_domains

    Type:    domain-list
    Default: unset

    See sender_host_accept_relay and related options below.

relay_domains_include_local_mx

    Type:    boolean
    Default: false

    This option permits any host to relay to any domain that has an MX
    record pointing at the local host. See sender_host_accept_relay below.

relay_match_host_or_sender

    Type:    boolean
    Default: false

    By default, if relaying controls are specified on both the remote host
    and the sender address, a message is accepted only if both conditions
    are met. If relay_match_host_or_sender is set, then either condition is
    good enough. See sender_host_accept_relay for more details.

remote_max_parallel

    Type:    integer
    Default: 1

    This option controls parallel delivery to remote sites. If the value is
    less than 2, parallel delivery is disabled, and Exim does all the
    remote deliveries for a message one by one, from a single delivery
    process. Otherwise, if a message has to be delivered to more than one
    remote host, then up to remote_max_parallel deliveries are done simul-
    taneously, each in a separate process. If there are more than
    remote_max_parallel hosts to be delivered to, then the maximum number
    of processes are started, and as each one finishes, another is begun.
    The order of starting processes is the same as if sequential delivery
    were being done, and can be controlled by the remote_sort option. If
    parallel delivery takes place while running with debugging turned on,
    the debugging output from each delivery process is tagged with its
    process id.

    The overhead in doing this is a fork to set up a separate process for
    each delivery, and the associated management of the subprocess (includ-
    ing getting back the result of the delivery attempt). As well as the
    process overhead, there may be a small additional penalty paid for
    parallel delivery. If host is found to be down, this fact cannot be
    communicated to any deliveries that are running in parallel, though it
    will be passed on to any that start afterwards. This is no worse than
    if there were two separate messages being delivered simultaneously.

    The option controls only the maximum number of parallel deliveries from
    one Exim process. Since Exim has no central queue manager, there is no
    way of controlling the total number of simultaneous deliveries if the
    configuration allows a delivery attempt as soon as a message is
    received. If you want to control the total number of deliveries on the
    system, then you need to set the queue_only option, which ensures that
    all incoming messages are simply added to the queue. Then set up an
    Exim daemon to start queue runner processes at appropriate intervals
    (probably fairly often, e.g. every minute), and limit the total number
    of queue runners by setting the queue_run_max parameter. As each queue
    runner delivers only one message at a time, the maximum number of
    deliveries that can then take place at once is queue_run_max multiplied
    by remote_max_parallel.

    If it is purely remote deliveries you want to control, then use
    queue_smtp instead of queue_only. This has the added benefit of doing
    the SMTP routing before queuing, so that several messages for the same
    host will eventually get delivered down the same connection.

remote_sort

    Type:    domain-list
    Default: unset

    When there are a number of remote deliveries for a message, they are
    sorted by domain into the order given by this list. For example,

      remote_sort = "*.cam.ac.uk:*.uk"

    would attempt to deliver to all addresses in the cam.ac.uk domain
    first, then to those in the uk domain, then to any others.

retry_interval_max

    Type:    time
    Default: 24h

    Chapter 32 describes Exim's mechanisms for controlling the intervals
    between delivery attempts for messages that cannot be delivered
    straight away. This option sets an overall limit to the length of time
    between retries.

return_path_remove

    Type:    boolean
    Default: true

    RFC 822 states that the Return-path header is 'added by the final
    transport system that delivers the message to its recipient' (section
    4.3.1), which implies that this header should not be present in
    incoming messages. If this option is true, Return-path headers are
    removed from messages as they are read. Exim's local transports
    (appendfile and pipe) have options for adding Return-path headers at
    the time of local delivery.

return_size_limit

    Type:    integer
    Default: 100K

    This option sets limit in bytes on the size of messages that are
    returned to sender. If it is set to zero there is no limit. If the body
    of any message that is to be included in an error message is greater
    than the limit, it is truncated, and a comment pointing this out is
    added at the top. The actual cutoff may be greater than the value
    given, owing to the use of buffering for transferring the message in
    chunks. The idea is just to save bandwidth on those undeliverable
    15-megabyte messages. If message_size_limit is set, the value of
    return_size_limit should be somewhat smaller.

rfc1413_except_hosts

    Type:    host-list
    Default: unset

    If this option is set, RFC 1413 identification calls are not made to     |
    any host which matches an item in the list. The items in the host list   |
    should not themselves contain ident data.                                |

rfc1413_except_nets

    Type:    net-list
    Default: unset

    If this option is set, RFC 1413 identification calls are not made to
    any host on the listed networks.

rfc1413_query_timeout

    Type:    time
    Default: 60s

    This sets the timeout on RFC 1413 identification calls. If it is set to
    zero, no RFC 1413 calls are ever made. This is more efficient than
    setting a global pattern in one of the except options.

security

    Not implemented under OS/2.

sender_accept

    Type:    address-list
    Default: unset

    This option requests the acceptance of incoming SMTP mail from the
    specified envelope senders only. It operates like sender_reject (see
    below), and is also modified by sender_reject_except.

sender_accept_recipients

    Type:    address-list
    Default: unset

    This operates in exactly the same way as sender_accept except that
    rejection is given in the form of a 550 error code to every RCPT TO
    command instead of rejecting MAIL FROM. This seems to be the only way
    of saying 'no' to some mailers.

sender_address_relay

    Type:    address-list
    Default: unset

    See sender_host_accept_relay below.

sender_host_accept

    Type:    host-list
    Default: unset

    If this option is set, incoming SMTP calls are accepted only from the
    hosts listed, possibly also qualified by an RFC 1413 identification.
    (Calls from networks listed in sender_net_accept are also accepted.)
    However, if a call arrives from a host (and identification) which is
    also listed in sender_host_reject or from a network listed in
    sender_net_reject, the call is rejected. Chapter 40 contains details of
    this facility; see also sender_accept and sender_reject.

sender_host_accept_relay

    Type:    host-list
    Default: unset

    An MTA is said to "relay" a message if it receives it from some host
    and delivers it directly to another host as a result of a remote
    address contained in it. Expanding a local address via an alias or
    forward file and then passing the message on is not relaying.

    If any of the relaying options is set, a check is made on incoming
    recipient addresses in messages received from other hosts at the time
    of the RCPT TO command in the SMTP dialogue. If the domain in a
    recipient address matches an entry either in local_domains or in
    relay_domains, or if relay_domains_include_local_mx is set and the
    domain has an MX record pointing to the local host, the address is
    always accepted (at least as far as this check is concerned - a
    subsequent verification check may fail it).

    Otherwise, the address is accepted only if the host is permitted to
    relay to arbitrary domains, as specified by the options
    sender_net_accept_relay, sender_host_accept_relay, sender_net_reject_
    relay and sender_host_reject_relay. If all of these are unset then

     .   If relay_domains is set, no hosts are permitted to relay to
         arbitrary domains.

     .   If relay_domains is unset, all hosts are permitted to relay to
         arbitrary domains.

    When at least one of the host or net relay options is set, the address
    is accepted only if sender_host_accept_relay and
    sender_net_accept_relay are both null or if the host matches one of
    their patterns, and if the host does not match any pattern in
    sender_host_reject_relay or sender_net_reject_relay. Thus a 'reject'     |
    option acts as an exception list to an 'accept' option, and not the      |
    other way round.                                                         |

    In addition to the tests on the host, if sender_address_relay is set,
    the sender's address from the MAIL FROM command must match one of its
    patterns to allow relaying to an arbitrary domain. However, if
    relay_match_host_or_sender is set, an address is accepted for relaying
    if either the host is acceptable or the sender matches an item in
    sender_address_relay. Chapter 40 contains further details of this
    facility.

sender_host_reject

    Type:    host-list
    Default: unset

    If this option is set, incoming SMTP calls from the hosts listed,
    possibly also qualified by an RFC 1413 identification, are rejected.
    Chapter 40 contains details of this facility. See also the RBL options.

sender_host_reject_recipients

    Type:    host-list
    Default: unset

    If this option is set, all recipients in incoming SMTP calls from the
    hosts listed, possibly also qualified by an RFC 1413 identification,
    are rejected. Chapter 40 contains details of this facility, which
    differs from sender_host_reject only in the point in the SMTP dialogue
    at which the rejection occurs.

sender_host_reject_relay

    Type:    host-list
    Default: unset

    Recipient addresses in domains other than those in local_domains or
    relay_domains are rejected from hosts that match this list, even if
    they match a pattern in sender_host_accept_relay or
    sender_net_accept_relay. If you don't want to do any relaying at all,
    then relay_domains should be left unset, and sender_host_reject_relay
    set to *.

sender_net_accept

    Type:    net-list
    Default: unset

    If this option is set, incoming SMTP calls are accepted only from the
    IP networks specified (and from any hosts listed in
    sender_host_accept). However, if a call arrives from a host (and
    identification) which is also listed in sender_host_reject or from a
    network listed in sender_net_reject, the call is rejected. Chapter 40
    contains details of this facility; see also sender_reject.

sender_net_accept_relay

    Type:    net-list
    Default: unset

    This operates like sender_host_accept_relay, except that the check is
    done by IP network number.

sender_net_reject

    Type:    net-list
    Default: unset

    If this option is set, incoming SMTP calls from the listed networks are
    rejected. Chapter 40 contains details of this facility.

sender_net_reject_recipients

    Type:    net-list
    Default: unset

    If this option is set, all recipients on incoming SMTP calls from the
    listed networks are rejected. Chapter 40 contains details of this
    facility, which differs from sender_net_reject only in the point in the
    SMTP dialogue at which the rejection occurs.

sender_net_reject_relay

    Type:    net-list
    Default: unset

    Recipient addresses in domains other than those in local_domains or
    relay_domains are rejected from hosts on networks that match this list,
    even if they match sender_host_accept_relay or sender_net_accept_relay.
    Rejection happens at SMTP time, before any routers or directors are
    run. Chapter 40 contains details of this facility.

sender_reject

    Type:    address-list
    Default: unset

    This option can be set in order to reject mail from certain senders.
    The check is done on the sender's address as given in the MAIL FROM
    command in SMTP, but not for local senders where the logged-in user's
    address is going to override anyway.

    If the sender's address is source-routed, it is the final component of
    the address that is checked. The check is not done for batch SMTP
    input. If the check fails, a 5xx return code is given to MAIL FROM.
    This doesn't always stop remote mailers from trying again. See
    sender_reject_recipients for an alternative. Typical examples of the
    use of this option might be:

      sender_reject = "spamuser@some.domain:spam.domain"
      sender_reject = partial-dbm;/etc/mail/blocked/senders

    Note that this check operates on sender address domains independently
    of the sending host; sender_host_reject and sender_net_reject can be
    used to block all mail from particular hosts or nets, while
    sender_host_reject_relay, sender_net_reject_relay and
    sender_address_relay can be used to prevent unwanted relaying.

    There is also a sender_accept option. A sender is rejected if either of
    the following statements is true:

     .   Either sender_accept or sender_accept_recipients is set, and the
         sender does not match either of them, nor does it match
         sender_reject_except.

     .   Either sender_reject or sender_reject_recipients is set, and the
         sender matches one of them and does not match
         sender_reject_except.

sender_reject_except

    Type:    address-list
    Default: unset

    This option allows exceptions to be listed for the sender accept and
    reject options (see above).

sender_reject_recipients

    Type:    address-list
    Default: unset

    This operates in exactly the same way as sender_reject except that the
    rejection is given in the form of a 550 error code to every RCPT TO
    command instead of rejecting MAIL FROM. This seems to be the only way
    of saying 'no' to some mailers. See also sender_accept_recipients.

sender_try_verify

    Type:    boolean
    Default: false

    See sender_verify.

sender_unqualified_hosts

    Type:    host-list
    Default: unset

    This option lists those hosts from which Exim is prepared to accept
    unqualified sender addresses. The addresses are made fully qualified by
    the addition of the qualify_domain. Typically the hosts are local ones,
    but if you want to imitate the behaviour of mailers that accept
    unqualified addresses from anywhere, specify

      sender_unqualified_hosts = *

sender_unqualified_nets

    Type:    net-list
    Default: unset

    This option lists those IP networks from any host on which Exim is
    prepared to accept unqualified sender addresses. The addresses are made
    fully qualified by the addition of the qualify_domain. Typically local
    networks are specified. This is a more efficient option than using a
    wildcarded partial entry in sender_unqualified_hosts, because no DNS
    lookup is required.

sender_verify

    Type:    boolean
    Default: false

    If this option is true, envelope sender addresses on incoming SMTP
    messages are checked to ensure that they are valid. Messages with
    invalid envelope senders are rejected with a permanent error code if
    sender_verify_reject is set (the default). Otherwise a warning is
    logged. See section 39.2 for details of the rejection, which can happen
    at three different points of the SMTP dialogue. If a sender cannot
    immediately be verified, a temporary error code is returned after
    reading the data (so the headers can be logged). The sender_try_verify
    option is less severe: it operates in exactly the same way as
    sender_verify except that if an address cannot immediately be verified,
    it is accepted instead of being temporarily rejected.

sender_verify_batch

    Type:    boolean
    Default: true

    If this option is unset, then the sender_verify options are not applied
    to batched SMTP input.

sender_verify_except_hosts

    Type:    host-list
    Default: unset

    If sender_verify is true, this option specifies a list of hosts and RFC
    1413 identifications which are exempt from sender verification. It also  |
    suppresses the check caused by headers_sender_verify for matching        |
    hosts. See chapter 42 for details.                                       |

sender_verify_except_nets

    Type:    net-list
    Default: unset

    If sender_verify is true, this option specifies a list of IP networks
    which are exempt from sender checking. It also suppresses the check      |
    caused by headers_sender_verify for matching hosts. See chapter 42 for   |
    details.

sender_verify_fixup

    Type:    boolean
    Default: false

    Experience shows that many messages are sent out onto the Internet with
    invalid sender addresses in the envelopes (i.e. in the MAIL FROM
    command of the SMTP dialogue), but with valid addresses in the Sender,
    From, or Reply-to header fields. If sender_verify and                    |
    sender_verify_reject are true and this option is also true, an invalid   |
    envelope sender or one that cannot immediately be verified is replaced
    by a valid value from the headers. If sender_verify_verify_reject is
    false, the envelope sender is not changed, but Exim writes a log entry
    giving the correction it would have made. See chapter 42 for details.

sender_verify_log_details

    Type:    boolean
    Default: false

    Setting this option causes additional information about sender verifi-
    cation to be written to the reject log. It is intended to help sort out
    problems concerned with sender verification, and is more for debugging
    Exim than for regular use. Some of the information is about messages
    that are not rejected, that is, they passed the test.

sender_verify_reject

    Type:    boolean
    Default: true

    When this is set, a message is rejected if sender verification fails.
    If it is not set, a warning message is written to the main and reject
    logs, and the message is accepted (unless some other error occurs).

smtp_accept_max

    Type:    integer
    Default: 20

    This specifies the maximum number of simultaneous incoming SMTP calls
    that Exim will accept. It applies only to the listening daemon; there
    is no control (in Exim) when incoming SMTP is being handled by inetd.
    If the value is set to zero, no limit is applied.

smtp_accept_queue

    Type:    integer
    Default: 0

    If the number of simultaneous incoming SMTP calls handled via the
    listening daemon exceeds this value, then messages received are simply
    placed on the queue, and no delivery processes are started automati-
    cally. A value of zero implies no limit, and clearly any non-zero value
    is useful only if it is less than the smtp_accept_max value (unless
    that is zero). See also queue_only, queue_only_load, queue_smtp, and
    the various -od command line options.

smtp_accept_reserve

    Type:    integer
    Default: 0

    When smtp_accept_max is set greater than zero, this option specifies a
    number of SMTP connections that are reserved for connections from the
    hosts or networks that are specified in smtp_reserve_hosts and
    smtp_reserve_nets. The value set in smtp_accept_max includes this
    reserve pool. For example, if smtp_accept_max is set to 50 and
    smtp_accept_reserve is set to 5, then once there are 45 active
    connections, new ones are accepted only from hosts listed in
    smtp_reserve_hosts or from networks listed in smtp_reserve_nets.

smtp_banner

    Type:    string
    Default: see below

    This string, which is expanded every time it is used, is output as the
    initial positive response to an SMTP connection. The default setting
    is:

      smtp_banner = "${primary_hostname} ESMTP Exim ${version_number} \
        #${compile_number} ${tod_full}"

    Failure to expand the string causes a panic error. If you want to
    create a multiline response to the initial SMTP connection, use '\n' in
    the string at appropriate points. Note that the 220 code is not
    included in this string. Exim adds it automatically (several times in
    the case of a multiline response).

smtp_connect_backlog

    Type:    integer
    Default: 5

    This specifies a maximum number of waiting SMTP connections. Exim
    passes this value to the TCP/IP system when it sets up its listener.
    Once this number of connections are waiting for the daemon's attention,
    subsequent connection attempts are refused at the TCP/IP level. At
    least, that is what the manuals say. In Solaris 2.4 such connection
    attempts have been observed to time out. The default value of 5 is a
    conservative one, suitable for older and smaller systems. For large
    systems is it probably a good idea to increase this, possibly substan-
    tially (to 50, say). It also gives some protection against denial-of-
    service attacks by SYN flooding.

smtp_etrn_hosts

    Type:    host-list
    Default: unset

    RFC 1985 describes a new SMTP command called ETRN which is designed to
    overcome the security problems of the TURN command (which has fallen
    into disuse). Exim recognizes ETRN if the calling host matches an entry
    in this option or in smtp_etrn_nets. The ETRN command is concerned with
    'releasing' messages that are awaiting delivery to certain hosts. As
    Exim does not organize its message queue by host, the only form of ETRN
    that is supported is the one where the text starts with the '#' prefix,
    where the remainder of the text is specific to the SMTP server. A valid
    ETRN command causes a run of Exim with the -R option to happen, with
    the remainder of the ETRN text as its argument. For example,

      ETRN #brigadoon

    causes a delivery attempt on all messages with undelivered addresses
    containing the text 'brigadoon'. Because a separate delivery process is
    run to do the delivery, there is no security risk with ETRN.

smtp_etrn_nets

    Type:    net-list
    Default: unset

    See smtp_etrn_hosts above.

smtp_expn_hosts

    Type:    host-list
    Default: unset

    The SMTP EXPN command is supported only if the calling host matches
    smtp_expn_hosts or smtp_expn_nets. You must add 'localhost' explicitly
    if you want calls to 127.0.0.1 to be able to use it. A single-level
    expansion of the address is done. If an unqualified local-part is
    given, it is qualified with qualify_domain. There is a generic option
    for directors which permits them to be skipped when processing an EXPN
    command (compare with verification).

smtp_expn_nets

    Type:    net-list
    Default: unset

    See smtp_expn_hosts above.

smtp_load_reserve

    Type:    fixed-point
    Default: unset

    If the system load average ever gets higher than this, incoming SMTP
    calls are accepted only from those hosts that match an entry in
    smtp_reserve_hosts or smtp_reserve_nets. There are some operating sys-
    tems for which Exim cannot determine the load average (see chapter 1);
    for these this option has no effect.

smtp_receive_timeout

    Type:    time
    Default: 5m

    This sets a timeout value for SMTP reception. If a line of input
    (either an SMTP command or a data line) is not received within this
    time, the SMTP connection is dropped and the message abandoned.

smtp_reserve_hosts

    Type:    host-list
    Default: unset

    This option lists hosts for which SMTP connections are reserved; see
    smtp_accept_reserve and smtpload_reserve above.

smtp_reserve_nets

    Type:    net-list
    Default: unset

    This option lists IP networks for which SMTP connections are reserved;
    see smtp_accept_reserve and smtpload_reserve above.

smtp_verify

    Type:    boolean
    Default: false

    If this option is true, the SMTP command VRFY is supported on incoming
    SMTP connections; otherwise it is not.

split_spool_directory

    Type:    boolean
    Default: false

    If this option is set, it causes Exim to split its input directory into
    62 subdirectories, each with a single alphanumeric character as its
    name. The 5th character of the message-id is used to allocate messages
    to subdirectories; this is the least significant base-62 digit of the
    time of arrival of the message.

    Splitting up the spool in this way may provide better performance on
    systems where there are long mail queues, by reducing the number of
    files in any one directory. The msglog directory is also split up in a
    similar way to the input directory; however, if preserve_message_logs
    is set, all old msglog files are still placed in the single directory
    msglog.OLD.

    It is not necessary to take any special action for existing messages
    when changing split_spool_directory. Exim notices messages that are in
    the 'wrong' place, and continues to process them. If the option is
    turned off after a period of being on, the subdirectories will
    eventually empty and get deleted.

spool_directory

    Type:    string
    Default: compile-time configured (may be unset)

    This defines the directory in which Exim keeps its mail spool. The
    default value is taken from the compile-time configuration setting, if
    there is one. If not, this option must be set. The string is expanded,
    so it can contain, for example, a reference to ${primary_hostname}.

    If the spool directory name is fixed on your installation, it is
    recommended that you set it at build time rather than from this option,
    particularly if the log files are being written to the spool directory
    (see log_file_path). Otherwise log files cannot be used for errors that
    are detected early on, such as failures in the configuration file.

    Even with a compiled-in path, however, this option makes it possible to
    run testing configurations of Exim without using the standard spool.

strip_excess_angle_brackets

    Type:    boolean
    Default: false

    If this option is set, then redundant pairs of angle brackets round
    'route-addr' items in addresses are stripped. For example,
    <<xxx@a.b.c.d>> is treated as <xxx@a.b.c.d>. If this is in the envelope
    and the message is passed on to another MTA, the excess angle brackets
    are not passed on. If this option is not set, multiple pairs of angle
    brackets cause a syntax error.

strip_trailing_dot

    Type:    boolean
    Default: false

    If this option is set, a trailing dot at the end of a domain in an
    address is ignored. If this is in the envelope and the message is
    passed on to another MTA, the dot is not passed on. If this option is
    not set, a dot at the end of a domain causes a syntax error.

trusted_groups

    Not implemented under OS/2.

trusted_users

    Not implemented under OS/2.

unknown_login

    Type:    string
    Default: unset

    This is a specialized feature for use in unusual configurations. By
    default, if the uid of the caller of Exim can't be found in USER,
    Exim gives up. The unknown_login option can be used to set
    a login name to be used in this circumstance. When unknown_login
    is used, the value of unknown_username is used for the user's real name,
    unless this has been set by the -F option.

unknown_username

    Type:    string
    Default: unset

    See unknown_login.

uucp_from_pattern                                                            |
                                                                             |
    Type:    string                                                          |
    Default: see below                                                       |
                                                                             |
    Some applications that pass messages to an MTA via a command line        |
    interface use an initial line starting with 'From' to pass the envelope  |
    sender. In particular, this is used by UUCP software. Exim recognizes    |
    such a line by means of a regular expression that is set in              |
    uucp_from_pattern, and when the pattern matches, the sender address is   |
    constructed by expanding the contents of uucp_from_sender, provided      |
    that the caller of exim is a trusted user. The default pattern           |
    recognizes lines in the following two forms:                             |
                                                                             |
         From ph10 Fri Jan  5 12:35 GMT 1996                                 |
         From ph10 Fri, 7 Jan 97 14:00:00 GMT                                |
                                                                             |
    It checks only up to the hours and minutes, and allows for a 2-digit or  |
    4-digit year in the second case. The first word after 'From' is matched  |
    in the regular expression by a parenthesized subpattern. The default     |
    value for uucp_from_sender is '$1', which therefore just uses this       |
    first word ('ph10' in the example above) as the message's sender.        |
                                                                             |
uucp_from_sender                                                             |
                                                                             |
    Type:    string                                                          |
    Default: "$1"                                                            |
                                                                             |
    See uucp_from_pattern above.                                             |



                         11. DRIVER SPECIFICATIONS


The second, third, and fourth parts of Exim's configuration file specify
which transport, director, and router drivers are to be used. Directors and  |
routers are similar, in that an address is passed to a list of them in the   |
order in which they are defined, whereas the order in which transports are   |
specified is immaterial. A transport is invoked only after being passed an   |
address by a director or a router.                                           |
                                                                             |
The format of the configuration data is the same for all three types of      |
driver, and is as follows:                                                   |
                                                                             |
  <driver instance name>:                                                    |
    <option>                                                                 |
    ...                                                                      |
    <option>                                                                 |
                                                                             |
There are two kinds of option: generic and private. The generic options are  |
those that apply to all drivers of the same type (i.e. all directors, or     |
all routers, or all transports). There is always at least one generic        |
option, called driver, which specifies which particular driver is being      |
used. The private options are particular to each driver, and none need       |
appear.                                                                      |
                                                                             |
The options may appear in any order, except that the driver option must      |
precede any private options, since these depend on the particular driver.    |
For this reason, it is recommended that driver always be the first option.   |
                                                                             |
In previous versions of Exim, commas were used between options, and the      |
generic options had to precede the private ones and be terminated by a       |
semicolon. This is no longer the case. For backwards compatibility, commas   |
and semicolons are still permitted at the ends of options, but they are      |
ignored.                                                                     |

Each instance of a driver is given an identifying name for reference in
logging and elsewhere. This should not be confused with the name of the
underlying driver. For example, the configuration lines

  remote_smtp:
    driver = smtp

create an instance of the smtp transport driver whose name is remote_smtp.
The same driver code can be used more than once, with different instance
names and different option settings each time. A second instance of the
smtp transport, with different options, might be defined thus:

  special_smtp:
    driver = smtp
    service = 1234
    command_timeout = 10s

The names remote_smtp and special_smtp would be used to reference these
drivers from directors or routers.

Comment lines may appear in the middle of driver specifications. The full
list of option settings for any particular driver instance, including all
the defaults, can be extracted by making use of the -bP command line option
(see chapter 5).

The order of driver specifications in the configuration file matters for
the directors and the routers, since an address is passed to each of them
in turn until one is able to handle it. The order of transport specifi-
cations does not matter.

The next chapter discusses the environment in which local deliveries are
done, and how this is affected by the configurations of the relevant
directors, routers, and transports.

Subsequent chapters describe the generic options for each type of driver,
and these are followed by descriptions of each of the available drivers of
each type.



                12. ENVIRONMENT FOR RUNNING LOCAL TRANSPORTS


Local transports handle deliveries to files and pipes. (The autoreply
transport can be thought of as similar to a pipe.) Whenever a local
transport is run, Exim forks a subprocess for it. It also sets a
current file directory; for some transports a home directory setting
is also relevant.

The values used for the directories may come from several different
places. In many cases the director that handles the address associates
settings with that address. However, values may also be given in the
transport's own configuration, and these override anything that comes
with the address. The sections below contain a summary of the possible
sources of the values, and how they interact with each other.


12.2 Current and home directories

The pipe transport has a home_directory option. If this is set, it
overrides any home directory set by the director for the address. The value
of the home directory is set in the environment variable HOME while running
the pipe. It need not be set, in which case HOME is not defined.

The appendfile transport does not have a home_directory option. The only
use for a home directory in this transport is if the expansion variable
$home is used in one of its options, in which case the value set by the
director is used.

The appendfile and pipe transports have a current_directory option. If this
is set, it overrides any current directory set by the director for the
address. If neither the director nor the transport sets a current direc-
tory, then Exim uses the value of the home directory, if set. Otherwise it
sets the current directory to '/' before running a local transport.

The aliasfile, forwardfile, and localuser directors all have
current_directory and home_directory options, which are associated with any
addresses they explicitly direct to a local transport.

For forwardfile, if home_directory is not set and there is a file_directory
value, that is used instead. If it too is not set, but check_local_user is
set, the user's home directory is used. For localuser, if home_directory is
not set, the home directory is taken from the password file entry that this
director looks up. There are no defaults for current_directory in the
directors, because it defaults to the value of home_directory if it is not
set at transport time.

The smartuser director has no means of setting up home and current
directory strings; consequently any local transport that it uses must
specify them for itself if they are required.



                     13. GENERIC OPTIONS FOR TRANSPORTS


The generic options for transports are as follows:

add_headers

    Type:    string
    Default: unset

    This option specifies a string of text which is expanded and added to
    the header portion of a message as it is transported. It should be in
    the form of one or more RFC 822 header lines, separated by newlines
    (coded as '\n' inside a quoted string), for example:

      add_headers = "X-added: this is a header added at $tod_log\n\
                     X-added: this is another"

    Exim does not check the syntax of these added headers. A newline is
    supplied at the end if one is not present. The text is added at the end
    of any existing headers. If you include a blank line within the string,
    you can subvert this facility into adding text at the start of the
    message's body.

driver

    Type:    string
    Default: unset

    This specifies which of the available transport drivers is to be used.
    For example:

      driver = smtp

    There is no default, and this option must be set for every transport.

remove_headers

    Type:    string
    Default: unset

    This option consists of a colon-separated list of header names, not
    including the terminating colon, for example

      remove_headers = "return-recipt-to:acknowledge-to"

    Any existing headers matching those names are not included in any
    message that transmitted by the transport. However, added headers may
    have these names. Thus it is possible to replace a header by specifying
    it in remove_headers and supplying the replacement in add_headers.

transport_filter

    Type:    string
    Default: unset

    This option sets up a filtering (in the Unix shell sense) process for
    messages at transport time. It should not be confused with mail
    filtering as set up by individual users.

    When the message is about to be written out, the command specified by
    transport_filter is started up in a separate process, and the entire
    message, including the headers, is passed to it on its standard input
    (this in fact is done from a third process, to avoid deadlock). The
    filter is run before any SMTP-specific processing, such as turning '\n'
    into '\r\n' and escaping lines beginning with a dot.

    The filter's standard output is read and written to the message's
    destination. The filter can perform any transformations it likes, but
    of course should take care not to break RFC 822 syntax. A demonstration
    Perl script is provided in util/transport-filter.pl; this makes a few
    arbitrary modifications just to show the possibilities.

    The value of the option is the command string for starting up the
    filter. This is parsed by Exim in the same way as a command string for
    the pipe transport: Exim breaks it up into arguments and then expands
    each argument separately. The special argument $pipe_addresses is
    replaced by a number of arguments, one for each address that applies to
    this delivery. (This isn't an ideal name for this feature here, but as
    it was already implemented for the pipe transport, it seemed sensible
    not to change it.)

    The expansion variables $host and $host_address are available when the
    transport is a remote one. They are set only for the expansion of a
    transport filter command, as that is the only thing that is expanded
    after a connection has been set up. For example:

      transport_filter = "/some/directory/transport-filter.pl \
        $host $host_address $sender_address $pipe_addresses"

    If a transport filter is set on an autoreply transport, the original
    message is passed through the filter as it is being copied into the
    newly generated message, which happens if the return_message option is
    set.



                        14. THE APPENDFILE TRANSPORT


The appendfile transport delivers a message by appending it to a file in
the local filing system, or by creating an entirely new file in a specified
directory. In the latter case, 'maildir' format can optionally be used to
give added protection against failures that happen part-way through the
delivery. Appendfile can also be used as a pseudo-remote transport for
putting messages into files for remote delivery by some means other than
Exim.

The appendfile transport is typically used for local deliveries to users'
mailboxes, and in this case messages are sent to it explicitly by directors
(or, exceptionally, routers). It is also normally used for delivering
messages to files or directories whose names are obtained directly from
alias, forwarding, or filtering operations.

As appendfile is a local transport, it is always run in a separate
process.  The current directory is normally set to the user's home
directory. See chapter 12 for a discussion of the local delivery
environment.

If the transport fails for any reason, the message remains on the input
queue so that there can be another delivery attempt later. If there is an
error while appending to the file (e.g. quota exceeded, partition filled),
Exim attempts to reset the file's length and last modification time back to
what they were before.

Before appending to the file, a number of security checks are made, and the
file is locked. A detailed description is given below, after the list of
private options.


14.1 Private options for appendfile

batch

    Type:    string
    Default: "none"

    Normally, each address that is directed or routed to an appendfile
    transport is handled separately. In special cases it may be desirable
    to handle several addresses at once, for example, when passing a
    message with several addresses to a different mail regime (e.g. UUCP),
    though this is more often done using the pipe transport. If this option
    is set to the string 'domain', then all addresses with the same domain
    that are directed or routed to the transport are handled in a single
    delivery. If it is set to 'all' then multiple domains are batched. The
    list of addresses is included in the Envelope-to header if
    envelope_to_add is set (see below). The only difference between this
    option and bsmtp is the inclusion of SMTP command lines in the output
    for bsmtp.

batch_max

    Type:    integer
    Default: 100

    This limits the number of addresses that can be handled in a batch, and
    applies to both the batch and the bsmtp options.

bsmtp

    Type:    string
    Default: "none"

    This option is used to set up an appendfile transport as a pseudo-
    remote transport for delivering messages into local files in batch SMTP
    format for onward transmission by some non-Exim means. The value of the
    option must be one of the strings 'none', 'one', 'domain', or 'all'.
    The first of these turns the feature off. A full description of the
    batch SMTP mechanism is given in section 42.3. When bstmp is set, the
    batch option automatically takes the same value.

bsmtp_helo                                                                   |
                                                                             |
    Type:    boolean                                                         |
    Default: false                                                           |
                                                                             |
    When this option is set, a HELO line is added to the output at the       |
    start of each message written in batch SMTP format. Some software that   |
    reads batch SMTP is unhappy without this.                                |

create_directory

    Type:    boolean
    Default: true

    See section 14.3 below.

create_file

    Type:    string
    Default: "anywhere"

    This option constrains the location of files that are created by this
    transport. It must be set to one of the words 'anywhere', 'inhome', or
    'belowhome'. In the second and third cases, a home directory must have
    been set up for the address by the director that handled it. This
    option isn't useful when an explicit file name is given for normal
    mailbox deliveries; it is intended for the case when file names have
    been generated from user's .forward files, which are usually handled by
    an appendfile transport called address_file. See also file_must_exist.

current_directory

    Type:    string
    Default: unset

    If this option is set, it specifies the directory to make current when
    running the delivery process. The string is expanded at the time the
    transport is run. See chapter 12 for details of the local delivery
    environment.

delivery_date_add

    Type:    boolean
    Default: true

    If this option is true, a Delivery-date header is added to the message.
    This gives the actual time the delivery was made. As this is not a
    standard header, Exim has a configuration option (delivery_date_remove)
    which requests its removal from incoming messages, so that delivered
    messages can safely be resent to other recipients.

directory

    Type:    string
    Default: unset

    This option is mutually exclusive with the file option. If directory is
    set, the string is expanded, and the message is delivered into a new
    file in the given directory (or if maildir_format is set, into a
    subdirectory thereof), instead of being appended to a single mailbox
    file. See section 14.3 for details of this form of delivery.

envelope_to_add

    Type:    boolean
    Default: true

    If this option is true, an Envelope-to header is added to the message.
    This gives the original address(es) in the incoming envelope that
    caused this delivery to happen. More than one address may be present if
    batch or bsmtp is set, or if more than one original address was aliased  |
    or forwarded to the same final address. As this is not a standard        |
    header, Exim has a configuration option (envelope_to_remove) which
    requests its removal from incoming messages, so that delivered messages
    can safely be resent to other recipients.

file

    Type:    string
    Default: unset

    This option need not be set when appendfile is being used to deliver to
    files whose names are obtained from forwarding, filtering, or aliasing
    address expansions (by default under the instance name address_file),
    as in those cases the file name is associated with the address.
    Otherwise, the file option must be set unless the directory option is
    set. Either use_fcntl_lock or use_lockfile (or both) must be set with
    file. If you are using more than one host to deliver over NFS into the
    same mailboxes, you should always use lock files.

    The string value is expanded for each delivery, and must yield an
    absolute path. If the expansion contains a reference to the local_part
    variable, this is checked to ensure that it does not contain a '/'
    character - to prevent an unexpected change of directory. The most
    common settings of this option are variations on one of these examples:

      file = /var/spool/mail/${local_part}
      file = /home/${local_part}/inbox
      file = ${home}/inbox

    In the first example, all deliveries are done into the same directory.
    If Exim is configured to use lock files (see use_lockfile below) it
    must be able to create a file in the directory, so the 'sticky' bit
    must be turned on for deliveries to be possible, or alternatively the    |
    group option can be used to run the delivery under a group id which has  |
    write access to the directory.                                           |

    If there is no file name, or the expansion fails, or a local part
    contains a '/' character, a delivery error occurs.

file_must_exist

    Type:    boolean
    Default: false

    If this option is true, the file specified by the file option must
    exist, and an error occurs if it does not. Otherwise, it is created if
    it does not exist.

from_hack

    Type:    boolean
    Default: true

    If this option is true, lines in the body of the message that start
    with the string 'From ' are modified by adding the character '>' at
    their start. This is necessary for traditional BSD-format mailboxes,
    where such lines might otherwise indicate the start of a new message.

lock_interval

    Type:    time
    Default: 3s

    This specifies the time to wait between attempts to lock the file. See
    below for details of locking.

lock_retries

    Type:    integer
    Default: 10

    This specifies the maximum number of attempts to lock the file. A value
    of zero is treated as 1. See below for details of locking.

lockfile_timeout

    Type:    time
    Default: 30m

    When a lock file is being used (see use_lockfile), if a lock file
    already exists and is older than this value, it is assumed to have been
    left behind by accident, and Exim attempts to remove it.

maildir_format

    Type:    boolean
    Default: false

    If this option is set with the directory option, then the delivery is
    into a new file in the 'maildir' format that is used by some other mail
    software. See section 14.3 below.

maildir_retries

    Type:    integer
    Default: 10

    This option specifies the number of times to retry when writing a file
    in 'maildir' format. See section 14.3 below.

notify_comsat

    Type:    boolean
    Default: false

    If this option is true, the comsat daemon is notified after every
    successful delivery to a user mailbox. This is the daemon that notifies
    logged on users about incoming mail.

prefix

    Type:    string
    Default: see below

    The string specified here is expanded and output at the start of every
    message. The default is

      prefix = "From ${if def:return_path{$return_path}{MAILER-DAEMON}}\
        ${tod_bsdinbox}\n"

quota

    Type:    string
    Default: unset

    This option imposes a limit on the size of the file to which Exim is
    appending. The value is expanded, and must then be a numerical value
    (decimal point allowed), optionally followed by one of the letters K or
    M. The expansion happens while Exim is running as root or the Exim
    user, before setuid() is called for the delivery, so files that are
    inaccessible to the end user can be used to hold quota values that are
    looked up in the expansion. When delivery fails because this quota is
    exceeded, the handling of the error is as for system quota failures.
    The value specified is not accurate to the last byte, owing to
    separator lines and additional headers that may get added during the
    delivery.

require_lockfile

    Type:    boolean
    Default: true

    When a lock file is being used (see use_lockfile) and require_lockfile
    is true, a lock file must be created before delivery can proceed. If
    the option is not true, failure to create a lock file is not treated as
    an error, though failure of the fcntl() locking function is. This
    option should always be set when delivering from more than one host
    over NFS. It is required to be set if the file option is set and
    use_fcntl_lock is not set.

retry_use_local_part

    Type:    boolean
    Default: true

    When a local delivery suffers a temporary failure, both the local part
    and the domain are normally used to form a key that is used to
    determine when next to try the address. This handles common cases such
    as exceeding a quota, where the failure applies to the specific local
    part. However, when local delivery is being used to collect messages
    for onward transmission by some other means, a temporary failure may
    not depend on the local part at all. Setting this option false causes
    Exim to use only the domain when handling retries for this transport.

return_path_add

    Type:    boolean
    Default: true

    If this option is true, a Return-path header is added to the message.
    Although the return path is normally available in the prefix line of
    BSD mailboxes, this is commonly not displayed by MUAs, and so the user
    does not have easy access to it.

    RFC 822 states that the Return-path header is 'added by the final
    transport system that delivers the message to its recipient' (section
    4.3.1), which implies that this header should not be present in
    incoming messages. Exim has a configuration option, return_path_remove,
    which requests removal of this header from incoming messages, so that
    delivered messages can safely be resent to other recipients.

suffix

    Type:    string
    Default: "\n"

    The string specified here is expanded and output at the end of every
    message.

use_fcntl_lock

    Type:    boolean
    Default: true

    This option controls the use of the fcntl() function to lock a file
    when a message is being appended. It should be turned off only if you
    know that all your MUAs use lock file locking. When use_fcntl_lock is
    off, use_lockfile and require_lockfile must both be on.

use_lockfile

    Type:    boolean
    Default: true

    If this option is turned off, Exim does not attempt to create a lock
    file when appending to a file. Thus the only locking is by fcntl(). It
    is not possible to turn both use_lockfile and use_fcntl_lock off. You
    should only turn use_lockfile off if you are absolutely sure that every
    MUA that is ever going to look at your users' mailboxes uses fcntl()
    rather than a lock file, and even then only when you are not delivering
    over NFS from more than one host. In order to append to an NFS file
    safely from more than one host, it is necessary to take out a lock
    before opening the file, and the lock file achieves this. Otherwise,
    even with fcntl() locking, there is a risk of file corruption. See also
    the require_lockfile option.

14.2 Operational details for appending

Before appending to a file, Exim proceeds as follows:

 .   If the name of the file is /dev/null, no action is taken, and a
     success return is given.

 .   If use_lockfile is set, a lock file is built in a way that will work
     reliably over NFS, as follows:

      .   Create a 'hitching post' file whose name is that of the lock file
          with the current time, primary host name, and process id added,
          by opening for writing as a new file. If this fails with an
          access error, the message is frozen unless require_lockfile is
          false. Otherwise delivery is deferred.

      .   Close the hitching post file, and rename it to the lock file
          name.

      .   If the call to rename() succeeds, creation of the lock file has
          succeeded.

      .   Otherwise, unlink the hitching post name.

      .   If creation of the lock file failed, wait for lock_interval and
          try again, up to lock_retries times. However, since any program
          that writes to a mailbox should complete its task very quickly,
          it is reasonable to time out old lock files that are normally the
          result of user agent and system crashes. If an existing lock file
          is older than lockfile_timeout Exim attempts to unlink it before
          trying again.

 .   If the file already exists but is not a regular file, 
     delivery is deferred, and the message is frozen.

 .   If the file did not exist originally, defer delivery and freeze the
     message if the file_must_exist option is set. Otherwise, check that
     the file is being created in a permitted directory if the create_file
     option is set (deferring and freezing on failure), and then open for
     writing as a new file, with the O_EXCL and O_CREAT options.

 .   If opening fails because the file exists, obey the tests given above
     for existing files. However, to avoid looping in a situation where the
     file is being continuously created and destroyed, the exists/not-
     exists loop is broken after 10 repetitions, and the message is then
     frozen.

 .   If opening fails with any other error, defer delivery.

 .   Once the file is open, it is locked using fcntl() if use_fcntl_lock is
     true. (Exim ensures that at least one type of locking is configured.)
     If this fails, the file is closed, Exim waits for lock_interval and
     then goes back and re-opens it as above and tries again to lock it
     with fcntl(). This happens up to lock_retries times, after which the
     delivery is deferred.

At the end of delivery, Exim closes the file (which releases the fcntl()
lock) and then deletes the lock file if one was created.


14.3 Operational details for delivery to a new file

When the directory option is set, each message is delivered into a newly-
created file. No locking is performed while writing the message, as each
delivery creates a new file, so the various locking options of the
transport are ignored. The 'From' line that by default separates messages
in a single file is not normally needed, nor is the escaping of message
lines that start with 'From', and there is no need to ensure a newline at
the end of each message. Consequently, the default settings in appendfile
need changing as follows:

    no_from_hack
    prefix=""
    suffix=""

There are two different ways in which delivery to a single file can be
done, depending on the setting of the maildir_format option.

For non-maildir delivery, new files are created directly in the named
directory. For example, when delivering messages into files using the bsmtp
option (see section 42.3) a setting such as

  directory = /var/bsmtp/${host}

might be used. A message is written to a file with a temporary name, which
is then renamed when the delivery is complete. The final name is construc-
ted from the time and the file's inode number, and starts with the letter
'q' for compatibility with smail.

If the create_directory option is set (the default), an attempt is made to
create the directory if it does not exist; if it is created then its mode
is given by the directory_mode option. If creation fails, or if the
create_directory option is not set, then the delivery is deferred.

If the maildir_format option is true, then Exim

(a)  ensures that subdirectories called tmp, new, and cur exist within the
     given directory, and

(b)  delivers each message by writing it to a file whose name is
     tmp/<time>.<pid>.<host> and then renaming it into the new directory if
     all goes well.

If the subdirectories (and indeed the main directory itself) do not exist,
Exim creates them with mode directory_mode if the create_directory option
is true. Otherwise it freezes the delivery.

Before opening the temporary file, Exim calls stat() on its name. If any
response other than ENOENT (does not exist) is given, it waits 2 seconds
and tries again, up to maildir_retries times.



                        15. THE AUTOREPLY TRANSPORT


The autoreply transport is not a true transport in that it does not cause
the message to be transmitted. Instead, it generates another mail message,
usually as the result of mail filtering. A traditional 'vacation' message
is the standard example.

Autoreply is implemented as a local transport so that it runs under the uid
and gid of the local user and with appropriate current and home directories
(see chapter 12). The parameters of the message to be sent can be specified
in the configuration by the options described below, but in the common case
when autoreply is activated as a result of filtering, none of them are
normally set, because all the information is obtained from the filter file.

In an attempt to reduce the possibility of message cascades, messages
created by the autoreply transport always take form of delivery error
messages. That is, the envelope sender field is empty.

There is a subtle difference between directing a message to a pipe
transport that generates some text to be returned to the sender, and
directing it to an autoreply transport. This difference is noticeable only
if more than one address from the same message is so handled. In the case
of a pipe, the separate outputs from the different addresses are gathered
up and returned to the sender in a single message, while if autoreply is
used, a separate message is generated for each address passed to it.

The private options of the autoreply transport that describe the message
are used only when the address passed to it does not contain any reply
information. Thus the message is specified entirely by the director or by
the transport; it is never built from a mixture of options. The remaining
private options (file_optional and return_message) apply in all cases.


15.1 Private options for autoreply

bcc

    Type:    string
    Default: unset

    Specifies the addresses that are to receive 'blind carbon copies' of
    the message when the message is specified by the transport. The string
    is expanded.

cc

    Type:    string
    Default: unset

    Specifies recipients of the message and the contents of the Cc header
    when the message is specified by the transport. The string is expanded.

file

    Type:    string
    Default: unset

    The contents of the file are sent as the body of the message when the
    message is specified by the transport. The string is expanded. If both
    file and text are set, the text string comes first.

file_expand

    Type:    boolean
    Default: false

    If this is set, the contents of the file named by the file option are
    subjected to string expansion as they are added to the message.

file_optional

    Type:    boolean
    Default: false

    If this option is true, no error is generated if the file named by the
    file option does not exist or cannot be read.

from

    Type:    string
    Default: unset

    The contents of the From header when the message is specified by the
    transport. The string is expanded.

headers

    Type:    string
    Default: unset

    Specified additional RFC 822 headers that are to be added to the
    message when the message is specified by the transport. The string is
    expanded. Several can be given by using \n to separate them. There is
    no check on the format.

log

    Type:    string
    Default: unset

    This option names a file in which a record of every message sent is
    logged when the message is specified by the transport. The string is
    expanded.

once

    Type:    string
    Default: unset

    This option names a DBM database in which a record of each recipient is
    kept when the message is specified by the transport. The string is
    expanded. If a potential recipient is already in the database, no
    message is sent.

return_message

    Type:    boolean
    Default: false

    If this is set, a copy of the original message is returned with the new
    message, subject to the maximum size set in the return_size_limit
    general configuration option.

subject

    Type:    string
    Default: unset

    The contents of the Subject header when the message is specified by the
    transport. The string is expanded.

text

    Type:    string
    Default: unset

    This specifies a single string to be used as the body of the message
    when the message is specified by the transport. The string is expanded.
    If both text and file are set, the text comes first.

to

    Type:    string
    Default: unset

    Specifies recipients of the message and the contents of the To header
    when the message is specified by the transport. The string is expanded.



                          16. THE DEBUG TRANSPORT


The debug transport is provided for debugging purposes only. It has no
options and is not normally referenced in a configuration file.

The debug transport is used when the configuration option debug_transport
is set. It gets called instead of the real transport for all deliveries,
both local and remote, so no real mail delivery takes place at all.
Instead, the debug transport appends information about the message and a
copy of the message itself to the file named by the debug_transport option.
No locking is used.

The file must be writeable by Exim at the time of delivery.


                           17. THE PIPE TRANSPORT


The pipe transport is used to deliver messages via a pipe to a command
running in another process. This can happen when an address is expanded via
an alias, filter, or forward file, or when a director explicitly directs
the message to a pipe transport. The pipe transport can also be used via a
router as a pseudo-remote transport for passing messages for remote
delivery by some means other than Exim.

As pipe is a local transport, it is always run in a separate process.
Current and 'home' directories are controllable. See chapter 12 for
details of the local delivery environment.


17.1 Returned status and data

If the command exits with a non-zero return code, the delivery is deemed to
have failed, unless either the ignore_status option is set (in which case
the return code is treated as zero), or the return code is EX_TEMPFAIL,
which is interpreted as meaning 'try again later'. Many Unix systems define
EX_TEMPFAIL in sysexits.h, and they all seem to use a value of 75. For
those systems that don't have EX_TEMPFAIL, Exim assumes that a value of 75
has this meaning.

The return_output option can affect the result of a pipe delivery. If it is
set and the command produces any output, it is considered to have failed,
even if it gave a zero return code or if ignore_status is set. The output
from the command is sent as part of the delivery failure report. However,
if return_fail_output is set, output is returned only when the command
exits with a failure return code, that is, a value other than zero or
EX_TEMPFAIL.


17.2 How the command is run

By default, the command line is broken down into a command name and
arguments by the pipe transport. The restrict_to_path option can be used to
restrict the commands that may be run. Unquoted arguments are delimited by
white space; in double-quoted arguments, backslash is interpreted an escape
character in the usual way. This does not happen for single-quoted
arguments.

String expansion is applied to the command line except when it comes from a
traditional .forward file (commands from a filter file are expanded). The
expansion is applied to each argument in turn rather than to the whole
line. Thus the number of arguments cannot be changed as a result of string
expansion, and quotes or backslashes in inserted variables do not interact
with external quoting.

Special handling takes place when an argument consists precisely of the
text '$pipe_addresses'. This is not a general expansion variable; the only
place this string is recognized is when it appears as an argument for a
pipe or transport filter command. It causes each address that is being
handled to be inserted in the argument list at that point as a separate
argument. This avoids any problems with spaces or shell metacharacters, and
is of use when a pipe transport is handling groups of addresses in a batch
(see the batch option below).

The resulting command is then run directly from the transport. It is not
run under a shell. This lessens the security risks in cases when a command
from a user's filter file is built out of data that was taken from an
incoming message.

If a shell is required, it can of course be explicitly specified as the
command to be run. However, there are circumstances where existing commands
(for example, in .forward files) expect to be run under a shell and cannot
easily be modified. To allow for these cases, there is an option called
use_shell, which changes the way the pipe transport works. Instead of
breaking up the command line as just described, it expands it as a single
string and passes the result to cmd.exe. The restrict_to_path option and
the $pipe_addresses facility cannot be used with use_shell, and the whole
mechanism is inherently less secure.


17.3 Environment variables

The following environment variables are set up when the command is invoked:

  DOMAIN               the local domain of the address
  HOME                 the 'home' directory - see below
  HOST                 the host name when called from a router
  LOCAL_PART           see below
  LOGNAME              see below
  MESSAGE_ID           the message's id
  PATH                 as specified by the path option below
  QUALIFY_DOMAIN       the configured qualification domain
  SENDER               the sender of the message
  SHELL                cmd.exe
  USER                 see below

When a pipe transport is called directly from (for example) a smartuser
director, then LOCAL_PART is set to the local part of the address. When it
is called as a result of a forward or alias expansion, LOCAL_PART is set to
the local part of the address that was expanded. LOGNAME and USER are set
to the same value as LOCAL_PART for compatibility with other MTAs.

HOST is set only when a pipe transport is called from a router as a pseudo-
remote transport (e.g. for handling batched SMTP). It is set to the first
host name specified by the router (if any).

If the transport's home_directory option is set, then its value is used for
the HOME environment variable. Otherwise, certain directors may set a home
directory value, as described in chapter 12.


17.4 Private options for pipe

batch

    Type:    string
    Default: "none"

    Normally, each address that is directed or routed to a pipe transport
    is handled separately. In special cases it may be desirable to handle
    several addresses at once, for example, when passing a message with
    several addresses to a different mail regime (e.g. UUCP). If this
    option is set to the string 'domain', then all addresses with the same
    domain that are directed or routed to the transport are handled in a
    single delivery. If it is set to 'all' then multiple domains are
    batched. The list of addresses is included in the Envelope-to header if
    envelope_to_add is set (see below). The addresses can also be set up as
    separate arguments to the pipe command by means of the specially-
    recognized argument $pipe_addresses (see above). Otherwise, the only
    difference between this option and bsmtp is the inclusion of SMTP
    command lines in the output for bsmtp.

batch_max

    Type:    integer
    Default: 100

    This limits the number of addresses that can be handled in a batch, and
    applies to both the batch and the bsmtp options.

bsmtp

    Type:    string
    Default: "none"

    This option is used to set up a pipe transport as a pseudo-remote
    transport for delivering messages in batch SMTP format for onward
    transmission by some non-Exim means. The value of the option must be
    one of the strings 'none', 'one', 'domain', or 'all'. The first of
    these turns the feature off. A full description of the batch SMTP
    mechanism is given in section 42.3. When bstmp is set, the batch option
    automatically takes the same value.

bsmtp_helo                                                                   |
                                                                             |
    Type:    boolean                                                         |
    Default: false                                                           |
                                                                             |
    When this option is set, a HELO line is added to the output at the       |
    start of each message written in batch SMTP format. Some software that   |
    reads batch SMTP is unhappy without this.                                |

command

    Type:    string
    Default: unset

    This option need not be set when pipe is being used to deliver to pipes
    obtained from address expansions (usually under the instance name
    address_pipe). In other cases, the option must be set, to provide a
    command to be run. It need not yield an absolute path (see the path
    option below). The command is split up into separate arguments by Exim,
    and each argument is separately expanded. Both single and double quotes
    are recognized. In double-quoted arguments, backslash is an escape
    character in the usual way. If a shell is required, it must be
    explicitly requested, as the command is not run under a shell by
    default.

current_directory

    Type:    string
    Default: unset

    If this option is set, it specifies the directory to make current when
    running the delivery process. The string is expanded at the time the
    transport is run. If this is not set, the current directory is taken
    from data associated with the address. See chapter 12 for full details
    of the local delivery environment.

delivery_date_add

    Type:    boolean
    Default: false

    If this option is true, a Delivery-date header is added to the message.
    This gives the actual time the delivery was made. As this is not a
    standard header, Exim has a configuration option (delivery_date_remove)
    which requests its removal from incoming messages, so that delivered
    messages can safely be resent to other recipients.

directory

    Type:    string
    Default: unset

    This option was made obsolete by the introduction of the separate
    options current_directory and home_directory. If encountered, it is
    treated as synonymous with home_directory.

envelope_to_add

    Type:    boolean
    Default: false

    If this option is true, an Envelope-to header is added to the message.
    This gives the original address(es) in the incoming envelope that
    caused this delivery to happen. More than one address may be present if
    batch or bsmtp is set, or if more than one original address was aliased  |
    or forwarded to the same final address. As this is not a standard        |
    header, Exim has a configuration option (envelope_to_remove) which
    requests its removal from incoming messages, so that delivered messages
    can safely be resent to other recipients.

from_hack

    Type:    boolean
    Default: false

    If this option is true, lines in the body of the message that start
    with the string 'From ' are modified by adding the character '>' at
    their start. This is necessary for traditional BSD-format mailboxes,
    where such lines might otherwise indicate the start of a new message.

home_directory

    Type:    string
    Default: unset

    If this option is set, its expanded value is used to set the HOME
    environment variable before running the command. This overrides any
    value that is set by the director. If no current directory is supplied
    by the director or the transport, the home directory value is used for
    that as well. See chapter 12 for details of the local delivery
    environment.

ignore_status

    Type:    boolean
    Default: false

    If this option is true, the status returned by the subprocess that is
    set up to run the command is ignored, and Exim behaves as if zero had
    been returned. Otherwise, a non-zero status causes an error return from
    the transport unless the value is EX_TEMPFAIL, which causes the
    delivery to be deferred and tried again later.

log_fail_output

    Type:    boolean
    Default: false

    If this option is set and the command returns any output and also ends
    with a return code that is neither zero nor EX_TEMPFAIL, the first line
    of output is written to the main log.

log_output

    Type:    boolean
    Default: false

    If this option is set and the command returns any output, the first
    line of output is written to the main log, whatever the return code.

max_output

    Type:    integer
    Default: 20K

    This specifies the maximum amount of output that the command may
    produce on its standard output. If the limit is exceeded, the process
    running the command is killed. This is intended as a safety measure to
    catch runaway processes. The limit is applied whether any return_output
    option is set or not. Because of buffering effects, the amount of
    output may exceed the limit by a small amount before Exim notices.

path

    Type:    string-list
    Default: "/usr/bin"

    This option specifies the string that is set up in the PATH environment
    variable of the subprocess. If the command option does not yield an
    absolute path name, the command is sought in the PATH directories, in
    the usual way.

prefix

    Type:    string
    Default: see below

    The string specified here is expanded and output at the start of every
    message. The default is the same as for the appendfile transport,
    namely

      prefix = "From ${if def:return_path{$return_path}{MAILER-DAEMON}}\
        ${tod_bsdinbox}\n"

    This is required by the commonly-used /usr/ucb/vacation program, but it  |
    must not be present if delivery is to the Cyrus IMAP server.             |

restrict_to_path

    Type:    boolean
    Default: false

    When this option is set, the command name must contain no slashes. The
    command is searched for only in the directories listed in the path
    option. This option is intended for use in the case when a pipe command
    has been generated from user's .forward file. This is usually handled
    by an pipe transport called address_pipe.

retry_use_local_part

    Type:    boolean
    Default: true

    When a local delivery suffers a temporary failure, both the local part
    and the domain are normally used to form a key that is used to
    determine when next to try the address. This handles common cases such
    as exceeding a quota, where the failure applies to the specific local
    part. However, when local delivery is being used to collect messages
    for onward transmission by some other means, a temporary failure may
    not depend on the local part at all. Setting this option false causes
    Exim to use only the domain when handling retries for this transport.

return_fail_output

    Type:    boolean
    Default: false

    If this option is true, and the command produced any standard output
    and ended with a return code other than zero or EX_TEMPFAIL, the output
    is returned in the delivery error message. However, if the message has
    a null sender (i.e. it is a delivery error message), output from the
    command is discarded.

return_output

    Type:    boolean
    Default: false

    If this option is true, and the command produced any standard output,
    the delivery is deemed to have failed whatever the return code from the
    command, and the output is returned in the delivery error message.
    Otherwise, the output is just discarded. However, if the message has a
    null sender (i.e. it is a delivery error message), output from the
    command is always discarded, whatever the setting of this option.

return_path_add

    Type:    boolean
    Default: false

    If this option is true, a Return-path header is added to the message.
    RFC 822 states that the Return-path header is 'added by the final
    transport system that delivers the message to its recipient' (section
    4.3.1), which implies that this header should not be present in
    incoming messages. Exim has a configuration option, return_path_remove,
    which requests removal of this header from incoming messages, so that
    delivered messages can safely be resent to other recipients.

suffix

    Type:    string
    Default: "\n"

    The string specified here is expanded and output at the end of every
    message. The default is the same as for the appendfile transport.

timeout

    Type:    time
    Default: 1h

    If the command fails to complete within this time, it is killed. This
    normally causes the delivery to fail.

use_shell

    Type:    boolean
    Default: false

    If this option is set, it causes the command to be passed to /bin/sh
    instead of being run directly from the transport as described in
    section 17.2. This is less secure, but is needed in some situations
    where the command is expected to be run under a shell and cannot easily
    be modified. The restrict_to_path option and '$pipe_addresses' facility  |
    are incompatible with use_shell. The command is expanded as a single     |
    string, and handed to cmd.exe as data for its /c option.


17.5 Using an external local delivery agent

The pipe transport can be used to pass all messages that require local
delivery to a separate local delivery agent such as procmail.

The following is an example transport and director configuration for
procmail:

  # transport
  procmail_pipe:
    driver = pipe
    command = "/opt/local/bin/procmail -d ${local_part}"
    from_hack

  # director
  procmail:
    driver = localuser
    transport = procmail_pipe


The next example shows a transport and a director for a system where local   |
deliveries are handled by the Cyrus IMAP server.                             |
                                                                             |
  # transport                                                                |
  local_delivery_cyrus:                                                      |
    driver = pipe                                                            |
    command = "/usr/cyrus/bin/deliver \                                      |
              -m ${substr_1:${$local_part_suffix}} -- ${local_part}"         |
    return_output                                                            |
    log_output                                                               |
    prefix =                                                                 |
    suffix=                                                                  |
                                                                             |
  # director                                                                 |
  local_user_cyrus:                                                          |
    driver = localuser                                                       |
    suffix = .*                                                              |
    transport = local_delivery_cyrus                                         |
                                                                             |
Note the unsetting of prefix and suffix, and the use of return_output to     |
cause any text written by Cyrus to be returned to the sender.                |



                           18. THE SMTP TRANSPORT


The smtp transport delivers messages over TCP/IP connections using the SMTP
protocol. The list of hosts to try can either be taken from the address
that is being processed, or specified explicitly for the transport. Timeout
and retry processing (see chapter 32) is applied to each IP address
independently. The private options are as follows:

allow_localhost                                                              |
                                                                             |
    Type:    boolean                                                         |
    Default: false                                                           |
                                                                             |
    When a host specified in hosts or fallback_hosts (see below) turns out   |
    to be the local host, Exim freezes the message by default. However, if   |
    allow_localhost is set, it goes on to do the delivery anyway. This       |
    should be used only in special cases when the configuration ensures      |
    that no looping will result (e.g. a differently configured Exim is       |
    listening on the SMTP port).                                             |

batch_max

    Type:    integer
    Default: 0

    This controls the maximum number of separate message deliveries that
    can take place over a single TCP/IP connection. If the value is zero,
    there is no limit.

    When a message has been successfully delivered over a TCP/IP connec-
    tion, Exim looks in its hints database to see if there are any other
    messages awaiting a connection to the same host. If there are, a new
    delivery process is started for one of them, and the current TCP/IP
    connection is passed on to it. The new process may in turn create yet
    another process. Each time this happens, a sequence counter is
    incremented, and if it ever gets to the (non-zero) batch_max value, no
    further messages are sent on the same TCP/IP connection.

    For testing purposes, this value can be overridden by the -oB command
    line option.

command_timeout

    Type:    time
    Default: 5m

    This sets a timeout for receiving a response to an SMTP command that
    has been sent out. It is also used when waiting for the initial banner
    line from the remote host. Its value must not be zero.

connect_timeout

    Type:    time
    Default: 0s

    This sets a timeout for the connect() function, which sets up a TCP/IP
    call to a remote host. A setting of zero allows the system timeout
    (typically several minutes) to act. To have any effect, the value of
    this option must be less than the system timeout.

data_timeout

    Type:    time
    Default: 5m

    This sets a timeout for the transmission of each block in the data
    portion of the message. As a result, the overall timeout for a message
    depends on the size of the message. Its value must not be zero.

delay_after_cutoff

    Type:    boolean
    Default: true

    This option controls what happens when all remote IP addresses for a
    given domain have been inaccessible for so long that they have passed
    their retry cutoff times.

    In the default state, if the next retry time has not been reached for
    any of them, the address is bounced without trying any deliveries. In
    other words, Exim delays retrying an IP address after the final cutoff
    time until a new retry time is reached, and can therefore bounce an
    address without ever trying a delivery, when machines have been down
    for a long time. Some people are unhappy at this prospect, so...

    If delay_after_cutoff is set false, Exim behaves differently. If all IP
    addresses are past their final cutoff time, then Exim tries to deliver
    to those IP addresses that have not been tried since the message
    arrived. If there are none, of if they all fail, the address is
    bounced. In other words, it does not delay when a new message arrives,
    but immediately tries those expired addresses that haven't been tried
    since the message arrived. If there is a continuous stream of messages
    for the dead hosts, unsetting delay_after_cutoff means that there will
    be many more attempts to deliver to them.

dns_qualify_single

    Type:    boolean
    Default: true

    If the hosts or fallback_hosts option is being used and names are being
    looked up in the DNS, then the option to cause the resolver to qualify
    single-component names with the local domain is set.

dns_search_parents                                                           |
                                                                             |
    Type:    boolean                                                         |
    Default: false                                                           |
                                                                             |
    If the hosts or fallback_hosts option is being used and names are being  |
    looked up in the DNS, then the resolver option to enable the searching   |
    of parent domains is set. Many resolvers default this option to be on,   |
    but its use in resolving mail addresses has caused problems in cases     |
    where wildcard MX records exist, so the default was changed to false in  |
    Exim version 1.80.                                                       |

fallback_hosts

    Type:    string-list
    Default: unset

    String expansion is not applied to this option. The argument must be a
    colon-separated list of host names or IP addresses. If all the hosts
    for a particular address are failing, then Exim tries to deliver to the
    fallback hosts, in order, unless the address was routed via MX records,
    and the current host was in the original MX list. In that situation,
    the fallback host list is not used.

    The resolution of the host names on the fallback list is controlled by
    the gethostbyname(), mx_domains and non_mx_domains options, as for the
    hosts option. Fallback hosts apply both to cases when the host list
    comes with the address and when it is taken from hosts. This option
    provides a 'use a smart host only if delivery fails' facility.

final_timeout

    Type:    time
    Default: 10m

    This is the timeout that applies while waiting for the response to the
    final line containing just '.' that terminates a message. Its value
    must not be zero.

gethostbyname

    Type:    boolean
    Default: false

    If this option is true when the hosts and/or fallback_hosts options are
    being used, names are looked up using gethostbyname() instead of using
    the DNS. Of course, gethostbyname() may in fact use the DNS, but it may
    also consult other sources of information such as /etc/hosts.

hosts

    Type:    string-list
    Default: unset

    Hosts are associated with an address by a router such as lookuphost,     |
    which finds the hosts by looking up the address domain in the DNS.       |
    However, addresses can be passed to the smtp transport by any router or  |
    director, not all of which provide an associated host list. This option  |
    specifies a list of host names and/or IP addresses which are used if     |
    the address being processed does not have any hosts associated with it.  |

    The string is first expanded, before being interpreted as a colon-
    separated host list. The names are looked up either in the DNS or using
    gethostbyname(), depending on the other options.

    This option is typically used in association with a smartuser director
    that wants to direct messages to a particular host or hosts. The given
    hosts are tried in order, subject to their retry status. This option is
    ignored when the address has been routed by a router that supplies a
    host list (e.g. lookuphost).

interface

    Type:    string
    Default: unset

    This option specifies which interface to use when making an SMTP call.
    The string must be an IP address, for example:

      interface = 123.123.123.123

    If interface is not set, the system's IP functions choose which
    interface to use if there is more than one.

max_rcpt

    Type:    integer
    Default: 100

    This option limits the number of RCPT TO commands that are sent in a
    single SMTP message transaction. Each set of addresses is treated
    independently, and so can cause parallel connections to the same host
    if remote_max_parallel permits this.

multi_domain

    Type:    boolean
    Default: true

    When this option is set, the smtp transport can handle a number of
    addresses containing a mixture of different domains provided they all
    resolve to the same list of hosts. Turning the option off restricts the
    transport to handling only one domain at once. This is useful if you
    want to use $domain in an expansion for the transport, because it is
    set only when there is a single domain involved in a remote delivery.

mx_domains

    Type:    domain-list
    Default: unset

    If the hosts or fallback_hosts options are being used and names are
    being looked up in the DNS, then if the host name is in this list but
    not in non_mx_domains, it is required to have an MX record.

non_mx_domains

    Type:    domain-list
    Default: unset

    See mx_domains above.

serialize_hosts

    Type:    host-list
    Default: unset

    Because Exim operates in a distributed manner, if several messages for
    the same host arrive at around the same time, more than one simulta-
    neous connection to the remote host can occur. This is not usually a
    problem except when there is a slow link between the hosts. In that
    situation it may be helpful to restrict Exim to one connection at a
    time. This can be done by setting serialize_hosts or serialize_nets to
    match the relevant hosts.

    Exim implements serialization by means of a hints database in which a
    record is written whenever a process connects to one of the restricted
    hosts, and deleted when the the connection is completed. Obviously
    there is scope for records to get left lying around if there is a
    system or program crash. To guard against this, Exim ignores any
    records that are more than 6 hours old.

    However, if you set up any serialization, you should also arrange to
    delete the hints database whenever your system reboots. The names of
    the files all start with serialize-<transport name> and they are kept
    in the spool/db directory. There may be one or two files, depending on
    the type of DBM in use.

serialize_nets

    Type:    net-list
    Default: unset

    See serialise_hosts above.

service

    Type:    string
    Default: "smtp"

    This option specifies the TCP/IP port that is used to send the message.
    If it begins with a digit it is taken as a port number; otherwise it is
    looked up using getservbyname().



            19. COMMON GENERIC OPTIONS FOR DIRECTORS AND ROUTERS


Directors and routers have sufficiently many generic options in common to    |
make it worth documenting them jointly in this chapter, to save dupli-       |
cation. Any of these options can be used on any director or router.          |
Subsequent chapters describe the generic options that are specific either    |
to directors or to routers.                                                  |

condition                                                                    |
                                                                             |
    Type:    string                                                          |
    Default: unset                                                           |
                                                                             |
    This option specifies a test that has to succeed for the driver to be    |
    called. The string is expanded, and if the result is a forced failure    |
    or an empty string or one of the strings '0' or 'no' or 'false'          |
    (checked without regard to the case of the letters), the driver is not   |
    run. This provides a means of applying special-purpose conditions to     |
    the running of directors and routers. The $home variable is available    |
    in the expansion for directors that set it up. If the expansion fails,   |
    it causes Exim to panic. Some of the other options below are common      |
    special cases that could in fact be specified using condition.           |

domains

    Type:    domain-list
    Default: unset

    If this option is set, the driver is skipped unless the current domain   |
    matches one of the entries in the list, and does not match               |
    except_domains. If the match is achieved by means of a file lookup,      |
    then the data that the lookup returned for the domain is placed in the   |
    $domain_data variable for use in string expansions of the driver's       |
    private options. For directors, this option is the means by which a      |
    host can handle several independent local domains. For routers, it can   |
    be used to reduce the use of an expensive router such as queryprogram    |
    by doing a preliminary plausibility check on the domain. Note that the   |
    current domain may change as routing proceeds, as a router may replace   |
    the original with a different one for subsequent routers to use.         |

driver

    Type:    string
    Default: unset

    This option must always be set. It specifies the name of the director
    or router driver.

except_domains

    Type:    domain-list
    Default: unset

    If this option is set, then the driver is skipped if the domain matches
    anything in the list. If both domains and except_domains are set, the
    driver is run only if the domain matches domains and does not match
    except_domains.

except_local_parts

    Type:    string-list
    Default: unset

    If this option is set, then the driver is skipped if the local part
    matches anything in the list, which is tested in the same way as a
    domain list, and which may therefore contain file lookups. If both
    local_parts and except_local_parts are set, the driver is run only if
    the local part matches local_parts and does not match
    except_local_parts.

except_senders

    Type:    address-list
    Default: unset

    See the senders option below.

fail_verify

    Type:    boolean
    Default: false

    Setting this option has the effect of setting both fail_verify_sender
    and fail_verify_recipient to the same value.

fail_verify_recipient

    Type:    boolean
    Default: false

    If this option is true and an address is accepted by this driver when
    verifying a recipient, then verification fails. This option has no
    effect if the verify_recipient option is false.

fail_verify_sender

    Type:    boolean
    Default: false

    If this option is true and an address is accepted by this driver when
    verifying a sender, then verification fails. This option has no effect
    if the verify_sender option is false.

local_parts

    Type:    string-list
    Default: unset

    If this option is set, the driver is run only if the local part of the
    address matches an item in the list, which is tested in the same way as
    a domain list and which may therefore include file lookups. If the       |
    match is achieved by a lookup, then the data that the lookup returned    |
    for the local part is placed in the variable $local_part_data for use    |
    in expansions of the driver's private options. You might use this        |
    option, for example, if you have a large number of local virtual
    domains, and you want to send all postmaster mail to the same place
    without having to set up an alias in each virtual domain:

      postmaster:
        local_parts = postmaster
        driver = smartuser
        new_address = postmaster@real.dom.ain

    If both local_parts and except_local_parts are set, the driver is run
    only if the local part matches local_parts and does not match
    except_local_parts.

more

    Type:    boolean
    Default: true

    If this option is false, then if the driver fails to handle an address,
    no further drivers are tried, and directing or routing fails. This
    applies even in the case of address verification where the driver was
    not run because the verify option was off.

require_files

    Type:    string-list
    Default: unset

    The value of this option is first expanded and then interpreted as a
    colon-separated list of strings. If the option is used on a localuser
    director, or on a forwardfile director that has either of the
    check_local_user or file_directory options set, then the expansion
    variable $home may appear in the list, referring to the home directory
    of the user whose name is that of the local part of the address.

    Except as described below, each string must be a fully qualified file
    path, optionally preceded by '!'. The paths are passed to the stat()
    function to test for the existence of the files or directories. The
    driver is skipped if any paths not preceded by '!' do not exist, or if
    any paths preceded by '!' do exist.

    For example:

      require_files = mail:/some/file
      require_files = ${local_part}:${home}/.procmailrc

    The second of those works because the require_files string is expanded
    before use.

    If stat() cannot determine whether a file exists or not, delivery of
    the message is deferred. This can happen when NFS-mounted filesystems
    are unavailable.

    Sometimes stat() yields the error EACCES ('Permission denied'). This
    means that the user is not permitted to read one of the directories on
    the file's path. The default action is to consider this a configuration
    error, and delivery is deferred because the existence or non-existence
    of the file cannot be determined. However, in some circumstances it may
    be desirable to treat this condition as if the file did not exist. If
    the file name (or the '!' that preceeds the file name for non-
    existence) is preceded by a '+' character, then the EACCES error is
    treated as if the file did not exist. For example:

      require_files = +/some/file

    This option provides a general mechanism for predicating the running of
    a director or router on the existence or non-existence of certain files
    or directories. A failure to expand the string, or the presence of a
    non-fully-qualified path within it causes a panic error.

senders

    Type:    address-list
    Default: unset

    The values of this option and except_senders are expanded, and the
    results of the expansions must be colon-separated address lists, in the
    same format as used for general options like sender_reject. The driver
    is run only if the sender address matches something in the senders
    list, if set, and does not match anything in except_senders, if set.
    Using this option on a director makes it possible to implement closed
    mailing lists (see chapter 36).

    There are issues concerning verification when the running of directors
    or routers is dependent on the sender. When Exim is verifying an
    errors_to setting in either forwardfile or aliasfile, it sets the
    sender to the null string. If using the -bt option to check a
    configuration file, it is necessary also to use the -f option to set an
    appropriate sender. For incoming mail, the sender is unset when
    verifying the sender, but is available when verifying any recipients.
    If the SMTP VRFY command is enabled, it must be used after MAIL FROM if
    the sender address matters.

transport

    Type:    string
    Default: unset

    Some drivers require a transport to be supplied, some require that a
    transport not be supplied, and for some it is optional. The string must
    be the name of a configured transport instance, or expandable an         |
    string, thus allowing transports to be dynamically selected. The string  |
    is expanded at directing or routing time, and must yield the name of an  |
    available transport, even if the driver isn't going to match the         |
    address. If it does not, a panic crash occurs. This isn't as safe as     |
    fixed transports, whose existence is checked at initialization time.     |
    See also chapter 20.                                                     |

unseen

    Type:    boolean
    Default: false

    Setting this option has a similar effect to the unseen command
    qualifier in filter files. It causes an address to be passed on to
    subsequent drivers, even if the current one succeeds in handling it,
    and can be used to cause copies of messages to be delivered elsewhere.

verify

    Type:    boolean
    Default: true

    Setting this option has the effect of setting verify_sender and
    verify_recipient to the same value.

verify_only

    Type:    boolean
    Default: false

    If this option is set, the driver is used only when verifying an
    address, not when actually doing a delivery. It can be further
    restricted to verifying only senders or recipients by means of
    verify_sender and verify_recipient.

verify_recipient

    Type:    boolean
    Default: true

    If this option is false, then this driver is skipped when verifying
    recipient addresses. It is usual to set it false for instances of the
    smartuser director.

verify_sender

    Type:    boolean
    Default: true

    If this option is false, then this driver is skipped when verifying
    sender addresses. It is usual to set it false for instances of the
    smartuser director.


                           20. DEFAULT TRANSPORTS


When a director or a router knows what to do with a particular address, it
can send a copy of the message for that address to a named transport. Take,
for example, ordinary local delivery. A transport to handle this could be:

  local_delivery:
    driver = appendfile
    file = ${home}/inbox

This is referenced by a director that recognizes the local part of an
address as the name of a local user:

  localuser:
    driver = localuser
    transport = local_delivery

However, there are some transports that are not directly referenced from
directors or routers in this way. The need for them arises because aliasing
or forwarding operations may be permitted by the configuration to generate
destinations such as file names and pipe commands which are not mail
addresses. There is no further directing or routing required for these -
they simply have to be associated with an appropriate transport. The         |
directors that set up such deliveries have private options for specifying    |
which transports to use for these special cases, but if these are not set,   |
the association is done by using conventional names for the transports, as
follows:

 .   address_reply: A transport with this name is used when a user's filter
     file generates a message using the mail or vacation commands.

 .   address_directory: A transport with this name is used when a desti-
     nation that is a path name ending with a '/' character is encountered.

 .   address_directory2: A transport with this name is used when a desti-
     nation that is a path name ending with '//' is encountered. If such a
     transport does not exist, one with the name address_directory is used
     instead.

 .   address_file: A transport with this name is used when a destination
     that is a path name not ending with a '/' character is encountered.

 .   address_pipe: A transport with this name is used when a destination
     that is a pipe command is encountered.

Examples of these default transports can be seen in the default configur-
ation file. The names used can in fact be changed by means of general
configuration options with names address_file_transport etc.



                21. ADDITIONAL GENERIC OPTIONS FOR DIRECTORS


The following additional generic options apply to all directors, in          |
addition to the common generic options for both directors and routers which  |
are described in chapter 19. Directors are concerned with addresses whose    |
domains match something in local_domains, or which have been explicitly      |
determined to be local by a router.                                          |

expn

    Type:    boolean
    Default: true

    If this option is turned off, the director is skipped when verifying an
    address as a result of processing an SMTP EXPN command. You might, for
    example, want to turn it off on a director for users' .forward files,
    while leaving it on for the system alias file. The use of the SMTP EXPN
    command is permitted only from hosts that match the smtp_expn_hosts or
    smtp_expn_nets general options.

new_director

    Type:    string
    Default: unset

    Sometimes an administrator knows that it is pointless to reprocess
    addresses generated from alias or forward files with the same director
    again. For example, if an alias file translates real names into login
    ids there is no point searching the alias file again, especially if it
    is a large file.

    The new_director option can be set to the name of any director
    instance. It causes the directing of any generated local addresses to
    start at the named director instead of the first director. The named
    director can be any configured director. This option has no effect if
    the director in which it is set does not generate new addresses, or if
    such addresses are not in local domains.

prefix

    Type:    string-list
    Default: unset

    If this option is set, the director is skipped unless the local part
    starts with one of the given strings, or the prefix_optional option is
    true. A limited form of wildcard is available; if the prefix begins
    with an asterisk, it matches the longest possible sequence of arbitrary
    characters at the start of the local part. An asterisk should therefore
    always be followed by some character that does not occur in normal
    local parts. Wildcarding can be used to set up multiple user mailboxes,
    as described in chapter 35.

    While the director is running, the prefix is removed from the local
    part, and is available in the expansion variable local_part_prefix. If
    the director succeeds, this remains true during subsequent delivery.

    The prefix facility is commonly used to handle local parts of the form
    owner-something. Another common use is to support local parts of the
    form real-username to bypass a user's .forward file - helpful when
    trying to tell a user their forwarding is broken - by placing a
    director like this one immediately before the director that handles
    .forward files:

      real_localuser:
        driver = localuser
        transport = local_delivery
        prefix = real-

    If both prefix and suffix are set for a director, both conditions must
    be met if not optional. Care must be taken if wildcards are used in
    both a prefix and a suffix on the same director. Different separator
    characters must be used to avoid ambiguity.

prefix_optional

    Type:    boolean
    Default: false

    See prefix above.

suffix

    Type:    string-list
    Default: unset

    This option operates in the same way as prefix, except that the local
    part must end (rather than start) with the given string, the
    suffix_optional option determines whether the suffix is mandatory, and
    the wildcard * character, if present, must be the last character of the
    suffix. This option facility is commonly used to handle local parts of
    the form something-request and multiple user mailboxes of the form
    username-foo.

suffix_optional

    Type:    boolean
    Default: false

    See suffix above.


21.1 Skipping directors

The new_director generic option causes the directing of a generated local
address to start at a particular director, thus skipping those above it. A
number of other generic options can cause directors to be skipped for
particular cases. They interact with each other in the following way:

If the domain and local part are not in agreement with domains,
except_domains, local_parts, and except_local_parts (when set), or if the    |
condition option fails, or if verify_only is set and verification is not     |
happening, then the director is skipped and the next one is tried. None of
the other options is inspected.

Otherwise, if the more option is not set, no subsequent directors are ever
called, in any circumstances. The current director is itself called unless

 .   Verification is happening and its verify_sender or verify_recipient
     option (as appropriate) is turned off, or

 .   An SMTP EXPN command is being processed and its expn option is turned
     off, or

 .   There is a prefix or suffix mismatch, or

 .   The existence or non-existence of files listed in the require_files
     option is not as expected, or

 .   The sender of the message is not in agreement with senders and
     except_senders. This test is done after checking for file existence so
     that sender lists can contain references to files whose existence is
     tested.

The unseen option causes directing to continue when it would otherwise
cease, the complementary action to no_more, which causes it to cease when
it would otherwise continue.

The verify, fail_verify, and verify_only options make it possible to
separate those local parts which correspond to a real local delivery from
those which are recognized, but which do something else if actually
encountered in a message.

For example, a smartuser director might be used to pass all unrecognized
local parts to a script that tries to generate a helpful error message, or
to a different machine that might be able to handle them. This means that
no local part will ever cause a delivery failure. However, if (for example)
verification of senders is taking place (the sender_verify main configur-
ation option), you probably don't want <random-local-part@your.domain> to
be accepted. The solution is to set no_verify or no_verify_sender on the
smartuser director.

On our systems in Cambridge we keep a list of users whose accounts have
been cancelled, and their mail is piped to a script which sends back a more
helpful message than 'user unknown'. Verification of such local parts
should fail, but just setting no_verify on the director doesn't work,
because the local part is then passed to a localuser director that may
still find it in the password file. (Initially, cancellation just resets
the password.) This is the sort of case for which fail_verify was invented.
It makes it possible to fail an explicit list of local parts.



                         22. THE ALIASFILE DIRECTOR


The aliasfile director expands local parts by consulting a file of aliases.
The expansion may safely contain the same local part, because a director is
automatically skipped if any ancestor of a local part has the same name and
was processed by that director.

The alias file can be a text file that is searched linearly, or it may
be a DBM direct-access database. The case of letters is not
significant in searches. The exim_dbmbuild utility can be used to
convert a text file into a DBM database; the keys are lower-cased by
this process.


22.1 Alias file format

A textual alias file to be searched linearly consists of entries that start
with the alias name, terminated by a colon. The remainder of the entry
consists of a list of addresses, file names, or pipe commands, which can be
continued onto several lines by starting each of the continuation lines
with white space. The addresses are separated by commas or newlines.

By default, alias names are simple local parts such as 'postmaster', but if
the include_domain option is set, they must contain both a local part and a
domain, thus allowing aliases for more than one domain to be held in a
single file.

Lines starting with a # character are comments, and are ignored, and # may   |
also appear following a comma, in which case everything between # and the    |
end of the line is ignored.                                                  |

Other forms of alias file (DBM) involve lookups using the local part
as a key on files and databases that return a list of address, file,
or pipe items separated by commas or newlines.


22.2 Types of alias item

If an item is entirely enclosed in double quotes, these are removed, but
otherwise double quotes are retained, because some forms of mail address
require the use of quotes.

If an item begins with '\' and the rest of the item parses as a valid RFC
822 address that does not include a domain, the backslash is simply
ignored. It is not, however, necessary to include '\' in aliases to prevent
directing loops, because Exim has its own methods of loop detection.

An item is treated as a pipe command if it begins with '|' and does not
parse as a valid RFC 822 address that include a domain. Both single and
double quotes can be used for enclosing arguments to the pipe command; no
interpretation of escapes is done for single quotes.

An item is interpreted as a path name if it begins with '/' and does not
parse as a valid RFC 822 address that includes a domain. For example,

  /home/world/minbari

is treated as a file name, but

  /s=molari/o=babylon/@x400gate.way

is treated as an address. If a generated path name ends with a '/'
character, it is interpreted as a directory name rather than a file name.
See chapter 20 for a discussion of the handling of pipe and file items.

An item of the form

  :include:<path name>

may also appear, in which case a list of further items is taken from the
given file and included at that point. These items are not subject to
expansion when the expand option is set.

Sometimes you want to throw away mail to a particular local part. An alias
entry with no addresses causes Exim to generate an error, so this cannot be
used. However, another special item that may appear in an alias file is

  :blackhole:

which does what its name implies. The delivery for the current address is
abandoned without further ado, and no error message is generated. This is
more efficient than directing a message to /dev/null as it happens at
directing time.

                                                                             |
22.3 Duplicate addresses                                                     |
                                                                             |
Exim removes duplicate addresses from the list to which it is delivering,    |
so as to deliver just one copy to each address. This does not apply to       |
deliveries directed at pipes by different immediate parent addresses, but    |
an indirect aliasing scheme of the type                                      |
                                                                             |
  pipe:       |/some/command ${local_part}                                   |
  localpart1: pipe                                                           |
  localpart2: pipe                                                           |
                                                                             |
does not work with a message that is addressed to both local parts, because  |
when the second is aliased to the intermediate local part 'pipe' it gets     |
discarded as being the same as a previously handled address. However, a      |
scheme such as                                                               |
                                                                             |
  localpart1: |/some/command ${local_part}                                   |
  localpart2: |/some/command ${local_part}                                   |
                                                                             |
does result in two different pipe deliveries, because the immediate parents  |
of the pipes are distinct.                                                   |


22.4 Errors in alias files

If skip_syntax_errors is set, a malformed address that causes a parsing
error is skipped, and an entry is written in the main log. This may be
useful for mailing lists that are automatically managed, but note the
inherent danger. Otherwise, if an error is detected while generating the
list of new addresses, the message is frozen, except for the special case
of inability to open an included file, when no_freeze_missing_include is
set. In this case, delivery is simply deferred.


22.5 Specifying a transport

If a transport is specified for this director, then the message is directed
to that transport for any local part which is found in the file, any data
in the file that is associated with the local part being ignored. Thus the
same processing can be done for any local part that is listed in the file.
For example, a file containing a list of cancelled users can be used to
direct messages addressed to them to a particular script.


22.6 Aliasfile private options


current_directory

    Type:    string
    Default: unset

    This option associates a current directory with any address that
    aliasfile directs to a local transport. This can happen either because
    a transport is explicitly configured for the director, or because it
    generates a delivery to a file or a pipe. The option string is expanded
    and is set as the current directory during the delivery process, unless
    overridden by a setting on the transport. See chapter 12 for details of
    the local delivery environment.

directory

    Type:    string
    Default: unset

    This option is obsolete, having been replaced by current_directory and
    home_directory. If used, it sets the value of home_directory.

directory_transport                                                          |
                                                                             |
    Type:    string                                                          |
    Default: unset                                                           |
                                                                             |
    An aliasfile director sets up a direct delivery to a directory when a    |
    path name ending with a slash is specified as a new 'address' (see       |
    chapter 20). The transport used is taken from the global option          |
    address_directory, unless this option is set to override it. The string  |
    must be the name of a configured transport.                              |
                                                                             |
directory2_transport                                                         |
                                                                             |
    Type:    string                                                          |
    Default: unset                                                           |
                                                                             |
    An aliasfile director sets up a direct delivery to a directory when a    |
    path name ending with two slashes is specified as a new 'address' (see   |
    chapter 20). The transport used is taken from the global option          |
    address_directory2, unless this option is set to override it. The        |
    string must be the name of a configured transport.                       |

errors_to

    Type:    string
    Default: unset

    Delivery errors for any addresses generated by this director are sent
    to the address that results from expanding this string, if it is set
    and if it verifies as valid. Otherwise the address associated with the
    incoming address (normally the sender) is used. A typical use might be

      errors_to = "aliasmaster"

    See also syntax_errors_to.

expand

    Type:    boolean
    Default: false

    If this option is set true, then the text obtained by looking up the
    local part is passed through the string expansion mechanism before
    being interpreted as a list of alias items. Addresses that are
    subsequently added by means of the 'include' mechanism are not
    expanded.

file

    Type:    string
    Default: unset

    This option specifies the name of the alias file, and it must be set if
    search_type specifies a single-key lookup; if it does not, an error
    occurs. (For query-style lookups, query must be set instead.) See
    chapter 6 for details of different lookup styles. The string is
    expanded before use; if expansion fails, Exim panics. The resulting
    string must be an absolute path for linear search and DBM lookups. If
    the original string does not start with '/' or '$' in these cases, Exim
    gives a configuration error when it starts up; otherwise, if an
    expanded string does not begin with '/' delivery is frozen.

file_transport                                                               |
                                                                             |
    Type:    string                                                          |
    Default: unset                                                           |
                                                                             |
    An aliasfile director sets up a direct delivery to a file when a path    |
    name not ending in a slash is specified as a new 'address' (see chapter  |
    20). The transport used is taken from the global option address_file,    |
    unless this option is set to override it. The string must be the name    |
    of a configured transport.                                               |

forbid_file

    Type:    boolean
    Default: false

    If this option is true, then this director may not generate a new
    address which specifies delivery to a local file or directory. If it
    attempts to do so, a delivery failure occurs.

forbid_pipe

    Type:    boolean
    Default: false

    If this option is true, then this director may not generate a new
    address which specifies delivery to a pipe. If it attempts to do so, a
    delivery failure occurs.

freeze_missing_include

    Type:    boolean
    Default: true

    If a file named by the 'include' mechanism fails to open, delivery is
    frozen if this option is true. Otherwise, delivery is just deferred.
    Unsetting this option can be useful if included files are NFS mounted
    and may not always be available.

home_directory

    Type:    string
    Default: unset

    This option associates a home directory with any address that aliasfile
    directs to a local transport. This can happen either because a
    transport is explicitly configured for the director, or because it
    generates a delivery to a file or a pipe. The option string is expanded
    and is set as the home directory during the delivery process, unless
    overridden by a setting on the transport. See chapter 12 for details of
    the local delivery environment.

include_domain

    Type:    boolean
    Default: false

    Setting this option true causes the key that is looked up to be 'local-
    part@domain' instead of just 'local-part'. Thus a single file can be
    used to hold aliases for many local domains. This option has no effect
    if the search type specifies a query-style lookup.

optional

    Type:    boolean
    Default: false

    If the file cannot be opened because it does not exist (the ENOENT
    error) and this option is set, the director simply fails to match the
    address. Otherwise any failure to open the file causes an entry to be
    written to the log and delivery to be deferred.

pipe_transport                                                               |
                                                                             |
    Type:    string                                                          |
    Default: unset                                                           |
                                                                             |
    An aliasfile director sets up a direct delivery to a pipe when a string  |
    starting with a vertical bar character is specified as a new 'address'   |
    (see chapter 20). The transport used is taken from the global option     |
    address_pipe, unless this option is set to override it. The string must  |
    be the name of a configured transport.                                   |

query

    Not implemented under OS/2.

rewrite

    Type:    boolean
    Default: true

    If this option is set false, addresses generated by the director are
    not subject to address rewriting. Otherwise, they are treated like new
    addresses.

search_type

    Type:    string
    Default: unset

    This option must be set to one of the strings 'lsearch' or 'dbm',
    specifying the type of data lookup. For these search types, file
    is required and query must not be set. See chapter 6 for details
    of the different lookup styles.

    Single-key search types for aliasfile can be preceded by partial-        |
    and/or followed by *. The former isn't likely to be useful very often,   |
    but the latter provides a default facility. Note, however, that if two   |
    addresses in the same message provoke the use of the default, only one   |
    copy gets delivered, but any added Envelope-to header contains all the   |
    original addresses.                                                      |

skip_syntax_errors

    Type:    boolean
    Default: false

    If skip_syntax_errors is set, a malformed address that causes a parsing
    error is skipped, and an entry is written in the main log. This may be
    useful for mailing lists that are automatically managed, but note the
    inherent danger.

syntax_errors_to

    Type:    string
    Default: unset

    This option applies only when skip_syntax_errors is set. If any
    addresses are skipped because of syntax errors, a mail message is sent
    to the address specified by syntax_errors_to, giving details of the
    failing address(es). Often it will be appropriate to set
    syntax_errors_to to be the same address as errors_to.



                        23. THE FORWARDFILE DIRECTOR


The forwardfile director can be used for two different but related
operations. Its effect is to replace a local part with a list of addresses,
file names, or pipe commands, taken from a single file. It gets its name
from the common case where the file is in a user's home directory and is
called .forward, but another common use is for expanding mailing lists,
which are discussed in more detail in chapter 36. A transport must not be
specified for this director. A configuration error occurs if one is given.

When handling a user's .forward file, a home directory is normally set
to that of the user. However, these may alternatively be specified by
options to the director.


23.1 Forward file items

The contents of the file are a list of addresses, file names, or pipe
commands, separated by commas or newlines. Items that are empty are
ignored. This includes items consisting solely of RFC 821 address comments.
If an item is entirely enclosed in double quotes, these are removed, but
otherwise double quotes are retained, because some forms of mail address
require the use of quotes.

An item may safely be the same local part as the one currently under
consideration, because a director is automatically skipped if any ancestor
has the same local part and was processed by that director. Thus a user
with login name spqr who wants to preserve a copy of mail and also forward
it somewhere else can set up a file such as

  spqr, spqr@reme.xx

without provoking a loop. A backslash before an unqualified local part is
permitted for compatibility with other mailers, but causes an error if it
appears before a qualified address. Care must be taken if there are alias
names for local users. For example if the system alias file contains

  Sam.Reman: spqr

then

  Sam.Reman, spqr@reme.xx

in spqr's forward file fails on an imcoming message addressed to Sam.Reman,
because the aliasfile director does not process Sam.Reman the second time
round.

An item is interpreted as a file name if it begins with '/' and does not
parse as a valid RFC 822 address that includes a domain. For example,

  /home/world/shadow

is treated as a file name, but

  /s=molari/o=babylon/@x400gate.way

is treated as an address.

An item is treated as a pipe command if it begins with '|' and does not
parse as a valid RFC 822 address that include a domain. Both single and
double quotes can be used for enclosing arguments to the pipe command; no
interpretation of escapes is done for single quotes.

Lines starting with a # character are comments, and are ignored, and # may
also appear following a comma, in which case everything between # and the    |
end of the line is ignored. If the file is empty, or contains only blank
lines and comments, the director behaves as if it did not exist.

If a message is addressed to two different local parts, each of which
results in an expansion that generates an identical file name or pipe
command, two different deliveries occur, though of course the delivery
processes run with different values in the LOCAL_PART environment variable,
and with different uids (in the common case).

Instead of an address, file name, or pipe command, an item of the form

  :include:<path name>

may appear, in which case an list of addresses is taken from the given file
and included at that point, unless the forbid_include option is set.


23.2 Errors in forward files

If skip_syntax_errors is set, a malformed address that causes a parsing
error is skipped, and an entry is written in the main log. This may be
useful for mailing lists that are automatically managed, but note the
inherent danger. The option should never be set for users' .forward files.
Otherwise, if any error is detected while generating the list of new
addresses, the message is frozen, except for the special case of inability
to open an included file when no_freeze_missing_include is set. In this
case, delivery is simply deferred.


23.3 Filter files

As an alternative to treating the file as a simple list of addresses, the
forwardfile director can be configured, by means of the filter option, to
read a file and interpret it as a list of "filtering" instructions if it
conforms to a specific format. The instructions can specify various actions
such as appending the message to certain mail folders, or forwarding it to
other users, predicated on the content of the message. Details of the
syntax and semantics of filter files are described in a separate document
entitled "Exim's User interface to mail filtering"; this is intended for
use by end users.


23.4 The home directory

The home expansion variable can be used in a number of local options for
forwardfile. Its value depends on the way the options are set up, as
follows:

 .   If check_local_user is set without file_directory, then the user's
     home directory is set in the home expansion variable when expanding
     the file option that specifies a forward or filter file.

 .   If file_directory is set without check_local_user, then the expanded
     value of file_directory is set in the home expansion variable when
     expanding the file option. If home appears in the string for
     file_directory, its substitution value is the empty string.

 .   If both check_local_user and file_directory are set, home in the
     string for file_directory is the user's home directory, but home in
     the file option is the expanded value of file_directory.

It is thus possible to specify

  file = ${home}/.forward

to look up .forward files without first statting the home directory to see
if it exists. This is not recommended if home directories are NFS mounted.

If the generic option require_files contains home, it takes the same value
as it does when expanding the file option, and this value is also used for
home if encountered in a filter file.


23.5 Forwardfile private options


check_ancestor

    Type:    boolean
    Default: false

    Although this option is off by default in the code, it is set in the
    default configuration file for handling users' .forward files. It is
    recommended for this use of the forwardfile director. When set, if a
    generated address is the same as any ancestor of the current address,
    then it is not used, but instead the current address gets passed on to
    subsequent directors. This helps in the case where local part A is
    aliased to B, and B has a .forward file pointing back to A, for
    example: 'Joe.Bloggs' is aliased to 'jb' and ~jb/.forward contains:

      \Joe.Bloggs, some.other.address

    Without the check_ancestor setting, either local part ('jb' or
    'joe.bloggs') gets processed once by each director and so ends up as it
    was originally. If 'jb' is the real mailbox name, then mail to 'jb'
    gets delivered (having been turned into 'joe.bloggs' by the .forward
    file and back to 'jb' by the alias), while mail to 'joe.bloggs' fails.
    Setting check_ancestor on the forwardfile director prevents it from
    turning 'jb' back into 'joe.bloggs' when that was the original address.

check_local_user

    Type:    boolean
    Default: true

    If this option is true, then the local part that is passed to this
    director is checked to ensure that it is the login of a local
    user. The director fails to handle the address if it is not. In
    addition, when this option is true, the string specified for the
    file option is taken as relative to the user's home directory if
    it is not an absolute path, unless the file_directory option is set.

current_directory

    Type:    string
    Default: unset

    This option associates a current directory with any address that
    forwardfile directs to a local transport because it specifies a file
    name or pipe command. The option string is expanded and is set as the
    current directory during the delivery process, unless overridden by a
    setting on the transport. See chapter 12 for details of the local
    delivery environment.

directory

    Type:    string
    Default: unset

    This is an obsolete name for the file_directory option.

directory_transport                                                          |
                                                                             |
    Type:    string                                                          |
    Default: unset                                                           |
                                                                             |
    A forwardfile director sets up a direct delivery to a directory when a   |
    path name ending with a slash is specified as a new 'address' (see       |
    chapter 20). The transport used is taken from the global option          |
    address_directory, unless this option is set to override it. The string  |
    must be the name of a configured transport.                              |
                                                                             |
directory2_transport                                                         |
                                                                             |
    Type:    string                                                          |
    Default: unset                                                           |
                                                                             |
    A forwardfile director sets up a direct delivery to a directory when a   |
    path name ending with two slashes is specified as a new 'address' (see   |
    chapter 20). The transport used is taken from the global option          |
    address_directory2, unless this option is set to override it. The        |
    string must be the name of a configured transport.                       |

errors_to

    Type:    string
    Default: unset

    Delivery errors for any addresses generated by this director are sent
    to the address that results from expanding this string, if it is set
    and if it verifies as valid. Otherwise the address associated with the
    incoming address (normally the sender) are used. See also
    syntax_errors_to.

file

    Type:    string
    Default: unset

    This option must be set. The string is expanded before use - see above
    for a discussion of the home expansion variable. If expansion fails,
    Exim panics. The expanded string must start with a '/' character unless
    check_local_user is true, or a file_directory option is set. A non-
    absolute path is interpreted relative to the file_directory setting if
    it exists; otherwise it is interpreted relative to the user's home
    directory.

    If a non-absolute path is used, Exim uses the stat() function to check
    the directory before attempting to open the file therein. If the
    directory is inacessible, the delivery to the current address is
    deferred. This distinguishes between the cases of a non-existent file
    (where the director cannot handle the address) and an unmounted NFS
    directory (where delivery should be deferred). Thus the difference
    between the two settings

      file = .forward
      file = $home/.forward

    is that in the second case the directory is not checked with stat().

    If the file exists but is empty or contains only blank and comment
    lines starting with #, Exim behaves as if it did not exist, and the
    director fails to handle the address. Note that this is not the case
    when the file contains syntactically valid items that happen to yield
    empty addresses, for example, items containing only RFC 822 address
    comments.

file_directory

    Type:    string
    Default: unset

    The string is expanded before use - see above for a discussion of the
    home expansion variable. The option sets a directory path which is used
    if the file option does not specify an absolute path. This on its own
    is not very useful, since the directory string could just as well be
    prepended to the file string. However, if a separate directory is
    given, it is treated like a directory obtained from check_local_user,
    and its existence is tested before trying to open the file. If the
    directory appears not to exist, delivery is deferred. Thus, a setting
    such as

      directory = /usr/forwards
      file = ${local_part}.forward

    defers delivery if /usr/forwards appears not to exist. This can be
    useful if the directory is NFS mounted. If check_local_user is also
    set, file_directory takes precedence in determining the directory name
    for non-absolute files.

    If forwardfile sets up a delivery to a file or a pipe command and the
    home_directory option is not set, then the directory specified by
    file_directory, or if that is not set, the home directory obtained from
    check_local_user is associated with the address during delivery.

file_transport                                                               |
                                                                             |
    Type:    string                                                          |
    Default: unset                                                           |
                                                                             |
    A forwardfile director sets up a direct delivery to a file when a path   |
    name not ending in a slash is specified as a new 'address' (see chapter  |
    20). The transport used is taken from the global option address_file,    |
    unless this option is set to override it. The string must be the name    |
    of a configured transport.                                               |

filter

    Type:    boolean
    Default: false

    If this option is set, and the forwarding file starts with the text '#
    Exim filter', then it is interpreted as a set of filtering commands
    instead of a list of forwarding addresses. Details of the syntax and
    semantics of filter files are described in a separate document entitled
    "Exim' User interface to mail filtering"; this is intended for use by
    end users.

    The logging facility in filter files is available only if the filter is
    being run under some unprivileged uid. The system configuration must
    specify that seteuid() is available, either user or check_local_user
    must be set on the director, forbid_filter_log must not be set, and the
    global security setting must not be 'setuid'. Writing the log takes
    place while the filter file is being interpreted, that is, at directing
    time. It does not queue up for later like the delivery commands. The
    reason for this is so that a log file need be opened only once for
    several write operations.

forbid_file

    Type:    boolean
    Default: false

    If this option is true, then this director may not generate a new
    address which specifies delivery to a local file. If it attempts to do
    so, a delivery failure occurs.

forbid_filter_log

    Type:    boolean
    Default: false

    If this option is true, use of the logging facility in filter files is
    not permitted. This is in any case available only if the filter is
    being run under some unprivileged uid, which is normally the case for
    ordinary users' .forward files on a system with seteuid() available.

forbid_include

    Type:    boolean
    Default: false

    If this option is true, then items of the form

      :include:<path name>

    are not permitted, and if one is encountered, the message is frozen.

forbid_pipe

    Type:    boolean
    Default: false

    If this option is true, then this director may not generate a new
    address which specifies delivery to a pipe. If it attempts to do so, a
    delivery failure occurs.

forbid_reply

    Type:    boolean
    Default: false

    If this option is true, then this director may not generate an
    automatic reply message. If it attempts to do so, a delivery failure
    occurs. Automatic replies can be generated only from filter files, not
    from traditional forward files.

freeze_missing_include

    Type:    boolean
    Default: true

    If a file named by the 'include' mechanism fails to open, delivery is
    frozen if this option is true. Otherwise, delivery is just deferred.
    Unsetting this option can be useful if included files are NFS mounted
    and may not always be available.

home_directory

    Type:    string
    Default: unset

    If this option is set, it associates a home directory with any address
    that forwardfile directs to a local transport because it specifies a
    file name or pipe command. The option string is expanded and set as the
    home directory during the delivery process, unless overridden by a
    setting on the transport. If home_directory is not set, then the
    directory specified by file_directory, or if that is not set, the home
    directory obtained from check_local_user is associated with the address
    during delivery. See chapter 12 for details of the local delivery
    environment. This option has no effect during the running of the
    forwardfile director.

ignore_eacces                                                                |
                                                                             |
    Type:    boolean                                                         |
    Default: false                                                           |
                                                                             |
    If this option is set and an attempt to open the forward file yields     |
    the EACCES error (permission denied) then forwardfile behaves as if the  |
    file did not exist.                                                      |
                                                                             |
ignore_enotdir                                                               |
                                                                             |
    Type:    boolean                                                         |
    Default: false                                                           |
                                                                             |
    If this option is set and an attempt to open the forward file yields     |
    the ENOTDIR error (something on the path is not a directory) then        |
    forwardfile behaves as if the file did not exist.                        |


pipe_transport                                                               |
                                                                             |
    Type:    string                                                          |
    Default: unset                                                           |
                                                                             |
    A forwardfile director sets up a direct delivery to a pipe when a        |
    string starting with a vertical bar character is specified as a new      |
    'address' (see chapter 20). The transport used is taken from the global  |
    option address_pipe, unless this option is set to override it. The       |
    string must be the name of a configured transport.                       |

reply_transport                                                              |
                                                                             |
    Type:    string                                                          |
    Default: unset                                                           |
                                                                             |
    A forwardfile director sets up a delivery to an autoreply transport      |
    when a mail or vacation command is used in a filter file (see chapter    |
    20). The transport used is taken from the global option address_reply,   |
    unless this option is set to override it. The string must be the name    |
    of a configured transport.                                               |

rewrite

    Type:    boolean
    Default: true

    If this option is set false, addresses generated by the director are
    not subject to address rewriting. Otherwise, they are treated like new
    addresses.

skip_syntax_errors

    Type:    boolean
    Default: false

    If skip_syntax_errors is set, a malformed address that causes a parsing
    error is skipped, and an entry is written in the main log. This may be
    useful for mailing lists that are automatically managed, but note the
    inherent danger. It should never be set for users' .forward files.

syntax_errors_to

    Type:    string
    Default: unset

    This option applies only when skip_syntax_errors is set. If any
    addresses are skipped because of syntax errors, a mail message is sent
    to the address specified by syntax_errors_to, giving details of the
    failing address(es). Often it will be appropriate to set
    syntax_errors_to to be the same address as errors_to.



                         24. THE LOCALUSER DIRECTOR


The localuser director checks whether the local part of an address is
the login of a local user. If it is, and if other conditions set by
options are met, it accepts the address and sets up a transport for
it. The user's home directory is set up by default to be used while
running the delivery process. The generic transport option must always
be specified.

The generic require_files option may contain references to $home when used
with this director. Thus it is possible to pick out all users with
particular files in their home directories and route their mail to a
specific transport. This could be used, for example, to check for a
.procmailrc file and then to route delivery via procmail if one is found.

current_directory

    Type:    string
    Default: unset

    This option string is expanded and set as the current directory during
    the delivery process, unless overridden by a setting on the transport.
    See chapter 12 for details of the local delivery environment.

directory

    Type:    string
    Default: unset

    This is an obsolete name for the match_directory option. It was changed
    to avoid confusion with directory options in other drivers, which have
    a different kind of meaning.

home_directory

    Type:    string
    Default: unset

    This option overrides the home directory that is derived from the
    HOMEBASE variable. The string is expanded and set as the home
    directory during the delivery process, unless overridden by a setting
    on the transport. See chapter 12 for details of the local delivery
    environment.


match_directory

    Type:    string
    Default: unset

    If this option is set, the user's home directory, must match the
    given string. If it does not, the director fails to match the
    address. This provides a way of partitioning the local users by
    home directory. The string is expanded before use if it
    contains any $ characters. If expansion fails, Exim panics, unless the
    failure was explicitly triggered by a 'fail' item in a conditional sub-
    expression in the expansion, in which case the director just fails to
    handle the address.

    If the expanded string starts with an asterisk, then the remainder must
    match the end of the home directory name; if it starts with a
    circumflex, a regular expression match is performed. In fact, the
    matching process is the same as is used for domain list items and may
    include file lookups.

On central systems at Cambridge, when a user account is cancelled, it
remains in the password file for a while, with the home directory set to
/home/CANCELLED. We use the match_directory option to detect mail addressed
to such users and bounce it with an explanatory message.



                         25. THE SMARTUSER DIRECTOR


The smartuser director matches any local part, so it can be used to handle
local addresses that all other directors have failed. It is, of course,
subject to the generic director options, so specific instances can be used
for all addresses in certain domains, or all local parts with certain
prefixes or suffixes, or specific local parts.

Smartuser can generate a new address from the old one, and cause that to be
re-processed, or it can set a transport for the current address, optionally
changing the address. Common uses are to pipe the message to a script that
generates an information message to be returned to the sender, or to send
the message to another host for processing.


new_address

    Type:    string
    Default: unset

    This option specifies a new address, to replace the current one. It
    must be a qualified address (i.e. contain an '@' character). The string
    is expanded, and so settings such as

      new_address = ${local_part}@some.new.host

    can be used, or a file lookup on the local part can be done. If the
    generic transport option is not specified, this option is required, and
    the new address is processed by the directors and routers in the normal
    way. If a transport is specified, the new address just replaces the old
    one when the message is delivered.

panic_expansion_fail

    Type:    boolean
    Default: true

    If the expansion of new_address fails as a result of an explicit 'fail'
    item in an expansion sub-expression, the director just fails to handle
    the address. Otherwise, an expansion failure is treated as a serious
    configuration error, and causes a panic, unless this option is set
    false, in which case the same action is taken as for 'fail'.



                 26. ADDITIONAL GENERIC OPTIONS FOR ROUTERS


The following additional generic options apply to all routers, in addition   |
to the common generic options for both directors and routers which are       |
described in chapter 19. Routers are concerned with addresses whose domains  |
do not match something in local_domains.                                     |

pass_on_timeout

    Type:    boolean
    Default: false

    If a router times out during a host lookup, it normally causes deferral
    of the address. If pass_on_timeout is set, the address is instead
    passed on to the next router. This may be helpful for systems that are
    intermittently connected to the Internet.

self

    Type:    string
    Default: "freeze"

    This option specifies what is to happen if routing a remote address
    ends up pointing at the local host. Normally this indicates either an
    error in Exim's configuration (for example, the domain should be listed
    as local), or an error in the DNS (for example, the MX shouldn't point
    at this host). The default action is to freeze the message. The
    following alternatives are provided for use in special cases:

     .   defer
         Delivery of the message is tried again later.

     .   reroute: <domain>
         The domain is changed to the given domain, and the address is
         passed back to be reprocessed by the directors and routers. No
         rewriting of headers takes place.

     .   reroute: rewrite: <domain>
         The domain is changed to the given domain, and the address is
         passed back to be reprocessed by the directors and routers. Any
         headers that contain the original domain are rewritten.

     .   local                                                               |
         The address is passed to the directors, as if its domain were a     |
         local domain, even though it does not match anything in             |
         local_domains. This can be used to treat all domains whose lowest   |
         MX records point to the host as local domains. During directing     |
         (and any subsequent local deliveries) the variable $self_hostname   |
         is set to the name of the local host that the router encountered.   |
         This can be used to distinguish between different cases for hosts   |
         with multiple names.                                                |

     .   fail_soft
         The router fails, leaving the address to be passed to any
         following routers.

     .   fail_hard
         The router fails, and the address is not passed to any following
         routers. Consequently, delivery fails and an error report is
         generated.

     .   send
         The anomaly is ignored and the message is transmitted anyway. This
         setting should be used with extreme caution. It makes sense only
         in cases where the program that is listening on the SMTP port is
         not this version of Exim. That is, it must be some other MTA, or
         Exim with a different configuration file that handles the domain
         in another way.

    When a router just rewrites, that is, does not set up IP addresses, the
    self option is not relevant.


26.1 Skipping routers

Some of the generic options can cause routers to be skipped in particular
cases. They interact with each other in the following way:

If the domain and local part are not in agreement with domains,
except_domains, except_local_parts and local_parts (when set), or if the     |
condition option fails, or if verify_only is set but verification is not     |
happening, then the router is skipped and the next one is tried. None of
the other options is inspected.

Otherwise, if the more option is not set, no subsequent routers are ever
called, in any circumstances. The current router is itself called unless

 .   Verification is happening and its verify_sender or verify_recipient
     option (as appropriate) is turned off, or

 .   The existence or non-existence of files listed in the require_files
     option is not as expected, or

 .   The sender of the message is not in agreement with senders and
     except_senders. This test is done after checking for file existence so
     that sender lists can contain references to files whose existence is
     tested.

The unseen option causes routing to continue when it would otherwise cease,
the complementary action to no_more, which causes it to cease when it would
otherwise continue.



                         27. THE DOMAINLIST ROUTER


The domainlist router compares a list of domain patterns with the domain it
is trying to route. When a match is found, the information associated with
the pattern can specify several different actions:

 .   The message can be sent to a specific host, or one of a number of
     hosts.

 .   The domain name can be replaced by a new name, which can be

     (i)  passed to the next router; or

     (ii) looked up directly in the DNS, with or without MX processing; or

     (iii)looked up using gethostbyname().

     Of course, gethostbyname() may well do its own DNS lookup, but it does
     not do MX processing, and it may also reference other sources of
     information, such as /etc/hosts.

The list of patterns can be specified as an option string, or looked up in
a file or database, or both; at least one of the route_list, route_file, or
route_query options must be set. A transport must be set when the routing
is completed by this router, that is, when the address is not passed on to
subsequent routers. Each routing entry can specify its own transport, with
the generic transport option acting as a default for those that don't.


route_file

    Type:    string
    Default: unset

    If this option is set, search_type must be set to one of the single-key
    lookup types, and route_query must not be set. See chapter 6 for
    details of file and database lookups. The domain being routed is used
    as the key for the lookup, and the resulting data must be a list of
    routing rules in the form described below. The file name is expanded
    before use.

route_list

    Type:    string-list, semicolon-separated
    Default: unset

    This string is a list of routing rules, in the form defined below. Note
    that, unlike most string lists, the items are separated by semicolons.
    This is so that they may contain colon-separated host lists.

route_query

    Not implemented under OS/2.

search_type

    Type:    string
    Default: unset

    This option is mandatory when either route_file or route_query is
    specified. It must be set to one of the strings 'lsearch', or 'dbm',
    specifying the type of file search.

    The name may be preceded by 'partial-', indicating a simple
    wildcard file lookup that works as follows:

    (a)  Exim first tries to look up the domain exactly as given.

    (b)  If that fails, it adds '*.' on the front of the domain, and looks
         that up.

    (c)  If that fails, it replaces the first component of the domain with
         '*' and tries that, and continues chopping off components in this
         way until either the lookup succeeds, or there are fewer than two
         non-* components left.

    Thus, for example, if you put an entry keyed by *.austen.fict.film in
    your database, that entry will be used for

    (1)  austen.fict.film by rule (b) above, having failed on rule (a). (If
         you are worried about the resource waste implied by this, you can
         always add an entry for austen.fict.film as well.)

    (2)  emma.austen.fict.film at the first attempt in rule (c), having
         failed on rules (a) and (b).

    A domain such as jane.fict.film will fail, having tried 3 lookups:
    jane.fict.film, *.jane.fict.film, *.fict.film, but it won't waste
    effort looking up *.film because that has only one non-* component. In
    fact, the minimum number of components can be altered by including a
    number immediately before the hyphen. For example, 'partial4-dbm'
    specifies a minimum of four non-* components.


27.1 Routing rules

Routing rules specified in route_list are scanned before route_file or       |
route_query are used. The contents of route_list is a string consisting of   |
a sequence of routing rules, separated by semicolons. If a semicolon is      |
needed in an rule, it can be entered as two semicolons. Empty rules are      |
ignored. The format of each rule is                                          |
                                                                             |
  <domain pattern>  <host-list>  <options>                                   |
                                                                             |
The following example contains a simple domain pattern and just one rule:    |
                                                                             |
  route_list = "dict.ref.book mail-1.ref.book:mail-2.ref.book byname"        |
                                                                             |
The three parts of a rule are separated by white space and only the domain   |
pattern must be present in every rule. Each domain pattern in a route_list   |
is in the same format as an item in a domain list (see section 7.11), that   |
is, it may be wildcarded or a regular expression, or a file or database      |
lookup (see chapter 6 for details). The rules in route_list are searched in  |
order until one of the patterns matches the domain that is being routed.     |
The host list and options are then used as described below.                  |
                                                                             |
If no rule in route_list matches the domain, it is used as the key for a     |
lookup of the type specified by search_type, using either route_file or      |
route_query, as appropriate. The data returned from a successful lookup      |
must be a string containing a host list and options, separated by white      |
space. For example, a line in a linearly searched route file might be:       |
                                                                             |
  dict.ref.book:  mail-1.ref.book:mail-2.ref.book  byname                    |
                                                                             |
Note that there are two different uses of the colon character in this line.  |
The first one is the delimiter of the key in the file, while the second is   |
the normal list delimiter in the host list, which in this example consists   |
of two host names. As both the host list and the options are not compulsory  |
in a rule, the data returned from a lookup can legitimately be an empty      |
string in some circumstances (see Application of routing rules below).       |
                                                                             |
If the domain does not match anything in route_list and looking it up using  |
route_file or route_query also fails, then the router cannot handle the      |
address, and it gets passed on to the next router, unless no_more is set.    |
                                                                             |
                                                                             |
27.2 Host list format                                                        |
                                                                             |
If a host list is present in the rule which matches the domain, it is        |
expanded before use. The result of the expansion must be a colon-separated   |
list of host names and/or IP addresses. Some string expansion items may      |
contain white space, and if this is the case, the host list must be          |
enclosed in single or double quotes, because otherwise white space termin-   |
ates it. The numeric expansion variables are available during host list      |
expansion. These are mainly used when the domain is matched against a        |
regular expression domain pattern in a route_list string, but $1 is also     |
set when partial matching is done in a file lookup.                          |
                                                                             |
If the expansion of the host list is forced to fail (by using the 'fail'     |
item in a conditional construction), the router just fails to handle the     |
address, and (unless no_more is set) it gets passed on to the next router.   |
If expansion fails for some other reason, the message is frozen, since this  |
considered to be a configuration error.                                      |
                                                                             |
                                                                             |
27.3 Options format                                                          |
                                                                             |
Options can be present only if there is a host list. They are a sequence of  |
words, but in practice no more than two are ever present. One of the words   |
can be the name of one of the configured transports, and this overrides the  |
transport option on the router for this particular routing rule only. The    |
other word (if present) specifies how the IP addresses of the hosts in the   |
host list are to be found:                                                   |
                                                                             |
 .   byname: use gethostbyname(), or use literal IP addresses if present.    |
     Literal IP addresses are written without any surrounding square         |
     brackets.                                                               |
                                                                             |
 .   bydns: use the DNS, doing the full MX and A record processing.          |
                                                                             |
 .   bydns_a: look up a A records for the host(s) in the DNS; fail if there  |
     are none.                                                               |
                                                                             |
 .   bydns_mx: look up MX records for the host(s) in the DNS; fail if there  |
     are none.                                                               |
                                                                             |
                                                                             |
27.4 Application of routing rules                                            |
                                                                             |
When a rule has been found that matches the current domain, either by        |
matching one of the rules in route_list, or by a successful lookup in        |
route_file or using route_query, the host list and options are used in a     |
number of different ways, depending on which are present and on whether a    |
transport has been specified.                                                |
                                                                             |
 .   If there is no host list (and therefore necessarily no options          |
     either), then a local transport (i.e. not an SMTP transport) must be    |
     specified for the router via the generic transport option. Failure to   |
     specify such a transport is a configuration error. The address is       |
     routed to the transport. In all other cases, a host list must be        |
     provided.                                                               |
                                                                             |
 .   If there is a host list and a local transport is specified either by    |
     the generic transport option, or by an option item on the rule, then    |
     the host list must contain just a single host name which is passed to   |
     the transport in the $host variable. Any byxxx options are ignored.     |
                                                                             |
 .   If no byxxx option is present, then any remote transport setting is     |
     ignored, and there must be just one name in the host list. The address  |
     is passed on to the next router, with the domain being routed being     |
     replaced by the name from the host list.                                |
                                                                             |
 .   Otherwise, a remote (i.e. SMTP) transport must be specified, either     |
     via the generic transport option or by a transport name as an option    |
     setting, and there may be many hosts in the list. Their IP addresses    |
     are looked up according to the byxxx option. If any of them are found   |
     to be the local host, that one and all those that follow it are         |
     discarded. If the first host is found to be the local host, then the    |
     generic self option specifies what happens. Otherwise, the address is   |
     passed to the specified transport, along with the ordered list of       |
     hosts. The transport will try delivering to each host in turn, until    |
     one accepts the message.                                                |
                                                                             |
The various different possibilities for configuring the domainlist router    |
make it possible to use it for a number of different routing requirements,   |
as shown in the examples in the next section.                                |
                                                                             |
                                                                             |
27.5 Domainlist examples                                                     |
                                                                             |
 .   Routing to a gateway to another mail environment can be set up using a  |
     wildcarded domain pattern that matches some pseudo top-level domain.    |
     For example, to route certain addresses to UUCP and Bitnet gateways:    |
                                                                             |
       uucp_bitnet:                                                          |
         driver = domainlist                                                 |
         route_list = "*.uucp   uugateway.fict.book; \                       |
                       *.bitnet bngateway.ref.book"                          |
                                                                             |
     The two rules match domains ending in .uucp and .bitnet respectively,   |
     and because no options or transport are specified in either case, the   |
     name of the appropriate gateway domain is taken from the host list and  |
     passed to subsequent routers for further routing. So, for example,      |
     mail addressed to user@faraway.uucp is routed by applying subsequent    |
     routers to the domain uugateway.fict.book to determine where to send    |
     it.                                                                     |
                                                                             |
     If there are two hosts servicing one of these domains and they are not  |
     connected to a single domain name (by MX records for example), you may  |
     want to quote two names in the host list portion of a rule. In this     |
     case, you have to specify one of the byxxx options, to get the names    |
     looked up by domainlist, since it can pass on only a single domain      |
     name to other routers. A transport must also be provided:               |
                                                                             |
       uucp:                                                                 |
         driver = domainlist                                                 |
         transport = smtp                                                    |
         route_list = "\                                                     |
           *.uucp uugate1.fict.book:uugate2.fict.book byname"                |
                                                                             |
     In this case, no further routers are called.                            |
                                                                             |
 .   A host that is itself a gateway can 'deliver' messages to pipes or      |
     into files in batched SMTP format for onward transportation by some     |
     other means. In this case, the route list entry can be as simple as a   |
     single domain name in a configuration like this:                        |
                                                                             |
       route_append:                                                         |
         driver = domainlist                                                 |
         transport = batchsmtp_appendfile                                    |
         route_list = gated.domain                                           |
                                                                             |
     though often a pattern is used to pick up more than one domain. If      |
     there are several domains or groups of domains with different trans-    |
     port requirements, different transports can be listed in the routing    |
     information:                                                            |
                                                                             |
       route_append:                                                         |
         driver = domainlist                                                 |
         route_list = "\                                                     |
           *.gated.domain1  $domain  batch_appendfile; \                     |
           *.gated.domain2  \                                                |
             ${lookup{$domain}dbm{/domain2/hosts}{$value}fail} \             |
             batch_pipe"                                                     |
                                                                             |
     The first of these just passes the domain in the $hosts variable,       |
     which doesn't achieve much (since it is also in $domain) but the        |
     second does a file lookup to find a value to pass, causing the router   |
     to fail to handle the address if the lookup fails.                      |
                                                                             |
 .   Routing mail directly to UUCP software is a specific case of the use    |
     of domainlist in a gateway to another mail environment. This is an      |
     example of one way it can be done, taken from a real configuration:     |
                                                                             |
       # Transport                                                           |
       uucp:                                                                 |
         driver = pipe                                                       |
         user = nobody                                                       |
         command = "/usr/local/bin/uux -r - \                                |
           ${substr_-5:$host}!rmail ${local_part}"                           |
         return_fail_output = true                                           |
                                                                             |
       # Router                                                              |
       uucphost:                                                             |
         transport = uucp                                                    |
         driver = domainlist                                                 |
         route_file = /usr/local/exim/uucphosts                              |
         search_type = lsearch                                               |
                                                                             |
     The file /usr/local/exim/uucphosts contains entries like                |
                                                                             |
       darksite.ethereal.ru:           darksite.UUCP                         |
                                                                             |
     It can be set up more simply without adding and removing '.UUCP' but    |
     this way makes clear the distinction between the domain name            |
     darksite.ethereal.ru and the UUCP host name darksite.                   |
                                                                             |
 .   A "mail hub" is a machine which receives mail for a number of domains   |
     via MX records in the DNS and delivers it via its own private routing   |
     mechanism. Often the final destinations are behind a firewall, with     |
     the mail hub being the one machine that can connect to machines both    |
     inside and outside the firewall. The domainlist router can be set up    |
     for this kind of purpose:                                               |
                                                                             |
       through_firewall:                                                     |
         driver = domainlist                                                 |
         transport = smtp                                                    |
         route_file = /internal/host/routes                                  |
         search_type = lsearch                                               |
                                                                             |
     For a small number of cases, the routing could be inline, using the     |
     route_list option, but for a larger number a file lookup would be       |
     easier to manage, and the file containing the internal routing might    |
     contain lines like this:                                                |
                                                                             |
       dict.ref.book:  mail-1.ref.book:mail-2.ref.book  byname               |
                                                                             |
     The DNS would be set up with an MX record for dict.ref.book pointing    |
     to the mail hub, which would then then forward mail for dict.ref.book   |
     to one of the two specified machines, looking up their addresses using  |
     gethostbyname().                                                        |
                                                                             |
     If the domain names are in fact the names of the machines to which the  |
     mail is to be sent by the mail hub, then the configuration can be       |
     quite simple. For example,                                              |
                                                                             |
       hub_route:                                                            |
         driver = domainlist                                                 |
         transport = smtp                                                    |
         route_list = *.rhodes.tvs  $domain  byname                          |
                                                                             |
     This configuration routes domains that match *.rhodes.tvs by calling    |
     gethostbyname() on the domain that matched. A similar approach can be   |
     taken if the host name can be obtained from the domain name by simple   |
     manipulation that the expansion facilities can handle.                  |
                                                                             |
 .   The domainlist router can also be used to forward all non-local mail    |
     to a "smart host" by using a configuration like                         |
                                                                             |
       smart_route:                                                          |
         driver = domainlist                                                 |
         transport = smtp                                                    |
         route_list = "*  smarthost.ref.book  bydns_a"                       |
                                                                             |
     which causes all messages containing remote addresses to be sent to     |
     the single host smarthost.ref.book, whose address (in this example) is  |
     obtained from its DNS address record. If a colon-separated list of      |
     smart hosts is given, they are tried in order. A router like this       |
     should be the last one in the configuration file, since it will route   |
     any domain whatsoever.                                                  |
                                                                             |


                          28. THE IPLITERAL ROUTER


This router succeeds if the 'domain' being routed takes the form of an RFC
822 domain literal, that is, an IP address in dotted-quad notation enclosed
in square brackets. For example, this router handles the address

  root@[111.1.1.1]

by setting up delivery to the host with that IP address. If an IP literal
turns out to refer to the local host, the generic self option determines
what happens. The RFCs require support for domain literals, though it seems
anachronistic in today's Internet. There are no private options for this
router; a transport must be set using the generic transport option.



                          29. THE IPLOOKUP ROUTER


The iplookup router was written to fulfil a specific requirement in
Cambridge.

The iplookup router routes an address by sending it over a TCP or UDP
connection to one or more specific hosts. The host can then return the same
or a different address - in effect rewriting the recipient address in the
message's envelope. If this process fails, the address can be passed on to
other routers, or delivery can be deferred.

Background, for those that are interested: We have an Oracle database of
all Cambridge users, and one of the bits of data it maintains for each user
is where to send mail addressed to <user>@cam.ac.uk. The MX records for
cam.ac.uk point to a central machine that has a large alias list that is
abstracted from the database. Mail from outside is switched by this system,
and originally internal mail was also done this way. However, this resulted
in a fair number of messages travelling from some of our larger systems to
the switch and back again. The Oracle machine now runs a UDP service that
can be called by the iplookup router in Exim to find out where
<user>@cam.ac.uk addresses really have to go; this saves passing through
the central switch, and in many cases saves doing any remote delivery at
all.

Since iplookup is just a re-writing router, a transport must not be
specified for it.


hosts

    Type:    string
    Default: unset

    This option must be supplied. Its value is a colon-separated list of
    host names. The hosts are looked up using gethostbyname and are tried
    in order until one responds to the query.

optional

    Type:    boolean
    Default: false

    If optional is true, then if no response is obtained from any host, the
    address is passed on to the next router. If optional is false, delivery
    to this address is deferred.

protocol

    Type:    string
    Default: udp

    This option can be set to 'udp' or 'tcp' to specify which of the two
    protocols is to be used.

query

    Type:    string
    Default: "${local_part}@${domain} ${local_part}@${domain}"

    This defines the content of the query that is sent to the remote hosts.
    The repetition serves as a way of checking that a response is to the
    correct query in the default case (see response_pattern below).

reroute

    Type:    string
    Default: unset

    If this option is not set, the rerouted address is precisely the byte
    string returned by the remote host, up to the first white space, if
    any. If set, the string is expanded to form the rerouted address. It
    can include parts matched in the response by response_pattern by means
    of numeric variables such as $1, $2, etc. The variable $0 refers to the
    entire input string, whether or not a pattern is in use. In all cases,
    the rerouted address must end up in the form <local_part>@<domain>.

response_pattern

    Type:    string
    Default: unset

    This option can be set to a regular expression that is applied to the
    string returned from the remote host. If the pattern does not match the
    response, the router fails. If response_pattern is not set, no checking
    of the response is done, unless the query was defaulted, in which case
    there is a check that the text returned after the first white space is
    the original address. This checks that the answer that has been
    received is in response to the correct question. For example, if the
    response is just a new domain, the following could be used:

      response_pattern = "^([^@]+)$"
      reroute = "${local_part}@${1}"

service

    Type:    integer
    Default: 0

    This option must be supplied. It specifies the port number for the TCP
    or UDP call.

timeout

    Type:    time
    Default: 5s

    This specifies the amount of time to wait for a response from the
    remote machine. The same timeout is used for the connect() function for
    a TCP call. It does not apply to UDP.



                         30. THE LOOKUPHOST ROUTER


The lookuphost router looks up the hosts that handle mail for a given
domain either via the gethostbyname() function, or by using the DNS
directly. A transport must always be set (using the generic transport
option) for this router.


gethostbyname

    Type:    boolean
    Default: false

    If this is true, the gethostbyname() function is used and the options
    relating to the DNS are ignored. Otherwise, the name is looked up
    directly in the DNS. Of course, gethostbyname() may do its own DNS
    lookup, but it may also access other sources of information such as
    /etc/hosts.

mx_domains

    Type:    domain-list
    Default: unset

    This option, together with non_mx_domains, applies to domains that are
    looked up in the DNS for non-source-routed RFC 822 addresses (that is,
    addresses that do not start with @). A domain which is in mx_domains
    but is not in non_mx_domains is required to have an MX record in order
    to be recognised. For example, if all the mail hosts in fict.book are
    known to have MX records, except for those in discworld.fict.book,
    options of the form

      mx_domains = *.fict.book
      non_mx_domains = *.discworld.fict.book

    could be used. This would cause messages addressed to a machine with
    only an A record to be bounced immediately instead sitting on the queue
    until the delivery timed out. Note, however, that for source-routed RFC
    822 addresses (ones that start with @) this restriction does not apply,
    as the first domain in such an address is a machine name. The
    collapse_source_routes main configuration option provides a way of
    locking out the use of source routes.

non_mx_domains

    Type:    domain-list
    Default: unset

    See mx_domains above.

qualify_single

    Type:    boolean
    Default: true

    If domains are being looked up in the DNS, then the resolver option
    that causes it to qualify single-component names with the default
    domain (RES_DEFNAMES) is set. For example, on a machine called
    dictionary.ref.book, looking up the domain thesaurus would cause the
    name thesaurus.ref.book to be looked up.

rewrite_headers

    Type:    boolean
    Default: true

    An abbreviated name may be expanded to its full form by both
    gethostbyname() or by DNS lookup, or as a result of the widen_domains
    option. For example, if an address is specified as dormouse@teaparty,
    the domain might get expanded to teaparty.wonderland.fict.book. If this
    option is true, then all occurrences of the abbreviated name in the
    headers of the message are rewritten with the full name. This option
    should be turned off only when it is known that no message is ever
    going to be sent outside an environment where the abbreviation makes
    sense.

    When an MX record is looked up in the DNS and matches a wildcard
    record, nameservers normally return a record containing the name that
    has been looked up, making it impossible to detect whether a wildcard
    was present or not. However, some nameservers have recently been seen
    to return the wildcard entry. If the name returned by a DNS lookup
    begins with an asterisk, it is not used for header rewriting.

search_parents                                                               |
                                                                             |
    Type:    boolean                                                         |
    Default: false                                                           |
                                                                             |
    If domains are being looked up in the DNS, then the resolver option      |
    that causes it to search parent domains (RES_DNSRCH) is set if this      |
    option is true. This is different from the qualify_single option in      |
    that it applies to domains containing dots. For example, on a machine    |
    in the fict.book domain, when looking up teaparty.wonderland initially   |
    fails, the resolver automatically tries teaparty.wonderland.fict.book    |
    if this option is set. The default setting of this option used to be     |
    true, but this causes problems in domains that have a wildcard MX        |
    record, because any domain that does not have its own MX record then     |
    matches the local wildcard. The default was changed to false in Exim     |
    1.80.                                                                    |

self_mx                                                                      |
                                                                             |
    Type:    string                                                          |
    Default: "freeze"                                                        |
                                                                             |
    This obsolete option is no longer supported. It is superseded by the     |
    generic self option.                                                     |

widen_domains

    Type:    string-list
    Default: unset

    If a lookup fails and this option is set, each of its strings in turn
    is added onto the end of the domain, and the lookup is tried again. For
    example, if

      widen_domains = "fict.book:ref.book"

    is set and a lookup of klingon.dictionary fails, then
    klingon.dictionary.fict.book is looked up, and if this fails, then
    klingon.dictionary.ref.book is tried. This option applies to lookups
    using gethostbyname() as well as to DNS lookups. Note that when the DNS
    is being used for lookups, the qualify_single and search_parents
    options cause some widening to be undertaken inside the DNS resolver.



                        31. THE QUERYPROGRAM ROUTER


The queryprogram router routes a domain by running an external command and
acting on its output. This is an expensive way to route, and is intended
mainly for use in lightly-loaded systems, or for performing experiments.
However, if it is possible to use the domains generic option to skip this
router for most addresses, then it could sensibly be used in special cases.
There are two private options:


command

    Type:    string
    Default: unset

    This option must be set, and must start with a '/' character. It
    specifies the command that is to be run. It is expanded before use.
    Failure to expand causes the router to fail and the message to be
    frozen.

timeout

    Type:    time
    Default: 1h

    If the command does not complete within the timeout period, its process
    is killed and the message gets frozen. A value of zero time specifies
    no timeout.

The standard output of the command is connected to a pipe, which is read
when the command terminates. It should consist of a single line of output,
containing up to five fields, separated by white space. The first field is
one of the following words:

 .   OK: routing succeeded; the remaining fields specify what to do.

 .   FAIL: routing failed; pass the address to the next router.

 .   FORCEFAIL: routing failed; do not pass the address to any more
     routers.

 .   DEFER: routing could not be completed at this time; try again later.

 .   ERROR: some disastrous error occured; freeze the message.

When the first word is not OK, the remainder of the line is an error
message explaining what went wrong. For example:

  FAIL  queryprogram cannot route to unseen.discworld.fict.book

Otherwise, the line must be formatted as follows:

  OK <transport name> <new domain> <option> <arbitrary text>

The second field is the name of a transport instance, or a + character,
which means that the transport specified for the router using the generic
transport option is to be used, if set.

If the third field is not empty or a + character, it is a new domain name
to replace the current one. If a transport is specified and the fourth
field is not empty or a + character, it specifies the method of looking up
the new name. This can be one of the words 'byname', 'bydns', 'bydns_a', or
'bydns_mx'. For example,

  OK  smtp  gate.star.fict.book  bydns_a

causes the message to be sent using the smtp transport to the host
gate.star.fict.book, whose address is looked up as a DNS address record. If
the host turns out to be the local host, what happens is controlled by the
generic self option.

The fifth field, if present, is made available to the transport via the
expansion variable $route_option. For example, a line such as

  OK special + + /computed/filename

sends the message to the special transport, which can use $route_option in
its configuration to access the text '/computed/filename'.

The fourth and fifth fields are ignored and the new domain name (if any) is
passed to the next router if no transport is specified in the response line
(i.e. a + character is given) and the generic transport option is also
unset.



                          32. RETRY CONFIGURATION


The fifth part of the configuration file contains a list of retry rules
which control how often Exim tries to deliver messages that cannot be
delivered at the first attempt. If there are no retry rules, Exim gives up
after the first failure. The -brt command line option can be used to test
which retry rule will be used for a given address or domain.

Retry processing applies to directing and routing as well as to delivering.
The retry rules do not distinguish between these three actions, so it is
not possible, for example, to specify different behaviour for failures to
route the domain snark.fict.book and failures to deliver to the host
snark.fict.book. I didn't think anyone would ever need this added compli-
cation, so did not implement it. Internally, however, the actual retry
times for routing, directing, and transporting are maintained
independently.

Each retry rule occupies one line and consists of three parts. The rules
are searched in order until one which matches the current domain (and
possibly local part) is found.

The first field in a retry rule is a key for the rule, which may be an
address (local_part@domain), a plain domain, a wild-carded domain (i.e.
starting with an asterisk), a domain lookup (as in a domain list), or a
regular expression. The first form must be used only with local domains;
the local part may begin with an asterisk.

The string used to match the keys consists of "local_part@domain" for local
deliveries, and just the domain for remote ones. Regular expressions always
match against this entire string. Otherwise, if there is no local part in
the key then the local part isn't used in the matching. Thus an entry
such as

  lookingglass.fict.book   *          F,24h,30m;

matches any address whose domain is lookingglass.fict.book, whether it is a
local address or a remote one.

When looking for a retry rule after a routing attempt has failed (for        |
example, after a DNS timeout), each line in the retry configuration is       |
tested against the address's domain name, but when looking for a retry rule  |
after a remote delivery attempt has failed, each line in the retry           |
configuration is first tested against the remote host name, and then         |
against the address's domain name. For example, if the MX records for        |
a.b.c.d are

  a.b.c.d  MX  5  x.y.z
           MX  6  p.q.r
           MX  7  m.n.o

and the retry rules are

  p.q.r    *          F,24h,30m;
  a.b.c.d  *          F,4d,45m;

then failures to deliver to host p.q.r use the first rule to determine
retry times, but for all the other hosts for the domain a.b.c.d, the second
rule is used, and that rule would also be used when routing to a.b.c.d       |
fails to complete.                                                           |

The second field in a retry rule is the name of a particular error, or an
asterisk, which matches any error. The errors that can be tested for are:

     refused_MX: connection refused from a host obtained from an MX record

     refused_A: connection refused from a host not obtained from an MX
     record

     refused: any connection refusal

     timeout_connect: connection timed out

     timeout_DNS: DNS lookup timed out

     timeout: any timeout

     quota: quota exceeded in local delivery

     quota_<time>: quota exceeded in local delivery, and the mailbox has
     not been read for <time>.

The quota errors apply both to system-enforced quotas and to Exim's own
quota mechanism in the appendfile transport.

The third field in a retry rule is a sequence of retry parameter sets,
separated by semicolons. Each set consists of

  <letter>,<cutoff time>,<arguments>

The letter identifies the algorithm for computing a new retry time; the
cutoff time is the time beyond which this algorithm no longer applies, and
the arguments vary the algorithm's action. The cutoff time is measured from
the time that the first failure for the domain (combined with the local
part if relevant) was detected, not from the time the message was received.

The available algorithms are:

 .   F: retry at fixed intervals. There is a single time parameter
     specifying the interval.

 .   G: retry at geometrically increasing intervals. The first argument
     specifies a starting value for the interval, and the second a
     multiplier.

Here are some example retry rules suitable for use when
wonderland.fict.book is a local domain:

  alice@wonderland.fict.book quota_5d  F,7d,3h
  wonderland.fict.book       quota_5d
  wonderland.fict.book       *         F,1h,15m; G,2d,1h,2;
  lookingglass.fict.book     *         F,24h,30m;
  *                          refused_A F,2h,20m;
  *                          *         F,2h,15m; G,16h,2h,1.5; F,5d,8h

The first rule sets up special handling for mail to
alice@wonderland.fict.book when there is an over-quota error and the
mailbox hasn't been read for at least 5 days. Retries continue every three
hours for 7 days. The second rule handles over-quota errors for all other
local parts at wonderland.fict.book; the absence of a local part has the
same effect as supplying '*@'. As no retry algorithms are supplied,
messages that fail are bounced immediately.

The third rule handles all other errors at wonderland.fict.book; retries
happen every 15 minutes for an hour, then with geometrically increasing
intervals until two days have passed since a delivery first failed. The
fourth rule controls retries for the domain lookingglass.fict.book, whether
it is local or remote, and the remaining two rules handle all other
domains, with special action for connection refusal from hosts that were
not obtained from an MX record.

The final rule in a retry configuration should always have asterisks in the
first two fields so as to provide a general catch-all for any addresses
that do not have their own special handling. This example tries every 15
minutes for 2 hours, then with intervals increasing by a factor of 1.5 up
to 16 hours, then every 8 hours up to 5 days.

When computing the next retry time, the algorithm definitions are scanned
in order until one whose cutoff time has not yet passed is reached. This is
then used to compute a new retry time that is later than the current time.
In the case of fixed interval retries, this simply means adding the
interval to the current time. For geometrically increasing intervals, retry
intervals are computed from the rule's parameters until one that is greater
than the previous interval is found. The main configuration variable
retry_interval_max limits the maximum interval between retries.

A single remote domain may have a number of hosts associated with it, and
each host may have more than one IP address. Retry algorithms are selected
on the basis of the domain name, but are applied to each IP address
independently. If, for example, a host has two IP addresses and one is
broken, Exim will generate retry times for it and will not try to use it
until its next retry time comes. Thus the good IP address is likely to be
tried first most of the time.

Retry times are hints rather than promises. Exim does not make any attempt
to run deliveries exactly at the computed times. Instead, a queue-running
process starts delivery processes for delayed messages periodically, and
these attempt new deliveries only for those addresses that have passed
their next retry time. Therefore, whatever you set in the retry rules, the   |
minimum time between retries is the interval between queue-running pro-      |
cesses. There is no point in setting retry times of 15 minutes if your       |
queue-runners happen only once an hour.                                      |


32.1 Long-term failures

Special processing happens when an address has been failing for so long
that the cutoff time for the last algorithm has been reached. If this is
the case for a local delivery, or for all IP addresses associated with a
remote delivery, a subsequent delivery failure causes Exim to give up on
the address, and a delivery error message is generated. In order to cater
for new messages that may use the failing address, however, a next retry
time is still computed from the final algorithm, and is used as described
below.

If the delivery is a local one, one delivery attempt is always made for any
subsequent messages. If it fails, the address fails immediately. The post-
cutoff retry time is not used.

If the delivery is remote, there are two possibilities, controlled by the
delay_after_cutoff option of the smtp transport. The option is true by
default and in that case:

     Until the post-cutoff retry time for one of the IP addresses is
     reached, any attempt to deliver to the failing address is bounced
     immediately. After that time, one new delivery attempt is made to
     those IP addresses that are past their retry times, and if that still
     fails, the address is bounced and new retry times are computed.

In other words, Exim delays retrying an IP address after the final cutoff
time until a new retry time is reached, and can therefore bounce an email
address without ever trying a delivery when machines have been down for a
long time. This ensures that few resources are wasted in repeatedly trying
to delivery to a broken destination, but if it does recover, Exim will
eventually notice.

If delay_after_cutoff is set false, Exim behaves differently. If all IP
addresses are past their final cutoff time, Exim tries to deliver to those
IP addresses that have not been tried since the message arrived. If there
are none, or if they all fail, the address is bounced. In other words, it
does not delay when a new message arrives, but tries the expired addresses
immediately, unless they have been tried since the message arrived. If
there is a continuous stream of messages for the failing domains, unsetting
delay_after_cutoff means that there will be many more attempts to deliver
to failing IP addresses than when delay_after_cutoff is true.

An additional rule is needed to cope with cases where a host is intermit-
tently available, or when a message has some attribute that prevents its
delivery when others to the same address get through. Because some messages
are successfully delivered, the 'retry clock' keeps getting restarted, and
so a message could remain on the queue for ever. To prevent this, if a
message has been on the queue for longer than the cutoff time of any
applicable retry rule, the associated email address is failed after its
next temporary delivery error. A new retry time is not computed in this
case, so that other messages for the same address are considered
immediately.

Even with this rule a large queue of messages can take a long time to clear
if some occasionally get delivered, because the intermittent failures delay
delivery attempts on the others (and the above rule acts only after a
delivery attempt). There is therefore an ultimate clean-up rule which
causes all the remaining addresses in a message to be failed, whether or
not there has just been a delivery attempt, if the message has been on the
queue for longer than the longest cutoff time for any retry rule in the
configuration file.

The data in the retry hints database can be inspected by using the
exim_dumpdb or exim_fixdb utility programs (see chapter 47). The latter
utility can also be used to change the data. The exinext utility script can
be used to find out what the next retry times are for the hosts associated
with a particular mail domain, and also for local deliveries that have been
deferred.



                           33. ADDRESS REWRITING


Some people believe that configured address rewriting is a Mortal Sin.
Others believe that life is not possible without it. Exim provides the
facility; you do not have to use it. There are two cases that are commonly
encountered:

 .   The company hitch.fict.book has a number of machines that exchange
     mail with each other behind a firewall, but only a single gateway to
     the outer world. The gateway rewrites *.hitch.fict.book as
     hitch.fict.book.

 .   A machine rewrites the local parts of its own users so that, for
     example, fp42@hitch.fict.book becomes Ford.Prefect@hitch.fict.book.

In general, rewriting addresses from one's own system or domain has some
legitimacy. Rewriting other addresses should be done only with great care
and in special circumstances.

Rewriting of headers happens when a message is received, which is why it is
possible to rewrite the Bcc header (though Exim removes a Bcc header only
when the -t option is used). It does not apply to headers that are added by
the generic transport option add_headers.

Rewriting rules for envelope addresses are applied to new addresses that
are generated by aliasing or forwarding operations, unless no_rewrite is
set on the relevant directors.

Exim's rewriting configuration appears as the sixth part of the runtime
configuration file. It can be tested by the -brw command line option. This
takes an address (which can be a full RFC 822 address) as its argument. The
output is a list of how the address would be transformed by the rewriting
rules for each of the different places it might appear, that is, for each
different header and for the envelope sender and recipient fields.

The rewriting configuration consists of lines of rewriting rules in the
form

  <source pattern>  <replacement>  <flags>

The rules are scanned in order and relacements from earlier rules can
themselves be replaced as a result of later rules (but see the 'q' flag).
Long rules can be split over several lines by terminating all but the last
with a backslash character. Leading white space on continuation lines is
ignored. If the replacement string contains spaces, which can happen for
certain forms of expansion expression, it must be enclosed in double
quotes, and the normal quoting conventions apply inside them.

$local_part and $domain can be used in the replacement string to refer the
the address that is being rewritten. Note that complete lookup-driven
rewriting can be done by a line of the form

  *@*   ${lookup ...

where the lookup key is derived from $1 and $2 or $local_part and $domain.


33.1 Rewriting patterns

The source pattern can be one of the following forms. Note that it is not
enclosed in quotes, and there is no special processing of any characters.
In particular, if it is a regular expression, \ characters must not be
doubled.

 .   An address containing a local part and a domain, either of which may
     start with an asterisk, implying independent wildcard matching, for
     example

       *@orchestra-land.fict.book

 .   A local part, possibly starting with an asterisk, and a lookup item
     (as in a domain list), for example

       root@lsearch;/special/domains

     If there is an asterisk in the local part, the value of the wild part
     is placed in the first numerical variable. If the lookup is a partial
     one, the wild part of the domain is placed in the next numerical
     variable, the fixed part of the domain is placed in the succeeding
     variable. Thus, for example, if the address foo@bar.baz.com is pro-
     cessed by a rewriting rule of the form

       *@partial-dbm;/some/dbm/file    <replacement string>

     and the key in the file that matches the domain is *.baz.com, then

       $1 = foo
       $2 = bar
       $3 = baz.com

     If the address foo@baz.com is looked up, this matches the same
     wildcard file entry, and in this case $2 is set to the empty string,
     but $3 is still set to 'baz.com'. If a non-wild key is matched in a
     partial lookup, then again $2 is set to the empty string and $3 is set
     to the whole domain. For non-partial lookups, no numerical variables
     are set.

 .   A lookup without a local part, for example

       partial-dbm;/rewrite/database

     This works as for an "address-list" configuration item - the domain is
     first looked up, possibly partially, and if that fails, the whole
     address is then looked up (not partially). When a partial lookup
     succeeds, the numerical variable $1 contains the wild part of the
     domain, and $2 contains the fixed part.

 .   A regular expression. This is matched against the entire address, with
     the domain part lower-cased.


33.2 Rewriting replacements

The replacement is a string which is expanded. Within the expansion, the
variables $local_part and $domain refer to the address that is being
rewritten. If the pattern is a regular expression, the numerical variables
refer to the bracketed sub-expressions therein, with ${0} referring to the
entire address. For example, if the pattern

  ^(red|white).king@(wonderland|lookingglass).fict.book$

is matched against the address red.king@lookingglass.fict.book then

  ${0}   is red.king@lookingglass.fict.book
  ${1}   is red
  ${2}   is lookingglass

If the pattern is not a regular expression, the numerical variables refer
to the character strings matched by asterisks, with ${1} associated with
the first asterisk. Once again, ${0} refers to the entire address. For
example, if the pattern

  *queen@*.fict.book

is matched against the address hearts-queen@wonderland.fict.book then

  ${0}   is hearts-queen@wonderland.fict.book
  ${1}   is hearts-
  ${2}   is wonderland

Note that if the local part does not start with an asterisk, but the domain
does, then it is ${1} that contains the wild part of the domain.


33.3 Rewriting flags

The flag characters may appear in any order. There are two flags which
control the way the rewriting process works: 'q' and 'w'. If the 'q' flag
is set on a rule, then no further rewriting rules are considered for an
address that has matched the rule's pattern.

When an address in a header is rewritten, the rewriting normally applies
only to the working part of the address, with any comments and RFC 822
'phrase' left unchanged. For example, rewriting might change

  From: Ford Prefect <fp42@restaurant.hitch.fict.book>

into

  From: Ford Prefect <prefectf@hitch.fict.book>

Sometimes there is a need to replace the whole address item, and this can
be done by adding the flag letter 'w' to a rule. If this is set on a rule
that causes an address in a header to be rewritten, the entire address is
replaced, not just the working part. The replacement must be a complete RFC
822 address, including the angle brackets if necessary. When the 'w' flag
is set on a rule that causes an envelope address to be rewritten, all but
the working part of the replacement address is discarded.

The remainder of the flags field may be empty, in which case the rewriting
rule applies to all headers and to both the sender and recipient fields of
the envelope. Otherwise, one or more of the following letters can be given
to control which addresses are rewritten:

  E       rewrite all envelope fields
  F       rewrite the envelope From field
  T       rewrite the envelope To field
  b       rewrite the Bcc header
  c       rewrite the Cc header
  f       rewrite the From header
  h       rewrite all headers
  r       rewrite the Reply-to header
  s       rewrite the Sender header
  t       rewrite the To header

You should be particularly careful about rewriting Sender headers, and
restrict this to special known cases in your own domains.


33.4 Rewriting examples

Here is an example of the two common rewriting paradigms:

  *@*.hitch.book.fict  $1@hitch.book.fict
  *@hitch.book.fict    ${lookup{$1}dbm{/etc/realnames}\
                       {$value}fail}@hitch.book.fict bcfrF

Note the use of 'fail' in the lookup expansion. This causes the string
expansion to fail, and in this context it has the effect of leaving the
original address unchanged, but Exim goes on to consider subsequent
rewriting rules, if any, since the 'q' flag is not present in that rule. An
alternative to 'fail' would be to supply ${1} explicitly, which would cause
the rewritten address to be the same as before, at the cost of a small bit
of processing. Not supplying either of these is an error, since the
rewritten address would then contain no local part.

Exim does not handle addresses in the form of 'bang paths'. If it sees such
an address it treats it as an unqualified local part which it qualifies
with the local qualification domain (if the source of the message is local
or if the remote host is permitted to send unqualified addresses).
Rewriting can sometimes be used to handle simple bang paths with a fixed
number of components. For example, the rule

  ^([^!]+)!(.*)@your\.domain$   $2@$1

rewrites a two-component bang path 'host.name!user' as the domain address
'user@host.name'.



                     34. THE DEFAULT CONFIGURATION FILE


The default configuration file supplied with Exim as configure.default
is suffient for a host with simple mail requirements. It contains comments   |
about options you might want to set, but which it lets default, together     |
with the following actual settings:                                          |
                                                                             |
                                                                             |
34.1 Main configuration settings                                             |
                                                                             |
There are three explicit options in this section:                            |
                                                                             |
  host_lookup_nets = 0.0.0.0/0                                               |
                                                                             |
This specifies the sending IP networks for which a DNS reverse lookup is     |
done, in order to get the host name from the IP address of an incoming       |
message. The default setting matches all IP addresses. The host name         |
appears in the log and in messages' Received headers.                        |
                                                                             |
  sender_host_reject_relay = *                                               |
                                                                             |
This prevents all other hosts from using your host as a mail relay. This     |
setting is here because there has been a lot of relay abuse on the           |
Internet. If you want to provide relaying services, you will have to change  |
this option, and/or set relay_domains. See chapter 40 for more details.      |

As the primary_hostname, qualify_domain, and local_domains options are not
specified, they will all take the name of the local host, as obtained by
the uname() function, as their value.


34.2 Transport configuration settings

Five local transports and one remote transport are defined. The first
one is

  local_delivery:
    driver = appendfile
    file = /var/mail/${local_part}

which is set up to deliver to local mailboxes in a traditional 'sticky bit'
directory. To deliver into files in users' home directories, a configur-
ation such as

  local_delivery:
    driver = appendfile
    file = /home/${local_part}/inbox

should be substituted. An alternative setting for the file option is

    file = ${home}/inbox

The second local transport is

  address_pipe:
    driver = pipe
    return_output

This transport, whose name (address_pipe) is conventional, is automatically
used by Exim when a local part that is expanded via an alias or forward
file causes delivery to a pipe. Any output from the pipe is returned to the
sender of the message. The third local transport is

  address_file:
    driver = appendfile

This transport, whose name (address_file) is conventional, is automatically
used by Exim when a local part that is expanded via an alias or forward
file causes delivery to a specified file (by generating a path name not
ending in '/'). The fourth local transport is

  address_directory:
    driver = appendfile
    no_from_hack
    prefix = ""
    suffix = ""

This transport, whose name (address_directory) is conventional, is auto-
matically used by Exim when a local part that is expanded via an alias or
forward file into a path name ending in '/', which causes delivery to a new
file in the specified directory. In this case there is no need for the
conventional message separators that separate multiple messages in a single
file. The final local transport is

  address_reply:
    driver = autoreply

This transport, whose name (address_reply) is conventional, is automati-
cally used by Exim when a local part that is expanded via a filter file
causes an automatic reply to a message to be generated. The only remote
transport is

  remote_smtp:
    driver = smtp

This transport is used to do external deliveries over SMTP, with default
options.


34.3 Director configuration settings

Three directors are specified for the default configuration. Note that the
order of director definitions matters. The first director causes local
parts to be checked against the system alias file, which is searched
linearly:

  system_aliases:
    driver = aliasfile
    file = /etc/aliases
    search_type = lsearch

The second director comes into play if a local part does not match a system
alias:

  userforward:
    driver = forwardfile
    no_verify
    file = .forward
  # filter

An attempt is made to look for a file called .forward in the home directory
of a local user. However, this director is skipped when verifying
addresses. The filter option is commented out in the default configuration.
Thus .forward files are treated in the conventional manner, but filtering
can be enabled by removing the # character. The final director is

  localuser:
    driver = localuser
    transport = local_delivery

This checks that a local part is the login of a local user, and if so,
directs the message to be delivered using the local_delivery transport.


34.4 Router configuration settings

Two routers are defined in the default configuration. The first is

  lookuphost:
    driver = lookuphost
    transport = remote_smtp

and its default settings cause it to look up the domain in the DNS, in
order to determine the host to which a message should be sent, using the
smtp transport. The second router is

  literal:
    driver = ipliteral
    transport = remote_smtp

This handles 'domains' that are actually RFC 822 domain literals, that is,
IP addresses enclosed in square brackets.


34.5 Retry rules

A single retry rule is given in the default configuration:

  *    *   F,2h,15m; G,16h,2h,1.5; F,4d,8h

This causes any temporarily failing address to be retried every 15 minutes
for 2 hours, then at intervals increasing by a factor of 1.5 until 16 hours
have passed, then every 8 hours up to 4 days.


34.6 Rewriting configuration

There are no rewriting rules in the default configuration file.



                        35. MULTIPLE USER MAILBOXES


The wild card facility of the generic prefix and suffix options for
directors allows you to configure Exim to permit users to make use of
arbitrary local part prefixes or suffixes in any way they wish. A director
such as

  userforward:
    driver = forwardfile
    suffix = -*
    suffix_optional
    filter
    file = .forward

runs a user's .forward file for all local parts of the form "username-*".
Within the filter file the user can distinguish different cases by testing
the variable local_part_suffix. For example:

  if $local_part_suffix contains -special then
    save /home/$local_part/Mail/special
  endif

If the filter file does not exist, or does not deal with such addresses,
they fall through to subsequent directors, and, assuming no subsequent use
of the suffix option is made, they presumably fail. Thus users have control
over what suffixes are valid.

Alternatively, a suffix can be used to trigger the use of a different
.forward file - which is the way a similar facility is implemented in
another MTA:

  userforward:
    driver = forwardfile
    suffix = -*
    suffix_optional
    filter
    file = .forward${local_part_suffix}

If there is no suffix, .forward is used; if the suffix is "-special", for
example, then .forward-special is used. Once again, if the appropriate file
does not deal with the address, it is passed on to subsequent directors.



                   36. USING EXIM TO HANDLE MAILING LISTS


Exim can be used to run simple mailing lists, but for large and/or           |
complicated requirements, the use of specialized mailing list software is    |
recommended.                                                                 |

The forwardfile director can be used to handle mailing lists where each
list is maintained in a separate file, which can therefore be managed by an
independent manager. The domains director option can be used to run these
lists in a separate domain from normal mail. For example:

  lists:
    driver = forwardfile
    domains = lists.ref.book
    no_more
    file = /opt/lists/${local_part}
    no_check_local_user
    forbid_pipe
    forbid_file
    errors_to = ${local_part}-request@lists.ref.book

The domain lists.ref.book must appear as one of the domains in the
local_domains configuration option. This director is used only when an
address refers to that domain. Because the no_more option is set, if the
local part of the address does not match a file in the /opt/lists
directory, causing the director to fail, no subsequent directors are tried,
and the whole delivery fails.

The no_check_local_user option stops Exim insisting that the local
part is the login id of a local user. The forbid_pipe and forbid_file
options prevent a local part from being expanded into a file name or a
pipe delivery.

The errors_to option specifies that an delivery errors caused by addresses
taken from a mailing list are to be sent to the given address rather than
the original sender of the message. However, before acting on this, Exim
verifies the error address, and ignores it if verification fails.

In the example above, mail sent to dicts@lists.ref.book is passed on to
those addresses contained in /opt/lists/dicts, with error reports directed
to dicts-request@lists.ref.book, provided that this address can be veri-     |
fied. For example, there could be a file called /opt/lists/dicts-request     |
containing the address(es) of this particular list's manager(s), but other   |
approaches, such as setting up an earlier director (possibly using the       |
prefix or suffix options) to handle addresses of the form owner-xxx or xxx-  |
request, are possible.                                                       |

If an entry in a forward file contains a syntax error, Exim normally defers
delivery of the entire message. This may not be appropriate when the list
is being maintained automatically from address texts supplied by users. If
the skip_syntax_errors option is set on the forwardfile director, it just
skips entries that fail to parse, noting the incident on the log. If in
addition syntax_errors_to is set to a valid address, messages about skipped
addresses are sent to it.

It is not advisable to have list files that are NFS mounted, since the
absence of the mount cannot be distinguished from a non-existent file. One
way round this is to use an aliasfile director where the alias file is
local and contains a list of the lists, and each alias expansion is simply
an 'include' item to get the list from a separate, NFS mounted file. If
no_freeze_missing_include is set for the aliasfile director, an unavailable
file then just causes delivery to be deferred.


36.1 Closed mailing lists

The examples so far have assumed open mailing lists, to which anybody may
send mail. It is also possible to set up closed lists, where mail is
accepted from specified senders only. This is done by making use of the
generic senders option. The following example uses the same file for each
list, both as a list of recipients and as a list of permitted senders. In
this case, it is necessary to set up a separate director to handle the
'-request' address.

  # Handle mail to xxx-request@lists.ref.book;
  # anybody can mail to this address.

  lists_request:
    driver = forwardfile
    domains = lists.ref.book
    no_more
    suffix = -request
    file = /opt/lists/${local_part}${local_part_suffix}
    no_check_local_user

  # Handle mail to xxx@lists.ref.book;
  # only the subscribers to a list may mail to it.

  lists:
    driver = forwardfile
    domains = lists.ref.book
    no_more
    require_files = /opt/lists/${local_part}
    senders = lsearch;opt/lists/${local_part}
    file = /opt/lists/${local_part}
    no_check_local_user
    forbid_pipe
    forbid_file
    skip_syntax_errors
    errors_to = ${local_part}-request@lists.ref.book

The require_files option is needed to ensure that the file exists before
trying to search it via the senders option; an attempt to search a non-
existent file causes Exim to panic. If the file does not exist - that is,
if the list is unknown, the director fails, but because no_more is set, no
further directors are tried, and so Exim gives up.



                            37. VIRTUAL DOMAINS


There are a number of ways in which virtual domains can be handled in Exim.
As this seems to be quite a common requirement, some ways of doing this are
described here. These are not the only possibilities.


37.1 All mail to a given host

Simply sending all mail for a domain to a given host isn't really a virtual
domain; it is just a routing requirement that can be handled by a
domainlist router.

To send all mail for a domain to a particular local part at a given host,
define the domain as local, then process it with a smartuser director that
sets the new delivery address and passes the message to an smtp transport
which specifies the host. Alternatively, use a forwardfile director point-
ing to a fixed file name; the file can contain any number of addresses to
which each message is forwarded.


37.2 Virtual domain not preserving envelope

A virtual domain that does not preserve the envelope information when
delivering can be handled by an alias file defined for a local domain. If
you are handling a large number of local domains, you can define them as a
file lookup. For example:

  local_domains = "your.normal.domain:\
                   dbm;/customer/domains"

Where /customer/domains is a dbm file built from a source file that
contains just a list of domains:

  # list of virtual domains for customers
  customer1.domain
  customer2.domain

This can be turned into a dbm file by exim_dbmbuild.

You can then set up a director to handle the customer domains, arranging a
separate alias file for each domain. A single director can handle all of
them if the names follow a fixed pattern. Permissions can be arranged so
that appropriate people can edit the alias files. The domains option
ensures that this director is used only for the customer domains. The DBM
file lookup is cached, so it isn't too inefficient to do this. The no_more
setting ensures that if the lookup fails, Exim gives up on the address
without trying any subsequent directors.

  virtual:
    driver = aliasfile
    domains = dbm;/customer/domains
    no_more
    file = /etc/mail/$domain
    search_type = lsearch

A succesful aliasing operation results in a new envelope recipient address,
which is then directed or routed from scratch.


37.3 Virtual domain preserving envelope

If you want to arrange for mail for a given domain to be sent on to a host
that is dependent on the local part, without changing the envelope
recipient of the message, then the following is one way of doing it.

Set up the domains as local, and create an aliasfile director for them, as
above, but in addition, specify a transport for the director:

  virtual:
    driver = aliasfile
    domains = dbm;/customer/domains
    transport = virtual_smtp
    no_more
    file = /etc/mail/$domain
    search_type = lsearch

Each domain has its own alias file, but the provision of a transport means
that this is used purely as a check list of local parts. The data portion
of each alias is not used.

The transport has to look up the appropriate host to which the message must
be sent:

  virtual_smtp:
    driver = smtp
    hosts = ${lookup{$domain}dbm{/virtual/routes}{$value}fail}

The file /virtual/routes contains lines of the form

  customer1.domain:  cust1.host
  customer2.domain:  cust2.host

and the messages get delivered with RCPT TO (the envelope) containing the
original destination address (e.g. postmaster@customer1.domain). In fact,
you could use the same file for /virtual/routes and /customer/domains,
since the lookup on the latter doesn't make any use of the data - it's just
checking that the file contains the key.



                     38. INTERMITTENTLY CONNECTED HOSTS


It is becoming quite common (because it is cheaper) for hosts to connect to
the Internet periodically rather than remain connected all the time. The
normal arrangement is that mail for such hosts accumulates on a system that
is permanently connected.

If such a 'holding system' is running Exim, then it should be configured
with a long retry period for the intermittent host. For example:

  cheshire.wonderland.fict.book    *   F,24h,5d

This stops a lot of failed delivery attempts from occurring, but Exim
remembers which messages it has queued up for that host. Once the
intermittent host comes online, forcing delivery of one message (either by
using the -M or -R options, or by using the ETRN SMTP command - see
smtp_etrn_hosts) causes all the queued up messages to be delivered, often
down a single SMTP connection. While the host remains connected, any new
messages get delivered immediately.



                     39. VERIFICATION OF INCOMING MAIL


Exim always checks the syntax of SMTP commands, and rejects any that are     |
invalid. There are a number of options that cause Exim to verify the         |
semantic validity of the data in an incoming SMTP message. Verification      |
failures can cause the message to be rejected, or they can just be logged.   |
Other types of control over incoming mail are discussed in subsequent        |
chapters.                                                                    |
                                                                             |
                                                                             |
39.1 Host verification                                                       |
                                                                             |
The name of the sending host is looked up using gethostbyaddr() if its IP    |
address matches one of the networks specified in host_lookup_nets (which is  |
unset in the Exim binary, but in the default configuration file is set to    |
match all hosts). In some environments this might involve an expensive DNS   |
lookup, so some sites may wish to disable it. However, an SMTP server for    |
local desktop systems (which are frequently misconfigured) can normally      |
look up their host names cheaply. This improves the contents of Exim's logs  |
by including the correct host names.                                         |
                                                                             |
Even if its address doesn't match host_lookup_nets, a sending host's real    |
name is looked up from its IP address if the argument it provides for the    |
HELO or EHLO command is the local host's own name, or the name of one of     |
its local domains, which seems to be a fairly common misconfiguration.       |
                                                                             |
A host name that is obtained from looking up the sender's IP address is      |
placed in the $sender_host_name variable. If no lookup was done, or if the   |
lookup failed, that variable is left empty. Failure to look up the sending   |
host's name is not of itself an error, nor is it by default an error for     |
the name given in the HELO or EHLO commands (which is placed in              |
$sender_host_helo) to be different.                                          |
                                                                             |
The RFCs specifically state that mail should not be refused on the basis of  |
the HELO or EHLO commands. However, there are installations that do want to  |
be strict in this area, and to support them, Exim has the helo_verify        |
option.                                                                      |
                                                                             |
When helo_verify is set, a HELO or EHLO command must precede any MAIL        |
commands in an incoming SMTP connection. If there wasn't one, all MAIL       |
commands are rejected with a permanent error code. In addition, the          |
argument supplied by HELO or EHLO is verified. If it is in the form of a     |
literal IP address in square brackets, it must match the actual IP address   |
of the sending host. If it is a domain name, then the sending host's name    |
is looked up from its IP address (whether or not it matches                  |
host_lookup_nets) and compared against it. If the comparison fails, the IP   |
addresses associated with the HELO or EHLO name are looked up using          |
gethostbyname() and compared against the sending host's IP address. If none  |
of them match, the HELO or EHLO command is rejected with a permanent error   |
code, and an entry is written in the main and reject logs.                   |


39.2 Sender verification

When the sender_verify configuration option is set, Exim checks the senders
of incoming SMTP messages, that is, the addresses given in the SMTP MAIL
FROM commands. The check is performed by running the same verification code
as is used then Exim is called with the -bv option. The check is performed
when the MAIL FROM command is received. If the address cannot immediately
be verified (typically because of DNS timeouts), a temporary failure error
response (code 451) is given to the MAIL FROM command, unless
sender_try_verify is set, in which case the message is accepted with a
warning message.

What happens if verification fails depends on the setting of the
sender_verify_reject option. If it is set (the default) then the message is
rejected. Otherwise a warning message is logged, and processing continues.

Because remote postmasters always want to see the message headers when
there is a problem, Exim does not give an error response immediately a
sender address fails (permanently or temporarily), but instead it reads the
data for the message first. The headers of rejected messages are written to
the rejectlog file, for use in tracking down the problem or tracing mail
abusers. Up to three envelope recipients are also logged with the headers.

Unfortunately, there are a number of mailers in use that treat any SMTP
error response given after the data has been transmitted as a temporary
failure. Exim sends code 554 when it rejects a message because of a bad
sender, and RFC 821 is quite clear in stating that all codes starting with
5 are always 'permanent negative completion' replies. However, it does not
give any guidance as to what should be done on receiving such replies, and
some mailers persist in trying to send messages when they receive such a
code at the end of the data.

To get round this, Exim keeps a database in which it remembers the bad
sender address and host name when it rejects a message. If the same host
sends the same bad sender address within 24 hours, Exim rejects the message
at the MAIL FROM stage, before it reads the data for the message. This
should prevent the sender from trying to send the message again, but there
seem to be plenty of broken mailers out there that do keep on trying,
sometimes for days on end.

In an attempt to shut such MTAs up, if the same host sends the same bad
sender for a third time within 24 hours, MAIL FROM is accepted, but all
subsequent RCPT TO commands are rejected with a 550 error code. This means
'unknown user' and if a remote mailer doesn't treat that as a hard error,
it is very seriously broken.

The sender_verify_except_hosts and sender_verify_except_nets options can be
used to specify hosts and RFC 1413 idents or IP networks for which sender
verification is not applied. If a cluster of hosts all check incoming
external messages, there is no need to waste effort checking mail sent
between them. For example:

  sender_verify_except_hosts = "*.ref.book:exim@mailer.fict.book"

It is unfortunately the case that lots of messages are sent out onto the
Internet with invalid senders. In some cases, the message itself contains a
valid return address in one of its headers. If the sender_verify_fixup
option is set as well as sender_verify, Exim does not reject a message if
the sender is invalid, provided it can find a Sender, Reply-to, or From
header (whose existence is checked in that order) and that header contains
a valid address. Instead, it replaces the sender with the valid address,
and records the fact that it has done so by adding a header of the form:

  X-BadReturnPath: <invalid address> rewritten using <name> header

The fixup happens for both permanent and temporary errors. This covers the
case when the bad addresses refer to some DNS zone whose nameservers are
unreachable. This approach is, of course, fixing the symptom and not the
disease.

If sender_verify_fixup is set when sender_verify_reject is false, Exim does  |
not modify the message, but records in the log the fixup it would have       |
made.                                                                        |


39.3 Header verification

Exim's sender verification options can be used to block messages with bad
envelope senders. However, if a message arrives with a null envelope
sender, that is, if the SMTP command was

  MAIL FROM:<>

then Exim has nothing to check, and is forced to accept the message (unless
it fails a other checks, of course). If headers_sender_verify_errmsg is
set, then for messages that have null senders (purporting to be mail
delivery error messages), Exim does some checking of the RFC 822 headers.
It looks for a valid address in the Sender, Reply-To, and From headers, in
that order, and if one cannot be found, the message is rejected, unless
headers_checks_fail is false, in which case it just makes a warning entry
in the reject log.

Unfortunately, because it has to read the message before doing this check,
the rejection happens after the end of the data, and it is known that some
mailers do not treat hard (5xx) errors correctly at this point - they keep
the message on their spools and try again later, but that is their problem,
though it does waste some resources.

The option headers_sender_verify is also available. It insists on there
being a valid Sender, Reply-to, or From header on all incoming SMTP
messages, not just those with null senders.

The sender_verify_except_hosts and sender_verify_except_nets options pro-    |
vide a means of excepting hosts from the header sender verification checks.  |

A common spamming ploy is to send syntactically invalid headers such as

  To: @

The option headers_check_syntax causes Exim to check the syntax of all
headers that can contain lists of addresses (Sender, From, Reply-to, To,
Cc, and Bcc) on all incoming messages (both local and SMTP). This is a
syntax check only. Like the headers_sender_verify options, the rejection
happens after the end of the data, and it is also controlled by
headers_checks_fail; if that is false, a bad message is accepted, with a
warning on the rejectlog.


39.4 Receiver verification

By default, Exim just checks the syntax of addresses given in the SMTP RCPT
TO command. This minimizes the time required for an SMTP message transfer,
and also makes it possible to provide special processing for unknown local
parts in local domains, by using a smartuser director to pass messages with
unknown local parts to a script or to another host.

Some installations prefer to check receiver addresses as they are received.
If the receiver_verify option is set, the same code that is used by the -bv
option is used to check incoming addresses, unless the remote host matches
an entry in receiver_verify_except_hosts or receiver_verify_except_nets. If
verification fails, a permanent negative response is given to the RCPT TO
command. If there is a temporary failure, a temporary error is given,
unless receiver_try_verify is set, in which case the address is accepted.

It is also possible to restrict the addresses that are verified to certain
domains by setting receiver_verify_addresses, and receiver verification can
also be made conditional on the sender address by setting
receiver_verify_senders and/or receiver_verify_senders_except. All of these
options operate only when receiver_verify or receiver_try_verify is set.



                 40. OTHER POLICY CONTROLS ON INCOMING MAIL


Exim provides a number of facilities for controlling incoming mail from      |
remote hosts, in addition to the verification options described in the       |
previous chapter. These controls can be used to stop unwanted messages       |
getting into your machine. After a message has been accepted, the filtering  |
mechanism described in chapter 41 can be used to check it before going       |
ahead with delivery.                                                         |
                                                                             |
An MTA is said to "relay" a message if it receives it from some host and     |
delivers it directly to another host as a result of a remote address         |
contained within it. Expanding a local address via an alias or forward file  |
and then passing the message on to a remote host does not count as           |
relaying. There are special options for controlling which remote hosts may   |
use the local host as a relay.                                               |
                                                                             |
The options described in this chapter control three stages of checking that  |
are applied to an incoming SMTP message:                                     |
                                                                             |
(1)  At the start of an SMTP connection, a check on the remote host is       |
     made, leading to one of the following conclusions:                      |
                                                                             |
     (i)  No mail whatsoever is acceptable from the remote host.             |
                                                                             |
     (ii) The remote host is permitted to send messages to local recipients  |
          only, but is not permitted to use the local host as a relay.       |
                                                                             |
     (iii)The remote host is permitted to send messages to local recipi-     |
          ents, and can also use the local host as a relay to certain        |
          specified domains only.                                            |
                                                                             |
     (iv) The remote host is permitted to send mail to any recipient.        |
                                                                             |
     If the host is completely unacceptable, the SMTP connection may be      |
     rejected immediately, or (depending on the configuration) the message   |
     may be refused later on by a rejection at the end of the message (so    |
     the headers can be logged) or by rejecting every recipient.             |
                                                                             |
(2)  The message's sender, which is obtained from the MAIL FROM command, is  |
     checked. Again there is a choice of immediate rejection, or delayed     |
     rejection of all recipients.                                            |
                                                                             |
(3)  Unless there are no controls on relaying, each recipient address is     |
     checked as it obtained from a RCPT TO command.                          |
                                                                             |
These checks are all in addition to any verification that may be enabled.    |
The following sections give details of the various checking options.         |
                                                                             |
                                                                             |
40.1 Host checking using RBL                                                 |
                                                                             |
The Realtime Blocking List (RBL) is a blacklist of hosts that is maintained  |
in the DNS. See http://maps.vix.com/rbl/ for the background to this. If the  |
rbl_domains option is set, Exim looks up inverted incoming IP addresses in   |
each of the given domains. For example, if the setting is                    |
                                                                             |
  rbl_domains = rbl.maps.vix.com:local.rbl.xxx.yyy                           |
                                                                             |
and an SMTP call is received from the host whose IP address is 131.111.8.1,  |
then DNS lookups for address records for                                     |
                                                                             |
  1.8.111.131.rbl.maps.vix.com                                               |
  and                                                                        |
  1.8.111.131.local.rbl.xxx.yyy                                              |
                                                                             |
are done. If an RBL lookup succeeds, the message is rejected by refusing     |
all recipients, that is, by giving permanent error returns to all RCPT TO    |
commands, except for any recipients that are listed in                       |
recipients_reject_except. It is fairly common to set                         |
                                                                             |
  recipients_reject_except = postmaster@your.domain                          |
                                                                             |
in order to accept mail to postmaster from blacklisted hosts. When a         |
message is to be rejected, a TXT record is looked up in the DNS, and if it   |
exists, its contents are returned as part of the 550 rejection message. If   |
a lookup times out or otherwise fails to give a decisive answer, the mail    |
is not blocked.                                                              |
                                                                             |
Networks and individual hosts can be excepted from RBL checking by setting   |
rbl_except_nets to match them.                                               |
                                                                             |
If rbl_reject_recipients is turned off, then any hosts that are found by     |
searching rbl_domains are just logged rather than causing the message's      |
recipients to be rejected.                                                   |
                                                                             |
If rbl_warn_header is true (the default) and rbl_reject_recipients is        |
false, an X-RBL-Warning header is added to the message, containing the RBL   |
warning text. This can be detected later by the system-wide filter file, or  |
in individual users' private filter files.                                   |
                                                                             |
                                                                             |
40.2 Other host checking                                                     |
                                                                             |
If sender_host_accept is set, Exim accepts mail only from a host (plus       |
ident) that matches one of its entries; however, it rejects any call that    |
matches sender_host_reject. Thus sender_host_reject can be used to cut out   |
exceptions from a wildcarded item in sender_host_accept.                     |
                                                                             |
Calls are rejected as a result of these options by sending a 5xx error code  |
as soon as the connection is received. Since this does not relate to any     |
particular message, the remote host is likely to keep on trying to send      |
mail (possibly to an alternative MX host) until it times out. This may be    |
what is wanted in some circumstances (for example, you want temporarily to   |
hold back incoming mail).                                                    |
                                                                             |
When dealing with incoming spam, however, one wants a message to be          |
rejected once and for all, and sender_host_reject_recipients should be used  |
instead of sender_host_reject. A call from a host which matches this option  |
is not rejected at the start; instead, every RCPT TO command is subse-       |
quently rejected. This should cause the remote MTA to cease trying to        |
deliver the message.                                                         |
                                                                             |
The format of the the accept and reject options is a colon-separated list    |
of domain items, as described in section 7.11, including RFC 1413 ident      |
values associated with any of them. When an ident value is preceded by an    |
exclamation mark, it matches any RFC 1413 identification other than the      |
given one. For example,                                                      |
                                                                             |
  sender_host_accept = root@hub.biog.book                                    |
                                                                             |
accepts calls only from root on the host hub.biog.book, while                |
                                                                             |
  sender_host_reject = !root@hub.biog.book                                   |
                                                                             |
accepts calls from any host except those from hub.biog.book made by a non-   |
root user. The host names in these entries can be wildcarded, or can be      |
regular expressions. However, this flexibility is gained at the cost of      |
performance, particularly when a daemon listener is used.                    |
                                                                             |
If a complete host name is given, it is looked up using gethostbyname()      |
when the daemon starts up, and subsequently the checks can be performed      |
using only the IP address. On the other hand, if a wildcarded name or        |
regular expression is given, the check has to be performed by doing a        |
reverse lookup on the IP address for each call, in order to get the host     |
name to match against the wildcarded string. Therefore, it is best to avoid  |
wild cards and regular expressions wherever possible, apart from the case    |
of a single * character, which matches anything, and which is recognized     |
specially.                                                                   |
                                                                             |
For each of the options described above there is a corresponding option      |
which defines a set of hosts by an IP network number and a mask. They are    |
sender_net_accept, sender_net_reject, and sender_net_reject_recipients.      |
                                                                             |
Each entry in one of these lists consists of an IP network number and a      |
mask, separated by a slash. For example:                                     |
                                                                             |
  sender_net_accept = 131.111.0.0/16                                         |
  sender_net_reject = 131.111.8.0/24                                         |
                                                                             |
accepts calls only from the 131.111.0.0 network, unless the call is from     |
the 131.111.8.0 subnet. The host and net tests interact - for example, a     |
call from a network listed in sender_net_accept is rejected if the host      |
appears in sender_host_reject.                                               |
                                                                             |
                                                                             |
40.3 Sender checking                                                         |
                                                                             |
Incoming messages can be rejected on the basis of the sender address, as     |
given in the MAIL FROM command. A list of senders to reject is set by the    |
sender_reject configuration option; see its description in chapter 10 for    |
details. There is also a sender_accept option for use in special cases, and  |
a sender_reject_except option to list exceptions.                            |
                                                                             |
Some MTAs continue to try to deliver a message even after receiving a 5xx    |
error code for MAIL FROM. The alternative configuration option               |
sender_reject_recipients is provided for use in such cases. It accepts the   |
MAIL FROM command but rejects all subsequent RCPT TO commands. There is      |
also a corresponding sender_accept_recipients option.                        |
                                                                             |
                                                                             |
40.4 Control of relaying                                                     |
                                                                             |
There are two aspects of control over relaying via the local host, which     |
might be termed 'incoming' and 'outgoing'. A host which is acting as a       |
gateway or an MX backup is concerned with incoming relaying from arbitrary   |
hosts to a specific set of domains. A host which is acting as a smart host   |
for a number of clients is concerned with outgoing relaying from those       |
clients to the Internet at large. Often the same host is fulfilling both     |
functions.                                                                   |
                                                                             |
Incoming relaying is controlled by restricting the domains to which an       |
arbitrary host may send; outgoing relaying is controlled by restricting the  |
hosts which may send to an arbitrary domain. There is a certain pleasing     |
symmetry in this.                                                            |
                                                                             |
The relaying check happens whenever a message's recipient is received, that  |
is, immediately after a RCPT TO command. The first check is whether the      |
address would cause relaying at all: if its domain matches something in      |
local_domains then it is destined to be handled on the local host as a       |
local address, and relaying is not involved.                                 |
                                                                             |
Otherwise, there is first a check for legitimate incoming relaying, by       |
seeing if the domain matches anything in relay_domains, or, when             |
relay_domains_include_local_mx is set, if it is a domain whose lowest MX     |
record points to the local host. If it does match, this is an acceptable     |
incoming relay, and it is permitted to proceed.                              |
                                                                             |
For example, if the FooBar company has a firewall machine through which all  |
mail from external hosts must pass, and this machine's configuration         |
contains                                                                     |
                                                                             |
  local_domains = foobar.com                                                 |
  relay_domains = *.foobar.com                                               |
                                                                             |
then mail from external hosts is rejected, unless it is for a domain ending  |
in foobar.com.                                                               |
                                                                             |
If a recipient address represents an outgoing relay, it is accepted only if  |
the sending host is permitted to relay to arbitrary domains, and if the      |
sender address is acceptable. The following options specify the set of       |
hosts:                                                                       |
                                                                             |
  sender_host_accept_relay                                                   |
  sender_net_accept_relay                                                    |
  sender_host_reject_relay                                                   |
  sender_net_reject_relay                                                    |
                                                                             |
If all four are unset then                                                   |
                                                                             |
 .   If relay_domains is set, that is, if the host has been set up with      |
     specific incoming relaying, no hosts are permitted to relay to          |
     arbitrary domains, that is, no outgoing relaying is permitted.          |
                                                                             |
 .   If relay_domains is unset, all hosts are permitted to relay to          |
     arbitrary domains and no relay control is exercised.                    |
                                                                             |
When at least one of the host or net options is set, the address is          |
accepted only if sender_host_accept_relay and sender_net_accept_relay are    |
both null or if the host matches one of their patterns, and if the host      |
does not match any pattern in sender_host_reject_relay or                    |
sender_net_reject_relay.                                                     |
                                                                             |
For example, if the FooBar company's IP network is 192.153.213.0, and all    |
hosts on that network send their outgoing mail via the firewall machine,     |
then its configuration should contain                                        |
                                                                             |
  sender_net_accept_relay = 192.153.213.0/24                                 |
                                                                             |
in order to allow only the internal hosts to use it as a relay to arbitrary  |
domains.                                                                     |
                                                                             |
In addition to the tests on the host, if sender_address_relay is set, the    |
sender's address from the MAIL FROM command must match one of its patterns   |
to allow outgoing relaying to an arbitrary domain. However, if               |
relay_match_host_or_sender is set, an address is accepted for outgoing       |
relaying if either the host is acceptable or the sender matches an item in   |
sender_address_relay. Of course, sender addresses can easily be forged, but  |
the sender check does mean you can prevent some kinds of unwanted mail from  |
going through your host.                                                     |
                                                                             |
If you don't want to do any relaying at all, then relay_domains should be    |
left unset, and sender_host_reject_relay set to *, in which case the only    |
acceptable recipient addresses are those that contain a local domain. This   |
is the setting in the default configuration file. It does not prevent a      |
local user from setting up forwarding to to some external system, nor does   |
it prevent the 'percent hack' from working; you should ensure that           |
percent_hack_domains is left unset if you don't want to support it.          |
                                                                             |
If you have a list of domains that any host can relay to, but there are no   |
hosts or networks that are permitted to relay to arbitrary domains (for      |
example, if your host is an MX backup for some domains), then set            |
relay_domains. This implies sender_host_reject_relay = * if no host or net   |
accept or reject options are set.                                            |
                                                                             |
If the recipient address is an RFC 821 source routed address, that is, an    |
address of the form <@hop1,@hop2:user@domain>, it is the final domain which  |
is tested. By default, however, Exim will send the message to the hop1       |
domain, unless it is a local domain. The collapse_source_routes option can   |
be used to prevent this.                                                     |
                                                                             |
As all the relay checking is done at RCPT TO time on incoming messages, the  |
directors and routers are not involved. Depending on the the configuration   |
of these drivers, an address that appears to be remote to the relay          |
checking code (i.e. its domain does not match local_domains) may neverthe-   |
less end up being delivered locally, and similarly an apparently local       |
address may end up being delivered to some other host.                       |
                                                                             |
None of the relay checking applies when mail is passed to Exim locally       |
using the -bm, -bs or -bS options, but it does apply when -bs is used from   |
inetd.                                                                       |
                                                                             |
Exim does not attempt to fully qualify domains at RCPT TO time. If an        |
incoming message contains a domain which is not fully qualified, it is       |
treated as a non-local, non-relay domain (unless partial domains are         |
included in local_domains or relay_domains, but this is not recommended).    |
The use of domains that are not fully qualified is non-standard, but it is   |
a commonly encountered usage when an MTA is being used as a smart host by    |
some remote UA. In this situation, it would be usual to permit the UA host   |
to relay to any domain, so in practice there is not normally a problem.      |
                                                                             |
                                                                             |
40.5 Prohibition messages                                                    |
                                                                             |
It is possible to add a site-specific message to the error response that is  |
sent when an incoming SMTP command fails for policy reasons, for example if  |
the sending host is in a host reject list. This is done by setting the       |
option prohibition_message, which causes one or more additional response     |
lines with the same error code and a multiline marker to be output before    |
the standard response line. For example, setting                             |
                                                                             |
  prohibition_message = "contact postmaster@my.site for details"             |
                                                                             |
causes the response to a RCPT TO command for a blocked recipient to be       |
                                                                             |
  550-contact postmaster@my.site for details                                 |
  550 rejected: administrative prohibition                                   |
                                                                             |
The string is expanded, and so it can do file lookups if necessary. If it    |
ends up as an empty string, no additional reponse is transmitted. To make    |
it possible to distinguish between the several different types of adminis-   |
trative rejection, the variable $prohibition_reason is set to a character-   |
istic text string in each case. The possibilities are as follows:            |
                                                                             |
  host_reject                the host is in a reject list                    |
  host_accept                the host is not in an accept list               |
  host_reject_recipients     the host is in a reject_recipients list         |
  host_accept_recipients     the host is not in an accept_recipients list    |
  host_reject_relay          the host is in a reject_relay list              |
  host_accept_relay          the host is in an accept_relay list             |
  sender_reject              the sender is in a reject list                  |
  sender_accept              the sender is not in an accept list             |
  sender_verify              sender verification failed                      |
  sender_relay               the sender is not in a sender relay list        |
                                                                             |
In addition, if relay_match_host_or_sender is set, there are                 |
                                                                             |
  sender+host_reject_relay  the sender is not in a sender relay list         |
                              and the host is in a reject relay list         |
  sender+host_accept_relay  the sender is not in a sender relay list         |
                              and the host is not in an accept relay list    |
                                                                             |
For example, if the configuration contains                                   |
                                                                             |
  prohibition_message = "${lookup{$prohibition_reason}lsearch\               |
    {/etc/exim/reject.messages}{$value}}"                                    |
                                                                             |
and the file /etc/exim/reject.messages contains (inter alia)                 |
                                                                             |
  host_accept_relay:  host not in relay list                                 |
                                                                             |
then a response to a relay attempt might be                                  |
                                                                             |
  550-host not in relay list                                                 |
  550 relaying to <santa@northpole.com> prohibited by administrator          |
                                                                             |
Because some administrators may want to put in quite long messages, and it   |
isn't possible to get newlines into the text returned from an lsearch        |
lookup, Exim treats the vertical bar character as a line separator in this   |
text. If you want the looked up text to be re-expanded, you can use the      |
expand operator. For example, the setting                                    |
                                                                             |
  prohibition_message = "${lookup{$prohibition_reason}lsearch\               |
    {/etc/exim/reject.messages}{${expand:$value}}}"                          |
                                                                             |
when used with a file entry of the form                                      |
                                                                             |
  host_accept_relay:  Host $sender_fullhost is not permitted to              |
                      relay |through $primary_hostname.                      |
                                                                             |
might produce                                                                |
                                                                             |
  550-Host that.host.name [111.222.3.4] is not permitted to relay            |
  550-through this.host.name.                                                |
  550 relaying to <penguins@southpole.com> prohibited by administrator       |
                                                                             |
This facility does not apply when the prohibition is due to an entry in a    |
Realtime Blocking List and a message is available from a DNS TXT record. In  |
that circumstance, the TXT message is used instead.                          |



                     41. SYSTEM-WIDE MESSAGE FILTERING


The previous chapters described checks that can be applied to messages       |
before they are accepted by a host. There is also a mechanism for checking   |
messages once they have been received, but before they are delivered. This   |
is the system message filter. It operates in a similar manner to users'      |
filter files, but which is run just once per message at the start of a       |
delivery attempt, before any routing or directing is done.                   |

The message_filter option names the filter file.

The filter file can contain any of the normal filtering commands, as
described in the separate document "Exim's User interface to mail filter-
ing". However, because the system filter is run just once per message, the
variable $local_part is not available, nor does the 'personal' condition
make any sense. In addition to the generally available filter commands
there are two extra commands which are available only in system filter
files:

  freeze   the message is frozen unless it was previously manually thawed
           (see below)
  fail     all recipients are failed

There is also an extra expansion variable, $recipients, containing a list
of all the recipients of the message, separated by commas and white space.
The extra commands and variable are not available to ordinary users and are
faulted in normal use and in testing via -bf.

If the filter sets up any deliveries, an extra header line is added to them
with the name X-Envelope-To. This contains up to 100 of the original
message's envelope recipients. If the filter specifies any significant
deliveries, then the message's own recipients list is ignored; otherwise it
is added to any recipients set up by the filter.

The freeze command is ignored if the message has been manually unfrozen and
not manually frozen since. This means that automatic freezing by a system
filter can be used as a way of checking out suspicious messages. If a
message is found to be all right, manually unfreezing it allows it to be
delivered.

Take great care with the fail option when basing the decision to fail on
the contents of the message, because this option causes a normal delivery
error message to be generated, and it will of course include the contents
of the original message and will therefore trigger the fail option again
(causing a mail loop) unless steps are taken to prevent this. Testing the
error_message condition is one way to prevent this. You could use, for
example

  if
    $message_body contains "this is spam" and not error_message
  then
    fail
  endif

though of course that might still let through unwanted messages. The
alternative is clever checking of the body and/or headers to detect error
messages caused by the filter.



                            42. SMTP PROCESSING


Two kinds of SMTP processing are supported: SMTP over TCP/IP, and so-called
'batched SMTP'. The latter is the name for a process in which batches of
messages are stored in files, using SMTP commands as separators and to
contain the envelope information. Such batches are delivered to or received
from other systems using some transport mechanism other than Exim. For each
kind of SMTP processing there are two aspects: outgoing and incoming.


42.1 Outgoing SMTP over TCP/IP

This is implemented by the smtp transport. Exim does not at present use
ESMTP for sending mail, as it has no facilities for using the information
it might get back. At some point in the future this may change.

Responses from the remote host are supposed to be terminated by CR followed
by LF. However, there are known to be hosts that do not send CR characters,
so in order to be able to interwork with such hosts, Exim treats LF on its
own as a line terminator.

If a message contains a number of different addresses, all those that
resolve to the same set of hosts, in the same order, are sent in a single
SMTP transaction, even if they are for different domains, unless there are
more than the setting of the max_rcpts option in the smtp transport allows,
in which case they are split into groups containing no more than max_rcpts
addresses each. The order of hosts with identical MX values is not
significant when checking whether addresses can be batched in this way.

Exim's retry hints are based on host name plus IP address, so if one
address of a multi-homed host is broken, it will soon be skipped most of
the time. When the smtp transport suffers a temporary failure while trying
to deliver a message, Exim updates its wait-smtp database, which contains
records indexed by host name that remember which messages are waiting for
each particular host.

When a message is successfully delivered over a TCP/IP SMTP connection,
Exim looks in the wait-smtp database to see if there are any queued
messages waiting for the host to which it is connected. If it finds one, it
creates a new process using the -MC option and passes the TCP/IP socket to
it. The new process does only those deliveries that are routed to the
connected host, and may in turn pass the socket on to a third process, and
so on. The batch_max option of the smtp transport can be used to limit the
number of messages sent down a single connection. The second and subsequent
messages delivered down an SMTP connection are identified in the main log
by the addition of an asterisk after the closing square bracket of the IP
address.


42.2 Incoming SMTP over TCP/IP

Incoming SMTP messages can be accepted in one of two ways: by running a
listening daemon, or by using inetd. In the latter case, the entry in
/etc/inetd.conf should be like this:

  smtp  stream  tcp  nowait  exim  /exim/exim  in.exim  -bs

Exim distinguishes between this case and the case of a user agent using the
-bs option by checking whether the standard input is a socket using the
getpeername() function.

Commands from the remote host are supposed to be terminated by CR followed
by LF. However, there are known to be hosts that do not send CR characters,
so in order to be able to interwork with such hosts, Exim treats LF on its
own as a line terminator.

When a message is successfully received, Exim includes the local message id
in its response to the final '.' that terminates the data. If the remote
host logs this text it can help with tracing what has happened to a
message.

The Exim daemon can limit the number of simultaneous incoming connections
it is prepared to handle (see the smtp_accept_max configuration option).
Additional connection attempts are rejected using the SMTP temporary error
code 421. On some operating systems the SIGCHLD signal that is used to
detect when a subprocess has finished can get lost at busy times. However,
the daemon looks for completed subprocesses every time it wakes up, so
provided there are other things happening (new incoming calls, starts of
queue runs), the completion of processes created to handle incoming calls
should get noticed eventually. If, however, Exim appears not to be
accepting as many incoming connections as expected, sending the daemon a
SIGCHLD signal will wake it up and cause it to check for any completed
subprocesses.

Exim can reserve some SMTP slots for specific hosts or networks, and can
also be set up to reject SMTP calls from non-reserved hosts or networks at
times of high system load - for details see the smtp_accept_reserve,
smtp_load_reserve, smtp_reserve_hosts and smtp_reserve_nets configuration
options.

If the queue_only (or -odq option) option is not set, the daemon normally
starts a delivery process for each message received. However, the number of
simultaneously running delivery processes started in this way can be
limited by the smtp_accept_queue option, and the queue_only_load option can
specify a system load average above which immediate delivery is suspended.
When either limit is reached, subsequently received messages are just put
on the input queue.

The controls just described that involve counts of incoming SMTP calls
(smtp_accept_max and smtp_accept_reserve) are not available when Exim is
started up from the inetd daemon, since each connection is handled by an
entirely separate Exim process. Control by load average is, however,
available.

The SMTP command VRFY is accepted only when the configuration option
smtp_verify is set, and if so, it runs exactly the same code as when Exim
is called with the -bv option.

The SMTP command EXPN is is permitted only if the calling host matches
smtp_expn_hosts (add 'localhost' if you want calls to 127.0.0.1 to be able
to use it) or smtp_expn_nets. A single-level expansion of the address is
done. If an unqualified local-part is given, it is qualified with
qualify_domain.

The SMTP command DEBUG is not supported at all.

RFC 1985 describes a new SMTP command called ETRN which is designed to
overcome the security problems of the TURN command (which has fallen into
disuse). Exim recognizes ETRN if the calling host matches an entry in
smtp_etrn_hosts or smtp_etrn_nets. The ETRN command is concerned with
'releasing' messages that are awaiting delivery to certain hosts. As Exim
does not organize its message queue by host, the only form of ETRN that is
supported is the one where the text starts with the '#' prefix, where the
remainder of the text is specific to the SMTP server. A valid ETRN command
causes a run of Exim with the -R option to happen, with the remainder of
the ETRN text as its argument. For example,

  ETRN #brigadoon

causes a delivery attempt on all messages with undelivered addresses
containing the text 'brigadoon'.


42.3 Outgoing batched SMTP

Both the appendfile and pipe transports can be used for handling batched
SMTP. Each has an option called bsmtp which, if set to anything other than
'none' causes the message to be output in SMTP format. The message is
written to the file or pipe preceded by the SMTP commands MAIL FROM and
RCPT TO, and followed by a line containing a single dot. The SMTP command    |
HELO is not normally used, but if the transport's bsmtp_helo option is set   |
true, a HELO command line precedes each message.                             |

Lines in the message starting with a dot get an extra dot added. If the
prefix or suffix options are set, their contents are included after the
SMTP commands; normally they would be specified as empty, to override the
defaults. No return-path or delivery-date header is ever added.

The value of the bsmtp option determines how multiple addresses in a single
message may be batched, if other conditions permit. If the value of bsmtp
is 'one', then there is no batching, and a copy of the message is output
for each address. If the value is 'domain' then a single copy (with
multiple RCPT TO commands) is output for all addresses that have the same
domain. If the value is 'all' then only a single copy of the message is
written. The batching is further constrained by other parameters:

 .   If any of the transport's expandable strings contain a reference to
     $local_part, then no batching takes place.

 .   If any of the transport's expandable strings contains a reference to
     $domain, then only domain batching is done.

 .   Addresses are not batched if they have different error addresses or
     different associated hosts.

 .   The transport must set the uid and gid for delivery. If at some future
     time routers are allowed to set the uid/gid, then batching can only
     occur for addresses that have the same uid/gid set up.

Here is an example of a transport and router for batched SMTP:

  # transport
  smtp_appendfile:
    driver = appendfile
    directory = /var/bsmtp/${host}
    bsmtp = all
    prefix =
    suffix =

  # router
  route_append:
    driver = domainlist
    transport = smtp_appendfile
    route_list = "some.domain  batch.host"

This causes messages addressed to some.domain to be written in batched SMTP
format to /var/bsmtp/batch.host, with only a single copy of each message.
Note that prefix and suffix must be explicitly changed from their defaults.


42.4 Incoming batched SMTP

The -bS command line option causes Exim to accept one or more messages by
reading SMTP on the standard input, but to generate no responses. All
errors are reported by sending mail. If the caller is trusted, then the
senders in the MAIL FROM commands are believed; otherwise the sender is
always the caller of Exim. Unqualified senders and receivers are not
rejected (there seems little point) but instead just get qualified.
Receiver verification and administrative rejection is not done, even if
configured. HELO and EHLO act as RSET; VRFY, EXPN, ETRN, HELP, and DEBUG
act as NOOP; QUIT quits.



                           43. MESSAGE PROCESSING


Exim performs various transformations on the sender and recipient addresses
of all messages that it handles, and also on the messages' header lines.
Some of these are optional and configurable, while others always take
place. All of this processing, except rewriting as a result of routing,
happens when a message is received, before it is first written to the
spool.


43.1 Unqualified addresses

By default, Exim expects every address it receives from an external host to
be fully qualified. Unqualified addresses cause negative responses to SMTP
commands. However, because SMTP is used as a means of transporting messages
from MUAs running on personal workstations, there is sometimes a require-
ment to accept unqualified addresses from specified hosts or IP networks.

Exim has two pairs of options that separately control which hosts or
networks may send unqualified sender or receiver addresses in SMTP com-
mands. The options are sender_unqualified_hosts and
sender_unqualified_nets, and receiver_unqualified_hosts and
receiver_unqualified_nets. In all cases, if an unqualified address is
accepted, it is qualified by adding the value of qualify_domain or
qualify_receiver, as appropriate.

RFC 822 makes provision for headers starting with the string resent-. It
states that in general, the resent- fields should be treated as containing
a set of information that is independent of the set of original fields, and
that information for one set should not automatically be taken from the
other. If Exim finds any resent- headers in the message, it applies the
following transformations only to the resent- header set, leaving the
unqualified set alone.

Any addresses that are unqualified are made fully qualified by adding the
qualify_domain or qualify_recipient value, as appropriate. Unqualified
addresses are accepted only from local sources or from hosts that match one
of the receiver_unqualified or sender_unqualified options, as appropriate.


43.2 The Bcc header

If Exim is called with the -t option, to take recipient addresses from a
message's headers, it removes any Bcc header that may exist (after
extracting its addresses), unless the message has no To or Cc header, in
which case a Bcc header with no addresses is left in the message, in
accordance with RFC 822. If -t is not present on the command line, any
existing Bcc header is not removed.

If Exim is called to receive a message with the recipient addresses given
on the command line, and there is no Bcc, To, or Cc header in the message,
it normally adds a To header, listing the recipients. Some mailing list
software is known to submit messages in this way, and in this case the
creation of a To header is not what is wanted. If the always_bcc option is
set, Exim adds an empty Bcc header instead in this circumstance.


43.3 The Date header

If a message has no Date header, Exim adds one, giving the current date and
time.


43.4 The Delivery-date header

Delivery-date headers are not part of the standard RFC 822 header set. Exim
can be configured to add them to the final delivery of messages. (See the
delivery_date_add option in the appendfile and pipe transports.) They
should not be present in messages in transit. If the delivery_date_remove
configuration option is set (the default), Exim removes delivery-date
headers from incoming messages.


43.5 The Envelope-to header

Envelope-to headers are not part of the standard RFC 822 header set. Exim
can be configured to add them to the final delivery of messages. (See the
envelope_to_add option in the appendfile and pipe transports.) They should
not be present in messages in transit. If the envelope_to_remove configur-
ation option is set (the default), Exim removes envelope-to headers from
incoming messages.


43.6 The From header

If an incoming message does not contain a From header, Exim adds one
containing the sender's address. This is obtained from the message's
envelope in the case of remote messages; for locally-generated
messages the calling user's login name and full name are used to
construct an address, as described in section 43.12 below. They are
obtained from the environment variables USER and USERFULLNAME.


43.7 The Message-id header

If an incoming message does not contain a Message-id header, Exim con-
structs one and adds it to the message. The id is constructed from Exim's
internal message id, preceded by the letter E to ensure it starts with a
letter, and followed by @ and the primary host name. Additional information
can be included in this header by setting the message_id_header_text
option.


43.8 The Received header

A Received header is added at the start of every message. The contents of
this header are defined by the received_header_text configuration option,
and Exim automatically adds a semicolon and a timestamp to the configured
string.


43.9 The Return-path header

Return-path headers are defined as something the MTA may insert when it
does the final delivery of messages. (See the return_path_add option in the
appendfile and pipe transports.) Therefore, they should not be present in
messages in transit. If the return_path_remove configuration option is set
(the default), Exim removes Return-path headers from incoming messages.


43.10 The Sender header

For locally-originated messages, unless originated by a trusted user using
the -f or -bs command line option, any existing Sender header is removed. A
check is then made to see if the address given in the From header is the
correct (local) sender of the message. If not, a Sender header giving the
true sender address is added to the message. No processing of the Sender
header is done for messages originating externally.


43.11 The To header

If a message has no To, Cc, or Bcc header, Exim adds an empty Bcc header,
in accordance with RFC 822, except when the message is being received
locally with the recipients supplied on the command line. In this case, a
To header listing the recipients is normally added. Some mailing list
software is known to submit messages in this way, and in this case the
creation of a To header is not what is wanted. If the always_bcc option is
set, Exim adds an empty Bcc header instead in this circumstance. An
Apparently-to header is never added.


43.12 Constructed addresses

When Exim constructs a sender address for a locally-generated message, it
uses the form

  <user name> <<login>@<qualify_domain>>

For example:

  Zaphod Beeblebrox <zaphod@end.univ>

The user name is obtained from the -F command line option if set.  The
unknown_username option can be used to specify user names in cases
when there is no environment variable set. In all cases the user name
is made to conform to RFC 822 by quoting all or parts of it if
necessary.


43.13 Case of local parts

RFC 822 states that the case of letters in the local parts of addresses
cannot be assumed not to be significant. Exim preserves the case of local
parts of remote addresses. However, when it is processing an address in one
of its local domains, the case of letters in the local part is not
significant unless the locally_caseless option is set.


43.14 Rewriting addresses

Rewriting of sender and recipient addresses, and addresses in headers, can
happen automatically, or as the result of configuration options, as
described in chapter 33.

Automatic rewriting includes qualification, as mentioned above. The other
case in which it can happen is when an incomplete non-local domain is
given. The routing process may cause this to be expanded into the full
domain name. For example, a header such as

  To: hare@teaparty

might get rewritten as

  To: hare@teaparty.wonderland.fict.book

Rewriting as a result of routing is the one kind of message processing that
does not happen at input time, as it cannot be done until the address has
been routed.

Strictly, one should not do any deliveries of a message until all its
addresses have been routed, in case any of the headers get changed as a
result of routing. However, doing this in practice would hold up many
deliveries for unreasonable amounts of time, just because one address could
not immediately be routed. Exim therefore does not delay other deliveries
when routing of one or more addresses is deferred.



                       44. AUTOMATIC MAIL PROCESSING


This chapter describes some of the ways in which incoming mail can be
processed automatically, either on a system-wide basis, or as specified by
individual users.


44.1 System-wide automatic processing

Simple re-addressing of messages can be handled by aliasfile or forwardfile
directors. The particular case of mailing lists is covered in chapter 36.
Other kinds of automatic processing can be handled by suitable configur-
ations of directors and transports. As an example, here is an extract from
the configuration of a system which tries to send back helpful information
when a message is received for an unknown user. The last director in the
configuration is:

  unknownuser:
    driver = smartuser
    transport = unknownuser_pipe
    no_verify

This collects all the addresses whose local parts haven't been matched by
any other director, and directs them to a special pipe transport, whose
configuration is:

  unknownuser_pipe:
    driver = pipe
    command = /opt/exim/util/baduser.sh
    ignore_status
    return_output

The script is run, and it applies heuristics and a "soundex" search to
the local part, in an attempt to produce a list of possible users for
whom the message might have been intended. This is then included in a
message that is written to its standard output; Exim picks this up and
returns it to the sender as part of the delivery error message.

Chapter 41 describes how to arrange to run a system filter file once per     |
message. Sometimes there is a requirement to set up similar automatic        |
processing, but on a per-address basis, that is, the filter is run once for  |
each address. This can be done by using a director such as the following:    |

  filter_per_address:
    driver = forwardfile
    no_verify
    filter
    file = /etc/per-address-filter
    no_check_local_user

See the separate document entitled "Exim's User interface to mail filter-
ing" which describes the available filtering commands. Care should be taken
to ensure that none of the commands in the filter file specify a
significant delivery if the message is to go on to be delivered to its
intended recipient. The director will not then claim to have dealt with the
address, so it will be passed on to subsequent directors to be delivered in
the normal way. Note that a traditional (non-filter) .forward file does not
have this property, so cannot be used in this way, though you could use it
to forward all mail for a particular domain to a single recipient in a
different domain.


44.2 Automatic processing by users

Users can cause their mail to be processed automatically by creating
.forward files, provided that Exim's configuration contains an appropriate
forwardfile director. Traditionally, such files contain just a list of
forwarding addresses, local files, and pipe commands, but if the
forwardfile director has the filter option set, users can access Exim's
filtering facilities by beginning a .forward file with the text '# Exim
filter'. Details of the syntax and semantics of filter files are described
in a separate document entitled "Exim's User interface to mail filtering";
this is intended for use by end users.

The name .forward is purely conventional; a forwardfile director can be
configured to use any arbitrary name. As there are some finger daemons that
display the contents of users' .forward files, some sites might like to use
a different name when mail filtering is provided.

What users may do in their .forward files can be constrained by various
options of the forwardfile director:

 .   If the filter option is not set, then only traditional .forward files
     are permitted.

 .   If the forbid_file option is set, then neither a traditional .forward
     file, nor a filter file may direct that a message be appended to a
     particular local file. An attempt to do so causes a delivery error.

 .   if the forbig_log option is set, then the use of the log command in a
     filter file is not permitted.

 .   If the forbid_pipe option is set, then neither a traditional .forward
     file, nor a filter file may direct that a message be piped to a user-
     specified command. An attempt to do so causes a delivery error.

 .   If the forbid_reply option is set, then a filter file may not direct
     that a new mail message be created. An attempt to do so causes a
     delivery error.

If piping is permitted, the pipe transport that is used (conventionally
called address_pipe) can constrain the command to be taken from a particu-
lar set of files. Pipe commands generated from traditional .forward files
are not string-expanded, but when a pipe command is generated in a filter
file, each argument is separately expanded.

If delivery to specified files is permitted, the appendfile transport that
is used (conventionally called address_file) can specify that the file must
already exist, or can restrict the whereabouts of its creation by means of
the create_file option.


44.3 Simplified vacation processing

The traditional way of running the "vacation" program is for a user to set
up a pipe command in a .forward file. This is prone to error by
inexperienced users. There are two features of Exim that can be used to
make this process simpler for users:

 .   A local part prefix such as 'vacation-' can be specified on a director
     which causes the message to be delivered directly to the "vacation"
     program, or uses Exim's autoreply transport. The contents of a user's
     .forward file are then much simpler. For example:

       spqr, vacation-spqr

 .   The require_files generic director option can be used to trigger a
     vacation delivery by checking for the existence of a certain file in
     the user's home directory. The unseen generic option should also be
     used, to ensure that the original delivery also proceeds. In this
     case, all the user has to do is to create a file called, say,
     .vacation, containing a vacation message.

Another advantage of both these methods is that they both work even when
the use of arbitrary pipes by users is locked out.



                               45. LOG FILES


Exim writes four different log files into its main directory, unless
a runtime option called log_file_path is defined to specify a different
directory.

 .   The file called mainlog records the arrival of each message and each
     delivery in a single line in each case. The format is as compact as
     possible, in an attempt to keep down the size of log files. Two-
     character flag sequences make it easy to pick out these lines. A
     number of other events are also recorded on the main log. Some of
     these entries can be suppressed by changing the value of the log_level
     configuration option.

 .   The file called rejectlog records information from messages that are
     rejected as a result of a configuration option (that is, for policy
     reasons) for example, because their return paths are invalid. In this
     particular case, the headers are written to this log, following a copy
     of the one-line message that is also written to the main log. For
     other rejections, just a single line is written to the reject log.

 .   The file called paniclog is written when Exim suffers a disaster and
     has to bomb out. This should be checked regularly to pick up any
     problems. When exim cannot open its panic log, it tries as a last
     resort to write to the system log. This is opened with
     LOG_PID+LOG_CONS and the facility code of LOG_MAIL. The message itself
     is written at priority LOG_CRIT.

(Note: the OS/2 version does not yet include writing to the system
log. This will be corrected in a future release of Exim for OS/2.)

 .   On systems that support signal handlers that restart a system call on
     exit, Exim reacts to a USR1 signal by writing a line describing its
     current activity to a file called processlog. This makes it possible
     to find out what each exim process on a machine is currently doing.


45.1 Logging message reception

The format of the single-line entry in the main log that is written for
every message received is as in the example below, which is split over
several lines in order to fit it on the page:

1995-10-31 08:57:53 0tACW1-0005MB-00 <= kryten@dwarf.fict.book
  H=mailer.fict.book [123.123.123.123] U=exim
  P=smtp S=5678 id=<incoming message id>

The H and U fields identify the remote host and record the RFC 1413
identity of the user that sent the message, if one was received. The number  |
given in square brackets is the IP address of the sending host. If there is  |
just a single host name in the H field, as above, it has been verified to    |
correspond to the IP address (see the host_lookup_nets option). If the name  |
is in parentheses, it was the name quoted by the remote host in the SMTP     |
HELO or EHLO command, and has not been verified. If verification yields a    |
different name to that given for HELO or EHLO, then the verified name        |
appears first, followed by the HELO or EHLO name in parentheses.             |
                                                                             |
Misconfigured hosts (and mail forgers) sometimes put an IP address, with or  |
without brackets, in the HELO or EHLO command, leading to entries in the     |
log containing things like                                                   |
                                                                             |
  H=(10.21.32.43) [123.99.8.34]                                              |
  H=([10.21.32.43]) [123.99.8.34]                                            |
                                                                             |
which can be confusing. Only the final address in square brackets can be     |
relied on.                                                                   |

For locally generated messages, the H field is omitted, and the U field
contains the login name of the caller of Exim. The P field specifies the
protocol used to receive the message, the S field is the message size, and
the id field records the existing message id, if present.

If the log_received_sender option is on, the unrewritten original sender of  |
a message is added to the end of the log line that records the message's     |
arrival, after the word 'from'. If the log_received_recipients option is     |
on, a list of all the recipients of a message is added to the log line,
preceded by the word 'for'. The happens after any unqualified addresses are
qualified, but before any rewriting is done. if the log_subject option is
on, the subject of the message is added to the log line, preceded by T= (T
for 'topic', since S is already used for 'size').

A delivery error message is shown with the sender address '<>', and if it
is a locally-generated error message, this is normally followed by an item
of the form

  R=<message-id>

which is a reference to the local identification of the message that caused
the error message to be sent.


45.2 Logging Deliveries

The format of the single-line entry in the main log that is written for
every delivery is as in one of the examples below, for local or remote
deliveries, respectively. Each example has been split into two lines in
order to fit it on the page.

1995-10-31 08:59:13 0tACW1-0005MB-00 => marv <marv@hitch.fict.book>
  D=localuser T=local_delivery
1995-10-31 09:00:10 0tACW1-0005MB-00 => monk@holistic.fict.book
  R=lookuphost T=smtp H=holistic.fict.book [234.234.234.234]

For local deliveries, the original address is given in angle brackets after
the final delivery address, which might be a pipe or a file. If intermedi-
ate address(es) exist between the original and the final address, the last
of these is given in round brackets after the final address.

For remote deliveries, if the log_smtp_confirmation option is on, the
response to the final '.' in the SMTP transmission is added to the log
line, preceded by C=. If the final delivery address is not the same as the
original address (owing to changes made by routers), the original is shown
in angle brackets.

The generation of a reply message by a filter file gets logged as a
'delivery' to the addressee, preceded by '>'. The D and T items record the
director and transport. For remote deliveries, the router, transport, and
host are recorded.

When more than one address is included in a single delivery (e.g. two SMTP
MAIL FROM commands in one transaction) then the second and subsequent
addresses are flagged with -> instead of =>. When two or more messages are
delivered down a single SMTP connection, an asterisk follows the IP
addresses for the second and subsequent messages.

When the -N debugging option is used to prevent delivery from actually       |
occuring, log entries are flagged with '*>' instead of '=>'.                 |


45.3 Deferred deliveries

When a delivery is deferred, a line of the following form is logged:

1995-12-19 16:20:23 0tRiQz-0002Q5-00 == marvin@endrest.book
  T=smtp defer (146): Connection refused

In the case of remote deliveries, the error is the one that was given for
the last IP address that was tried. Details of individual SMTP failures are
also written to the log, so the above line would be preceded by something
like

1995-12-19 16:20:23 0tRiQz-0002Q5-00 Failed to connect to endrest.book
  [239.239.239.239]: Connection refused

When a deferred address is skipped because its retry time has not been
reached, a message is written to the log, but this can be suppressed by
changing the log_level option.


45.4 Delivery failures

If a delivery fails, a line of the following form is logged:

1995-12-19 16:20:23 0tRiQz-0002Q5-00 ** jim@trek99.film
  <jimtrek99.film>: unknown mail domain

This is followed (eventually) by a line giving the address to which the
delivery error has been sent.


45.5 Completion

A line of the form

  1995-10-31 09:00:11 0tACW1-0005MB-00 Completed

is written to the main log when a message is about to be removed from the
spool file at the end of its processing.


45.6 Log level

The log_level configuration option controls the amount of data written to
the main log. The higher the number, the more is written. A value of 6
causes all possible messages to appear, though higher levels may get
defined in future. Zero sets a minimal level of logging, with higher levels
adding the following, successively:

  1  rejections because of policy
     re-addressing by the system filter

  2  rejections because of message size

  3  verification failures

  4  SMTP timeouts
     SMTP connection refusals because too busy

  5  'retry time not reached [for any host]'
     'spool file locked'
     'message is frozen' (when skipping it in a queue run)
     'error message sent to ...'

  6  invalid HELO and EHLO arguments (see host_lookup_nets)

The default log level is 5, which is on the verbose side. Rejection
information is still written to the reject log in all cases.


45.7 Message log

In addition to the four main log files, Exim writes a log file for each
message that it handles. The names of these per-message logs are the
message ids, and they are kept in the msglog subdirectory of the spool
directory. A single line is written to the message log for each delivery
attempt for each address. It records either a successful delivery, or the
reason (temporary or permanent) for failure. When a local part is expanded
by aliasing or a forwarding file, a line is written to the message log when
all its child deliveries are completed. SMTP connection failures for each
remote host are also logged here. The log is deleted when processing of the
message is complete, unless preserve_message_logs is set, but this should
be used only with great care because they can fill up your disc very
quickly.



                         46. DAY-TO-DAY MANAGEMENT


This chapter describes some of the regular tasks that need to be done to
keep Exim running smoothly.

                                                                             |
46.1 The panic log                                                           |
                                                                             |
When certain disasters occur, Exim writes entries to its panic log. These    |
are often copied to the main log as well, but can get lost amid the mass of  |
other entries. The panic log should be empty under normal circumstances. It  |
is therefore a good idea to check it (or to have a cron script check it)     |
regularly, in order to become aware of any problems.                         |


46.2 The reject log

If checking of sender addresses on incoming mail is enabled, the headers of
rejected messages are written to the reject log. Other policy rejections
also cause entries in this log, which should be regularly inspected to
ensure that the checking is working properly, and to pick up errors such as
missing DNS entries.


46.4 Statistics

The eximstats script (see chapter 37) produces statistics about messages
received and delivered, by analysing log files.


46.5 What is Exim doing?

On systems that can restart a system call after receiving a signal, Exim
responds to the SIGUSR1 signal by writing a line describing what it is
doing to its processlog file. The exiwhat script (see chapter 37) sends the
signal to all Exim processes it can find, having first emptied the log
file. It then waits a bit before displaying the results. In order to run
exiwhat successfully you have to have sufficient privilege to send the
signal to the Exim processes, so it is normally run as root.

When the number of processes handling incoming SMTP calls is limited by
setting the smtp_accept_max option, the daemon uses the SIGCHLD signal to
detect when any of its subprocesses finishes. On some operating systems
this signal sometimes gets lost when the system is very busy. However,
Exim's daemon cleans up subprocesses every time it wakes up, so even if
SIGCHLD doesn't happen, the completion of subprocesses should eventually
get noticed.


46.6 Changing the configuration

A changed configuration file is picked up immediately by any Exim processes
that are subsequently started, and by any existing process that re-execs
Exim, but it will not be noticed by any existing processes. The daemon
process can be caused to restart itself by sending it the SIGHUP signal,
which should also be sent when a new version of the Exim binary is
installed. Restarting causes its process id to change. The current process
id is written to a file whose name depends on the type of daemon being run.
By default, the file is written in Exim's spool directory, but a compile-
time configuration of PID_FILE_PATH can be used to cause it to be placed
elsewhere. When the daemon is both listening for incoming SMTP on the
standard port and periodically starting queue runner processes, the file is
called exim-daemon.pid. If it is doing only one of these things, the option
that started it (either -bd or -q<time>) is added to the file name. It is
not necessary to use SIGHUP when changing the contents of any files
referred to in the configuration (e.g. alias files) since each delivery
process reads such files independently.


46.7 Watching the queue

The queue of messages awaiting delivery can be examined by running the Exim
monitor (see chapter 48), or by obeying "exim -bp" periodically. The
exiqsumm utility script can be called to obtain a summary of the waiting
messages for each domain, sorted by domain, age, or message count.

If any messages are frozen, their header files and message log files should
be examined to determine the cause of the problem. Once the problem is
believed to be fixed, the messages can be unfrozen by the administrator,
who can also kick off an immediate delivery attempt, and also change
recipient and sender addresses if necessary.


46.8 Holding domains

The options hold_domains and hold_domains_except allow mail for particular
domains to be held on the queue manually. These options are intended as
temporary operational measures for delaying the delivery of mail while some
problem is being sorted out, or some new configuration tested.



                             47. EXIM UTILITIES


A number of utility scripts and programs are supplied with Exim. Most of
them are built as part of the normal building process, but the log file
analyser is entirely free-standing.


47.1 Querying Exim processes

Exiwhat is not yet implemented under OS/2.

47.2 Summarising the queue

The exiqsumm utility is a Perl script, which reads the output of 'exim
-bp' and produces a summary of the messages by outputting a line like
the following for each domain:

    3   2322   74m   66m  msn.com

This contains the number of messages for that domain, their total volume,
and the lengths of time the oldest and the newest have been waiting. By
default the output is sorted on the domain name, but exiqsumm has the
options -a and -c, which cause it to be sorted by oldest message and by
count of messages, respectively.

The output of 'exim -bp' is based on the original addresses in the message,
so no addresses generated by aliasing or forwarding are included.
Consequently this applies also to the output from exiqsumm.


47.3 Extracting log information

The exigrep utility is a Perl script that extracts from one or more
log files all entries relevant to any message whose log entries
contain at least one that matches a given pattern. The pattern match
is case-insensitive. Thus one can search for all mail for a given user
or a given host, for example. The usage is:

  exigrep [-l] <pattern> [<log file>] ...

where the -l flag means 'literal', that is, treat all characters in the
pattern as standing for themselves. Otherwise the pattern must be a Perl
regular expression. If no file names are given on the command line, the
standard input is read.


47.5 Making DBM files

The exim_dbmbuild program reads an input file in the format of an alias
file (see chapter 22) and writes a DBM database using the lower-cased alias
names as keys and the remainder of the information as data. Two arguments
are required: the name of the input file (which can be a single hyphen to
indicate the standard input), and the base name of the output database. For
example:

  exim_dbmbuild /etc/aliases /etc/aliases

reads the system alias file and creates a DBM database using /etc/aliases
as the base name. In systems that use the ndbm routines, the database
consists of two files called (in this case) /etc/aliases.dir and
/etc/aliases.pag, while in systems using the ndbm interface to the db
routines a single file called /etc/aliases.db is used. If the native db
interface is in use (USE_DB is set in a compile-time configuration file)
then a single file with no added prefix is used. In this case the two file
names on the command line must be different. The utility in fact creates
the database under a temporary name, and then renames the file(s).


47.6 Individual retry times

This has also not been implemented yet under OS/2.


47.7 Database maintenance

Three utility programs are provided for maintaining the DBM files that Exim
uses to contain its delivery hint information. Each program requires two
arguments. The first specifies the name of Exim's spool directory, and the
second is the name of the database it is to operate on. These are as
follows:

 .   retry: the database of retry information

 .   reject: the database of information about rejected messages

 .   wait-smtp: the database of information about messages waiting for SMTP
     hosts

 .   serialize-smtp: the database of information about current connections
     to hosts which are restricted to one connection at once

The entire contents of a database are written to the standard output by the
exim_dumpdb program, which has no options or arguments other than the spool
and database names. For example, to dump the retry database:

  exim_dumpdb /var/spool/exim retry

Two lines of output are produced for each entry:

    T:mail.ref.book:242.242.242.242 146 77 Connection refused
  31-Oct-1995 12:00:12  02-Nov-1995 12:21:39  02-Nov-1995 20:21:39 *

The first item on the first line is the key of the record. It starts with
one of the letters D, R, or T, depending on whether it refers to a
directing, routing, or transport retry. For a local delivery, the next part
is the local address; for a remote delivery it is the name of the remote
host, followed by its failing IP address. Then there follows an error code,
an additional error code, and a textual description of the error.

The three times on the second line are the time of first failure, the time
of the last delivery attempt, and the computed time for the next attempt.
The line ends with an asterisk if the cutoff time for the last retry rule
has been exceeded.

Each output line from exim_dumpdb for the reject database consists of a
date and time, followed by the letter T or F, followed by the address that
was rejected, followed by the name of the host that sent the bad address
(as given in the SMTP HELO command). The letter is F if only one previous
rejection of this address has been done recently, and T if a second has
occurred, causing rejection of the MAIL FROM command, and subsequently
rejection of the RCPT TO commands.

Each output line from exim_dumpdb for the wait-smtp database consists of a
host name followed by a list of ids for messages that are or were waiting
to be delivered to that host. If there are a very large number for any one
host, continuation records, with a sequence number added to the host name,
may be seen. The data in these records is often out of date, because a
message may be routed to several alternative hosts, and Exim makes no
effort to keep cross references.

Each output line from exim_dumpdb for the serialize-wmtp database consists
of a host name preceded by the time that Exim made a connection to that
host. Exim keeps track of connections only for those hosts or networks that
have been configured for serialization.

The exim_tidydb utility program is used to tidy up the contents of the
databases. If run with no options, it removes all records from a database
that are more than 30 days old. The cutoff date can be altered by means of
the -t option, which must be followed by a time. For example, to remove all
records older than a week from the retry database:

  exim_tidydb -t 7d /var/spool/exim retry

For the wait-smtp database, the -f option can also be used (it has no
effect for other databases). This causes a check to be made to ensure that
message ids in database records are those of messages that are still on the
queue. Other message ids are removed, and if this leaves records empty,
they are also removed.

The exim_tidydb utility outputs comments on the standard output whenever it
removes information from the database. It is suggested that it be run
periodically on all three databases, but at a quiet time of day, since it
requires a database to be locked (and therefore inaccessible to Exim) while
it does its work.

The exim_fixdb program is a utility for interactively modifying databases.
Its main use is for testing Exim, but it might also be occasionally useful
for getting round problems in a live system. It has no options, and its
interface is somewhat crude. On entry, it prompts for input with a >
character. A key of a database record can then be entered, and the data for
that record is displayed.

If 'd' is typed at the next prompt, the entire record is deleted. For the
reject, wait-smtp, and serialize-smtp databases, that is the only operation
that can be carried out. For the retry database, each field is output
preceded by a number, and data for individual fields can be changed by
typing the field number followed by new data, for example:

  > 4 951102:1000

resets the time of the next delivery attempt. Time values are given as a
sequence of digit pairs for year, month, day, hour, and minute. Colons can
be used as optional separators.


47.8 Mail statistics

A Perl script called eximstats is supplied in the util directory. This has
been hacked about quite a bit over time. It now gives quite a lot of
information by default, but there are options for suppressing various parts
of it. Following any options, the arguments to the script are a list of
files, which should be main log files.

Eximstats extracts information about the number and volume of messages
received from or delivered to various hosts. The information is sorted both
by message count and by volume, and the top 50 hosts in each category are
listed on the standard output. For messages delivered and received locally,
similar statistics are produced per user.

The output also includes total counts and statistics about delivery errors,
and histograms showing the number of messages received and deliveries made
in each hour of the day. A delivery with more than one address in its
'envelope' (e.g. an SMTP transaction with more than one RCPT TO command) is
counted as a single delivery by eximstats.

Though normally more deliveries than receipts are reported (as messages may
have multiple recipients), it is possible for eximstats to report more
messages received than delivered, even though the spool is empty at the
start and end of the period in question. If an incoming message contains no
valid recipients, no deliveries are recorded for it. An error report is
handled as an entirely separate message.

Eximstats always outputs a grand total summary giving the volume and number
of messages received and deliveries made, and the number of hosts involved
in each case. It also outputs the number of messages that were delayed
(that is, not completely delivered at the first attempt), and the number
that had at least one address that failed.

The remainder of the output is in sections that can be independently
disabled or modified by various options. It consists of a summary of
deliveries by transport, histograms of messages received and delivered per
time interval (default per hour), information about the time messages spent
on the queue, a list of relayed messages, lists of the top 50 sending
hosts, local senders, destination hosts, and destination local users by
count and by volume, and a list of delivery errors that occurred.

The relay information lists messages that were actually relayed, that is,    |
they came from a remote host and were directly delivered to some other       |
remote host. A delivery that is considered as a relay by the checking        |
features described in 40.4, because its domain is not in local_domains,      |
might still end up being delivered locally under some configurations, and    |
if this happens it doesn't show up as a relay in the eximstats output.       |

The options for eximstats are as follows:


-nt    Suppress the statistics about delivery by transport.

-h<n>  This option controls the histograms of messages received and deliv-
       eries per time interval. By default the time interval is one hour.
       If -h0 is given, the histograms are suppressed; otherwise the value
       of <n> gives the number of divisions per hour, so -h2 sets an
       interval of 30 minutes, and the default is equivalent to -h1.

-q0    Suppress information about times messages spend on the queue.

-q<n1>...
       This option sets an alternative list of time intervals for the
       queueing information. The values are separated by commas and are in
       seconds, but can involve arithmetic multipliers, so for example you
       can set 3*60 to specify 3 minutes. A setting such as

         -q60,5*60,10*60

       causes eximstats to give counts of messages that stayed on the queue
       for less than one minute, less than five minutes, less than ten
       minutes, and over ten minutes.

-nr    Suppress information about messages relayed through this host.

-nr/pattern/
       Suppress information about relayed messages that match the pattern,
       which is matched against a string of the following form (split over
       two lines here in order to fit it on the page):                       |
                                                                             |
         H=<host> [<ip address>] A=<sender address> =>                       |
           H=<host> A=<recipient address>                                    |
                                                                             |
       for example                                                           |
                                                                             |
         H=in.host [1.2.3.4] A=from@some.where =>                            |
           H=out.host A=to@else.where                                        |
                                                                             |
       The sending host name appears in parentheses if it has not been       |
       verified as matching the IP address. The mail addresses are taken     |
       from the envelope, not the headers. This option allows you to screen
       out hosts whom you are happy to have using your host as a relay.

-t<n>  Sets the 'top' count to <n>. This controls the listings of the 'top
       <n>' hosts and users by count and volume. The default is 50, and
       setting 0 suppresses the output altogether.

-tnl   Omit local information from the 'top' listings.

-ne    Suppress the list of delivery errors.



                        49. SECURITY CONSIDERATIONS


This chapter discusses a number of issues concerned with security, some of
which are also covered in other parts of this manual.

For reasons that this author does not understand, some people have promoted
Exim as a 'particularly secure' mailer. Perhaps it is because of the
existence of this chapter in the documentation. However, the intent of the
chapter is simply to describe the way Exim works in relation to certain
security concerns, not to make any specific claims about the effectiveness
of its security as compared with other MTAs.

What follows is a description of the way Exim is supposed to be. Best
efforts have been made to try to ensure that the code agrees with the
theory, but an absence of bugs can never be guaranteed. Any that are
reported will get fixed as soon as possible.


49.2 Reading forward files

The forwardfile director does not necessarily have to read from users'
home directories. It can be given a directory explicitly. The above
remarks are applicable in this case also.

Forward files are permitted to contain :include: items unless forbidden by
setting forbid_include in the director.

When the filtering option is enabled for forward files, users can construct
pipe commands that contain data from the incoming message by quoting
variables such as $sender_address. To prevent the contents of inserted data
from interfering with a command, the string expansion is done after the
command line is split up into separate arguments, and the command is run
directly instead of passing the command line to a shell.


49.3 Delivering to local files

Full details of the checks applied by appendfile before it writes to a file
are given in chapter 14.


49.4 IPv4 source routing

Many operating systems suppress IP source-routed packets in the kernel, but
some cannot be made to do this. Exim is configured by default to log
incoming IPv4 source-routed TCP calls, and then to drop the call. These
actions can be independently turned off. Alternatively, the IP options can
be deleted instead of dropping the call. Things are all different in IPv6.
No special checking is currently done.


49.5 The VRFY, EXPN, and ETRN commands in SMTP

Support for these SMTP commands is disabled by default. The VRFY command
can be enabled by setting smtp_verify. The EXPN command can be enabled for
specific sets of hosts or nets by setting smtp_expn_hosts or
smtp_expn_nets, and there is a similar pair of options controlling ETRN.


49.8 Use of argv[0]

Exim examines the last component of argv[0], and if it matches one of a set
of specific strings, Exim assumes certain options. For example, calling
Exim with the last component of argv[0] set to 'rsmtp' is exactly
equivalent to calling it with the option -bS. There are no security
implications in this.


49.9 Use of %f formatting

The only use made of '%f' by Exim is in formatting load average values.
These are actually stored in integer variables as 1000 times the load
average. Consequently, their range is limited and so therefore is the
length of the converted output.


49.11 Use of sprintf()

A large number of occurrences of 'sprintf' in the code are actually calls
to string_sprintf(), a function which returns the result in malloc'd store.
The intermediate formatting is done into a large fixed buffer by a function
that runs through the format string itself, and checks the length of each
conversion before performing it, thus preventing buffer overruns. [This was
not true before Exim version 1.70.]

The remaining uses of sprintf() happen in controlled circumstances where
the output buffer is known to be sufficiently long to contain the converted
string.


49.12 Use of debug_printf() and log_write()

Arbitrary strings are passed to both these functions, but they do their
formatting by calling the function string_vformat(), which runs through the
format string itself, and checks the length of each conversion. [This was
not true before Exim version 1.70.]


49.13 Use of strcat() and strcpy()

These should be used only in cases where the output buffer is known to be
large enough to hold the result.



                         50. FORMAT OF SPOOL FILES


A message on Exim's spool consists of two files, whose names are the
message id followed by -D and -H, respectively. The data portion of the
message is kept in the -D file on its own. The message's 'envelope',
status, and headers are all kept in the -H file, whose format is described
in this chapter. Each of these two files contains the final component of
its own name as its first line. This is insurance against disc crashes
where the directory is lost but the files themselves are recoverable.

Files whose names end with -J may also be seen in the spool directory.
These are journal files, used to record addresses to which the message has
been delivered during the course of a delivery run. At the end of the run,
the -H file is updated, and the -J file is deleted.

The second line of the file contains the address of the message's
sender as transmitted on the 'envelope', contained in angle
brackets. In the case of incoming SMTP mail, this is the address given
in the MAIL FROM command. For locally generated mail, the sender
address is created by Exim from the login of the current user and the
configured qualify_domain, except when Exim is called by a trusted
user that supplied a sender address via the -f option. The sender
address is null if the message is a delivery failure report.

The third line contains two numbers. The first is the time that the
message was received, in the form supplied by the Unix time() function
- a number of seconds since the start of the epoch. The second number
is a count of the number of messages warning of delayed delivery that
have been sent to the sender.

There follow a number of optional lines, each of which starts with a hyphen
when present. These can appear in any order:

 .   -frozen <time>: The message is frozen, and the freezing happened at
     <time>. No deliveries will be attempted while the message remains
     frozen, but the auto_thaw configuration option can specify a time
     delay after which a delivery will be attempted.

 .   -host_name <text>: This records the name of the remote host from which
     the message was received.

 .   -host_address <address>: This records the IP address of the remote
     host from which the message was received.

 .   -ident <text>: This records the ident string obtained from the remote
     host from which the message was received.

 .   -local: The message is from a local sender.

 .   -localerror: The message is a locally-generated delivery error report.

 .   -manual_thaw: The message was frozen but has been thawed manually,
     that is, by an explicit Exim command rather than via the auto-thaw
     process.

 .   -resent: The message contains Resent- headers, so the alternative set
     of header names is to be used (see RFC 822).

 .   -user_null_sender: The message was received from an unprivileged user
     with the -f option specifying '<>' as the sender.

Following the options are those addresses to which the message is not to be
delivered. This set of addresses is initialized from the command line when
the -t option is used; otherwise it starts out empty. Whenever a successful
delivery is made, the address is added to this set. The addresses are kept
internally as a balanced binary tree, and it is a representation of that
tree which is written to the spool file. If an address is expanded via an
alias or forward file, the original address is added to the tree when
deliveries to all its child addresses are completed.

If the tree is empty, there is a single line in the spool file containing
just the text XX. Otherwise, each line consists of two letters, which are
either Y or N, followed by an address. The address is the value for the
node of the tree, and the letters indicate whether the node has a left
branch and/or a right branch attached to it, respectively. If branches
exist, they immediately follow. Here is an example of a three-node tree:

  YY darcy@austen.fict.book
  NN alice@wonderland.fict.book
  NN editor@thesaurus.ref.book

After the non-recipients tree, there is a list of the message's recipients.
This is a simple list, preceded by a count. It includes all the original
recipients of the message, including those to whom the message has already
been delivered. For example,

  4
  editor@thesaurus.ref.book
  darcy@austen.fict.book
  rdo@foundation
  alice@wonderland.fict.book

A blank line separates the envelope and status information from the headers
which follow. A header may occupy several lines of the file, and to save
effort when reading it in, each header is preceded by a number and an
identifying character. The number is the number of characters in the
header, including any embedded newlines and the terminating newline. The
character is one of the following:

  <blank>  header in which Exim has no special interest
   B       Bcc header
   C       Cc header
   F       From header
   P       Received header - P for 'postmark'
   R       Reply-to header
   S       Sender header
   T       To header
   *       replaced or deleted header

Deleted or replaced (rewritten) headers remain in the spool file for
debugging purposes. They are not transmitted when the message is delivered.
When Resent- headers are present, it is those headers that have the
appropriate flags. Here is a typical set of headers:

  111P Received: by hobbit.fict.book with local (Exim 0.17 #8)
          id E0tHplY-0000mG-00; Tue, 21 Nov 1995 10:17:32 +0000
  049  Message-Id: <E0tHplY-0000mG-00@hobbit.fict.book>
  038* X-rewrote-sender: bb@hobbit.fict.book
  042* From: Bilbo Baggins <bb@hobbit.fict.book>
  049F From: Bilbo Baggins <B.Baggins@hobbit.fict.book>
  099* To: alice@wonderland.fict.book, rdo@foundation,
   darcy@austen.fict.book, editor@thesaurus.ref.book
  109T To: alice@wonderland.fict.book, rdo@foundation.fict.book,
   darcy@austen.fict.book, editor@thesaurus.ref.book
  038  Date: Tue, 21 Nov 1995 10:17:32 +0000

The asterisked headers indicate that the envelope sender, From header, and
To header have been rewritten, the last one because routing expanded the
unqualified domain foundation.



                       51. ADDING NEW DRIVERS TO EXIM


Not yet written for under OS/2.

