Exim Filter Specification - The pipe command

Go to the first, previous, next, last section, table of contents.

## The pipe command

         pipe <command>
    e.g. pipe "$home/bin/countmail $sender_address"

This command causes a separate process to be 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).

The command supplied to pipe is split up by Exim into a command name and a number of arguments, 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 the the command 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, the following environment variables are set up:

    DOMAIN               the local domain of the address
    HOME                 your home directory
    LOCAL_PART           your login name
    LOGNAME              your login name
    MESSAGE_ID           the message's unique id
    PATH                 the command search path
    SENDER               the sender of the message
    SHELL                /bin/sh
    USER                 your login name

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 822 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.

The pipe 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.

Go to the first, previous, next, last section, table of contents.