Skip to content

filterit.1

Jump to bottom
Manvendra Bhangui edited this page Feb 25, 2024 · 4 revisions

NAME

filterit - Filter incoming mails based on email headers

SYNOPSIS

in .qmailext: | [/usr/bin]filterit [ -n ] [ -r ] [ -x ] -h header -k keyword -c comparision -a action -A action_val -d default_action -D default_action_val [ -b bounce_message ] [ -e exit_value_on_match ]

DESCRIPTION

filterit is a filter that can be used in dot-qmail(5). It expects descriptor 0 to be seekable and reads it to get all email headers. It can be used to deliver mail to a Maildir folder, forward mail to an address or simply exit with some value when it matches a user-defined criteria specified on the command line. filterit can be used to decide if you want to deliver to a specific folder, forward to any email address, drop or bounce the message. If filterit is called in .qmail without a path, it is executed as an internal command by qmail-local.

When delivering to a Maildir, filterit forks a child and does the Maildir delivery in the child. filterit expects HOME, RPLINE, DTLINE environment variables to be present. If RPLINE environment variable is not present, it expects SENDER environment variable in order to set the RPLINE environment variable and insert the Return-Path header. If the DTLINE environment variable is not present, it expects LOCAL, HOST, environment variables to be present in order to set the DTLINE environment variable and insert the the Delivered-To header. This is not a problem when being called from a .qmail file as qmail-local sets all these environment variables. But if called from a script that is not executed by qmail-local. filterit will exit 100, if these environment variables are not set. Also, filterit will exit 100 if it finds the maildir path two consequent dots. filterit will create the Maildir if it does not exist.

When forwarding to an address, filterit expects NEWSENDER, DLINE environment variables to be present. If the DTLINE environment variable is not present, it expects LOCAL, HOST, environment variables to be present in order to set the DTLINE environment variable and insert the the Delivered-To header. This is not a problem when being called from a .qmail file as qmail-local sets all these environment variables. But if called from a script that is not executed by qmail-local, filterit will exit 100, if these environment variables are not set. If running as non-root, filterit uses environment set according to files in $HOME/.defaultqueue directory. You can skip $HOME/.defaultqueue if SKIP_LOCAL_ENVIRONMENT is set. If QUEUE_BASE environment variable is not set, it additionally uses environment set according to files in /etc/indimail/control/defaultqueue directory (for any uid). When forwarding, filterit rewrites the sender using Sender Rewriting Scheme if SRS** has been configured. See** indimail-srs(5) for information on how to do this.filterit inserts X-Forwarded-To header as the forwarding address and X-Forwarded-For header as the NEWSENDER address. filterit uses qmail-queue(8) to put an email to be forwarded in the queue.

When bouncing a message (-a bounce -A 100 or -d bounce -D 100), message will be bounced with the text

  "message failed to evade local filter(s) set by recipient"

You can use the -b option to change the bounce message;

OPTIONS

-n
Do not take any action. Just display the result of filtering

-r
Reverse the match. A match becomes no match. No match becomes match

-x
Insert X-FilterIT header which shows the filterit invocation arguments and if a matched occurred

-n header
Use header to match all headers in a 822-format message.

-k keyword
Use the string keyword in header from a 822-format message. The criteria for a match depends on the type of comparision used (-c option)

-c comparision
Use comparision as the criteria for deciding a match. This is a string with one of the following values:

Comparision Type Criteria for match
equals match happens when header value = keyword
contains match happens when header value contains keyword
starts with match happens when header value starts with keyword
ends with match happens when header value ends with keyword
numerical logical expression Here %p in keyword gets replaced with header
value
regexp Match happens when a regular expression in
keyword matches the header value

-a type -A action_value
Action to take when there is a match. This has one of the following values:

Action type Description
exit Exit with action_value
forward Forward to address action_value
maildir Deliver to a Maildir action_value. This has to start with
'./Maildir/' and end with '/' and must not contain two
consequent dots

-d type -D action_value
default action to take when there is no match. This has one of the following values:

Action type Description
exit Exit with action_value
forward Forward to address action_value
maildir Deliver to a Maildir action_value. This has to start with
'./Maildir/' and end with '/' and must not contain two
consequent dots

-b bounce_message
Set bounce_message as the default bounce message.

-e exit_value_on_match
When a match occurs and when filterit is either doing maildir delivery or forwarding, filterit will exit 99 to prevent subsequent instructions in .qmail to run. Using this changes the default exit value of 99 to exit_value_on_match.

EXAMPLES

The below example shows three invocations of filterit with the final instructions to deliver it to the Maildir.

NOTE: It is important to test the filter before including it in a .qmail file. You can pass the -n option to the filterit command line argument. Wrong usage can lead to mails boucing, getting dropped or deferred.

  # Move mail to Quarantine folder and exit 99, else exit 0
  # qmail-queue qhspi puts the header X-QHPSI: clean. passing
  # -r option to filterit makes the filter match when the header
  # does not have "clean" as the header value
  # this filter will exit 99 on match, causing qmail-local to
  # stop at this line
  | filterit -xr -h X-QHPSI -k "clean" -c "Equals" -a Maildir
      -A ./Maildir/.Quarantine/ -d exit -D 0

  # Move mail to Spam folder and exit 99, else exit 0
  # bogofilter inserts the X-bogosity header like below
  # X-Bogosity: No, spamicity=0.520000, cutoff=9.90e-01, ...
  # The filter below will move the mail to Spam folder if X-Bogosity
  # value starts with "Yes".
  # additionally -e 0 is passed which makes the filter exit 0 on a
  # match. This allows qmail-local to go to the next filter even
  # though the filter has a match
  | filterit -x -h X-Bogosity -k "Yes" -c "Starts with" -a Maildir
      -A ./Maildir/.Spam/ -d exit -D 0 -e 0

  # match criteria same as above, but this filter forwards spam mails
  # to spam_collection@yourdomain.org instead of putting it in Maildir
  # this filter will exit 99 on match, causing qmail-local to
  # stop at this line
  | filterit -x -h X-Bogosity -k "Yes" -c "Starts with" -a forward
      -A spam_collection@yourdomain.org -d exit -D 0

  # If the mail passes through the above filters, deliver it to Maildir
  ./Maildir/

  # NOTE: The command lines above have been broken into two lines
          for readability. In a real dot-qmail you will have those
          as a single line

SEE ALSO

dot-qmail(5), qmail-local(8), qmail-queue(8), maildir(5), indimail-srs(5), qmail-command(8), qmail-qfilter(1),

Clone this wiki locally