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.
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.
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.
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.
There are 5 different filter types. I will describe them one by one now and then show you how to combine them.
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.
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.
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.
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
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.
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.
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)
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.