Exim 4.10 Specification chapter 23

Previous Next Contents (Exim 4.10 Specification)

# 23. Generic options for transports

The following generic options apply to all transports:

### body_only

Type: boolean
Default: false

If this option is set, the message's headers are not transported. It is mutually exclusive with `headers_only`. If it is used with the appendfile or pipe transports, the settings of `message_prefix` and `message_suffix` should be checked, because this option does not automatically suppress them.

### current_directory

Type: string, expanded
Default: unset

This specifies the current directory that is to be set while running the transport, overriding any value that may have been set by the router.

### debug_print

Type: string, expanded
Default: unset

If this option is set and debugging is enabled (see the -d command line option), the string is expanded and included in the debugging output when the transport is run. This is to help with checking out the values of variables and so on when debugging driver configurations. For example, if a `headers_add` option is not working properly, `debug_print` could be used to output the variables it references. A newline is added to the text if it does not end with one.

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

### driver

Type: string
Default: unset

This specifies which of the available transport drivers is to be used. There is no default, and this option must be set for every transport.

### 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 the transport is configured to handle several addresses at once, or if more than one original address was redirected 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.

### group

Type: string
Default: Exim group

This option specifies a gid for running the transport process, overriding any value that the router supplies, and also overriding any value associated with `user` (see below).

### headers_add

Type: string, expanded
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. If the result of the expansion is an empty string, or if the expansion is forced to fail, no action is taken. Other expansion failures are treated as errors and cause the delivery to be deferred. The expanded string should be in the form of one or more RFC 2822 header lines, separated by newlines (coded as ``\n''), for example:

      headers_add = 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. This is not recommended. Additional headers can also be specified by routers. See chapter 14 and section 43.13.

### headers_only

Type: boolean
Default: false

If this option is set, the message's body is not transported. It is mutually exclusive with `body_only`. If it is used with the appendfile or pipe transports, the settings of `message_prefix` and `message_suffix` should be checked, since this option does not automatically suppress them.

### headers_remove

Type: string, expanded
Default: unset

This option is expanded; the result must consist of a colon-separated list of header names, not including the terminating colon, for example:

      headers_remove = return-receipt-to:acknowledge-to

Any existing headers matching those names are not included in any message that is transmitted by the transport. If there are multiple instances of a header, they are all removed. However, added headers may have these names. Thus it is possible to replace a header by specifying it in `headers_remove` and supplying the replacement in `headers_add`. Headers to be removed can also be specified by routers. See chapter 14 and section 43.13.

### headers_rewrite

Type: string
Default: unset

This option allows addresses in header lines to be rewritten at transport time, that is, as the message is being copied to its destination. The contents of the option are a colon-separated list of rewriting rules. Each rule is in exactly the same form as one of the general rewriting rules that are applied when a message is received. These are described in chapter 30. For example,

      headers_rewrite = a@b c@d f : \
                        x@y w@z

changes `a@b` into `c@d` in From: header lines, and `x@y` into `w@z` in all address-bearing header lines. The rules are applied to the header lines just before they are written out at transport time, so they affect only those copies of the message that pass through the transport. However, only the message's original header lines, and any that were added by a system filter, are rewritten. If a router or transport adds header lines, they are not affected by this option. These rewriting rules are not applied to the envelope. You can change the return path using `return_path`, but you cannot change envelope recipients at this time.

### home_directory

Type: string, expanded
Default: unset

This option specifies a home directory setting for the transport, overriding any value that may be set by the router. The home directory is placed in `$home` while expanding the transport's private options.

### initgroups

Type: boolean
Default: false

If this option is true and the uid for the delivery process is provided 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.

### message_size_limit

Type: string, expanded
Default: 0

This option controls the size of messages passed through the transport. It is expanded before use; any expansion failure causes delivery to be deferred. The result of the expansion must be a sequence of digits, optionally followed by K or M. If its value is greater than zero and the size of a message exceeds the limit, the address is failed. If there is any chance that the resulting bounce message could be routed to the same transport, you should ensure that `return_size_limit` is less than the transport's `message_size_limit`, as otherwise the bounce message will fail to get delivered.

