qmail-qfilter(1)qmail-qfilter(1)NAMEqmail-qfilter - front end for qmail-queue that does filtering
SYNOPSISqmail-qfilter filter [ -- filter ... ]
DESCRIPTIONqmail-qfilter sends the message text through each of the filter com‐
mands 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 fil‐
ter, or qmail-queue. If the filter does not modify the message it
passes unchanged to the next step. It also makes the envelope avali‐
able 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 pro‐
gram 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 fil‐
ters. 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.
SEE ALSOqmail-queue(8)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 fil‐
ter. 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.
qmail-qfilter(1)
