pipe <command>
e.g. pipe "$home/bin/countmail $sender_address"
This command sets up delivery to a specified command using a pipe. Remember, however, that no deliveries are done while the filter is being processed. All deliveries happen later on. Therefore, the result of running the pipe is not available to the filter.
When the deliveries are done, a separate process is run, and a copy of the message is passed on its standard input. The process runs as the user, under the user's primary group. Any secondary groups to which the user may belong are not normally taken into account, though the system administrator can configure Exim to set them up. More than one pipe command may appear; each one causes a copy of the message to be written to its argument pipe, provided they are different (duplicate pipe commands are ignored).
When the time comes to transport the message, the command supplied to pipe is split up by Exim into a command name and a number of arguments. These are delimited by white space except for arguments enclosed in double quotes, in which case backslash is interpreted as an escape, or in single quotes, in which case no escaping is recognized. Note that as the whole command is normally supplied in double quotes, a second level of quoting is required for internal double quotes. For example:
pipe "$home/myscript \"size is $message_size\""
String expansion is performed on the separate components after the line has been split up, and the command is then run directly by Exim; it is not run under a shell. Therefore, substitution cannot change the number of arguments, nor can quotes, backslashes or other shell metacharacters in variables cause confusion.
Documentation for some programs that are normally run via this kind of pipe often suggest that the command should start with
IFS=" "
This is a shell command, and should not be present in Exim filter files, since it does not normally run the command under a shell.
However, there is an option that the administrator can set to cause a shell to be used. In this case, the entire command is expanded as a single string and passed to the shell for interpretation. It is recommended that this be avoided if at all possible, since it can lead to problems when inserted variables contain shell metacharacters.
The default PATH set up for the command is determined by the system administrator, usually containing at least /usr/bin so that common commands are available without having to specify an absolute file name. However, it is possible for the system administrator to restrict the pipe facility so that the command name must not contain any / characters, and must be found in one of the directories in the configured PATH. It is also possible for the system administrator to lock out the use of the pipe command altogether.
When the command is run, a number of environment variables are set up. The complete list for pipe deliveries may be found in the Exim reference manual. Those that may be useful for pipe deliveries from user filter files are:
| DOMAIN | the domain of the address |
| HOME | your home directory |
| LOCAL_PART | see below |
| LOCAL_PART_PREFIX | see below |
| LOCAL_PART_SUFFIX | see below |
| LOGNAME | your login name |
| MESSAGE_ID | the message's unique id |
| PATH | the command search path |
| RECIPIENT | the complete recipient address |
| SENDER | the sender of the message |
| SHELL | /bin/sh |
| USER | see below |
LOCAL_PART, LOGNAME, and USER are all set to the same value, namely, your login id. LOCAL_PART_PREFIX and LOCAL_PART_SUFFIX may be set if Exim is configured to recognize prefixes or suffixes in the local parts of addresses. For example, a message addressed to pat-suf2@domain.example may cause user pat's filter file to be run. If this sets up a pipe delivery, LOCAL_PART_SUFFIX is -suf2 when the pipe command runs. The system administrator has to configure Exim specially for this feature to be available.
If you run a command that is a shell script, be very careful in your use of data from the incoming message in the commands in your script. RFC 2822 is very generous in the characters that are legally permitted to appear in mail addresses, and in particular, an address may begin with a vertical bar or a slash. For this reason you should always use quotes round any arguments that involve data from the message, like this:
/some/command '$SENDER'
so that inserted shell meta-characters do not cause unwanted effects.
Remember that, as was explained earlier, the pipe command is not run at the time the filter file is interpreted. The filter just defines what deliveries are required for one particular addressee of a message. The deliveries themselves happen later, once Exim has decided everything that needs to be done for the message.
A consequence of this is that you cannot inspect the return code from the pipe command from within the filter. Neverthless, the code returned by the command is important, because Exim uses it to decide whether the delivery has succeeded or failed.
The command should return a zero completion code if all has gone well. Most non-zero codes are treated by Exim as indicating a failure of the pipe. This is treated as a delivery failure, causing the message to be returned to its sender. However, there are some completion codes which are treated as temporary errors. The message remains on Exim's spool disc, and the delivery is tried again later, though it will ultimately time out if the delivery failures go on too long. The completion codes to which this applies can be specified by the system administrator; the default values are 73 and 75.
The pipe command should not normally write anything to its standard output or standard error file descriptors. If it does, whatever is written is normally returned to the sender of the message as a delivery error, though this action can be varied by the system administrator.