<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><style xmlns="" type="text/css">
div.added { background-color: #ffff99; }
div.deleted { text-decoration: line-through;
background-color: #FF7F7F; }
div.changed { background-color: #99ff99; }
div.off { }
span.added { background-color: #ffff99; }
span.deleted { text-decoration: line-through;
background-color: #FF7F7F; }
span.changed { background-color: #99ff99; }
span.off { }
pre.literallayout {
background-color: #E8E8D0;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div[class=changed] pre.literallayout {
background-color: #99ff99;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div.literallayout {
background-color: #E8E8D0;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div[class=changed] div.literallayout {
background-color: #99ff99;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
</style><title>24. Generic options for transports</title><meta name="generator" content="DocBook XSL Stylesheets V1.72.0" /><link rel="start" href="index.html" title="Specification of the Exim Mail Transfer Agent" /><link rel="up" href="index.html" title="Specification of the Exim Mail Transfer Agent" /><link rel="prev" href="ch23.html" title="23. Environment for running local transports" /><link rel="next" href="ch25.html" title="25. Address batching in local transports" /></head><body><div class="navheader">
<table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ch23.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch25.html">Next</a></td></tr></table></div>
<div class="chapter" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a href="index.html#toc0220" id="CHAPtransportgeneric">24. Generic options for transports</a></h2></div></div>
</div>
<p>
<a id="IIDgenoptra1" class="indexterm"></a>
<a id="IIDgenoptra2" class="indexterm"></a>
<a id="IIDgenoptra3" class="indexterm"></a>
The following generic options apply to all transports:
</p>
<p>
<a id="id582116" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">body_only</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id582198" class="indexterm"></a>
<a id="id582213" class="indexterm"></a>
<a id="id582227" class="indexterm"></a>
If this option is set, the message’s headers are not transported. It is
mutually exclusive with <span><strong class="option">headers_only</strong></span>. If it is used with the <span><strong class="command">appendfile</strong></span>
or <span><strong class="command">pipe</strong></span> transports, the settings of <span><strong class="option">message_prefix</strong></span> and
<span><strong class="option">message_suffix</strong></span> should be checked, because this option does not
automatically suppress them.
</p>
<p>
<a id="id582274" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">current_directory</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
<a id="id582359" class="indexterm"></a>
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.
If the expansion fails for any reason, including forced failure, an error is
logged, and delivery is deferred.
</p>
<p>
<a id="id582381" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">disable_logging</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
If this option is set true, nothing is logged for any
deliveries by the transport or for any
transport errors. You should not set this option unless you really, really know
what you are doing.
</p>
<p>
<a id="id582470" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">debug_print</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
<a id="id582555" class="indexterm"></a>
If this option is set and debugging is enabled (see the <span><strong class="option">-d</strong></span> command line
option), the string is expanded and included in the debugging output when the
transport is run.
If expansion of the string fails, the error message is written to the debugging
output, and Exim carries on processing.
This facility is provided to help with checking out the values of variables and
so on when debugging driver configurations. For example, if a <span><strong class="option">headers_add</strong></span>
option is not working properly, <span><strong class="option">debug_print</strong></span> could be used to output the
variables it references. A newline is added to the text if it does not end with
one.
</p>
<p>
<a id="id582593" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">delivery_date_add</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id582676" class="indexterm"></a>
If this option is true, a <span class="emphasis"><em>Delivery-date:</em></span> 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 (<span><strong class="option">delivery_date_remove</strong></span>) which
requests its removal from incoming messages, so that delivered messages can
safely be resent to other recipients.
</p>
<p>
<a id="id582705" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">driver</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
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.
</p>
<p>
<a id="id582793" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">envelope_to_add</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id582875" class="indexterm"></a>
If this option is true, an <span class="emphasis"><em>Envelope-to:</em></span> 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 (<span><strong class="option">envelope_to_remove</strong></span>) which requests
its removal from incoming messages, so that delivered messages can safely be
resent to other recipients.
</p>
<p>
<a id="id582908" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">group</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>Exim group</em></span></td></tr></tbody></table></div>
<p>
<a id="id582992" class="indexterm"></a>
This option specifies a gid for running the transport process, overriding any
value that the router supplies, and also overriding any value associated with
<span><strong class="option">user</strong></span> (see below).
</p>
<p>
<a id="id583016" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">headers_add</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
<a id="id583101" class="indexterm"></a>
<a id="id583116" class="indexterm"></a>
This option specifies a string of text that is expanded and added to the header
portion of a message as it is transported, as described in section
<a href="ch44.html#SECTheadersaddrem" title="44.17 Adding and removing header lines in routers and transports">44.17</a>. Additional header lines can also be specified by
routers. 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.
</p>
<p>
<a id="id583147" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">headers_only</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id583229" class="indexterm"></a>
<a id="id583243" class="indexterm"></a>
<a id="id583258" class="indexterm"></a>
If this option is set, the message’s body is not transported. It is mutually
exclusive with <span><strong class="option">body_only</strong></span>. If it is used with the <span><strong class="command">appendfile</strong></span> or <span><strong class="command">pipe</strong></span>
transports, the settings of <span><strong class="option">message_prefix</strong></span> and <span><strong class="option">message_suffix</strong></span> should be
checked, since this option does not automatically suppress them.
</p>
<p>
<a id="id583305" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">headers_remove</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
<a id="id583389" class="indexterm"></a>
<a id="id583404" class="indexterm"></a>
This option specifies a string that is expanded into a list of header names;
these headers are omitted from the message as it is transported, as described
in section <a href="ch44.html#SECTheadersaddrem" title="44.17 Adding and removing header lines in routers and transports">44.17</a>. Header removal can also be specified by
routers. 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.
</p>
<p>
<a id="id583435" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">headers_rewrite</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
<a id="id583517" class="indexterm"></a>
<a id="id583531" class="indexterm"></a>
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 <a href="ch31.html" title="31. Address rewriting">31</a>. For
example,
</p>
<pre class="literallayout">headers_rewrite = a@b c@d f : \
x@y w@z
</pre><p>
changes <span class="emphasis"><em>a@b</em></span> into <span class="emphasis"><em>c@d</em></span> in <span class="emphasis"><em>From:</em></span> header lines, and <span class="emphasis"><em>x@y</em></span> into
<span class="emphasis"><em>w@z</em></span> 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 <span class="emphasis"><em>not</em></span> applied to the
envelope. You can change the return path using <span><strong class="option">return_path</strong></span>, but you cannot
change envelope recipients at this time.
</p>
<p>
<a id="id583612" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">home_directory</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
<a id="id583696" class="indexterm"></a>
<a id="id583711" class="indexterm"></a>
This option specifies a home directory setting for a local transport,
overriding any value that may be set by the router. The home directory is
placed in <em class="varname">$home</em> while expanding the transport’s private options. It is also
used as the current directory if no current directory is set by the
<span><strong class="option">current_directory</strong></span> option on the transport or the
<span><strong class="option">transport_current_directory</strong></span> option on the router. If the expansion fails
for any reason, including forced failure, an error is logged, and delivery is
deferred.
</p>
<p>
<a id="id583746" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">initgroups</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id583828" class="indexterm"></a>
<a id="id583839" class="indexterm"></a>
<a id="id583854" class="indexterm"></a>
If this option is true and the uid for the delivery process is provided by the
transport, the <em class="function">initgroups()</em> function is called when running the transport
to ensure that any additional groups associated with the uid are set up.
</p>
<p>
<a id="id583881" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">message_size_limit</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>0</em></span></td></tr></tbody></table></div>
<p>
<a id="id583966" class="indexterm"></a>
<a id="id583980" class="indexterm"></a>
<a id="id583995" class="indexterm"></a>
This option controls the size of messages passed through the transport. It is
expanded before use; the result of the expansion must be a sequence of decimal
digits, optionally followed by K or M. If the expansion fails for any reason,
including forced failure, or if the result is not of the required form,
delivery is deferred. If the value is greater than zero and the size of a
message exceeds this 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 <span><strong class="option">return_size_limit</strong></span> is less than the transport’s
<span><strong class="option">message_size_limit</strong></span>, as otherwise the bounce message will fail to get
delivered.
</p>
<p>
<a id="id584021" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">rcpt_include_affixes</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id584104" class="indexterm"></a>
<a id="id584119" class="indexterm"></a>
<a id="id584134" class="indexterm"></a>
<a id="id584148" class="indexterm"></a>
When this option is false (the default), and an address that has had any
affixes (prefixes or suffixes) removed from the local part is delivered by any
form of SMTP or LMTP, the affixes are not included. For example, if a router
that contains
</p>
<pre class="literallayout">local_part_prefix = *-
</pre><p>
routes the address <span class="emphasis"><em>abc-xyz@some.domain</em></span> to an SMTP transport, the envelope
is delivered with
</p>
<pre class="literallayout">RCPT TO:<xyz@some.domain>
</pre><p>
This is also the case when an ACL-time callout is being used to verify a
recipient address. However, if <span><strong class="option">rcpt_include_affixes</strong></span> is set true, the
whole local part is included in the RCPT command. This option applies to BSMTP
deliveries by the <span><strong class="command">appendfile</strong></span> and <span><strong class="command">pipe</strong></span> transports as well as to the
<span><strong class="command">lmtp</strong></span> and <span><strong class="command">smtp</strong></span> transports.
</p>
<p>
<a id="id584230" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">retry_use_local_part</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>see below</em></span></td></tr></tbody></table></div>
<p>
<a id="id584313" class="indexterm"></a>
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.
</p>
<p>
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 <span><strong class="option">retry_use_local_part</strong></span> false.
</p>
<p>
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.
</p>
<p>
<a id="id584349" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">return_path</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
<a id="id584433" class="indexterm"></a>
<a id="id584444" class="indexterm"></a>
<a id="id584459" class="indexterm"></a>
If this option is set, the string is expanded at transport time and replaces
the existing return path (envelope sender) value in the copy of the message
that is being delivered. An empty return path is permitted. This feature is
designed for remote deliveries, where the value of this option is used in the
SMTP MAIL command. If you set <span><strong class="option">return_path</strong></span> for a local transport, the
only effect is to change the address that is placed in the <span class="emphasis"><em>Return-path:</em></span>
header line, if one is added to the message (see the next option).
</p>
<p>
<span class="bold"><strong>Note:</strong></span> A changed return path is not logged unless you add
<span><strong class="option">return_path_on_delivery</strong></span> to the log selector.
</p>
<p>
<a id="id584507" class="indexterm"></a>
The expansion can refer to the existing value via <em class="varname">$return_path</em>. This is
either the message’s envelope sender, or an address set by the
<span><strong class="option">errors_to</strong></span> option on a router. 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
section <a href="ch47.html#SECTverp" title="47.6 Variable Envelope Return Paths (VERP)">47.6</a>.
</p>
<p>
<span class="bold"><strong>Note</strong></span>: If a delivery error is detected locally, including the case when a
remote server rejects a message at SMTP time, the bounce message is not sent to
the value of this option. It is sent to the previously set errors address.
This defaults to the incoming sender address, but can be changed by setting
<span><strong class="option">errors_to</strong></span> in a router.
</p>
<p>
<a id="id584560" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">return_path_add</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id584642" class="indexterm"></a>
If this option is true, a <span class="emphasis"><em>Return-path:</em></span> 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.
</p>
<p>
RFC 2821 states that the <span class="emphasis"><em>Return-path:</em></span> header is added to a message “<span class="quote">when
the delivery SMTP server makes the final delivery</span>”. This implies that this
header should not be present in incoming messages. Exim has a configuration
option, <span><strong class="option">return_path_remove</strong></span>, which requests removal of this header from
incoming messages, so that delivered messages can safely be resent to other
recipients.
</p>
<p>
<a id="id584686" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">shadow_condition</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
See <span><strong class="option">shadow_transport</strong></span> below.
</p>
<p>
<a id="id584779" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">shadow_transport</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
<a id="id584862" class="indexterm"></a>
<a id="id584873" class="indexterm"></a>
A local transport may set the <span><strong class="option">shadow_transport</strong></span> option to the name of
another local transport. Shadow remote transports are not supported.
</p>
<p>
Whenever a delivery to the main transport succeeds, and either
<span><strong class="option">shadow_condition</strong></span> is unset, or its expansion does not result in the empty
string or one of the strings “<span class="quote">0</span>” or “<span class="quote">no</span>” or “<span class="quote">false</span>”, the message is also
passed to the shadow transport, with the same delivery address or addresses. If
expansion fails, no action is taken except that non-forced expansion failures
cause a log line to be written.
</p>
<p>
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 <span><strong class="option">shadow_transport</strong></span> 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
</p>
<pre class="literallayout">ST=<shadow transport name>
</pre><p>
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 acknowledgment policies based on message
headers that some sites insist on.
</p>
<p>
<a id="id584952" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">transport_filter</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
<a id="id585037" class="indexterm"></a>
<a id="id585051" class="indexterm"></a>
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.
</p>
<p>
When the message is about to be written out, the command specified by
<span><strong class="option">transport_filter</strong></span> is started up in a separate, parallel process, and
the entire message, including the header lines, is passed to it on its standard
input (this in fact is done from a third process, to avoid deadlock). The
command must be specified as an absolute path.
</p>
<p>
The lines of the message that are written to the transport filter are
terminated by newline (“<span class="quote">\n</span>”). The message is passed to the filter before any
SMTP-specific processing, such as turning “<span class="quote">\n</span>” into “<span class="quote">\r\n</span>” and escaping
lines beginning with a dot, and also before any processing implied by the
settings of <span><strong class="option">check_string</strong></span> and <span><strong class="option">escape_string</strong></span> in the <span><strong class="command">appendfile</strong></span> or
<span><strong class="command">pipe</strong></span> transports.
</p>
<p>
The standard error for the filter process is set to the same destination as its
standard output; this is read and written to the message’s ultimate
destination. The process that writes the message to the filter, the
filter itself, and the original process that reads the result and delivers it
are all run in parallel, like a shell pipeline.
</p>
<p>
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
<em class="filename">util/transport-filter.pl</em>; 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.
</p>
<p>
<a id="id585145" class="indexterm"></a>
A transport filter can be used to provide content-scanning on a per-user basis
at delivery time if the only required effect of the scan is to modify the
message. For example, a content scan could insert a new header line containing
a spam score. This could be interpreted by a filter in the user’s MUA. It is
not possible to discard a message at this stage.
</p>
<p>
<a id="id585162" class="indexterm"></a>
A problem might arise if the filter increases the size of a message that is
being sent down an SMTP connection. 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 <span><strong class="option">size_addition</strong></span> option on the <span><strong class="command">smtp</strong></span> transport, either to allow for
additions to the message, or to disable the use of SIZE altogether.
</p>
<p>
<a id="id585198" class="indexterm"></a>
The value of the <span><strong class="option">transport_filter</strong></span> option is the command string for starting
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 <span><strong class="command">pipe</strong></span> transport:
Exim breaks it up into arguments and then expands each argument separately (see
section <a href="ch29.html#SECThowcommandrun" title="29.3 How the command is run">29.3</a>). Any kind of expansion failure causes delivery
to be deferred. The special argument <em class="varname">$pipe_addresses</em> 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
<span><strong class="command">pipe</strong></span> transport, it seemed sensible not to change it.)
</p>
<p>
<a id="id585249" class="indexterm"></a>
<a id="id585261" class="indexterm"></a>
The expansion variables <em class="varname">$host</em> and <em class="varname">$host_address</em> 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:
</p>
<pre class="literallayout">transport_filter = /some/directory/transport-filter.pl \
$host $host_address $sender_address $pipe_addresses
</pre><p>
Two problems arise if you want to use more complicated expansion items to
generate transport filter commands, both of which due to the fact that the
command is split up <span class="emphasis"><em>before</em></span> expansion.
</p>
<div class="itemizedlist">
<ul type="disc"><li><p>
If an expansion item contains white space, you must quote it, so that it is all
part of the same command item. If the entire option setting is one such
expansion item, you have to take care what kind of quoting you use. For
example:
</p>
<pre class="literallayout">transport_filter = '/bin/cmd${if eq{$host}{a.b.c}{1}{2}}'
</pre><p>
This runs the command <span><strong class="command">/bin/cmd1</strong></span> if the host name is <span class="emphasis"><em>a.b.c</em></span>, and
<span><strong class="command">/bin/cmd2</strong></span> otherwise. If double quotes had been used, they would have been
stripped by Exim when it read the option’s value. When the value is used, if
the single quotes were missing, the line would be split into two items,
<code class="literal">/bin/cmd${if</code> and <code class="literal">eq{$host}{a.b.c}{1}{2}</code>, and an error would occur when
Exim tried to expand the first one.
</p>
</li><li><p>
Except for the special case of <em class="varname">$pipe_addresses</em> that is mentioned above, an
expansion cannot generate multiple arguments, or a command name followed by
arguments. Consider this example:
</p>
<pre class="literallayout">transport_filter = ${lookup{$host}lsearch{/a/file}\
{$value}{/bin/cat}}
</pre><p>
The result of the lookup is interpreted as the name of the command, even
if it contains white space. The simplest way round this is to use a shell:
</p>
<pre class="literallayout">transport_filter = /bin/sh -c ${lookup{$host}lsearch{/a/file}\
{$value}{/bin/cat}}
</pre></li></ul></div>
<p>
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. The command should
normally yield a zero return code. Transport filters are not supposed to fail.
A non-zero code is taken to mean that the transport filter encountered some
serious problem. Delivery of the message is deferred; the message remains on
the queue and is tried again later. It is not possible to cause a message to be
bounced from a transport filter.
</p>
<p>
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 <span><strong class="option">return_message</strong></span> option is set.
</p>
<p>
<a id="id585415" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">transport_filter_timeout</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>time</em></span></td><td align="right">Default: <span class="emphasis"><em>5m</em></span></td></tr></tbody></table></div>
<p>
<a id="id585498" class="indexterm"></a>
When Exim is reading the output of a transport filter, it a applies a timeout
that can be set by this option. Exceeding the timeout is normally treated as a
temporary delivery failure. However, if a transport filter is used with a
<span><strong class="command">pipe</strong></span> transport, a timeout in the transport filter is treated in the same
way as a timeout in the pipe command itself. By default, a timeout is a hard
error, but if the <span><strong class="command">pipe</strong></span> transport’s <span><strong class="option">timeout_defer</strong></span> option is set true, it
becomes a temporary error.
</p>
<p>
<a id="id585537" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">user</strong></span></td><td align="center">Use: <span class="emphasis"><em>transports</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>Exim user</em></span></td></tr></tbody></table></div>
<p>
<a id="id585621" class="indexterm"></a>
<a id="id585636" class="indexterm"></a>
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 <span><strong class="option">group</strong></span>
option is not set.
</p>
<p>
For deliveries that use local transports, a user and group are normally
specified explicitly or implicitly (for example, as a result of
<span><strong class="option">check_local_user</strong></span>) by the router or transport.
</p>
<p>
<a id="id585672" class="indexterm"></a>
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.
<a id="id585697" class="indexterm"></a>
<a id="id585706" class="indexterm"></a>
<a id="id585718" class="indexterm"></a>
</p>
</div>
<div class="navfooter">
<table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch23.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch25.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div>
</body></html>
