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.
Option: 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'.
Option: debug_print
Type: string
Default: unset
If this option is set and debugging is enabled (see `-d', `-v', and `debug_level'), then 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.
Option: domains
Type: domain-list
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. This applies in particular to any query-style lookup that uses the `$key' variable, because otherwise it gets expanded too early. If the string is given in quotes, backslashes have to be escaped a second time.
The driver is skipped unless the current domain matches the list. 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.
Option: driver
Type: string
Default: unset
This option must always be set. It specifies which of the available directors or routers is to be used.
Option: errors_to
Type: string
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.
Option: 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.
Option: 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.
Option: 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.
Option: 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 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.
Option: group
Type: string
Default: "see below"
If a driver queues an address for a local transport, and the transport does not specify a group, then 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 "Environment for running local transports".
Option: headers_add
Type: string
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.
Option: headers_remove
Type: string
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:
remove_headers = "return-receipt-to:acknowledge-to"
It is used at transport time as described under `headers_add' above.
Option: initgroups
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, then 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 "Environment for running local transports".
Option: local_parts
Type: string-list
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. This applies in particular to any query-style lookup that uses the `$key' variable, because otherwise it gets expanded too early. If the string is given in quotes, backslashes have to be escaped a second time.
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, 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
Option: 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 (see section "Skipping directors and routers"). However, if a router explicitly passes an address to the following router by means of the setting
self = fail_soft
then the setting of `more' is ignored.
Option: 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.
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). However, 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()'). 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, then 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 `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.
Option: senders
Type: address-list
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 "Using Exim to handle mailing lists").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.
Option: transport
Type: string
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.
Option: unseen
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.
Option: user
Type: string
Default: "see below"
If the driver queues an address for a local transport, and the transport does not specify a user, then 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 "Environment for running local transports".
Option: verify
Type: boolean
Default: true
Setting this option has the effect of setting `verify_sender' and `verify_recipient' to the same value.
Option: verify_only
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'.
Option: 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.
Option: 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.
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, then 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 "Skipping directors" in chapter "Additional generic options for directors").
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 delivery 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.