File: spec_18.html

package info (click to toggle)
exim-html 3.20-1
links: PTS
area: main
in suites: etch, etch-m68k, sarge, woody
size: 2,868 kB
ctags: 4,188
sloc: makefile: 40; sh: 19
file content (1068 lines) | stat: -rw-r--r-- 31,300 bytes
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.52
     from spec on 25 November 2000 -->

<TITLE>Exim Specification - 18. The pipe transport</TITLE>
</HEAD>
<body bgcolor="#FFFFFF" text="#00005A" link="#FF6600" alink="#FF9933" vlink="#990000">
Go to the <A HREF="spec_1.html">first</A>, <A HREF="spec_17.html">previous</A>, <A HREF="spec_19.html">next</A>, <A HREF="spec_59.html">last</A> section, <A HREF="spec_toc.html">table of contents</A>.
<P><HR><P>


<H1><A NAME="SEC501" HREF="spec_toc.html#TOC501">18. The pipe transport</A></H1>
<P>
<A NAME="IDX1216"></A>
<A NAME="IDX1217"></A>
The <EM>pipe</EM> transport is used to deliver messages via a pipe to a command
running in another process. This can happen when when a director explicitly
directs a message to a <EM>pipe</EM> transport, and also when an address is expanded
via an alias, filter, or forward file that specifies a pipe command. In this
case, $<EM>local_part</EM> contains the local part that was aliased or forwarded,
while $<EM>address_pipe</EM> contains the text of the pipe command itself.

</P>
<P>
A <EM>pipe</EM> transport can also be used from a router as a pseudo-remote transport
for passing messages for remote delivery by some means other than Exim.

</P>
<P>
As <EM>pipe</EM> is a local transport, it is always run in a separate process,
normally under a non-privileged uid and gid. In the common case, these are the
uid and gid belonging to the user whose <TT>`.forward'</TT> file directed the message at
the pipe. In other cases the uid and gid have to be specified explicitly,
either on the transport or on the director or router that handled the address.
Current and `home' directories are also controllable. See chapter
13 for details of the local delivery environment.

</P>

<P>



<H2><A NAME="SEC502" HREF="spec_toc.html#TOC502">18.1 Returned status and data</A></H2>

<P>
<A NAME="IDX1218"></A>
If the command exits with a non-zero return code, the delivery is deemed to
have failed, unless either the <EM>ignore_status</EM> option is set (in which case
the return code is treated as zero), or the return code is one of those listed
in the <EM>temp_errors</EM> option, which are interpreted as meaning `try again
later'.
In this case, delivery is deferred.

</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>
The <EM>return_output</EM> 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 files, it is considered to have failed, even if it gave a zero return
code or if <EM>ignore_status</EM> is set. The output from the command is sent as part
of the delivery failure report. However, if <EM>return_fail_output</EM> is set,
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 <EM>temp_errors</EM>.

</P>



<H2><A NAME="SEC503" HREF="spec_toc.html#TOC503">18.2 How the command is run</A></H2>

<P>
<A NAME="IDX1219"></A>
<A NAME="IDX1220"></A>
The command line is (by default) broken down into a command name and arguments
by the <EM>pipe</EM> transport. The <EM>allow_commands</EM> and <EM>restrict_to_path</EM> options
can be used to restrict the commands that may be run.
<A NAME="IDX1221"></A>
Unquoted arguments are delimited by white space; in double-quoted arguments,
backslash is interpreted as an escape character in the usual way. This does not
happen for single-quoted arguments.

</P>
<P>
String expansion is applied to the command line except when it comes from a
traditional <TT>`.forward'</TT> 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

<PRE>
command = /some/path ${if eq{$local_part}{postmaster}{xxx}{yyy}}
</PRE>

<P>
will not work, because the expansion item gets split between several
arguments. You have to write

<PRE>
command = /some/path "${if eq{$local_part}{postmaster}{xxx}{yyy}}"
</PRE>

