-
-
Notifications
You must be signed in to change notification settings - Fork 2
spawn filter.8
spawn-filter - qmail-local / qmail-remote interceptor
spawn-filter args
spawn-filter is a qmail-local / qmail-remote interceptor to help qmail run custom filters for email being sent by qmail-local or qmail-remote. It can run any script or program which reads messages on fd 0 and writes the output on fd 1. Whatever is output on fd 1, will be the input on descriptor 0 for qmail-local and qmail-remote. Thus the output of the filter program becomes the message that will be delivered to the destination. The filter can be turned on individually for local and remote mails by defining, QMAILLOCAL and QMAILREMOTE environment variables, to the path of spawn-filter respectively in qmail-send's supervise or rc script. If spawn-filter is invoked as qmail-local or qmail-remote, it executes qmail-local or qmail-remote after running the custom filter. The filter script or program is run as a child of spawn-filter.
spawn-filter is run by qmail-lspawn or qmail-rspawn with the same args that is passed to qmail-local or qmail-remote. If QMAILLOCAL is set as /usr/bin/spawn-filter, qmail-lspawn runs spawn-filter with the same args that is passed to qmail-local. If QMAILREMOTE is set as /usr/bin/spawn-filter, qmail-rspawn runs spawn-filter with the same args that is passed to qmail-remote.
spawn-filter unsets QMAILREMOTE when it runs as qmail-local. Similarly, it unsets QMAILLOCAL when it runs as qmail-remote. This is useful in scripts to figure out whether spawn-filter is running as qmail-local or qmail-remote. You can set QLOCAL, QREMOTE environment variable to make spawn-filter run an alternate qmail-local, qmail-remote programs. The alternate programs are expected to support the same interface as the original qmail-local and qmail-remote.
Filters can be run by defining the environment variable FILTERARGS or by using the control file filterargs (see below). spawn-filter uses /bin/sh to run the filter (with arguments) specified by the FILTERARGS environment variable (or the control file filterargs). The environment variable FILTERARGS apply to both local and remote mails. For individual domain level control, it is best to set using the control file filterargs (see below the section on control files). The environment variable FILTERARGS takes precedence over the control file.
spawn-filter sets multiple environment variables which can be conveniently used in programs/scripts which get invoked by setting FILTERARGS environment variable or by rules in the filterargs control file. See the section on Environment Variables below.
spawn-filter unsets FILTERARGS, SPAMFILTER, QMAILLOCAL, QMAILREMOTE before running qmail-local or qmail-remote. spawn-filter unsets FILTERARGS, SPAMFILTER before running filter.
filterargs
This control file can be used to setup additional filters after running
the SPAM filters (See the section on SPAM Filtering). This file has the
following format.
domain:args
or
domain:args:envstr
for both local and remote deliveries
domain:remote:args
or
domain:remote:args:envstr
for remote deliveries and
domain:local:args
or
domain:local:args:envstr
for local deliveries.
domain can be an exact match, wildcard or a regular expression (if QREGEX environment variable is defined). If there are multiple lines which match domain, the first line that matches domain will be used.
For local deliveries, domain refers to the recipient domain. You can have the match done on sender domain by setting MATCH_SENDER_DOMAIN.
For remote deliveries, domain refers to the sender domain. You can have the match done on recipient domain by setting MATCH_RECIPIENT_DOMAIN.
envstr mentioned above is a string of environment variable additions or removals. e.g.
QREGEX=1,DKIMSIGNOPTIONS=-z 4,HOME=
sets QREGEX to 1, DKIMSIGNOPTIONS to "-z 4" and unsets HOME envrionment variable.
Here are two examples that calls qmail-dkim for DKIM signing / verification for all domains that end with .org. The first one uses regular expression and the second example uses simple wildcard match.
.*.org:remote:/usr/sbin/qmail-dkim:DKIMQUEUE=/bin/cat,QREGEX=1
*.org:remote:/usr/sbin/qmail-dkim:DKIMQUEUE=/bin/cat,QREGEX=
databytes
Maximum size of mail that will be accepted before passing it to
qmail-remote or qmail-local
If the environment variable DATABYTES is set, it overrides databytes. The value of databytes determines the maximum size of a message that spawn-filter will accept.
fromd.envrules
Specific environment variables can be set for specific senders. The
format of this file is of the form
pat:envar1=val,envar2=val,...]
where pat is a regular expression which matches a sender. envar1, envar2 are list of environment variables to be set. If var is omitted, the environment variable is unset. spawn-filter uses fromd.envrules to distinguish from from.envrules used by qmail-smtpd(8)
The name of the control file can be overridden by the environment variable FROMRULES. Any environment variable used by spawn-filter, qmail-remote or qmail-local can be set sender specific by using fromd.envrules.
rcpt.envrules
Specific environment variables can be set for specific recipients. The
format of this file is of the form
pat:envar1=val,envar2=val,...]
where pat is a regular expression which matches a sender. envar1, envar2 are list of environment variables to be set. If val is omitted, the environment variable is unset.
The name of the control file can be overridden by the environment variable RCPTRULES. Any environment variable used by spawn-filter, qmail-remote or qmail-local can be set recpient specific by using rcpt.envrules.
The following list of environment variables can be modified using envrules
QREGEX, QLOCAL, QREMOTE, SPAMFILTER, LOGFILTER, SPAMFILTERARGS, FILTERARGS, SPAMEXITCODE, HAMEXITCODE, UNSUREEXITCODE, REJECTSPAM, SPAMREDIRECT, SPAMIGNORE, SPAMIGNOREPATTERNS, RATELIMIT_DIR, DATABYTES, MDA, MYSQL_INIT_COMMAND, MYSQL_READ_DEFAULT_FILE, MYSQL_READ_DEFAULT_GROUP, MYSQL_OPT_CONNECT_TIMEOUT, MYSQL_OPT_READ_TIMEOUT, MYSQL_OPT_WRITE_TIMEOUT, QUEUEDIR, QUEUE_BASE, QUEUE_START, QUEUE_COUNT, RATELIMIT_DIR, and TMPDIR
The following list of environment variables which can be modified using envrules are specfic to qmail-remote.
CONTROLDIR, SMTPROUTE, SIGNKEY, OUTGOINGIP, DOMAINBINDINGS, AUTH_SMTP, MIN_PENALTY, and MAX_TOLERANCE
The following list of environment variables which can be modified using envrules are specfic to qmail-local. USE_SYNCDIR, USE_FSYNC, and LOCALDOMAINS
If SPAMFILTER is defined, spawn-filter additionally runs a command (with command line arguments) defined by SPAMFILTER environment variable. This gives spawn-filter the ability to filter mail messages based on the spam classification of the mail.
The environment variable SPAMFILTER apply to both local and remote mails. For individual domain level control, it is best to set using the control file spamfilter.
spawn-filter will attempt to make the descriptor 0 seekable if the environment variable MAKE_SEEKABLE is defined. This may be necessary for certain filter programs like bogofilter to prevent allocating memory for the mail message.
The spam filter program is expected to return 0, 1 or 2 in case the filter ran successfully without any temporary errors. For any other exit code, spawn-filter will assume that the filter program had some errors and will accordingly defer mail delivery.
In this case following interpretations on the exit status will be made
Exit Status Interpretation ----------- -------------- 0,1,2 Program ran successfully. Interpretation depends on filter implementation. Mail will be accepted unless REJECTSPAM is set. See description below. anything else Mail will be rejected with a temporary error
A typical application of this would be to run spam filtering software like spamassasin, bogofilter, etc=
When the exit code of the filter program matches SPAMEXITCODE, the mail is considered to be spam.
If REJECTSPAM is 0, mail is accepted. If REJECTSPAM is set to 1, the mail will be bounced back to the sender. If REJECTSPAM is greater than 1, the mail is blackholed. If SPAMREDIRECT is set, mails will be redirected to the recipient specified by the SPAMREDIRECT environment variable. If both REJECTSPAM and SPAMREDIRECT is set, spam mails will be bounced back to the sender with a copy redirected to the recipient specified in the SPAMREDIRECT environment variable
If individual domain level control is desired on REJECTSPAM and SPAMREDIRECT environment variable, the control files rejectspam and spamredirect can be setup without defining the REJECTSPAM and SPAMREDIRECT environment variable.
The other control files that control spam filtering are
rejectspam
The value of environment variable REJECTSPAM overrides this control
file. The format of this file is
domain:value
or
domain:value:envstr
without any extra spaces. The format also can be specified as
domain:remote:value
or
domain:remote:value:envstr
and
domain:local:value
or
domain:local:value:envstr
where domain is a valid (recipient) domain for which mails are being processed and value should be 0 if SPAM mails should be delivered 1 for rejecting and greater than 1 for blackholing. envstr mentioned above is a string of environment variable additions or removals. e.g.
QREGEX=1,HOME=
sets QREGEX to 1 and unsets HOME envrionment variable.
spamredirect
The value of environment variable SPAMREDIRECT overrides this control file.
The format of this file is
domain:value
or
domain:value:envstr
without any extra spaces. The format also can be specified as
domain:remote:recipient
or
domain:remote:recipient:envstr
and
domain:local:recipient
or
domain:remote:recipient:envstr
where domain is a valid (recipient) domain for which mails are being processed and address should be valid recipient where the spam mails should be redirected. envstr mentioned above is a string of environment variable additions or removals. e.g.
QREGEX=1,HOME=
sets QREGEX to 1 and unsets HOME envrionment variable.
spamfilter
The format of this file is of the form
domain:args
or
domain:args:envstr
for both local and remote mails.
domain:remote:args
or
domain:remote:args:envstr
for remote mails and
domain:local:args
or
domain:local:args,envstr
for local mails
where domain is a valid (recipient) domain for which mails are being processed and args is a list of aguments to be supplied to the filter program. envstr mentioned above is a string of environment variable additions or removals. The example below sets SPAMEXITCODE=0.
indimail.org:local:bogofilter -c /etc/indimail/bogofilter.cf -p -d /etc/indimail/indimail:SPAMEXITCODE=0
NOTE: For the control files spamfilter, filterargs, rejectspam, spamredirect domain can also be a regular expression or wildcard pattern. If QREGEX envronment variable is defined, regex is used, else wildmat)
spamignore
envelope sender addresses which should bypass spam filter.
spawn-filter will bypass the filter defined by SPAMFILTER and
directly exec qmail-local / qmail-remote, if the envelope sender
address is listed in spamignore. A line in spamignore may be of the
form **@**host, meaning every address at host. spamignore can be
overridden by the environment variable SPAMIGNORE. You can also
create spamignore.cdb using qmail-cdb(8), in which case
spawn-filter will use cdb function for fast lookup. You should
create the cdb file in case you have large number of entries.
spamignorepatterns
REGEX patterns of envelope sender addresses which should bypass spam
filter. spamignorepatterns can be overridden by the environment
variable SPAMIGNOREPATTERNS spamignorepatterns gets disabled of
you set QREGEX environment variable. spamignorepatterns uses
simple shell-style pattern matching unlike regular expressions used by
setting QREGEX environment variable.
spawn-filter sets few environment variables. The following environment variables are set for both local and remote deliveries
| Environment variable | Description | |
| ------------------------------------------------------------ | |
| DOMAIN | domain part of recipient address | |
| _EXT | the address extension | |
| _QQEH | qmail queue extra header | |
| _SENDER | envelope sender address | |
| _RECIPIENT | envelope recipient address | |
| SPAMREDIRECT | set to the envelope recipient if mail is identified | |
| | by spam and redirected to address other than the | |
| | original recipient using control file spamredirect | |
| QUEUEDIR | set to notification queue. This gets set when mail gets | |
| | redirected to another address using control file | |
| | spamredirect. spam filtering does not happen for | |
| | the notification queue | |
| QMAILREMOTE | set for remote deliveries | |
| QMAILLOCAL | set for local deliveries | |
spawn-filter exits 111 for any error (non-zero exit status by called program) or if it is not able to exec /usr/bin/qmail-local (for local mails) or /usr/bin/qmail-remote (for remote mails). It exits 100 (i.e mail will be bounced) if the REJECTSPAM environment variable is set (or the control file has rejectspam set for the domain) and the mail is found to be SPAM. It also exits 100 if the program/script defined by FILTERARGS (or defined in the control file filterargs) returns 100. If the program/script defined by FILTERARGS returns 2, then the mail gets blackholed. If the program/script defined by FILTERARGS exits non-zero status (other than 2), temporary error is issued and the mail stays in the queue. For all other cases where no errors occur, it exits 0.
qmail-lspawn(8), qmail-rspawn(8), qmail-local(8), qmail-remote(8), rd-remote(8), qmail-smtpd(8), qmail-multi(8), qmail-cdb(8), indimail-control(5), qmail-queue(8), qmail-command(8), bogofilter(1),
AUTHORS "Manvendra Bhangui" <mbhangui@gmail.com>.