NAME

qmail-qfilter - front end for qmail-queue that does filtering

SYNOPSIS

qmail-qfilter filter [ -- filter ... ]

DESCRIPTION

qmail-qfilter sends the message text through each of the filter commands named on the command line. Each filter is run seperately, with standard input opened to the input email, and standard output opened to a new temporary file that will become the input to either the next filter, or qmail-queue. If the filter does not modify the message it passes unchanged to the next step. It also makes the envelope avaliable to each filter as file descriptor 3. File descriptor 4 is opened to a new temporary file for the modified envelope, allowing the filter to modify the envelope or the message. If the filter does not modify the envelope, the envelope remains unchanged for either the next filter or qmail-queue. This provides compatibility for existing filters that do not know about the envelope. qmail-qfilter also opens up file descriptor 5 to a temporary file. If this file is empty after all the filters have executed, its contents are read and used to specify a program to execute in place of qmail-queue. Each filter on the command line in seperated with --.

RETURN VALUES

Returns 51 (out of memory), 53 (write error), or 81 (internal error) if it can't create the temporary files or has problems executing the filters. Returns 91 (bad envelope data) if it can't read or parse the envelope data. If a filter returns anything other than 0 or 99, qmail-qfilter returns its exit code. If a filter returns 99, qmail-qfilter returns 0 immediately without running any other filters. Otherwise returns the exit code of qmail-queue.

ENVIRONMENT

For cmpatibility with previous versions, qmail-qfilter sets QMAILUSER and QMAILHOST to the user and host portions of the envelope sender address, and unsets QMAILNAME. It also sets QMAILRCPTS to the list of envelope recipients, each followed by a newline.

It also sets ENVSIZE to the size of the envelope, MSGSIZE to the length of the message, and NUMRCPTS to the number of recipients. These values are updated before each filter is run.

If QQF_QMAILQUEUE is set, its value is used in place of qmail-queue.

NOTES

$QMAILQUEUE is deliberately not used to override qmail-queue in order to avoid recursive loops with configurations that set $QMAILQUEUE to invoke qmail-qfilter itself.

WARNINGS

If you are using qmail-inject -n as one of the filters, you may want to unset MAILUSER, USER, and LOGNAME by using env -u QMAILNAME -u MAILNAME -u NAME qmail-inject -n as the command to invoke qmail-inject. Note that some the env command with some OS's doesn't support the -u option.

A message with an excessive number of recipients (more than 64K bytes of recipient data on Linux) will cause execution of the filter programs to fail, and for the message to be rejected.

The same temporary file is reused for file descriptor 5 for each filter. Make sure each filter writes a trailing ASCII NUL byte following the program name, as multiple filters could otherwise overwrite the value in undesireable ways.