<P>
to ensure that it is all in one argument. If the whole command line is quoted,
then the internal quotes have to be escaped with backslashes (or single quotes
can be used). The expansion is done in this way, argument by argument, so that
the number of arguments cannot be changed as a result, and quotes or
backslashes in inserted variables do not interact with external quoting.

</P>
<P>
<A NAME="IDX1222"></A>
<A NAME="IDX1223"></A>
Special handling takes place when an argument consists precisely of the text
`$pipe_addresses'. 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 <EM>as a separate argument</EM>. This
avoids any problems with spaces or shell metacharacters, and is of use when a
<EM>pipe</EM> transport is handling groups of addresses in a batch (see the <EM>batch</EM>
option below).

</P>
<P>
The resulting command is then run in a subprocess directly from the transport,
<EM>not</EM> under a shell, with the message supplied on the standard input, and
the standard output and standard error both connected to a single pipe that is
read by Exim. The <EM>max_output</EM> option controls how much output the command may
produce, and the <EM>return_output</EM> and <EM>return_fail_output</EM> 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 <TT>`.forward'</TT> files) expect to be run
under a shell and cannot easily be modified. To allow for these cases, there is
an option called <EM>use_shell</EM>, which changes the way the <EM>pipe</EM> 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>/bin/sh</EM>. The <EM>restrict_to_path</EM>
option and the $<EM>pipe_addresses</EM> facility cannot be used with <EM>use_shell</EM>,
and the whole mechanism is inherently less secure.

</P>



<H2><A NAME="SEC504" HREF="spec_toc.html#TOC504">18.3 Environment variables</A></H2>

<P>
The following environment variables are set up when the command is invoked:

