<?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>29. The pipe transport</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="ch28.html" title="28. The lmtp transport" /><link rel="next" href="ch30.html" title="30. The smtp transport" /></head><body><div class="navheader">
<table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ch28.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch30.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#toc0235" id="CHAPpipetransport">29. The pipe transport</a></h2></div>
</div>
</div>
<p>
<a id="IIDpiptra1" class="indexterm"></a>
<a id="IIDpiptra2" class="indexterm"></a>
The <span><strong class="command">pipe</strong></span> transport is used to deliver messages via a pipe to a command
running in another process. One example is the use of <span><strong class="command">pipe</strong></span> as a
pseudo-remote transport for passing messages to some other delivery mechanism
(such as UUCP). Another is the use by individual users to automatically process
their incoming messages. The <span><strong class="command">pipe</strong></span> transport can be used in one of the
following ways:
</p>
<div class="itemizedlist">
<ul type="disc"><li><p>
<a id="id598194" class="indexterm"></a>
A router routes one address to a transport in the normal way, and the
transport is configured as a <span><strong class="command">pipe</strong></span> transport. In this case, <em class="varname">$local_part</em>
contains the local part of the address (as usual), and the command that is run
is specified by the <span><strong class="option">command</strong></span> option on the transport.
</p>
</li><li><p>
<a id="id598230" class="indexterm"></a>
If the <span><strong class="option">batch_max</strong></span> option is set greater than 1 (the default is 1), the
transport can handle more than one address in a single run. In this case, when
more than one address is routed to the transport, <em class="varname">$local_part</em> is not set
(because it is not unique). However, the pseudo-variable <em class="varname">$pipe_addresses</em>
(described in section <a href="ch29.html#SECThowcommandrun" title="29.3 How the command is run">29.3</a> below) contains all the addresses
that are routed to the transport.
</p>
</li><li><p>
<a id="id598272" class="indexterm"></a>
A router redirects an address directly to a pipe command (for example, from an
alias or forward file). In this case, <em class="varname">$address_pipe</em> contains the text of the
pipe command, and the <span><strong class="option">command</strong></span> option on the transport is ignored. If only
one address is being transported (<span><strong class="option">batch_max</strong></span> is not greater than one, or
only one address was redirected to this pipe command), <em class="varname">$local_part</em> contains
the local part that was redirected.
</p>
</li></ul></div>
<p>
The <span><strong class="command">pipe</strong></span> transport is a non-interactive delivery method. Exim can also
deliver messages over pipes using the LMTP interactive protocol. This is
implemented by the <span><strong class="command">lmtp</strong></span> transport.
</p>
<p>
In the case when <span><strong class="command">pipe</strong></span> is run as a consequence of an entry in a local user’s
<em class="filename">.forward</em> file, the command runs under the uid and gid of that user. In
other cases, the uid and gid have to be specified explicitly, either on the
transport or on the router that handles the address. Current and “<span class="quote">home</span>”
directories are also controllable. See chapter <a href="ch23.html" title="23. Environment for running local transports">23</a> for
details of the local delivery environment and chapter <a href="ch25.html" title="25. Address batching in local transports">25</a>
for a discussion of local delivery batching.
</p>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0236" id="SECID140">29.1 Concurrent delivery</a></h3></div>
</div>
</div>
<p>
If two messages arrive at almost the same time, and both are routed to a pipe
delivery, the two pipe transports may be run concurrently. You must ensure that
any pipe commands you set up are robust against this happening. If the commands
write to a file, the <span><strong class="option">exim_lock</strong></span> utility might be of use.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0237" id="SECID141">29.2 Returned status and data</a></h3></div>
</div>
</div>
<p>
<a id="id598396" class="indexterm"></a>
If the command exits with a non-zero return code, the delivery is deemed to
have failed, unless either the <span><strong class="option">ignore_status</strong></span> option is set (in which case
the return code is treated as zero), or the return code is one of those listed
in the <span><strong class="option">temp_errors</strong></span> option, which are interpreted as meaning “<span class="quote">try again
later</span>”. In this case, delivery is deferred. Details of a permanent failure are
logged, but are not included in the bounce message, which merely contains
“<span class="quote">local delivery failed</span>”.
</p>
<p>
If the return code is greater than 128 and the command being run is a shell
script, it normally means that the script was terminated by a signal whose
value is the return code minus 128.
</p>
<p>
If Exim is unable to run the command (that is, if <em class="function">execve()</em> fails), the
return code is set to 127. This is the value that a shell returns if it is
asked to run a non-existent command. The wording for the log line suggests that
a non-existent command may be the problem.
</p>
<p>
The <span><strong class="option">return_output</strong></span> option can affect the result of a pipe delivery. If it is
set and the command produces any output on its standard output or standard
error streams, the command is considered to have failed, even if it gave a zero
return code or if <span><strong class="option">ignore_status</strong></span> is set. The output from the command is
included as part of the bounce message. The <span><strong class="option">return_fail_output</strong></span> option is
similar, except that output is returned only when the command exits with a
failure return code, that is, a value other than zero or a code that matches
<span><strong class="option">temp_errors</strong></span>.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0238" id="SECThowcommandrun">29.3 How the command is run</a></h3></div>
</div>
</div>
<p>
<a id="id598496" class="indexterm"></a>
The command line is (by default) broken down into a command name and arguments
by the <span><strong class="command">pipe</strong></span> transport itself. The <span><strong class="option">allow_commands</strong></span> and
<span><strong class="option">restrict_to_path</strong></span> options can be used to restrict the commands that may be
run.
</p>
<p>
<a id="id598535" class="indexterm"></a>
Unquoted arguments are delimited by white space. If an argument appears in
double quotes, backslash is interpreted as an escape character in the usual
way. If an argument appears in single quotes, no escaping is done.
</p>
<p>
String expansion is applied to the command line except when it comes from a
traditional <em class="filename">.forward</em> file (commands from a filter file are expanded). The
expansion is applied to each argument in turn rather than to the whole line.
For this reason, any string expansion item that contains white space must be
quoted so as to be contained within a single argument. A setting such as
</p>
<pre class="literallayout">command = /some/path ${if eq{$local_part}{postmaster}{xx}{yy}}
</pre><p>
will not work, because the expansion item gets split between several
arguments. You have to write
</p>
<pre class="literallayout">command = /some/path "${if eq{$local_part}{postmaster}{xx}{yy}}"
</pre><p>
to ensure that it is all in one argument. The expansion is done in this way,
argument by argument, so that the number of arguments cannot be changed as a
result of expansion, and quotes or backslashes in inserted variables do not
interact with external quoting. However, this leads to problems if you want to
generate multiple arguments (or the command name plus arguments) from a single
expansion. In this situation, the simplest solution is to use a shell. For
example:
</p>
<pre class="literallayout">command = /bin/sh -c ${lookup{$local_part}lsearch{/some/file}}
</pre><p>
<a id="id598614" class="indexterm"></a>
<a id="id598628" class="indexterm"></a>
<a id="id598643" class="indexterm"></a>
Special handling takes place when an argument consists of precisely the text
<code class="literal">$pipe_addresses</code>. This is not a general expansion variable; the only
place this string is recognized is when it appears as an argument for a pipe or
transport filter command. It causes each address that is being handled to be
inserted in the argument list at that point <span class="emphasis"><em>as a separate argument</em></span>. This
avoids any problems with spaces or shell metacharacters, and is of use when a
<span><strong class="command">pipe</strong></span> transport is handling groups of addresses in a batch.
</p>
<p>
After splitting up into arguments and expansion, the resulting command is run
in a subprocess directly from the transport, <span class="emphasis"><em>not</em></span> under a shell. The
message that is being delivered is supplied on the standard input, and the
standard output and standard error are both connected to a single pipe that is
read by Exim. The <span><strong class="option">max_output</strong></span> option controls how much output the command
may produce, and the <span><strong class="option">return_output</strong></span> and <span><strong class="option">return_fail_output</strong></span> options
control what is done with it.
</p>
<p>
Not running the command under a shell (by default) lessens the security risks
in cases when a command from a user’s filter file is built out of data that was
taken from an incoming message. If a shell is required, it can of course be
explicitly specified as the command to be run. However, there are circumstances
where existing commands (for example, in <em class="filename">.forward</em> files) expect to be run
under a shell and cannot easily be modified. To allow for these cases, there is
an option called <span><strong class="option">use_shell</strong></span>, which changes the way the <span><strong class="command">pipe</strong></span> transport
works. Instead of breaking up the command line as just described, it expands it
as a single string and passes the result to <em class="filename">/bin/sh</em>. The
<span><strong class="option">restrict_to_path</strong></span> option and the <em class="varname">$pipe_addresses</em> facility cannot be used
with <span><strong class="option">use_shell</strong></span>, and the whole mechanism is inherently less secure.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0239" id="SECTpipeenv">29.4 Environment variables</a></h3></div>
</div>
</div>
<p>
<a id="id598759" class="indexterm"></a>
<a id="id598777" class="indexterm"></a>
The environment variables listed below are set up when the command is invoked.
This list is a compromise for maximum compatibility with other MTAs. Note that
the <span><strong class="option">environment</strong></span> option can be used to add additional variables to this
environment.
</p>
<div class="literallayout">
<code class="literal">DOMAIN </code> the domain of the address<br />
<code class="literal">HOME </code> the home directory, if set<br />
<code class="literal">HOST </code> the host name when called from a router (see below)<br />
<code class="literal">LOCAL_PART </code> see below<br />
<code class="literal">LOCAL_PART_PREFIX </code> see below<br />
<code class="literal">LOCAL_PART_SUFFIX </code> see below<br />
<code class="literal">LOGNAME </code> see below<br />
<code class="literal">MESSAGE_ID </code> Exim’s local ID for the message<br />
<code class="literal">PATH </code> as specified by the <span><strong class="option">path</strong></span> option below<br />
<code class="literal">QUALIFY_DOMAIN </code> the sender qualification domain<br />
<code class="literal">RECIPIENT </code> the complete recipient address<br />
<code class="literal">SENDER </code> the sender of the message (empty if a bounce)<br />
<code class="literal">SHELL </code> <code class="literal">/bin/sh</code><br />
<code class="literal">TZ </code> the value of the <span><strong class="option">timezone</strong></span> option, if set<br />
<code class="literal">USER </code> see below<br />
</div>
<p>
When a <span><strong class="command">pipe</strong></span> transport is called directly from (for example) an <span><strong class="command">accept</strong></span>
router, LOCAL_PART is set to the local part of the address. When it is
called as a result of a forward or alias expansion, LOCAL_PART is set to
the local part of the address that was expanded. In both cases, any affixes are
removed from the local part, and made available in LOCAL_PART_PREFIX and
LOCAL_PART_SUFFIX, respectively. LOGNAME and USER are set to the
same value as LOCAL_PART for compatibility with other MTAs.
</p>
<p>
<a id="id598940" class="indexterm"></a>
HOST is set only when a <span><strong class="command">pipe</strong></span> transport is called from a router that
associates hosts with an address, typically when using <span><strong class="command">pipe</strong></span> as a
pseudo-remote transport. HOST is set to the first host name specified by
the router.
</p>
<p>
<a id="id598969" class="indexterm"></a>
If the transport’s generic <span><strong class="option">home_directory</strong></span> option is set, its value is used
for the HOME environment variable. Otherwise, a home directory may be set
by the router’s <span><strong class="option">transport_home_directory</strong></span> option, which defaults to the
user’s home directory if <span><strong class="option">check_local_user</strong></span> is set.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0240" id="SECID142">29.5 Private options for pipe</a></h3></div>
</div>
</div>
<p>
<a id="id599011" class="indexterm"></a>
</p>
<p>
<a id="id599033" 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">allow_commands</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</em></span></td><td align="center">Type: <span class="emphasis"><em>string list</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="id599118" class="indexterm"></a>
The string is expanded, and is then interpreted as a colon-separated list of
permitted commands. If <span><strong class="option">restrict_to_path</strong></span> is not set, the only commands
permitted are those in the <span><strong class="option">allow_commands</strong></span> list. They need not be absolute
paths; the <span><strong class="option">path</strong></span> option is still used for relative paths. If
<span><strong class="option">restrict_to_path</strong></span> is set with <span><strong class="option">allow_commands</strong></span>, the command must either be
in the <span><strong class="option">allow_commands</strong></span> list, or a name without any slashes that is found on
the path. In other words, if neither <span><strong class="option">allow_commands</strong></span> nor
<span><strong class="option">restrict_to_path</strong></span> is set, there is no restriction on the command, but
otherwise only commands that are permitted by one or the other are allowed. For
example, if
</p>
<pre class="literallayout">allow_commands = /usr/bin/vacation
</pre><p>
and <span><strong class="option">restrict_to_path</strong></span> is not set, the only permitted command is
<em class="filename">/usr/bin/vacation</em>. The <span><strong class="option">allow_commands</strong></span> option may not be set if
<span><strong class="option">use_shell</strong></span> is set.
</p>
<p>
<a id="id599209" 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">batch_id</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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 the description of local delivery batching in chapter <a href="ch25.html" title="25. Address batching in local transports">25</a>.
</p>
<p>
<a id="id599303" 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">batch_max</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</em></span></td><td align="center">Type: <span class="emphasis"><em>integer</em></span></td><td align="right">Default: <span class="emphasis"><em>1</em></span></td></tr></tbody></table></div>
<p>
This limits the number of addresses that can be handled in a single delivery.
See the description of local delivery batching in chapter <a href="ch25.html" title="25. Address batching in local transports">25</a>.
</p>
<p>
<a id="id599396" 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">check_string</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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>
As <span><strong class="command">pipe</strong></span> writes the message, the start of each line is tested for matching
<span><strong class="option">check_string</strong></span>, and if it does, the initial matching characters are replaced
by the contents of <span><strong class="option">escape_string</strong></span>, provided both are set. The value of
<span><strong class="option">check_string</strong></span> is a literal string, not a regular expression, and the case of
any letters it contains is significant. When <span><strong class="option">use_bsmtp</strong></span> is set, the contents
of <span><strong class="option">check_string</strong></span> and <span><strong class="option">escape_string</strong></span> are forced to values that implement
the SMTP escaping protocol. Any settings made in the configuration file are
ignored.
</p>
<p>
<a id="id599516" 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">command</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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>
This option need not be set when <span><strong class="command">pipe</strong></span> is being used to deliver to pipes
obtained directly from address redirections. In other cases, the option must be
set, to provide a command to be run. It need not yield an absolute path (see
the <span><strong class="option">path</strong></span> option below). The command is split up into separate arguments by
Exim, and each argument is separately expanded, as described in section
<a href="ch29.html#SECThowcommandrun" title="29.3 How the command is run">29.3</a> above.
</p>
<p>
<a id="id599626" 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">environment</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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="id599711" class="indexterm"></a>
<a id="id599730" class="indexterm"></a>
This option is used to add additional variables to the environment in which the
command runs (see section <a href="ch29.html#SECTpipeenv" title="29.4 Environment variables">29.4</a> for the default list). Its value is
a string which is expanded, and then interpreted as a colon-separated list of
environment settings of the form <<span class="emphasis"><em>name</em></span>>=<<span class="emphasis"><em>value</em></span>>.
</p>
<p>
<a id="id599772" 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">escape_string</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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>
See <span><strong class="option">check_string</strong></span> above.
</p>
<p>
<a id="id599862" 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">freeze_exec_fail</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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="id599944" class="indexterm"></a>
<a id="id599955" class="indexterm"></a>
<a id="id599966" class="indexterm"></a>
Failure to exec the command in a pipe transport is by default treated like
any other failure while running the command. However, if <span><strong class="option">freeze_exec_fail</strong></span>
is set, failure to exec is treated specially, and causes the message to be
frozen, whatever the setting of <span><strong class="option">ignore_status</strong></span>.
</p>
<p>
<a id="id600000" 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">ignore_status</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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 true, the status returned by the subprocess that is set up to
run the command is ignored, and Exim behaves as if zero had been returned.
Otherwise, a non-zero status or termination by signal causes an error return
from the transport unless the status value is one of those listed in
<span><strong class="option">temp_errors</strong></span>; these cause the delivery to be deferred and tried again later.
</p>
<p>
<span class="bold"><strong>Note</strong></span>: This option does not apply to timeouts, which do not return a status.
See the <span><strong class="option">timeout_defer</strong></span> option for how timeouts are handled.
</p>
<p>
<a id="id600110" 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">log_defer_output</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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="id600192" class="indexterm"></a>
If this option is set, and the status returned by the command is
one of the codes listed in <span><strong class="option">temp_errors</strong></span> (that is, delivery was deferred),
and any output was produced, the first line of it is written to the main log.
</p>
<p>
<a id="id600222" 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">log_fail_output</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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, and the command returns any output, and also ends with a
return code that is neither zero nor one of the return codes listed in
<span><strong class="option">temp_errors</strong></span> (that is, the delivery failed), the first line of output is
written to the main log. This option and <span><strong class="option">log_output</strong></span> are mutually exclusive.
Only one of them may be set.
</p>
<p>
<a id="id600317" 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">log_output</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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 and the command returns any output, the first line of
output is written to the main log, whatever the return code. This option and
<span><strong class="option">log_fail_output</strong></span> are mutually exclusive. Only one of them may be set.
</p>
<p>
<a id="id600409" 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">max_output</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</em></span></td><td align="center">Type: <span class="emphasis"><em>integer</em></span></td><td align="right">Default: <span class="emphasis"><em>20K</em></span></td></tr></tbody></table></div>
<p>
This specifies the maximum amount of output that the command may produce on its
standard output and standard error file combined. If the limit is exceeded, the
process running the command is killed. This is intended as a safety measure to
catch runaway processes. The limit is applied independently of the settings of
the options that control what is done with such output (for example,
<span><strong class="option">return_output</strong></span>). Because of buffering effects, the amount of output may
exceed the limit by a small amount before Exim notices.
</p>
<p>
<a id="id600507" 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_prefix</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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>see below</em></span></td></tr></tbody></table></div>
<p>
The string specified here is expanded and output at the start of every message.
The default is unset if <span><strong class="option">use_bsmtp</strong></span> is set. Otherwise it is
</p>
<pre class="literallayout">message_prefix = \
From ${if def:return_path{$return_path}{MAILER-DAEMON}}\
${tod_bsdinbox}\n
</pre><p>
<a id="id600610" class="indexterm"></a>
<a id="id600621" class="indexterm"></a>
<a id="id600633" class="indexterm"></a>
This is required by the commonly used <em class="filename">/usr/bin/vacation</em> program.
However, it must <span class="emphasis"><em>not</em></span> be present if delivery is to the Cyrus IMAP server,
or to the <span><strong class="option">tmail</strong></span> local delivery agent. The prefix can be suppressed by
setting
</p>
<pre class="literallayout">message_prefix =
</pre><p>
<span class="bold"><strong>Note:</strong></span> If you set <span><strong class="option">use_crlf</strong></span> true, you must change any occurrences of
<code class="literal">\n</code> to <code class="literal">\r\n</code> in <span><strong class="option">message_prefix</strong></span>.
</p>
<p>
<a id="id600701" 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_suffix</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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>see below</em></span></td></tr></tbody></table></div>
<p>
The string specified here is expanded and output at the end of every message.
The default is unset if <span><strong class="option">use_bsmtp</strong></span> is set. Otherwise it is a single newline.
The suffix can be suppressed by setting
</p>
<pre class="literallayout">message_suffix =
</pre><p>
<span class="bold"><strong>Note:</strong></span> If you set <span><strong class="option">use_crlf</strong></span> true, you must change any occurrences of
<code class="literal">\n</code> to <code class="literal">\r\n</code> in <span><strong class="option">message_suffix</strong></span>.
</p>
<p>
<a id="id600832" 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">path</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span></td><td align="right">Default: <span class="emphasis"><em>see below</em></span></td></tr></tbody></table></div>
<p>
This option specifies the string that is set up in the PATH environment
variable of the subprocess. The default is:
</p>
<pre class="literallayout">/bin:/usr/bin
</pre><p>
If the <span><strong class="option">command</strong></span> option does not yield an absolute path name, the command is
sought in the PATH directories, in the usual way. <span class="bold"><strong>Warning</strong></span>: This does not
apply to a command specified as a transport filter.
</p>
<p>
<a id="id600943" 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">pipe_as_creator</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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="id601025" class="indexterm"></a>
If the generic <span><strong class="option">user</strong></span> option is not set and this option is true, the delivery
process is run under the uid that was in force when Exim was originally called
to accept the message. If the group id is not otherwise set (via the generic
<span><strong class="option">group</strong></span> option), the gid that was in force when Exim was originally called to
accept the message is used.
</p>
<p>
<a id="id601056" 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">restrict_to_path</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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>
When this option is set, any command name not listed in <span><strong class="option">allow_commands</strong></span> must
contain no slashes. The command is searched for only in the directories listed
in the <span><strong class="option">path</strong></span> option. This option is intended for use in the case when a pipe
command has been generated from a user’s <em class="filename">.forward</em> file. This is usually
handled by a <span><strong class="command">pipe</strong></span> transport called <span><strong class="option">address_pipe</strong></span>.
</p>
<p>
<a id="id601173" 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_fail_output</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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 true, and the command produced any output and ended with a
return code other than zero or one of the codes listed in <span><strong class="option">temp_errors</strong></span> (that
is, the delivery failed), the output is returned in the bounce message.
However, if the message has a null sender (that is, it is itself a bounce
message), output from the command is discarded. This option and
<span><strong class="option">return_output</strong></span> are mutually exclusive. Only one of them may be set.
</p>
<p>
<a id="id601273" 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_output</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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 true, and the command produced any output, the delivery is
deemed to have failed whatever the return code from the command, and the output
is returned in the bounce message. Otherwise, the output is just discarded.
However, if the message has a null sender (that is, it is a bounce message),
output from the command is always discarded, whatever the setting of this
option. This option and <span><strong class="option">return_fail_output</strong></span> are mutually exclusive. Only one
of them may be set.
</p>
<p>
<a id="id601370" 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">temp_errors</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</em></span></td><td align="center">Type: <span class="emphasis"><em>string list</em></span></td><td align="right">Default: <span class="emphasis"><em>see below</em></span></td></tr></tbody></table></div>
<p>
<a id="id601452" class="indexterm"></a>
This option contains either a colon-separated list of numbers, or a single
asterisk. If <span><strong class="option">ignore_status</strong></span> is false
and <span><strong class="option">return_output</strong></span> is not set,
and the command exits with a non-zero return code, the failure is treated as
temporary and the delivery is deferred if the return code matches one of the
numbers, or if the setting is a single asterisk. Otherwise, non-zero return
codes are treated as permanent errors. The default setting contains the codes
defined by EX_TEMPFAIL and EX_CANTCREAT in <em class="filename">sysexits.h</em>. If Exim is
compiled on a system that does not define these macros, it assumes values of 75
and 73, respectively.
</p>
<p>
<a id="id601497" 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">timeout</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</em></span></td><td align="center">Type: <span class="emphasis"><em>time</em></span></td><td align="right">Default: <span class="emphasis"><em>1h</em></span></td></tr></tbody></table></div>
<p>
If the command fails to complete within this time, it is killed. This normally
causes the delivery to fail (but see <span><strong class="option">timeout_defer</strong></span>). A zero time interval
specifies no timeout. In order to ensure that any subprocesses created by the
command are also killed, Exim makes the initial process a process group leader,
and kills the whole process group on a timeout. However, this can be defeated
if one of the processes starts a new process group.
</p>
<p>
<a id="id601593" 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">timeout_defer</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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 timeout in a <span><strong class="command">pipe</strong></span> transport, either in the command that the transport
runs, or in a transport filter that is associated with it, is by default
treated as a hard error, and the delivery fails. However, if <span><strong class="option">timeout_defer</strong></span>
is set true, both kinds of timeout become temporary errors, causing the
delivery to be deferred.
</p>
<p>
<a id="id601692" 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">umask</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</em></span></td><td align="center">Type: <span class="emphasis"><em>octal integer</em></span></td><td align="right">Default: <span class="emphasis"><em>022</em></span></td></tr></tbody></table></div>
<p>
This specifies the umask setting for the subprocess that runs the command.
</p>
<p>
<a id="id601778" 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">use_bsmtp</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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="id601860" class="indexterm"></a>
If this option is set true, the <span><strong class="command">pipe</strong></span> transport writes messages in “<span class="quote">batch
SMTP</span>” format, with the envelope sender and recipient(s) included as SMTP
commands. If you want to include a leading HELO command with such messages,
you can do so by setting the <span><strong class="option">message_prefix</strong></span> option. See section
<a href="ch45.html#SECTbatchSMTP" title="45.10 Outgoing batched SMTP">45.10</a> for details of batch SMTP.
</p>
<p>
<a id="id601898" 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">use_classresources</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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="id601980" class="indexterm"></a>
This option is available only when Exim is running on FreeBSD, NetBSD, or
BSD/OS. If it is set true, the <em class="function">setclassresources()</em> function is used to set
resource limits when a <span><strong class="command">pipe</strong></span> transport is run to perform a delivery. The
limits for the uid under which the pipe is to run are obtained from the login
class database.
</p>
<p>
<a id="id602011" 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">use_crlf</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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="id602093" class="indexterm"></a>
<a id="id602104" class="indexterm"></a>
This option causes lines to be terminated with the two-character CRLF sequence
(carriage return, linefeed) instead of just a linefeed character. In the case
of batched SMTP, the byte sequence written to the pipe is then an exact image
of what would be sent down a real SMTP connection.
</p>
<p>
The contents of the <span><strong class="option">message_prefix</strong></span> and <span><strong class="option">message_suffix</strong></span> options are
written verbatim, so must contain their own carriage return characters if these
are needed. When <span><strong class="option">use_bsmtp</strong></span> is not set, the default values for both
<span><strong class="option">message_prefix</strong></span> and <span><strong class="option">message_suffix</strong></span> end with a single linefeed, so their
values must be changed to end with <code class="literal">\r\n</code> if <span><strong class="option">use_crlf</strong></span> is set.
</p>
<p>
<a id="id602158" 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">use_shell</strong></span></td><td align="center">Use: <span class="emphasis"><em>pipe</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="id602241" class="indexterm"></a>
If this option is set, it causes the command to be passed to <em class="filename">/bin/sh</em>
instead of being run directly from the transport, as described in section
<a href="ch29.html#SECThowcommandrun" title="29.3 How the command is run">29.3</a>. This is less secure, but is needed in some situations
where the command is expected to be run under a shell and cannot easily be
modified. The <span><strong class="option">allow_commands</strong></span> and <span><strong class="option">restrict_to_path</strong></span> options, and the
<code class="literal">$pipe_addresses</code> facility are incompatible with <span><strong class="option">use_shell</strong></span>. The
command is expanded as a single string, and handed to <em class="filename">/bin/sh</em> as data for
its <span><strong class="option">-c</strong></span> option.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0241" id="SECID143">29.6 Using an external local delivery agent</a></h3></div>
</div>
</div>
<p>
<a id="id602312" class="indexterm"></a>
<a id="id602326" class="indexterm"></a>
<a id="id602338" class="indexterm"></a>
<a id="id602349" class="indexterm"></a>
<a id="id602365" class="indexterm"></a>
The <span><strong class="command">pipe</strong></span> transport can be used to pass all messages that require local
delivery to a separate local delivery agent such as <span><strong class="option">procmail</strong></span>. When doing
this, care must be taken to ensure that the pipe is run under an appropriate
uid and gid. In some configurations one wants this to be a uid that is trusted
by the delivery agent to supply the correct sender of the message. It may be
necessary to recompile or reconfigure the delivery agent so that it trusts an
appropriate user. The following is an example transport and router
configuration for <span><strong class="option">procmail</strong></span>:
</p>
<pre class="literallayout"># transport
procmail_pipe:
driver = pipe
command = /usr/local/bin/procmail -d $local_part
return_path_add
delivery_date_add
envelope_to_add
check_string = "From "
escape_string = ">From "
user = $local_part
group = mail
# router
procmail:
driver = accept
check_local_user
transport = procmail_pipe
</pre><p>
In this example, the pipe is run as the local user, but with the group set to
<span class="emphasis"><em>mail</em></span>. An alternative is to run the pipe as a specific user such as <span class="emphasis"><em>mail</em></span>
or <span class="emphasis"><em>exim</em></span>, but in this case you must arrange for <span><strong class="option">procmail</strong></span> to trust that
user to supply a correct sender address. If you do not specify either a
<span><strong class="option">group</strong></span> or a <span><strong class="option">user</strong></span> option, the pipe command is run as the local user. The
home directory is the user’s home directory by default.
</p>
<p>
<span class="bold"><strong>Note</strong></span>: The command that the pipe transport runs does <span class="emphasis"><em>not</em></span> begin with
</p>
<pre class="literallayout">IFS=" "
</pre><p>
as shown in some <span><strong class="option">procmail</strong></span> documentation, because Exim does not by default
use a shell to run pipe commands.
</p>
<p>
<a id="id602481" class="indexterm"></a>
The next example shows a transport and a router for a system where local
deliveries are handled by the Cyrus IMAP server.
</p>
<pre class="literallayout"># transport
local_delivery_cyrus:
driver = pipe
command = /usr/cyrus/bin/deliver \
-m ${substr_1:$local_part_suffix} -- $local_part
user = cyrus
group = mail
return_output
log_output
message_prefix =
message_suffix =
# router
local_user_cyrus:
driver = accept
check_local_user
local_part_suffix = .*
transport = local_delivery_cyrus
</pre><p>
Note the unsetting of <span><strong class="option">message_prefix</strong></span> and <span><strong class="option">message_suffix</strong></span>, and the use of
<span><strong class="option">return_output</strong></span> to cause any text written by Cyrus to be returned to the
sender.
<a id="id602524" class="indexterm"></a>
<a id="id602536" class="indexterm"></a>
</p>
</div>
</div>
<div class="navfooter">
<table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch28.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch30.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>
