Next Previous Contents

3. Usage

3.1 General Usage

Popsneaker is intended to be used in conjunction with a mail retrieval tool like fetchmail. The concept is to start popsneaker first to clean your mailaccount and then run fetchmail to download the mails popsneaker considered good.

3.2 Configuration

popsneakerrc

When started, popsneaker reads its configuration from one of the following files. Popsneaker uses the first file that exists.

~/.popsneakerrc
/etc/popsneakerrc
/usr/etc/popsneakerrc
/usr/local/etc/popsneakerrc

So the first thing you have to do is to create a popsneakerrc in at least one of the above positions. Be sure to make it accessible only by the user who starts popsneaker, because it contains the passwords for your mailaccounts.

To make this more easy for you, there is an example configuration file in the archive, which is installed automatically. This example contains many comments and has reasonable defaults, so it should be easy to set it up within seconds. The last section describes the filter rules, which are explained in a later chapter.

Startup

The next step is to make popsneaker start before fetchmail. The best way to achieve this is to add a preconnect statement to your fetchmailrc. Here is an example for a fetchmailrc entry:

poll pop.isp.com
   proto POP3
   user myremotename
   password mypassword
   is mylocalname
   options fetchall
   preconnect '/usr/local/bin/popsneaker pop.isp.com'

Make sure you use the "fetchall" option of fetchmail, because when popsneaker has finished its job, all messages in your mailbox are marked read. Without this option, fetchmail will not fetch any mails at all.

If you are using another mail retrieval tool than fetchmail, you can add a call to popsneaker to the same script that starts your retrieval tool. To use fetchmail as an example again, add the following into the script:

/usr/local/bin/popsneaker pop.isp.com
/usr/bin/fetchmail pop.isp.com

This also works with any other retrieval tool.

Logfile

It is advisable to read the logfile periodically, so that you can check which mail was deleted. A handy way would be to let cron mail the log to you, for example once per week. This can be done using either savelog or logrotate.

With savelog, you can write a script like this:

#!/bin/sh
LOG=/var/log/popsneaker.log
if [ -e $LOG ]; then
   cat $LOG | mail -s "popsneaker log" root
   savelog -p -c 1 $LOG >/dev/null
fi

With logrotate, this is even simpler. This statement in logrotate's config file mails the log once per week:

/var/log/popsneaker.log {
        missingok
        rotate 0
        mail root
        weekly
        notifempty
        copytruncate
}

You should make use of one of these methods, since no one else takes care of the logfile and it will become bigger and bigger. I would prefer the logrotate way if available. It is very easy to handle.

3.3 Filters

There are 5 different filter types. I will describe them one by one now and then show you how to combine them.

maxsize

Syntax: maxsize [options] <size>

This filter deletes mail, which exceeds a given size.

For example you can say:

maxsize 10000

to delete every mail, that is bigger than 10kB.

accept, assume and deny

Syntax: accept [options] "<rule>"
        assume [options] "<rule>"
        deny   [options] "<rule>"

With "accept" you can define mail which should in no way be deleted. So you can prevent the deletion of important mail (maybe from a good friend or your employer). This is like building a "positive"-list.

With "assume" you can define assumptions a mail must fullfill. For example, you can delete mail which is not directly addressed to you. Or you can delete mail which is not plain text.

"deny" is the opposite of "accept". You can define which mail should be deleted. Maybe you want to give some keywords here, or you want to avoid mail from special persons.

The rules itself are POSIX 1003.2 extended regular expressions. These expressions are processed on every line of the mailheader. To understand how it works, let's look at some examples:

Assume we want to stop all mail that comes from badguy@mytown.com. To make popsneaker delete such mail, put a

deny "^From: .*badguy@mytown\.com"

in your popsneakerrc. Or maybe you hate all people at mytown. Change this line to

deny "^From: .*mytown\.com"

to delete all mail from that domain.

"\" is used to quote special characters. If you want to use a character which is special to regular expressions, you must put a "\" in front of it.

In the above examples, we have to quote the "." in the domainname, because it has a special meaning in regular expressions.

To learn more about regular expressions read

man 7 regex

There are also some books and documents which describe regular expressions in detail.

dupcheck

Syntax: dupcheck -strict
        dupcheck -relaxed

The dupcheck filter detects duplicated incoming mails and deletes them except for one.

In "strict" mode, this filter compares the message-ids of the incoming mails. This will delete mails that were send to multiple of your email addresses. This should be save.

In "relaxed" mode, the filter compares the size, the subject and the sender of the mail. This will delete mails, that were send to you more than once (with intention or by mistake). Be aware, there is a small risk, that to many mails are deleted (when the same sender sends you some different mails with the same subject and exactly the same size).

If you are not sure which mode to use, use "strict". Duplicated mails are deleted silently and no logging is done.

Scoring

Syntax: score <value> [options] "<rule>"
        score_reset
        score_eval [condition] accept|deny

Scoring is a feature introduced in version 0.6.2 of popsneaker. You can now use a finer grain of control than "accept" and "deny".

The "score" filter rule changes the current score of a message by a given value if the rule matches.

score -10 "^subject: .*for free"