<PRE>
DOMAIN               the local domain of the address
HOME                 the `home' directory -- see below
HOST                 the host name when called from a router
LOCAL_PART           see below
LOGNAME              see below
MESSAGE_ID           the message's id
PATH                 as specified by the <EM>path</EM> option below
QUALIFY_DOMAIN       the configured qualification domain
SENDER               the sender of the message
SHELL                /bin/sh
USER                 see below
</PRE>

<P>
<A NAME="IDX1224"></A>
<A NAME="IDX1225"></A>
The <EM>environment</EM> option can be used to add additional variables to this
environment.

</P>
<P>
When a <EM>pipe</EM> transport is called directly from (for example) a <EM>smartuser</EM>
director, 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. LOGNAME and USER
are set to the same value as LOCAL_PART for compatibility with other MTAs.

</P>
<P>
<A NAME="IDX1226"></A>
HOST is set only when a <EM>pipe</EM> transport is called from a router as a
pseudo-remote transport (for example, for handling batched SMTP). It is set to
the first host name specified by the router (if any).

</P>
<P>
<A NAME="IDX1227"></A>
If the transport's <EM>home_directory</EM> option is set, its value is used for
the HOME environment variable. Otherwise, certain directors may set a home
directory value, as described in chapter 13.

</P>



<H2><A NAME="SEC505" HREF="spec_toc.html#TOC505">18.4 Private options for pipe</A></H2>

<P>
<A NAME="IDX1228"></A>

</P>
<P>

<P>
<A NAME="IDX1229"></A>


<H3><A NAME="SEC506" HREF="spec_toc.html#TOC506">allow_commands (pipe)</A></H3>

<P>
Type: string list, expanded<BR>
Default: unset

</P>
<P>
<A NAME="IDX1230"></A>
The string is expanded, and then is interpreted as a colon-separated list of
permitted commands. If <EM>restrict_to_path</EM> is not set, the only commands
permitted are those in the <EM>allow_commands</EM> list. They need not be absolute
paths; the <EM>path</EM> option is still used for relative paths. If
<EM>restrict_to_path</EM> is set with <EM>allow_commands</EM>, the command must
either be in the <EM>allow_commands</EM> list, or a name without any slashes that is
found on the path. In other words, if neither <EM>allow_commands</EM> nor
<EM>restrict_to_path</EM> 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

<PRE>
allow_commands = /usr/ucb/vacation
</PRE>

<P>
and <EM>restrict_to_path</EM> is not set, the only permitted command is
<EM>/usr/ucb/vacation</EM>. The <EM>allow_commands</EM> option may not be set if
<EM>use_shell</EM> is set.

</P>
<P>
<A NAME="IDX1231"></A>


<H3><A NAME="SEC507" HREF="spec_toc.html#TOC507">batch (pipe)</A></H3>

<P>
Type: string<BR>
Default: "none"

</P>
<P>
<A NAME="IDX1232"></A>
<A NAME="IDX1233"></A>
Normally, each address that is directed or routed to a <EM>pipe</EM> transport is
handled separately. In special cases it may be desirable to handle several
addresses at once, for example, when passing a message with several addresses
to a different mail regime (for example, UUCP). If this option is set to the
string `domain', all addresses with the same domain that are directed or routed
to the transport are handled in a single delivery. If it is set to `all',
multiple domains are batched. The list of addresses is included in the
<EM>Envelope-to:</EM> header
<A NAME="IDX1234"></A>
if <EM>envelope_to_add</EM> is set. The addresses can also be set up as
separate arguments to the pipe command by means of the specially-recognized
argument $<EM>pipe_addresses</EM> (see above). Otherwise, the only difference
between this option and <EM>bsmtp</EM> is the inclusion of SMTP command lines in the
output for <EM>bsmtp</EM>. When more than one address is being delivered,
$<EM>local_part</EM> is not set, and $<EM>domain</EM> is set only if they all have the
same domain.

</P>
<P>
<A NAME="IDX1235"></A>


<H3><A NAME="SEC508" HREF="spec_toc.html#TOC508">batch_max (pipe)</A></H3>

<P>
Type: integer<BR>
Default: 100

</P>
<P>
This limits the number of addresses that can be handled in a batch, and applies
to both the <EM>batch</EM> and the <EM>bsmtp</EM> options.

</P>
<P>
<A NAME="IDX1236"></A>


<H3><A NAME="SEC509" HREF="spec_toc.html#TOC509">bsmtp (pipe)</A></H3>

<P>
Type: string<BR>
Default: "none"

</P>
<P>
This option is used to set up a <EM>pipe</EM> transport as a pseudo-remote transport
for delivering messages in batch SMTP format for onward transmission by some
non-Exim means. The value of the option must be one of the strings `none',
`one', `domain', or `all'. The first of these turns the feature off. When
<EM>bstmp</EM> is set, the <EM>batch</EM> option automatically takes the same value.
The <EM>check_string</EM> and <EM>escape_string</EM> options are forced to the values

<PRE>
check_string = "."
escape_string = ".."
</PRE>

<P>
when batched SMTP is in use.
It is
usually necessary to suppress the default settings of the <EM>prefix</EM> and <EM>suffix</EM>
options. A full description of the batch SMTP mechanism is given in section
48.8. See also the <EM>use_crlf</EM> option.

</P>

<P>
<A NAME="IDX1237"></A>


<H3><A NAME="SEC510" HREF="spec_toc.html#TOC510">bsmtp_helo (pipe)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
When this option is set, a HELO line is added to the output at the
start of each message written in batch SMTP format. Some software that reads
batch SMTP is unhappy without this.

</P>
<P>
<A NAME="IDX1238"></A>


<H3><A NAME="SEC511" HREF="spec_toc.html#TOC511">check_string (pipe)</A></H3>

<P>
Type: string<BR>
Default: unset

</P>
<P>
As <EM>pipe</EM> writes the message, the start of each line is tested for matching
<EM>check_string</EM>, and if it does, the initial matching characters are replaced
by the contents of <EM>escape_string</EM>, provided both are set. The value of
<EM>check_string</EM> is a literal string, not a regular expression,
<font color=green>
and the case of any letters it contains is significant.
</font>
When the <EM>bsmtp</EM> option is set, the contents of <EM>check_string</EM> and
<EM>escape_string</EM> are forced to values that implement the SMTP escaping
protocol. Any settings made in the configuration file are ignored.

