Exim Specification - 14. Generic options for transports

Go to the first, previous, next, last section, table of contents.

# 14. Generic options for transports

The generic options for transports are as follows:

### body_only (transport)

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 prefix and suffix should be checked, since this option does not automatically suppress them.

### debug_print (transport)

Type: string
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 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 (transport)

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 (transport)

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.

### envelope_to_add (transport)

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 on transports that support them, 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.

### headers_add (transport)

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. 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 822 header lines, separated by newlines (coded as `\n' inside a quoted string), 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.

The name add_headers was formerly used for this option, and is retained as a synonym for backward compatibility. Additional headers can also be specified by directors and routers. See chapter 20 and section 49.13.

### headers_only (transport)

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 prefix and suffix should be checked, since this option does not automatically suppress them.

### headers_remove (transport)

Type: string
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 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.

The name remove_headers was formerly used for this option, and is retained as a synonym for backward compatibility. Headers to be removed can also be specified by directors and routers. See chapter 20 and section 49.13.

### headers_rewrite (transport)

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 34. 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, director, or transport adds header lines, these are not affected. These rewriting rules are not applied to the envelope. You can change the return path using return_path; you cannot change envelope recipients at this time.

### message_size_limit (transport)

Type: integer
Default: 0

This option controls the size of messages passed through the transport. If its value is greater than zero and the size of a message 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.

### return_path (transport)

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, Exim panics. This option can be used to support VERP (Variable Envelope Return Paths) -- see chapter 48.

### return_path_add (transport)

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

### shadow_condition (transport)

Type: string, expanded
Default: unset

See shadow_transport below.

### shadow_transport (transport)

Type: string
Default: unset

This facility is somewhat experimental, and may change in future. A local transport may set the shadow_transport option to the name of another, previously-defined, 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 (transport)

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 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 822 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 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

The filter process is run under the same uid and gid as the normal delivery. For remote deliveries this is the exim uid/gid if they are defined.

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.

Go to the first, previous, next, last section, table of contents.