<!DOCTYPE html PUBLIC "XSLT-compat"> <html lang="en-GB"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <link rel="stylesheet" type="text/css" href="../../../../common.css"> <meta name="author" content="The Exim Project. <http://www.exim.org/>"> <meta name="copyright" content="Copyright ©2010 The Exim Project. All rights reserved"> <meta name="description" content="Exim is a message transfer agent (MTA) developed at the University of Cambridge for use on Unix systems connected to the Internet."> <meta name="keywords" content="exim,smtp,mta,email"> <meta name="robots" content="noodp,noydir,index,follow"> <meta name="viewport" content="width=device-width"> <title>29. The pipe transport</title> <link rel="stylesheet" type="text/css" href="../../../../doc/chapter.css"> <link rel="canonical" href="http://www.exim.org/exim-html-current/doc/html/spec_html/ch29.html"> </head> <body> <h1 id="header"><a href="../../../..">Exim Internet Mailer</a></h1> <div id="outer"> <ul id="nav_flow" class="nav"> <li><a href="../../../../index.html">Home</a></li> <li><a href="../../../../mirrors.html">Download</a></li> <li><a href="../../../../docs.html">Documentation</a></li> <li><a href="../../../../maillist.html">Mailing Lists</a></li> <li><a href="http://wiki.exim.org/">Wiki</a></li> <li><a href="http://www.exim.org/bugzilla/">Bugs</a></li> <li><a href="../../../../credits.html">Credits</a></li> <li class="search"><form action="http://www.google.com/search" method="get"> <span class="search_field_container"><input type="search" name="q" placeholder="Search Docs" class="search_field"></span><input type="hidden" name="hl" value="en"><input type="hidden" name="ie" value="UTF-8"><input type="hidden" name="as_qdr" value="all"><input type="hidden" name="q" value="site:www.exim.org"><input type="hidden" name="q" value="inurl:exim-html-current"> </form></li> </ul> <div id="inner"><div id="content"> <a class="previous_page" href="ch28.html"><-previous</a><a class="next_page" href="ch30.html">next-></a><div id="chapter" class="chapter"> <h2 id="CHAPpipetransport" class="">Chapter 29 - The pipe transport</h2> <p> The <span class="docbook_command">pipe</span> transport is used to deliver messages via a pipe to a command running in another process. One example is the use of <span class="docbook_command">pipe</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 class="docbook_command">pipe</span> transport can be used in one of the following ways: </p> <ul> <li> <p> A router routes one address to a transport in the normal way, and the transport is configured as a <span class="docbook_command">pipe</span> transport. In this case, $local_part contains the local part of the address (as usual), and the command that is run is specified by the <span class="docbook_option">command</span> option on the transport. </p> </li> <li> <p> If the <span class="docbook_option">batch_max</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, $local_part is not set (because it is not unique). However, the pseudo-variable $pipe_addresses (described in section <a href="ch29.html#SECThowcommandrun" title="29. The pipe transport">29.3</a> below) contains all the addresses that are routed to the transport. </p> </li> <li> <p> A router redirects an address directly to a pipe command (for example, from an alias or forward file). In this case, $address_pipe contains the text of the pipe command, and the <span class="docbook_option">command</span> option on the transport is ignored. If only one address is being transported (<span class="docbook_option">batch_max</span> is not greater than one, or only one address was redirected to this pipe command), $local_part contains the local part that was redirected. </p> </li> </ul> <p> The <span class="docbook_command">pipe</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 class="docbook_command">lmtp</span> transport. </p> <p> In the case when <span class="docbook_command">pipe</span> is run as a consequence of an entry in a local user’s <span class="docbook_filename">.forward</span> 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 “home” 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"> <h3 id="SECID140" class="">1. Concurrent delivery</h3> <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 class="docbook_option">exim_lock</span> utility might be of use. </p> </div> <div class="section"> <h3 id="SECID141" class="">2. Returned status and data</h3> <p> If the command exits with a non-zero return code, the delivery is deemed to have failed, unless either the <span class="docbook_option">ignore_status</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 class="docbook_option">temp_errors</span> option, which are interpreted as meaning “try again later”. In this case, delivery is deferred. Details of a permanent failure are logged, but are not included in the bounce message, which merely contains “local delivery failed”. </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 <span class="docbook_function">execve()</span> 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 class="docbook_option">return_output</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 class="docbook_option">ignore_status</span> is set. The output from the command is included as part of the bounce message. The <span class="docbook_option">return_fail_output</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 class="docbook_option">temp_errors</span>. </p> </div> <div class="section"> <h3 id="SECThowcommandrun" class="">3. How the command is run</h3> <p> The command line is (by default) broken down into a command name and arguments by the <span class="docbook_command">pipe</span> transport itself. The <span class="docbook_option">allow_commands</span> and <span class="docbook_option">restrict_to_path</span> options can be used to restrict the commands that may be run. </p> <p> 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 <span class="docbook_filename">.forward</span> 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> <div class="docbook_literallayout"><pre> command = /some/path ${if eq{$local_part}{postmaster}{xx}{yy}} </pre></div> <p> will not work, because the expansion item gets split between several arguments. You have to write </p> <div class="docbook_literallayout"><pre> command = /some/path "${if eq{$local_part}{postmaster}{xx}{yy}}" </pre></div> <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> <div class="docbook_literallayout"><pre> command = /bin/sh -c ${lookup{$local_part}lsearch{/some/file}} </pre></div> <p> Special handling takes place when an argument consists of precisely the text <code class="docbook_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="docbook_emphasis">as a separate argument</span>. This avoids any problems with spaces or shell metacharacters, and is of use when a <span class="docbook_command">pipe</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="docbook_emphasis">not</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 class="docbook_option">max_output</span> option controls how much output the command may produce, and the <span class="docbook_option">return_output</span> and <span class="docbook_option">return_fail_output</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 <span class="docbook_filename">.forward</span> files) expect to be run under a shell and cannot easily be modified. To allow for these cases, there is an option called <span class="docbook_option">use_shell</span>, which changes the way the <span class="docbook_command">pipe</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 <span class="docbook_filename">/bin/sh</span>. The <span class="docbook_option">restrict_to_path</span> option and the $pipe_addresses facility cannot be used with <span class="docbook_option">use_shell</span>, and the whole mechanism is inherently less secure. </p> </div> <div class="section"> <h3 id="SECTpipeenv" class="">4. Environment variables</h3> <p> 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 class="docbook_option">environment</span> option can be used to add additional variables to this environment. </p> <div class="docbook_literallayout"><pre> <code class="docbook_literal">DOMAIN </code> the domain of the address <code class="docbook_literal">HOME </code> the home directory, if set <code class="docbook_literal">HOST </code> the host name when called from a router (see below) <code class="docbook_literal">LOCAL_PART </code> see below <code class="docbook_literal">LOCAL_PART_PREFIX </code> see below <code class="docbook_literal">LOCAL_PART_SUFFIX </code> see below <code class="docbook_literal">LOGNAME </code> see below <code class="docbook_literal">MESSAGE_ID </code> Exim’s local ID for the message <code class="docbook_literal">PATH </code> as specified by the <span class="docbook_option">path</span> option below <code class="docbook_literal">QUALIFY_DOMAIN </code> the sender qualification domain <code class="docbook_literal">RECIPIENT </code> the complete recipient address <code class="docbook_literal">SENDER </code> the sender of the message (empty if a bounce) <code class="docbook_literal">SHELL </code> <code class="docbook_literal">/bin/sh</code> <code class="docbook_literal">TZ </code> the value of the <span class="docbook_option">timezone</span> option, if set <code class="docbook_literal">USER </code> see below </pre></div> <p> When a <span class="docbook_command">pipe</span> transport is called directly from (for example) an <span class="docbook_command">accept</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> HOST is set only when a <span class="docbook_command">pipe</span> transport is called from a router that associates hosts with an address, typically when using <span class="docbook_command">pipe</span> as a pseudo-remote transport. HOST is set to the first host name specified by the router. </p> <p> If the transport’s generic <span class="docbook_option">home_directory</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 class="docbook_option">transport_home_directory</span> option, which defaults to the user’s home directory if <span class="docbook_option">check_local_user</span> is set. </p> </div> <div class="section"> <h3 id="SECID142" class="">5. Private options for pipe</h3> <p> </p> <p> </p> <table> <tr> <td><span class="docbook_option">allow_commands</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">string list</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> The string is expanded, and is then interpreted as a colon-separated list of permitted commands. If <span class="docbook_option">restrict_to_path</span> is not set, the only commands permitted are those in the <span class="docbook_option">allow_commands</span> list. They need not be absolute paths; the <span class="docbook_option">path</span> option is still used for relative paths. If <span class="docbook_option">restrict_to_path</span> is set with <span class="docbook_option">allow_commands</span>, the command must either be in the <span class="docbook_option">allow_commands</span> list, or a name without any slashes that is found on the path. In other words, if neither <span class="docbook_option">allow_commands</span> nor <span class="docbook_option">restrict_to_path</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> <div class="docbook_literallayout"><pre> allow_commands = /usr/bin/vacation </pre></div> <p> and <span class="docbook_option">restrict_to_path</span> is not set, the only permitted command is <span class="docbook_filename">/usr/bin/vacation</span>. The <span class="docbook_option">allow_commands</span> option may not be set if <span class="docbook_option">use_shell</span> is set. </p> <p> </p> <table> <tr> <td><span class="docbook_option">batch_id</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <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> </p> <table> <tr> <td><span class="docbook_option">batch_max</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">integer</span> </td> <td>Default: <span class="docbook_emphasis">1</span> </td> </tr> </table> <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> </p> <table> <tr> <td><span class="docbook_option">check_string</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">string</span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> As <span class="docbook_command">pipe</span> writes the message, the start of each line is tested for matching <span class="docbook_option">check_string</span>, and if it does, the initial matching characters are replaced by the contents of <span class="docbook_option">escape_string</span>, provided both are set. The value of <span class="docbook_option">check_string</span> is a literal string, not a regular expression, and the case of any letters it contains is significant. When <span class="docbook_option">use_bsmtp</span> is set, the contents of <span class="docbook_option">check_string</span> and <span class="docbook_option">escape_string</span> are forced to values that implement the SMTP escaping protocol. Any settings made in the configuration file are ignored. </p> <p> </p> <table> <tr> <td><span class="docbook_option">command</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> This option need not be set when <span class="docbook_command">pipe</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 class="docbook_option">path</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. The pipe transport">29.3</a> above. </p> <p> </p> <table> <tr> <td><span class="docbook_option">environment</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> 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. The pipe transport">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="docbook_emphasis">name</span>>=<<span class="docbook_emphasis">value</span>>. </p> <p> </p> <table> <tr> <td><span class="docbook_option">escape_string</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">string</span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> See <span class="docbook_option">check_string</span> above. </p> <p> </p> <table> <tr> <td><span class="docbook_option">freeze_exec_fail</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> Failure to exec the command in a pipe transport is by default treated like any other failure while running the command. However, if <span class="docbook_option">freeze_exec_fail</span> is set, failure to exec is treated specially, and causes the message to be frozen, whatever the setting of <span class="docbook_option">ignore_status</span>. </p> <p> </p> <table> <tr> <td><span class="docbook_option">ignore_status</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <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 class="docbook_option">temp_errors</span>; these cause the delivery to be deferred and tried again later. </p> <p> <span class="docbook_emphasis">Note</span>: This option does not apply to timeouts, which do not return a status. See the <span class="docbook_option">timeout_defer</span> option for how timeouts are handled. </p> <p> </p> <table> <tr> <td><span class="docbook_option">log_defer_output</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> If this option is set, and the status returned by the command is one of the codes listed in <span class="docbook_option">temp_errors</span> (that is, delivery was deferred), and any output was produced, the first line of it is written to the main log. </p> <p> </p> <table> <tr> <td><span class="docbook_option">log_fail_output</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <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 class="docbook_option">temp_errors</span> (that is, the delivery failed), the first line of output is written to the main log. This option and <span class="docbook_option">log_output</span> are mutually exclusive. Only one of them may be set. </p> <p> </p> <table> <tr> <td><span class="docbook_option">log_output</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <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 class="docbook_option">log_fail_output</span> are mutually exclusive. Only one of them may be set. </p> <p> </p> <table> <tr> <td><span class="docbook_option">max_output</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">integer</span> </td> <td>Default: <span class="docbook_emphasis">20K</span> </td> </tr> </table> <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 class="docbook_option">return_output</span>). Because of buffering effects, the amount of output may exceed the limit by a small amount before Exim notices. </p> <p> </p> <table> <tr> <td><span class="docbook_option">message_prefix</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">see below</span> </td> </tr> </table> <p> The string specified here is expanded and output at the start of every message. The default is unset if <span class="docbook_option">use_bsmtp</span> is set. Otherwise it is </p> <div class="docbook_literallayout"><pre> message_prefix = \ From ${if def:return_path{$return_path}{MAILER-DAEMON}}\ ${tod_bsdinbox}\n </pre></div> <p> This is required by the commonly used <span class="docbook_filename">/usr/bin/vacation</span> program. However, it must <span class="docbook_emphasis">not</span> be present if delivery is to the Cyrus IMAP server, or to the <span class="docbook_option">tmail</span> local delivery agent. The prefix can be suppressed by setting </p> <div class="docbook_literallayout"><pre> message_prefix = </pre></div> <p> <span class="docbook_emphasis">Note:</span> If you set <span class="docbook_option">use_crlf</span> true, you must change any occurrences of <code class="docbook_literal">\n</code> to <code class="docbook_literal">\r\n</code> in <span class="docbook_option">message_prefix</span>. </p> <p> </p> <table> <tr> <td><span class="docbook_option">message_suffix</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">see below</span> </td> </tr> </table> <p> The string specified here is expanded and output at the end of every message. The default is unset if <span class="docbook_option">use_bsmtp</span> is set. Otherwise it is a single newline. The suffix can be suppressed by setting </p> <div class="docbook_literallayout"><pre> message_suffix = </pre></div> <p> <span class="docbook_emphasis">Note:</span> If you set <span class="docbook_option">use_crlf</span> true, you must change any occurrences of <code class="docbook_literal">\n</code> to <code class="docbook_literal">\r\n</code> in <span class="docbook_option">message_suffix</span>. </p> <p> </p> <table> <tr> <td><span class="docbook_option">path</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">string</span> </td> <td>Default: <span class="docbook_emphasis">see below</span> </td> </tr> </table> <p> This option specifies the string that is set up in the PATH environment variable of the subprocess. The default is: </p> <div class="docbook_literallayout"><pre> /bin:/usr/bin </pre></div> <p> If the <span class="docbook_option">command</span> option does not yield an absolute path name, the command is sought in the PATH directories, in the usual way. <span class="docbook_emphasis">Warning</span>: This does not apply to a command specified as a transport filter. </p> <p class="changed"> </p> <table> <tr> <td><span class="docbook_option">permit_coredump</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p class="changed"> Normally Exim inhibits core-dumps during delivery. If you have a need to get a core-dump of a pipe command, enable this command. This enables core-dumps during delivery and affects both the Exim binary and the pipe command run. It is recommended that this option remain off unless and until you have a need for it and that this only be enabled when needed, as the risk of excessive resource consumption can be quite high. Note also that Exim is typically installed as a setuid binary and most operating systems will inhibit coredumps of these by default, so further OS-specific action may be required. </p> <p> </p> <table> <tr> <td><span class="docbook_option">pipe_as_creator</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> If the generic <span class="docbook_option">user</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 class="docbook_option">group</span> option), the gid that was in force when Exim was originally called to accept the message is used. </p> <p> </p> <table> <tr> <td><span class="docbook_option">restrict_to_path</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> When this option is set, any command name not listed in <span class="docbook_option">allow_commands</span> must contain no slashes. The command is searched for only in the directories listed in the <span class="docbook_option">path</span> option. This option is intended for use in the case when a pipe command has been generated from a user’s <span class="docbook_filename">.forward</span> file. This is usually handled by a <span class="docbook_command">pipe</span> transport called <span class="docbook_option">address_pipe</span>. </p> <p> </p> <table> <tr> <td><span class="docbook_option">return_fail_output</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <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 class="docbook_option">temp_errors</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 class="docbook_option">return_output</span> are mutually exclusive. Only one of them may be set. </p> <p> </p> <table> <tr> <td><span class="docbook_option">return_output</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <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 class="docbook_option">return_fail_output</span> are mutually exclusive. Only one of them may be set. </p> <p> </p> <table> <tr> <td><span class="docbook_option">temp_errors</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">string list</span> </td> <td>Default: <span class="docbook_emphasis">see below</span> </td> </tr> </table> <p> This option contains either a colon-separated list of numbers, or a single asterisk. If <span class="docbook_option">ignore_status</span> is false and <span class="docbook_option">return_output</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 <span class="docbook_filename">sysexits.h</span>. If Exim is compiled on a system that does not define these macros, it assumes values of 75 and 73, respectively. </p> <p> </p> <table> <tr> <td><span class="docbook_option">timeout</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">time</span> </td> <td>Default: <span class="docbook_emphasis">1h</span> </td> </tr> </table> <p> If the command fails to complete within this time, it is killed. This normally causes the delivery to fail (but see <span class="docbook_option">timeout_defer</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> </p> <table> <tr> <td><span class="docbook_option">timeout_defer</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> A timeout in a <span class="docbook_command">pipe</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 class="docbook_option">timeout_defer</span> is set true, both kinds of timeout become temporary errors, causing the delivery to be deferred. </p> <p> </p> <table> <tr> <td><span class="docbook_option">umask</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">octal integer</span> </td> <td>Default: <span class="docbook_emphasis">022</span> </td> </tr> </table> <p> This specifies the umask setting for the subprocess that runs the command. </p> <p> </p> <table> <tr> <td><span class="docbook_option">use_bsmtp</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> If this option is set true, the <span class="docbook_command">pipe</span> transport writes messages in “batch SMTP” 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 class="docbook_option">message_prefix</span> option. See section <a href="ch45.html#SECTbatchSMTP" title="45. SMTP processing">45.10</a> for details of batch SMTP. </p> <p> </p> <table> <tr> <td><span class="docbook_option">use_classresources</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> This option is available only when Exim is running on FreeBSD, NetBSD, or BSD/OS. If it is set true, the <span class="docbook_function">setclassresources()</span> function is used to set resource limits when a <span class="docbook_command">pipe</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> </p> <table> <tr> <td><span class="docbook_option">use_crlf</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> 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 class="docbook_option">message_prefix</span> and <span class="docbook_option">message_suffix</span> options are written verbatim, so must contain their own carriage return characters if these are needed. When <span class="docbook_option">use_bsmtp</span> is not set, the default values for both <span class="docbook_option">message_prefix</span> and <span class="docbook_option">message_suffix</span> end with a single linefeed, so their values must be changed to end with <code class="docbook_literal">\r\n</code> if <span class="docbook_option">use_crlf</span> is set. </p> <p> </p> <table> <tr> <td><span class="docbook_option">use_shell</span></td> <td>Use: <span class="docbook_emphasis">pipe</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> If this option is set, it causes the command to be passed to <span class="docbook_filename">/bin/sh</span> instead of being run directly from the transport, as described in section <a href="ch29.html#SECThowcommandrun" title="29. The pipe transport">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 class="docbook_option">allow_commands</span> and <span class="docbook_option">restrict_to_path</span> options, and the <code class="docbook_literal">$pipe_addresses</code> facility are incompatible with <span class="docbook_option">use_shell</span>. The command is expanded as a single string, and handed to <span class="docbook_filename">/bin/sh</span> as data for its <span class="docbook_option">-c</span> option. </p> </div> <div class="section"> <h3 id="SECID143" class="">6. Using an external local delivery agent</h3> <p> The <span class="docbook_command">pipe</span> transport can be used to pass all messages that require local delivery to a separate local delivery agent such as <span class="docbook_option">procmail</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 class="docbook_option">procmail</span>: </p> <div class="docbook_literallayout"><pre> # 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 " umask = 077 user = $local_part group = mail # router procmail: driver = accept check_local_user transport = procmail_pipe </pre></div> <p> In this example, the pipe is run as the local user, but with the group set to <span class="docbook_emphasis">mail</span>. An alternative is to run the pipe as a specific user such as <span class="docbook_emphasis">mail</span> or <span class="docbook_emphasis">exim</span>, but in this case you must arrange for <span class="docbook_option">procmail</span> to trust that user to supply a correct sender address. If you do not specify either a <span class="docbook_option">group</span> or a <span class="docbook_option">user</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="docbook_emphasis">Note</span>: The command that the pipe transport runs does <span class="docbook_emphasis">not</span> begin with </p> <div class="docbook_literallayout"><pre> IFS=" " </pre></div> <p> as shown in some <span class="docbook_option">procmail</span> documentation, because Exim does not by default use a shell to run pipe commands. </p> <p> The next example shows a transport and a router for a system where local deliveries are handled by the Cyrus IMAP server. </p> <div class="docbook_literallayout"><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 message_prefix = message_suffix = # router local_user_cyrus: driver = accept check_local_user local_part_suffix = .* transport = local_delivery_cyrus </pre></div> <p> Note the unsetting of <span class="docbook_option">message_prefix</span> and <span class="docbook_option">message_suffix</span>, and the use of <span class="docbook_option">return_output</span> to cause any text written by Cyrus to be returned to the sender. </p> </div> </div> <a class="previous_page" href="ch28.html"><-previous</a><a class="next_page" href="ch30.html">next-></a> </div></div> <iframe id="branding" name="branding" src="../../../../branding/branding.html" height="0" frameborder="no" scrolling="no"></iframe><div id="footer">Website design by <a href="https://secure.grepular.com/">Mike Cardwell</a>, of <a href="http://cardwellit.com/">Cardwell IT Ltd.</a> </div> <div class="left_bar"></div> <div class="right_bar"></div> <div id="toc"> <ul class="hidden"></ul> <img src="../../../../doc/contents.png" width="16" height="155"> </div> </div> <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script><script type="text/javascript" src="../../../../common.js"></script><script type="text/javascript" src="../../../../doc/chapter.js"></script> </body> </html>