The "score_reset" instruction sets the score value back to 0. This can be useful, if you have more than one block of independant score rules.

And the "score_eval" instruction makes a decision based upon the score value. The condition is set via options, possible settings are:

-lt <value>      True if the score is less than <value>.
-le <value>      True if the score is less or equal <value>.
-gt <value>      True if the score is greater than <value>.
-ge <value>      True if the score is greater or equal <value>.

A short example:

score_reset
score +10 "^References: .*mydomain\.net"
score +10 "^In-Reply-To: .*mydomain\.net"
score -5  "^Content-Type: text/html"
score -5  "^Message-ID: .*@127\.0\.0\.1"
score -10 "^(to|cc): .*,.*,.*,.*,.*,"
score_eval -gt 0 accept
score_eval -lt 0 deny

score_reset
score -10 -case "^Subject: .*FREE"
score -10 -case "^Subject: .*BUY"
score -10 -case "^Subject: .*CASH"
score -5  -case "^Subject: .*free"
score -5  -case "^Subject: .*buy"
score -5  -case "^Subject: .*cash"
score_eval -lt 5 deny

Options

The behaviour of some of the filter rules described above can be modified using the following options.

-case            This executes the filterrule case sensitive.
                 Case insensitive is the default. Only useful
                 for the accept, assume and deny rules.

-nocase          This executes the filterrule case insensitive.
                 This is the default. Only useful for the accept,
                 assume and deny rules.

-verbose         The rule is verbose and writes deletions of mail
                 to the logfile. This is the default.

-silent          The rule deletes mail silently without mentioning
                 it in the logfile.

Restricting headers

You can speed up the processing of the filter rules by making use of the restrict statement.

Syntax: restrict "header" ...

This way, only those headerlines that are mentioned in a restrict statement are used for comparisons. If you use restrictions, make sure to set up a restrict statement for every header your filters are using. All other headerlines are ignored. Every restrict can have multiple headerlines and you can also use multiple restrict statements.

If no restrict statement is given, all header lines are used. This is the default and a save decision.

Regular expressions

This is a short and very simplified summary about regular expressions.

A regular expression is a string of atoms with some special characters. An atom can be a single character, another regular expression included in parenthesis, or a range included in brackets. The following special characters can be added to atoms:

*    matches a sequence of 0 or more matches of the atom.
+    matches a sequence of 1 or more matches of the atom.
?    matches the atom 0 or 1 time.

There are also these special characters:

^    matches the beginning of a string.
$    matches the end of a string.
.    matches any character.
()   used to build more complex atoms.
[]   builds a range. Matches any character in the brackets.
|    is the logical "or".

In a range there are the following additional characters available:

-    used to build sequences (for example [0-9]).
^    negates a sequence ([^0-9] matches anything other than 0-9)

Example

This is a commented example for a filter script:

# ----------------------------------------------------------------
# Start of popsneakerrc.
#
# Lines that start with a "#" are comments.
#

# Account information.
#
account -protocol pop3 "pop.myisp.com" "loginname" "secret"
# This account supports the more secure APOP authentification.
account -protocol apop "pop.mymail.org" "loginname" "secret"

# This is my employers domain. No mail from this domain should be
# deleted.
#
accept "^From: .*business\.com"

#
# I have a very good friend. I want everything he sends.
#
accept "^From: .*my\.friend@isp\.com"

#
# From everone else I don't want mails bigger than 1 MB.
#
maxsize 1048576

#
# These are also some friends.
#
accept "^From: .*friend1"
accept "^From: .*friend2"

#
# Also accept replies to my mail.
#
accept "^Subject: Re: "

#
# A more advanced method of detecting replies.
#
accept "^References: .*my-domain.com"
accept "^In-Reply-To: .*my-domain.com"

#
# Accept mailinglists:
#
accept "^X-Mailing-List: "
accept "^List-Id: "

#
# No mail larger than 64 KB should pass this point.
#
maxsize 65536

#
# These are some spammers I get mail from.
#
deny -silent "^From: .*@buyers\.com"
deny -silent "^From: .*@get-it-all\.com"

#
# These are some keywords I don't like to see.
#
deny       -silent "^Subject: .*\$\$\$"
deny -case -silent "^Subject: .*MONEY"
deny -case -silent "^Subject: .*CREDIT"
deny -case -silent "^Subject: .*FREE"
deny -case -silent "^Subject: .*CASH"

#
# Some checks on the Message-ID:
#
assume "^Message-ID: .*<.+@.+\..+>"
deny   "^Message-ID: .*@127\.0\.0\.1"

#
# Get rid of HTML mails:
#
deny "^Content-Type: text/html"

#
# The mail should be addressed directly to me (many spammers don't do
# this). Be carefull: all possible addresses must be mentioned here or
# mail gets lost accidently. Note that mailinglists use their own
# "To"-field. They must be accepted before.
#
assume "^((To)|(Cc)): .*(\
(my\.address@business\.com)|(my\.address@private\.net)|\
(@mydomain\.net)|(anotherone@mail4free\.org))"

#
# End of popsneakerrc.
# ----------------------------------------------------------------

For a complete popsneakerrc with all possible options you should read the sample.popsneakerrc which comes with this archive.


Next Previous Contents