</P>
<P>
<A NAME="IDX1239"></A>


<H3><A NAME="SEC512" HREF="spec_toc.html#TOC512">command (pipe)</A></H3>

<P>
Type: string, expanded<BR>
Default: unset

</P>
<P>
This option need not be set when <EM>pipe</EM> is being used to deliver to pipes
obtained from address expansions (usually under the instance name
<EM>address_pipe</EM>). In other cases, the option must be set, to provide a command
to be run. It need not yield an absolute path (see the <EM>path</EM> option below).
The command is split up into separate arguments by Exim, and each argument is
separately expanded,
as described in section 18.2 above.

</P>
<P>
<A NAME="IDX1240"></A>


<H3><A NAME="SEC513" HREF="spec_toc.html#TOC513">current_directory (pipe)</A></H3>

<P>
Type: string, expanded<BR>
Default: unset

</P>
<P>
If this option is set, it specifies the directory to make current when running
the delivery process. The string is expanded at the time the transport is run.
If this is not set, the current directory is taken from data associated with
the address. See chapter 13 for full details of the local
delivery environment.

</P>
<P>
<A NAME="IDX1241"></A>


<H3><A NAME="SEC514" HREF="spec_toc.html#TOC514">environment (pipe)</A></H3>

<P>
Type: string, expanded<BR>
Default: unset

