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.
Type: string, expanded
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, 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.
Type: string, expanded
Default: unset
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.
Type: domain list, expanded
Default: unset
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.
Type: string
Default: unset
This option must always be set. It specifies which of the available directors or routers is to be used.
Type: string, expanded
Default: unset
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.
Type: boolean
Default: false
Setting this option has the effect of setting both fail_verify_sender and fail_verify_recipient to the same value.
Type: boolean
Default: false
If this option is true and an address is accepted by this driver when verifying a recipient, verification fails. This option has no effect if the verify_recipient option is false.
Type: boolean
Default: false
If this option is true and an address is accepted by this driver when verifying a sender, verification fails. This option has no effect if the verify_sender option is false.
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 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.
Type: string
Default: see below
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.
Type: string, expanded
Default: unset
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.
Type: string, expanded
Default: unset
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:
headers_remove = return-receipt-to:acknowledge-to
It is used at transport time as described under headers_add above.
Type: boolean
Default: false
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.
Type: string list, expanded
Default: unset
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:
postmaster: local_parts = postmaster driver = smartuser new_address = postmaster@real.dom.ain
Type: boolean
Default: true
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
or by some other means,
self = pass
Type: string list, expanded
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, 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:
require_files = mail:/some/file
require_files = ${local_part}:${home}/.procmailrc
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.
Type: address list, expanded
Default: unset
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.
Type: string, expanded
Default: unset
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.
Type: boolean
Default: false
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.
Type: string
Default: see below
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.
Type: boolean
Default: true
Setting this option has the effect of setting verify_sender and verify_recipient to the same value.
Type: boolean
Default: false
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.
Type: boolean
Default: true
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.
Type: boolean
Default: true
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
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.
Go to the first, previous, next, last section, table of contents.