The `pipe' 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 `pipe' transport, and also when an address is expanded via an alias, filter, or forward file that specifies a pipe command. In this case, `$local_part' contains the local part that was aliased or forwarded, while `$address_pipe' contains the text of the pipe command itself.
A `pipe' 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.
As `pipe' 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 `.forward' 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 "Environment for running local transports" for details of the local delivery environment.
If the command exits with a non-zero return code, the delivery is deemed to have failed, unless either the `ignore_status' option is set (in which case the return code is treated as zero), or the return code is one of those listed in the `temp_errors' option, which are interpreted as meaning `try again later'. In this case, delivery is deferred.
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.
The `return_output' 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 `ignore_status' is set. The output from the command is sent as part of the delivery failure report. However, if `return_fail_output' 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 `temp_errors'.
The command line is (be default) broken down into a command name and arguments by the `pipe' transport. The `allow_commands' and `restrict_to_path' options can be used to restrict the commands that may be run. 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.
String expansion is applied to the command line except when it comes from a
traditional `.forward' 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
will not work, because the expansion item gets split between several
arguments. You have to write
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.
command = /some/path ${if eq{$local_part}{postmaster}{xxx}{yyy}}
command = /some/path "${if eq{$local_part}{postmaster}{xxx}{yyy}}"
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 as a separate argument. This avoids any problems with spaces or shell metacharacters, and is of use when a `pipe' transport is handling groups of addresses in a batch (see the `batch' option below).
The resulting command is then run in a subprocess directly from the transport, not 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 `max_output' option controls how much output the command may produce, and the `return_output' and `return_fail_output' options control what is done with it.
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 `.forward' files) expect to be run under a shell and cannot easily be modified. To allow for these cases, there is an option called `use_shell', which changes the way the `pipe' transport works. Instead of breaking up the command line as just described, it expands it as a single string and passes the result to `/bin/sh'. The `restrict_to_path' option and the `$pipe_addresses' facility cannot be used with `use_shell', and the whole mechanism is inherently less secure.
The following environment variables are set up when the command is invoked:
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 `path' option below QUALIFY_DOMAIN the configured qualification domain SENDER the sender of the message SHELL /bin/sh USER see below
The `environment' option can be used to add additional variables to this environment.
When a `pipe' transport is called directly from (for example) a `smartuser' director, then 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.
HOST is set only when a `pipe' 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).
If the transport's `home_directory' option is set, then its value is used for the HOME environment variable. Otherwise, certain directors may set a home directory value, as described in chapter "Environment for running local transports".
Option: allow_commands
Type: string
Default: unset
The string is expanded, and then is interpreted as a colon-separated list of permitted commands. If `restrict_to_path' is not set, then the only commands permitted are those in the `allow_commands' list. They need not be absolute paths; the path option is still used for relative paths. If `restrict_to_path' is set with `allow_commands', then the command must either be in the `allow_commands' list, or a name without any slashes that is found on the path. In other words, if neither `allow_commands' nor `restrict_to_path' 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
allow_commands = /usr/ucb/vacation
and `restrict_to_commands' is not set, the only permitted command is `/usr/ucb/vacation'. The `allow_commands' option may not be set if `use_shell' is set.
Option: batch
Type: string
Default: "none"
Normally, each address that is directed or routed to a `pipe' 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', then 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' then multiple domains are batched. The list of addresses is included in the `Envelope-to:' header if `envelope_to_add' is set (see below). The addresses can also be set up as separate arguments to the pipe command by means of the specially-recognized argument `$pipe_addresses' (see above). Otherwise, the only difference between this option and `bsmtp' is the inclusion of SMTP command lines in the output for `bsmtp'. When more than one address is being delivered, `$local_part' is not set, and `$domain' is set only if they all have the same domain.
Option: batch_max
Type: integer
Default: 100
This limits the number of addresses that can be handled in a batch, and applies to both the `batch' and the `bsmtp' options.
Option: bsmtp
Type: string
Default: "none"
This option is used to set up a `pipe' 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
`bstmp' is set, the `batch' option automatically takes the same value.
The `check_string' and `escape_string' options are forced to the values
when batched SMTP is in use.
check_string = "."
escape_string = ".."
Option: bsmtp_helo
Type: boolean
Default: false
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.
Option: check_string
Type: string
Default: unset
As `pipe' writes the message, the start of each line is tested for matching `check_string', and if it does, the initial matching characters are replaced by the contents of `escape_string', provided both are set. The value of `check_string' is a literal string, not a regular expression. When the `bsmtp' option is set, the contents of `check_string' and `escape_string' are forced to values that implement the SMTP escaping protocol. Any settings made in the configuration file are ignored.
Option: command
Type: string
Default: unset
This option need not be set when `pipe' is being used to deliver to pipes obtained from address expansions (usually under the instance name `address_pipe'). In other cases, the option must be set, to provide a command to be run. It need not yield an absolute path (see the `path' option below). The command is split up into separate arguments by Exim, and each argument is separately expanded, as described in section "How the command is run" above.
Option: current_directory
Type: string
Default: unset
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 "Environment for running local transports" for full details of the local delivery environment.
Option: environment
Type: string
Default: unset
This option is used to add additional variables to the environment in which the command runs (see section "Environment variables" 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 `<name>=<value>'.
Option: escape_string
Type: string
Default: ">From "
See `check_string' above.
Option: freeze_exec_fail
Type: boolean
Default: false
Failure to exec the command in a pipe transport is by default treated like any other failure while running the command. However, if `freeze_exec_fail' is set, failure to exec is treated specially, and causes the message to be frozen, whatever the setting of `ignore_status'.
Option: from_hack
Type: boolean
Default: false
This option is obsolete and is retained only for backwards compatibility. Its value is ignored. It has been replaced by `check_string' and `escape_string'.
Option: group
Type: string
Default: unset
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 `getgrnam()'.
Option: home_directory
Type: string
Default: unset
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 "Environment for running local transports" for details of the local delivery environment.
Option: ignore_status
Type: boolean
Default: false
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.
Option: initgroups
Type: boolean
Default: false
If this option is true and the uid for the local delivery is specified by the `user' option, then the `initgroups()' function is called when running the transport to ensure that any additional groups associated with the uid are set up.
Option: log_defer_output
Type: boolean
Default: false
If this option is set and the status returned by the command is EX_TEMPFAIL and any output was produced, the first line of it is written to the main log.
Option: log_fail_output
Type: boolean
Default: false
If this option is set and the command returns any output and also ends with a return code that is neither zero nor EX_TEMPFAIL, the first line of output is written to the main log.
Option: log_output
Type: boolean
Default: false
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.
Option: max_output
Type: integer
Default: 20K
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 `return_output' option is set or not. Because of buffering effects, the amount of output may exceed the limit by a small amount before Exim notices.
Option: path
Type: string-list
Default: "/usr/bin"
This option specifies the string that is set up in the PATH environment variable of the subprocess. If the `command' option does not yield an absolute path name, the command is sought in the PATH directories, in the usual way.
Option: pipe_as_creator
Type: boolean
Default: false
If `user' is not set and this option is true, then 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 `group' option above, or by the director that processed the address), then 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 `never_users' configuration option overrides.
Option: prefix
Type: string
Default: "see below"
The string specified here is expanded and output at the start of every message. The default is the same as for the `appendfile' transport, namely
prefix = "From ${if def:return_path{$return_path}{MAILER-DAEMON}}\
${tod_bsdinbox}\n"
This is required by the commonly used `/usr/ucb/vacation' program, but it must not be present if delivery is to the Cyrus IMAP server, or to the `tmail' local delivery agent. The prefix can be suppressed by setting
prefix =
This is also usually necessary when doing batch SMTP deliveries.
Option: restrict_to_path
Type: boolean
Default: false
When this option is set, any command name not listed in `allow_commands' must contain no slashes. The command is searched for only in the directories listed in the `path' option. This option is intended for use in the case when a pipe command has been generated from a user's `.forward' file. This is usually handled by a `pipe' transport called `address_pipe'.
Option: retry_use_local_part
Type: boolean
Default: true
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.
Option: return_fail_output
Type: boolean
Default: false
If this option is true, and the command produced any output and ended with a return code other than zero or EX_TEMPFAIL, the output is returned in the delivery error message. However, if the message has a null sender (that is, it is a delivery error message), output from the command is discarded.
Option: return_output
Type: boolean
Default: false
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.
Option: suffix
Type: string
Default: "\n"
The string specified here is expanded and output at the end of every message. The default is the same as for the `appendfile' transport. It can be suppressed by setting
suffix =
and this is usually necessary when doing batch SMTP deliveries.
Option: temp_errors
Type: string
Default: "see below"
This option contains a colon-separated list of numbers. If `ignore_status' 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 `sysexits.h'. If Exim is compiled on a system that does not define these macros, it assumes values of 75 and 73, respectively.
Option: timeout
Type: time
Default: 1h
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.
Option: umask
Type: "octal
Default: integer" 022
This specifies the umask setting for the subprocess that runs the command.
Option: use_crlf
Type: boolean
Default: false
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.
The contents of the `prefix' and `suffix' options are written verbatim, so must contain their own carriage return characters if these are needed. Since the default values for both `prefix' and `suffix' end with a single linefeed, their values almost always need to be changed if `use_crlf' is set.
Option: use_shell
Type: boolean
Default: false
If this option is set, it causes the command to be passed to `/bin/sh' instead of being run directly from the transport as described in section "How the command is run". 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 `allow_commands' and `restrict_to_path' options, and the `$pipe_addresses' facility are incompatible with `use_shell'. The command is expanded as a single string, and handed to `/bin/sh' as data for its `-c' option.
Option: user
Type: string
Default: unset
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 `getpwnam()'. When `getpwnam()' 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 `group' option is not set.
The `pipe' transport can be used to pass all messages that require local
delivery to a separate local delivery agent such as `procmail'. 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 `procmail':
In this example, the pipe is run as the local user, but with the group set to
"mail". An alternative is to run the pipe as a specific user such as "mail"
or "exim", but in this case you must arrange for `procmail' to trust that
user to supply a correct sender address.
# 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 = ">From "
user = $local_part
group = mail
# director
procmail:
driver = localuser
transport = procmail_pipe
Note that the command that the pipe transport runs does not begin with
IFS=" "
as shown in the `procmail' documentation, because Exim does not by default use a shell to run pipe commands.
The next example shows a transport and a director for a system where local deliveries are handled by the Cyrus IMAP server.
# 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 =
# director local_user_cyrus: driver = localuser suffix = .* transport = local_delivery_cyrus
Note the unsetting of `prefix' and `suffix', and the use of `return_output' to cause any text written by Cyrus to be returned to the sender.
Go to the first, previous, next, last section, table of contents.