Directors and routers have sufficiently many generic options in common to make
it worth documenting them jointly in this chapter, to save duplication. 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.

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, and the address is offered to
the next one. 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.

If this option is set and debugging is enabled (see -d, -v, and
debug_level), the string is expanded and included in the debugging
output. This is to help with checking out the values of variables and so on
when debugging driver configurations. For example, if a condition option
appears not to be working, debug_print could be used to output the variables
it references. The output happens after checks for domains, local_parts,
suffix and prefix, but before checking require_files and condition. A
newline is added to the text if it does not end with one.

If this option is set, the string is expanded, and is then interpreted as a
colon-separated list. Because of the expansion, if any of the items contain
backslash or dollar characters, they must be escaped with a backslash. If the
string is given in quotes, backslashes have to be escaped a second time.
However, a special case is made for the string `$key', which is commonly used
in query-style lookups. Because such lookups are individually re-expanded
later, when they are used, the string `$key' is passed unchanged through the
initial overall expansion.

The driver is skipped unless the current domain matches the list. If the match
is achieved by means of a file lookup, 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.

Delivery errors for any addresses handled or generated by the director or
router are sent to the address that results from expanding this string, if it
is set, and if it verifies as valid.
In other words, this option sets the value of the envelope sender address to be
used for deliveries associated with the driver. If it is unset, or fails to
verify,
the errors address associated with the incoming address (normally the sender)
is used. A typical use might be

errors_to = aliasmaster

The errors_to setting associated with an address can be overridden if it
subsequently passes through other directors or routers that have their own
errors_to settings.

String expansion is not applied to this option. The argument must be a
colon-separated list of host names or IP addresses. If a driver queues an
address for a remote transport, this host list is associated with the address,
and used instead of the transport's fallback host list. See the
fallback_hosts option of the smtp transport for further details.

If a driver queues an address for a local transport, and the transport does
not specify a group, the group given here is used when running the
delivery process. If the string contains no $ characters, it is resolved when
Exim starts up. Otherwise, the string is expanded at the time the director or
router is run, and must yield either a digit string or a name which can be
looked up using getgrnam(). For most directors and routers the default is
unset, but for the forwardfile director with check_local_user set, and
for the localuser director, the default is taken from the passwd file. See
also initgroups and user and the discussion in chapter 13.

This option specifies a string of text which is expanded at directing or
routing time, and associated with any addresses that are processed by the
driver. If the expanded string is empty, or if the expansion is forced to fail,
the option has no effect. Other expansion failures are treated as configuration
errors.

The expanded string must be in the form of one or more RFC 822 header lines,
separated by newlines (coded as `\n' inside a quoted string). For example:

headers_add = X-added-header: added by $primary_hostname

Exim does not check the syntax of these added headers, except that a newline is
supplied at the end if one is not present. If an address passes through several
directors and/or routers
as a result of aliasing or forwarding operations, any headers_add or
headers_remove specifications are cumulative. This does not apply for
multiple directors and/or routers that result from the use of `unseen'.

At transport time, for each address, all original headers listed in
headers_remove are removed, and those specified by headers_add are added,
in the order in which they were attached to the address. Then any additional
headers specified by the transport are added. It is not possible to remove
headers added to an address by headers_add.

Addresses with different headers_add or headers_remove settings cannot be
batched.

The string is expanded at directing or routing time and is then associated with
any addresses that are processed by the driver.
If the expansion is forced to fail, the option has no effect. Other expansion
failures are treated as configuration errors.
After expansion, the string must consist of a colon-separated list of header
names, not including the terminating colon, for example:

If the driver queues an address for a local transport, and this option is true,
and the uid supplied by the router or director is not overridden by the
transport, the initgroups() function is called when running the
transport to ensure that any additional groups associated with the uid are set
up. See also group and user and the discussion in chapter
13.

If this option is set, the string is expanded, and is then interpreted as a
colon-separated list. Because of the expansion, if any of the items contain
backslash or dollar characters, they must be escaped with a backslash.
However, a special case is made for the string `$key', which is commonly used
in query-style lookups. Because such lookups are individually re-expanded
later, when they are used, the string `$key' is passed unchanged through the
initial overall expansion.

The driver is run only if the local part of the address matches the list, which
is tested in the same way as a domain list and which may therefore include
plain file names, file lookups, and negation. Because the string is expanded,
it is possible to make it depend on the domain, for example:

local_parts = dbm;/usr/local/specials/$domain

If the match is achieved by a lookup, 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:

If this option is false, and the driver declines 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 (see section 20.1).
However, if a router explicitly passes an address to the following router by
means of the setting

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, 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.

If any string is empty, it is ignored. Otherwise, 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.

The stat() function is normally run under the exim uid (or root if such is
not defined). During the delivery of a message, it is possible to arrange for
this test to be run under a specific uid and gid (which is set by means of
seteuid() and setegid()).

Warning: Unfortunately, this is not possible when the driver is being run
to verify addresses for an incoming SMTP message, because at that time, Exim
has given up its root privilege. Therefore, this facility is useful only if you
can set no_verify on drivers that use it.

If an item in a require_files list does not contain any forward slash
characters, it is taken to be the user (and optional group, separated by a
comma) to be used for testing subsequent files in the list. If no group is
specified but the user is specified symbolically, the gid associated with
the uid is used; otherwise the gid is not changed. For example:

The second example works because the require_files string is expanded before
use.
If a user or group name in a require_files list does not exist, the
require_files condition fails.

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 exclamation
mark that precedes the file name for non-existence) is preceded by a plus sign,
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
path within it that is not fully qualified causes a panic error.
This includes forced failure, because the whole string is expanded once, before
being interpreted as a list. If you want a particular variant of the expansion
to specify that no files are to be checked, you should cause it to yield an
empty string rather than forcing failure.

