-
-
Notifications
You must be signed in to change notification settings - Fork 2
qmail qfilter.1
qmail-qfilter - front end for qmail-queue that does filtering
qmail-qfilter filter [ -- filter ... ]
qmail-qfilter(1) allows indimail to execute message filters. It gets invoked by indimail programs using qmail-queue frontend when the QMAILQUEUE environment is set to qmail-qfilter or when passed as a command line argument having qmail-qfilter like below (which will have the message pass through qmail-dkim and qmail-qfilter).
QMAILQUEUE="/usr/sbin/qmail-dkim /usr/sbin/qmail-qfilter filter ..."
qmail-qfilter sends the message text through each of the filter commands named on the command line. Each filter is run separately, 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 available 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 is separated by --.
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 79 (bad envelope data) if it can't read or parse the envelope data.
qmail-qfilter returns exit code of filter, if the filter returns anything other than 0 or 99. If your filter exits 88, you can put your custom error string on standard error. This enables client like qmail-smtpd to report the error. The custom error string can be prefixed with D for permanent error and Z to indicate temporary error. If a filter returns 99, qmail-qfilter returns 0 immediately without running any other filters. If your filter returns 31, the mail will be permanently rejected. If your filter returns 71, the mail will be temporarily rejected.
For compatibility 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 or QUEUEPROG is set, that value is used in place of qmail-queue.
qfrontend(1), qmail-queue(8), qmail-multi(8),
NOTES $QMAILQUEUE is deliberately not used to override qmail-queue in order to avoid recursive loops with configurations that set $QMAILQUEUE.
WARNINGS If you are using qmail-inject
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
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.