### retry_use_local_part

Type: boolean
Default: see below

When a delivery suffers a temporary failure, a retry record is created in Exim's hints database. For remote deliveries, the key for the retry record is based on the name and/or IP address of the failing remote host. For local deliveries, the key is normally the entire address, including both the local part and the domain. This is suitable for most common cases of local delivery temporary failure - for example, exceeding a mailbox quota should delay only deliveries to that mailbox, not to the whole domain.

However, in some special cases you may want to treat a temporary local delivery as a failure associated with the domain, and not with a particular local part. (For example, if you are storing all mail for some domain in files.) You can do this by setting `retry_use_local_part` false.

For all the local transports, its default value is true. For remote transports, the default value is false for tidiness, but changing the value has no effect on a remote transport in the current implementation.

### return_path

Type: string, expanded
Default: unset

If this option is set, the string is expanded at transport time and replaces the existing return path (envelope sender) value. The expansion can refer to the existing value via `$return_path`. If the expansion is forced to fail, no replacement occurs; if it fails for another reason, delivery is deferred. This option can be used to support VERP (Variable Envelope Return Paths) - see chapter 42.

### return_path_add

Type: boolean
Default: false

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 2821 states that the Return-path: header is added to a message ``when the delivery SMTP server makes the final delivery''. This 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.

### shadow_condition

Type: string, expanded
Default: unset

See `shadow_transport` below.

### shadow_transport

Type: string
Default: unset

A local transport may set the `shadow_transport` option to the name of another local transport. Shadow remote transports are not supported.

Whenever a delivery to the main transport succeeds, and either `shadow_condition` is unset, or its expansion does not result in a forced expansion failure or the empty string or one of the strings ``0'' or ``no'' or ``false'', the message is also passed to the shadow transport, with the same delivery address or addresses. However, the result of the shadow transport is discarded and does not affect the subsequent processing of the message. Only a single level of shadowing is provided; the `shadow_transport` option is ignored on any transport when it is running as a shadow. Options concerned with output from pipes are also ignored.

The log line for the successful delivery has an item added on the end, of the form

`` `ST=<shadow transport name>`

If the shadow transport did not succeed, the error message is put in parentheses afterwards.

Shadow transports can be used for a number of different purposes, including keeping more detailed log information than Exim normally provides, and implementing automatic acknowledgement policies based on message headers that some sites insist on.

### transport_filter

Type: string, expanded
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 or via a system filter.

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). This happens before any SMTP-specific processing, such as turning ``\n'' into ``\r\n'' and escaping lines beginning with a dot, and also before any processing implied by the settings of `check_string` and `escape_string` in the appendfile or pipe transports.

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 2822 syntax. A demonstration Perl script is provided in util/transport-filter.pl; this makes a few arbitrary modifications just to show the possibilities. Exim does not check the result, except to test for a final newline when SMTP is in use. All messages transmitted over SMTP must end with a newline, so Exim supplies one if it is missing.

A problem might arise if the filter increases the size of a message that is being sent down an SMTP channel. If the receiving SMTP server has indicated support for the SIZE parameter, Exim will have sent the size of the message at the start of the SMTP session. If what is actually sent is substantially more, the server might reject the message. This can be worked round by setting the `size_addition` option on the smtp transport, either to allow for additions to the message, or to disable the use of SIZE altogether.

The value of the option is the command string for starting up the filter, which is run directly from Exim, not under a shell. The string 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 contain the name and IP address of the host to which the message is being sent. For example:

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

The filter process is run under the same uid and gid as the normal delivery. For remote deliveries this is the Exim uid/gid by default.

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.

### user

Type: string
Default: Exim user

This option specifies the user under whose uid the delivery process is to be run, overriding any uid that may have been set by the router. If the user is given as a name, the uid is looked up from the password data, and the associated group is taken as the value of the gid to be used if the `group` option is not set.

For remote transports, you should leave this option unset unless you really are sure you know what you are doing. When a remote transport is running, it needs to be able to access Exim's hints databases, because each host may have its own retry data.

Previous Next Contents (Exim 4.10 Specification)