</P>
<P>
<A NAME="IDX1242"></A>
<A NAME="IDX1243"></A>
This option is used to add additional variables to the environment in which the
command runs (see section 18.3 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 `&#60;<EM>name</EM>&#62;=&#60;<EM>value</EM>&#62;'.

</P>
<P>
<font color=green>
<A NAME="IDX1244"></A>


<H3><A NAME="SEC515" HREF="spec_toc.html#TOC515">escape_string (pipe)</A></H3>

<P>
Type: string<BR>
Default: unset

</P>
<P>
</font>
See <EM>check_string</EM> above.

</P>
<P>
<A NAME="IDX1245"></A>


<H3><A NAME="SEC516" HREF="spec_toc.html#TOC516">freeze_exec_fail (pipe)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
<A NAME="IDX1246"></A>
<A NAME="IDX1247"></A>
<A NAME="IDX1248"></A>
Failure to exec the command in a pipe transport is by default treated like
any other failure while running the command. However, if <EM>freeze_exec_fail</EM>
is set, failure to exec is treated specially, and causes the message to be
frozen, whatever the setting of <EM>ignore_status</EM>.

</P>
<P>
<A NAME="IDX1249"></A>


<H3><A NAME="SEC517" HREF="spec_toc.html#TOC517">from_hack (pipe)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
This option is obsolete and is retained only for backwards compatibility. Its
value is ignored. It has been replaced by <EM>check_string</EM> and <EM>escape_string</EM>.

</P>
<P>
<A NAME="IDX1250"></A>


<H3><A NAME="SEC518" HREF="spec_toc.html#TOC518">group (pipe)</A></H3>

<P>
Type: string<BR>
Default: unset

</P>
<P>
<A NAME="IDX1251"></A>
If this option is set, it specifies the group under whose gid the delivery
process is to be run. If it is not set, a value associated with a user may be
used (see below); otherwise a value must have been associated with the address
by the director which handled it. If the string contains no $ characters, it
is resolved when Exim starts up. Otherwise, the string is expanded at the time
the transport is run, and must yield either a digit string or a name which can
be looked up using <EM>getgrnam()</EM>.

</P>

<P>
<A NAME="IDX1252"></A>


<H3><A NAME="SEC519" HREF="spec_toc.html#TOC519">home_directory (pipe)</A></H3>

<P>
Type: string, expanded<BR>
Default: unset

</P>
<P>
If this option is set, its expanded value is used to set the HOME
environment variable before running the command. This overrides any value that
is set by the director. If no current directory is supplied by the director or
the transport, the home directory value is used for that as well. See chapter
13 for details of the local delivery environment.

</P>
<P>
<A NAME="IDX1253"></A>


<H3><A NAME="SEC520" HREF="spec_toc.html#TOC520">ignore_status (pipe)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<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 causes an error return from the transport unless
the value is EX_TEMPFAIL, which causes the delivery to be deferred and
tried again later.

</P>
<P>
<A NAME="IDX1254"></A>
<A NAME="IDX1255"></A>
<A NAME="IDX1256"></A>


<H3><A NAME="SEC521" HREF="spec_toc.html#TOC521">initgroups (pipe)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
If this option is true
and the uid for the local delivery is specified by the <EM>user</EM> option,
then the <EM>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 NAME="IDX1257"></A>


<H3><A NAME="SEC522" HREF="spec_toc.html#TOC522">log_defer_output (pipe)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
<A NAME="IDX1258"></A>
If this option is set, and the status returned by the command is
<font color=green>
one of the codes listed in <EM>temp_errors</EM> (that is, delivery was deferred),
</font>
and any output was produced, the first line of it is written to the main log.

</P>
<P>
<A NAME="IDX1259"></A>


<H3><A NAME="SEC523" HREF="spec_toc.html#TOC523">log_fail_output (pipe)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
If this option is set, and the command returns any output, and also ends with a
return code that is neither zero nor
<font color=green>
one of the return codes listed in <EM>temp_errors</EM> (that is, the delivery
failed),
</font>
the first line of output is written to the main log.

</P>
<P>
<A NAME="IDX1260"></A>


<H3><A NAME="SEC524" HREF="spec_toc.html#TOC524">log_output (pipe)</A></H3>

<P>
Type: boolean<BR>
Default: false

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

</P>
<P>
<A NAME="IDX1261"></A>


<H3><A NAME="SEC525" HREF="spec_toc.html#TOC525">max_output (pipe)</A></H3>

<P>
Type: integer<BR>
Default: 20K

</P>
<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
whether any <EM>return_output</EM> option is set or not. Because of buffering
effects, the amount of output may exceed the limit by a small amount before
Exim notices.

</P>
<P>
<A NAME="IDX1262"></A>


<H3><A NAME="SEC526" HREF="spec_toc.html#TOC526">path (pipe)</A></H3>

<P>
Type: string list<BR>
Default: "/usr/bin"

</P>
<P>
This option specifies the string that is set up in the PATH environment
variable of the subprocess.
If the <EM>command</EM> option does not yield an absolute path name, the command is
sought in the PATH directories, in the usual way.

</P>
<P>
<A NAME="IDX1263"></A>


<H3><A NAME="SEC527" HREF="spec_toc.html#TOC527">pipe_as_creator (pipe)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
<A NAME="IDX1264"></A>
If <EM>user</EM> 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 <EM>group</EM> option above, or
by the director that processed the address), the gid that was in force
when Exim was originally called to accept the message is used. Setting this
option may be necessary in order to get some free-standing local delivery
agents to work correctly. Note, however, that the <EM>never_users</EM> configuration
option overrides.

</P>
<P>
<A NAME="IDX1265"></A>


<H3><A NAME="SEC528" HREF="spec_toc.html#TOC528">prefix (pipe)</A></H3>

<P>
Type: string, expanded<BR>
Default: see below

</P>
<P>
The string specified here is expanded and output at the start of every message.
The default is the same as for the <EM>appendfile</EM> transport, namely

<PRE>
prefix = "From ${if def:return_path{$return_path}{MAILER-DAEMON}}\
  ${tod_bsdinbox}\n"
</PRE>

<P>
<A NAME="IDX1266"></A>
<A NAME="IDX1267"></A>
This is required by the commonly used <EM>/usr/ucb/vacation</EM> program,
but it must <EM>not</EM> be present if delivery is to the Cyrus IMAP server,
or to the <EM>tmail</EM> local delivery agent.
The prefix can be suppressed by setting

<PRE>
prefix =
</PRE>

<P>
This is also usually necessary when doing batch SMTP deliveries.

</P>

<P>
<A NAME="IDX1268"></A>


<H3><A NAME="SEC529" HREF="spec_toc.html#TOC529">restrict_to_path (pipe)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
When this option is set,
any command name not listed in <EM>allow_commands</EM>
must contain no slashes. The command is searched for only in the directories
listed in the <EM>path</EM> option. This option is intended for use in the case when a
pipe command has been generated from a user's <TT>`.forward'</TT> file. This is usually
handled by a <EM>pipe</EM> transport called <EM>address_pipe</EM>.

</P>
<P>
<A NAME="IDX1269"></A>


<H3><A NAME="SEC530" HREF="spec_toc.html#TOC530">retry_use_local_part (pipe)</A></H3>

<P>
Type: boolean<BR>
Default: true

</P>
<P>
When a local delivery suffers a temporary failure, both the local part and the
domain are normally used to form a key that is used to determine when next to
try the address. This handles common cases such as exceeding a quota, where the
failure applies to the specific local part. However, when local delivery is
being used to collect messages for onward transmission by some other means, a
temporary failure may not depend on the local part at all. Setting this option
false causes Exim to use only the domain when handling retries for this
transport.

</P>
<P>
<A NAME="IDX1270"></A>


<H3><A NAME="SEC531" HREF="spec_toc.html#TOC531">return_fail_output (pipe)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
If this option is true, and the command produced any output and ended with a
return code other than zero or
<font color=green>
one of the codes listed in <EM>temp_errors</EM> (that is, the delivery failed),
</font>
the output is returned in the delivery error message. However, if the message
has a null sender (that is, it is itself a delivery error message), output from
the command is discarded.

</P>
<P>
<A NAME="IDX1271"></A>


<H3><A NAME="SEC532" HREF="spec_toc.html#TOC532">return_output (pipe)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<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 delivery error message. Otherwise, the output is just
discarded. However, if the message has a null sender (that is, it is a delivery
error message), output from the command is always discarded, whatever the
setting of this option.

</P>
<P>
<A NAME="IDX1272"></A>


<H3><A NAME="SEC533" HREF="spec_toc.html#TOC533">suffix (pipe)</A></H3>

<P>
Type: string, expanded<BR>
Default: "\n"

</P>
<P>
The string specified here is expanded and output at the end of every message.
The default is the same as for the <EM>appendfile</EM> transport.
It can be suppressed by setting

<PRE>
suffix =
</PRE>

<P>
and this is usually necessary when doing batch SMTP deliveries.

</P>
<P>
<A NAME="IDX1273"></A>


<H3><A NAME="SEC534" HREF="spec_toc.html#TOC534">temp_errors (pipe)</A></H3>

<P>
Type: string<BR>
Default: see below

</P>
<P>
<A NAME="IDX1274"></A>
This option contains a colon-separated list of numbers. If <EM>ignore_status</EM> is
false and the command exits with a return code that matches one of the
numbers, the failure is treated as temporary and the delivery is deferred. The
default setting contains the codes defined by EX_TEMPFAIL and
EX_CANTCREAT in <EM>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 NAME="IDX1275"></A>


<H3><A NAME="SEC535" HREF="spec_toc.html#TOC535">timeout (pipe)</A></H3>

<P>
Type: time<BR>
Default: 1h

</P>
<P>
If the command fails to complete within this time, it is killed. This normally
causes the delivery to fail.
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 NAME="IDX1276"></A>


<H3><A NAME="SEC536" HREF="spec_toc.html#TOC536">umask (pipe)</A></H3>

<P>
Type: octal integer<BR>
Default: 022

</P>
<P>
This specifies the umask setting for the subprocess that runs the command.

</P>
<P>
<A NAME="IDX1277"></A>


<H3><A NAME="SEC537" HREF="spec_toc.html#TOC537">use_crlf (pipe)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
<A NAME="IDX1278"></A>
<A NAME="IDX1279"></A>
<A NAME="IDX1280"></A>
<A NAME="IDX1281"></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 <EM>prefix</EM> and <EM>suffix</EM> options are written verbatim, so must
contain their own carriage return characters if these are needed. Since the
default values for both <EM>prefix</EM> and <EM>suffix</EM> end with a single linefeed, their
values almost always need to be changed if <EM>use_crlf</EM> is set.

</P>
<P>
<A NAME="IDX1282"></A>


<H3><A NAME="SEC538" HREF="spec_toc.html#TOC538">use_shell (pipe)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
If this option is set, it causes the command to be passed to <EM>/bin/sh</EM> instead
of being run directly from the transport as described in section
18.2. 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
<EM>allow_commands</EM> and
<EM>restrict_to_path</EM> options, and the `$pipe_addresses' facility are
incompatible with <EM>use_shell</EM>. The command is expanded as a single string, and
handed to <EM>/bin/sh</EM> as data for its -<EM>c</EM> option.

</P>
<P>
<A NAME="IDX1283"></A>


<H3><A NAME="SEC539" HREF="spec_toc.html#TOC539">user (pipe)</A></H3>

<P>
Type: string<BR>
Default: unset

</P>
<P>
<A NAME="IDX1284"></A>
If this option is set, it specifies the user under whose uid the delivery
process is to be run. If it is not set, a value must have been associated with
the address by the director that handled it. If the string contains no $
characters, it is resolved when Exim starts up. Otherwise, the string is
expanded at the time the transport is run, and must yield either a digit string
or a name which can be looked up using <EM>getpwnam()</EM>. When <EM>getpwnam()</EM> is used,
either at start-up time or later, the group id value associated with the user
is taken as the value to be used if the <EM>group</EM> option is not set.

</P>



<H2><A NAME="SEC540" HREF="spec_toc.html#TOC540">18.5 Using an external local delivery agent</A></H2>

<P>
<A NAME="IDX1285"></A>
<A NAME="IDX1286"></A>
<A NAME="IDX1287"></A>
<A NAME="IDX1288"></A>
<A NAME="IDX1289"></A>
The <EM>pipe</EM> transport can be used to pass all messages that require local
delivery to a separate local delivery agent such as <EM>procmail</EM>. 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 director
configuration for <EM>procmail</EM>:

<PRE>
# transport
procmail_pipe:
  driver = pipe
  command = /opt/local/bin/procmail -d $local_part
  return_path_add
  delivery_date_add
  envelope_to_add
  check_string = "From "
  escape_string = "&#62;From "
  user = $local_part
  group = mail
</PRE>


<PRE>
# director
procmail:
  driver = localuser
  transport = procmail_pipe
</PRE>

<P>
In this example, the pipe is run as the local user, but with the group set to
<EM>mail</EM>. An alternative is to run the pipe as a specific user such as <EM>mail</EM>
or <EM>exim</EM>, but in this case you must arrange for <EM>procmail</EM> to trust that
user to supply a correct sender address.
If you don't specify either a <EM>group</EM> or a <EM>user</EM> option, the pipe command
is run as the local user. The home directory is the user's home directory by
default.

</P>
<P>
Note that the command that the pipe transport runs does <EM>not</EM> begin with

<PRE>
IFS=" "
</PRE>

<P>
as shown in the <EM>procmail</EM> documentation, because Exim does not by default use
a shell to run pipe commands.

</P>
<P>
<A NAME="IDX1290"></A>
The next example shows a transport and a director for a system where local
deliveries are handled by the Cyrus IMAP server.

<PRE>
# 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
  prefix =
  suffix =
</PRE>


<PRE>
# director
local_user_cyrus:
  driver = localuser
  suffix = .*
  transport = local_delivery_cyrus
</PRE>

<P>
Note the unsetting of <EM>prefix</EM> and <EM>suffix</EM>, and the use of <EM>return_output</EM> to
cause any text written by Cyrus to be returned to the sender.

</P>

<P><HR><P>
Go to the <A HREF="spec_1.html">first</A>, <A HREF="spec_17.html">previous</A>, <A HREF="spec_19.html">next</A>, <A HREF="spec_59.html">last</A> section, <A HREF="spec_toc.html">table of contents</A>.
</BODY>
</HTML>