The value of this option is expanded, and the result of the expansion must be
a colon-separated address list, 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 (when it is set).
Using this option on a director makes it possible to
implement closed mailing lists (see chapter 42).

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 if the sender address matters.

Some directors and routers require a transport to be supplied, except when
verify_only is set, where it is not relevant. Others 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 an expandable string, thus allowing
transports to be dynamically selected. At directing or routing time, when a
driver decides to accept an address, the string is expanded, and must yield the
name of an available transport. If it does not, delivery is deferred. This
isn't as safe as fixed transports, whose existence is checked at initialization
time.

Setting this option has a similar effect to the unseen command qualifier in
filter files.
It causes a copy of the incoming address to be passed on to subsequent drivers,
when the current one succeeds in handling it. It can be used to cause
copies of messages to be delivered elsewhere. The effect is to clone the
address before processing one copy of it, so options such as headers_add on
the current director do not affect the other copy.

If the driver queues an address for a local transport, and the transport does
not specify a user, the user given here is used when running the delivery
process. If the string contains no $ characters, it is resolved when Exim
starts up. Otherwise, the string is expanded at the time the director or router
is run, and must yield either a digit string or a name which can be looked up
using getpwnam(). In the latter case, the group associated with the user is
used as a default for the group option.

For most directors and routers the default for user is unset, but for the
forwardfile director with check_local_user set, and for the localuser
director, the default is taken from the passwd file. See also initgroups
and group and the discussion in chapter 13.

If this option is set, the driver is used only when verifying an address or
testing with the -bv option, not when actually doing a delivery, testing with
the -bt option, or running the SMTP EXPN command (see the expn generic
option for directors). It can be further restricted to verifying only senders
or recipients by means of verify_sender and verify_recipient.

If this option is false, this driver is skipped when verifying recipient
addresses. It is usual to set it false for instances of the smartuser
director
that have no other conditions imposed on the address.

If this option is false, this driver is skipped when verifying sender
addresses. It is usual to set it false for instances of the smartuser
director
that have no other conditions imposed on the address.

A number of the generic options that are common to directors and routers are
concerned with controlling which drivers are run in particular circumstances.
They interact with each other in the following way:

If the domain and local part of an address are not in agreement with domains
and local_parts (when set), or if the condition option fails, or if
verify_only is set and verification is not happening, the director or
router is skipped and the next one is tried.

Otherwise, if the more option is false, no subsequent drivers are ever
called, except when a router explicitly passes an address that routes to the
local host on to the following driver, by means of the
generic self option or the host_find_failed option of the domainlist
router. The current driver 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.

Both the senders and condition tests are done after checking for file
existence, so that they can contain references to files whose existence is
tested. The order of testing the options which are expanded strings is:
domains, local_parts, require_files, senders, condition. When any
test fails, no further expansions are done.

In the case of directors, there are some additional conditions that are tested
here (see section 21.1).

The unseen option causes directing or routing to continue when it would
otherwise cease. This is 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 addresses which correspond to a real 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 directing failure. However, if (for example)
verification of senders is taking place (the sender_verify main
configuration 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 can identify users whose accounts have recently
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 as
senders 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 a set of local parts that is defined by what a
specific director matches.