|
Notes for the user
|
Table of Contents
Introduction
PostArmor is an application that helps keeping your electronic mailbox free of what is officially called "unsolicited e-mail" and better known as "spam", those e-mails coming from nowhere with various, weird, sometimes offensive and even ridiculous subjects. On e-mail addresses that have been around for a while, the amount of spam mail easily overcomes the traffic of regular e-mail, sometimes forcing the user to change the address and be free... for a while, at least!
PostArmor offers a less drastic solution: it looks at the relevant parts of your e-mail before it leaves the mail server, and lets the legitimate messages pass through undisturbed, while leaving suspect messages on the server, to be reexamined later or just deleted after a while. Of course, there are rules that let the software decide: some come prebuilt inside the software (but can be changed by the user), others are specific to you and your business/interests, and you can teach PostArmor what you consider interesting and what is just junk.
How it works
The technical definition for PostArmor is e-mail proxy, with support for POP(Post Office Protocol): this means that it lies in between your e-mail client and the e-mail server(s) you're normally getting mail from. You just have to tell your client to ask PostArmor for e-mail, tell PostArmor where your real servers are, and you're in business! When you'll check mail with the client (be it Outlook, Eudora, Entourage, Netscape, or any client capable of POP3 communication), PostArmor will look at the e-mail on the server, and if they look "good", let them pass. Spam e-mail will be blocked on the server, and an (optional) report will be sent in a form of an e-mail, to let the client know that some messages didn't pass the filter. If one of the messages was indeed a "good" one, the user can change the settings of the program to let the message go through in the next check.
What is considered "spam"?
There are many characteristics that help distinguish spam from legitimate commercial e-mails at a first glance, and these can be used to discard it automatically, or accept it without reserve
- Origin
Some users and domains (the name you find after the "@" in the e-mails) are well known to produce unsolicited e-mail: a look at where the message comes from is enough to discard those. On the other hand, messages coming from sources you trust (for example your computer's manufacturer) can have a shortcut to your inbox, and don't go through all the evaluation process.
- Subject
Quite often spam e-mails are about products or services that are strictly regulated or outright illegal in many countries (but possibly not in the country/state the spam comes from), like porn, drugs, copying software,...: looking at keywords in the subject of the message is enough to discard it at once. The same is valid also for well-known scams/frauds that have been around the Internet for a while.
- Destination
Spam isn't sent just to your address: spammers work on thousands (if not millions) of e-mail at once, and to change every e-mail to insert the recipient's addresses is a waste of time (even though it's done automatically), so less sophisticated spammers don't care too much, and let messages go out without your address being anywhere in the message itself as it should. Fortunately for us, this is a fast way to discard spam messages.
- Return
As they're dealing with questionable practices, spammers protect themselves from reactions of the users (and in worst cases from law enforcement) giving out a fake sender address, so that users' replies are going nowhere. If all the checks above left a message in an "uncertain" state (i.e. not definitely positive nor definitely negative), PostArmor has the option to check if the sender address really exists: while time consuming (it takes some network traffic to do this) it's a good way to avoid losing mails from unknown people that are otherwise perfectly legitimate. On the other hand, if you plan to receive many mails from those people, it's a good idea to add them to your address book, in order to avoid those checks in the future.
Good messages that look like spam
Some e-mails could look as spam even though they're not: good examples are messages coming from big companies, magazines or from mailing lists, that have to deal with many thousands of users, but are sent only on request. To avoid having the software discard those messages, take a look at the mailing lists you've subscribed to, and add the domains to your address book as explained further, so that they'll never undergo the evaluation.
How to install
PostArmor can work in two modes: a GUI (Graphical User Interface) mode, that allows interaction with the user for configuration and spam handling, and a console (text-only) mode, useful to filter spam in the background. The installation is exactly the same, while launching and using it could be different: single users will prefer the GUI mode, that's also useful for the setup, while operating on a server will probably be in console mode.
Installing PostArmor
PostArmor is contained in a .jar file (on Mac OS 9 and X there are also applications that help to launch it, while on other operating systems there are script files that do the same job) and uses some text file in a XML format to read & store the configuration: to install the application just drag the PostArmor folder you've downloaded with the.jar file, the docs folder, the filters folder with its content and the helper applications (if present) in a place of your convenience. On multi-user systems, verify that PostArmor has permission to write inside the filters folder, otherwise it will fail to save the configuration. To launch the software in GUI mode, on many systems a double click on the .jar file is enough, when available you can use the helper applications to do the same. Use in console mode is covered below.
Uninstalling PostArmor
PostArmor doesn't write anything out of its own folder: removing the folder from your disk completely uninstalls the application
Getting started
Let's start with two typical configurations:
Example 1
Let's say you have an account myself@bigprovider.com, that you access with your email client at pop.bigprovider.com and user name myself with a POP-type protocol. After you've started the application:
- Click on the Add new account button (the "Plus" icon).
- Enter myself and click Next >
- Enter again myself (the software would have done that automatically) and click Next >
- Enter pop.bigprovider.com and click Next >
- Choose POP (or APOP if you know that the provider gives you Secure POP access) and click Next >
- Enter myself@bigprovider.com and click Next >
- If you've registered with SpamCop, enter the address you've received from them here and click Finish. You can safely leave this field empty, the SpamCop report function will be disabled, but you can still verify mail with their blacklist service (you don't need an account for that).
Now you'll have an item in the Account list named myself: double click on it and you'll get an (empty) window for the messages on the mail server. Connect to the Internet, and then click on the first button (the mailbox), and insert the password: if everything is correct, you'll wait a few seconds while PostArmor is checking the server and you'll get back a list of messages (if any, the window will stay empty if there are no messages). In green you'll see good messages, i.e. messages that PostArmor doesn't consider as spam, the yellow means that the messages are probably spam, they'll stay on the server for the set amount of time and will be deleted after (when time is passed, the color will turn to red). You'll never see messages that are definitely spam (like for example messages from servers listed in SpamCop as spammers or sender you'll put in your future "never accept" list), as they're immediately deleted: you can prevent this drastic behavior changing a triggering value (see further explanation).
You can manipulate the list now, marking messages for delete or retrieval, and get them later with your email client, or you can use PostArmor as a real-time filter configuring the email software as explained below.
NOTE: PostArmor doesn't download the messages, ever: to get them you've to connect with your email software.
Example 2
Let's say you have an account myself@mac.com, that you access with your email client at mail.mac.com and user name myself with a IMAP-type protocol. This is also the standard under Mac OS X for iTools accounts.
After you've started the application:
- Click on the Add new account button (the "Plus" icon).
- Enter myself and click Next >
- Enter again myself (the software would have done that automatically) and click Next >
- Enter mail.mac.com and click Next >
- Choose IMAP and click Next >
- Enter myself@mac.com and click Next >
- If you've registered with SpamCop, enter the address you've received from them here and click Finish. You can safely leave this field empty, the SpamCop report function will be disabled, but you can still verify mail with their blacklist service (you don't need an account for that).
From this point on, everything proceeds as the example above: the only difference will be when configuring the email client, as you'll have to change the mail server type from IMAP to POP if you want to check mail through PostArmor (the application emulates only a POP server - not even APOP, as security is less stringent when working on the same machine or in the same network).
Configuration
Configuring via GUI
When PostArmor is launched in GUI mode (default) the following window appears:
This window will be always open while you're using the software: closing it will exit the program.
The main component is a list of active accounts: of course, it will be empty at first launch. In the lower right corner, the number of messages waiting
on the server: the first number are the "good" messages, the second the total number of messages on all accounts.
View shows the message list relative to the selected account (see below): equivalent to a double click on an account name
Add adds a new account to the list, using the data specified in the detail below the list itself
Remove deletes an account (and all its messages/settings)
Modify substitutes the details of the selected account with the data in the fields below the list
Check checks the mail on all accounts: if no password was given yet during this session, the password to access the account is required
- Register asks for the license key: the software comes free for personal use, but is enabled for only one account. When the user registers the software, he's given a key (to insert here once) that unlocks the software and allows handling of unlimited accounts
- Global Settings puts up the global configuration dialog: see below for more informations
Clicking on "Add" or "Modify" will bring up a dialog to enter details of the account
- Account name the name given to this account: this is the value you've to insert in your e-mail client as username!.
CAUTION This is not just a description, it will be the actual user PostArmor expects to log in when checking mail, if it doesn't match the setup in the email client, a login error will result!
You can only enter this value when creating a new account, it cannot be changed later.
- Mail user name the name of the account on the external mail server: while this is typically the same of the Account name, it's not always the case.
Here, it is important you report the user name you use to connect to your regular server: if they don't match, a login error will result too as above, but in this case it will be the POP server that doesn't recognize the user
- Mail server the address of the mail server: typically pop.somewhere.com, mail.provider.com, and so on...
- Server type and port server type can be POP, APOP or IMAP, port is usually 110 for POP & APOP and 143 for IMAP, and is automatically set when you choose the account type: don't change these values, unless required by your ISP (Internet Service Provider)
If you don't know what to put here, just leave the defaults (POP and 110), as they're supported nearly anywhere.
- E-mail address the address you receive mail at on this server: this is used by the software also as an indication for "my address". It will typically have the form myself@myprovider.com
- Report address for SpamCop SpamCop has a reporting service for spam: when you subscribe (basic service is free), you get an email address where you can send spam for them to evaluate. Setting this field to that special address allows PostArmor to send automatically a report to SpamCop with a simple click.
- Do automatic check every ... minutes a non-zero value indicates the minutes to pass between automatic checks on the server for this account: a zero indicates that no auto check has to be performed, checks will be manual or via email client.
This setting will become active at the next startup of the software.
Settings window
The Global Settings dialog has two panes, described below: these settings are common for all accounts, while the same dialog, when called from inside the account messages' window, applies only to a specific account.
Options panel
The Options tab shows generic preferences:
- The upper part contains parameters related to the general working:
- Consider spam messages with... is the minimum score to consider message as spam (higher positive values means that a message is more likely to contain spam): this value is a threshold to let the messages through. The default of 10 is valid for most cases.
- Automatically delete spam after... is the number of days the messages will stay on the server after the evaluation, before being deleted automatically. The default value of 1 is safe and valid if you check your mail at least twice a day: higher values will keep your mailbox cluttered, while if you trust PostArmor blindly you can put a zero here (this means a "shot first, ask later" behaviour, as messages are deleted immediately after evaluation)
- or if score higher than... When a message passes this score, it is immediately deleted, regardless of the time it stayed on the server. With the default vaue of 99, messages coming from blocked addresses (that are assigned automatically a value of 100) will be deleted immediately too.
- Verify sender and assign a score of... if, after evaluating the message, the software has it in a "neutral" state (i.e. it's not definitely spam, nor it's "good" mail), it's possible to make a verification of the sender, that is, ask to the original domain if this is one of their users. This concept is quite simple (after all, you'd expect that the answer be always positive, but this is not the case), but allows a careful screening. The value inserted here, when non-zero, is added to the score in case of negative check (making the mail fall on the spam side) or subtracted in case of positive check. A value of zero (default) doesn't perform the check.
CAUTION: While very useful, this option involves some network traffic, that could slow down the check itself, especially in case the servers around the world have to search for a non-existing mail server. The best use of the option is coupled with the automatic check (see above).
- Automatically generate a report e-mail every... messages this option generates automatically an e-mail to the user, with a report of all the blocked messages, with the scores, when the e-mail client contacts PostArmor and at least the specified number of blocked messages is in the mailbox. This also means that the user doesn't have to look at the GUI to see if there are messages blocked (and potentially interesting). The report isn't generated if no message has been blocked.
- The middle part reports a list of addresses (or domains) that you receive regularly mail from: adding an address here means that a message coming from that address will pass through without any checking. The same is for whole domains (the part after the "@"): be careful, though, when adding domains like hotmail.com or yahoo.com, as many spammers use to fake addresses from there.
- In the lower part of the window there is also the list for the contrary, i.e. a list with domains that are always considered as originating spam, and messages from them have automatically a very high score: there is also a list of known spammer domains that isn't accessible by the GUI, if you feel that a domain has been incorrectly considered source of spam, let us know.
Filters panel
The Filters tab is at the heart of PostArmor functions
PostArmor uses for its evaluations a list of Rule sets, each with its specific weight (the importance for considering a message as spam), and a list of Rules that can be applied, typically related to each other when grouped in a single rule set: the upper part of the dialog handles the creation, removal and modification of Rule sets
- New and Remove buttons add or delete a rule set from the list
- Name is a descriptive name for the set: it helps the user to remember what that particular rule set checks
- Relation describes the type of relation that is applied between the rules internal to a specific set:
- Or means that the weight assigned to this set is applied if any of the rules is true
- And means that the weight assigned to this set is applied only if all the rules are true
- Sum means that the final weight assigned to this set is the sum of all the rules that are true
- Enabled when checked, the rule set is enabled, otherwise it is skipped during evaluation
The final score assigned to a message is the sum of all the weights collected through the evaluation: that is, if two or more sets are found true, the final score will be their sum.
The lower part of the window relates to the Rules contained in the set selected in the upper part
- New and Remove buttons add or delete a rule from the list
- Header is the part of the message where the check is done (typically the subject): a value of "Any" will check all the available parts (but not the contents! PostArmor tries to avoid downloading the content as much as possible)
- Match describes the type of match that is applied between the header and the given data:
- Contains means that the rule evaluates as true if the specified header contains the data
- Doesn't contain means that the rule evaluates as true if the specified header doesn't contain the data: no data is needed
- Is my address means that the rule evaluates as true if the specified header contains the address of the user
- Isn't my address means that the rule evaluates as true if the specified header doesn't contain the address of the user: again, no data is needed
- Data is the data against which the test of the rule is done: it could be a simple string (evaluated as it is, ignoring the case) or a more sophisticated regular expression (see below)
- RE if checked, means that the data have to be considered a regular expression and not as a simple string: regular expressions are well known to programmers (languages as Perl make them a primary tool), as they represent a powerful way to condense complex searches without the need to specify them one by one. It's beyond the scope of this document to explain how regular expressions work: further reference can be found at sites like this, this or this
Configuration - manual/scripted
This is a more specialistic approach: it's not suited for users of a single account or users without a training in configuration files in general and XML in particular: you can safely jump to the next section if you're not comfortable with those skills.
PostArmor uses a basic set of configurations contained in the default.xml file inside the filters folder. To understand what could be done here, look at the separate XML Format Reference. This allows configuration files to be handled by scripts and other languages used to treat text files (like Perl, for example): the following examples assume manual editing, but a skilled programmer can easily write automated procedures to do the same things.
What you'll probably do first is adding your account(s), in order to let PostArmor know where to find your servers: to do this
- Duplicate the user_template.xml file inside the filters folder and rename it as your user name will be (for example myuser.xml): this will be used later to store further user configurations and cache some message data
- In between the <USERS> and </USERS> tags put something like
<ACCOUNT proxyuser="myuser" user="myuser" server="mail.mac.com" type="POP" port="110" address="myuser@mac.com" />
Where:
- proxyuser is the user that you'll insert in your e-mail client (typically the same value as user, but it's not required)
- user is the name you're recognized by the POP server (comes from the e-mail client)
- server is the address of the POP server (again from the e-mail client)
- type and port are typically POP and 110 or IMAP and 143: don't touch these if not expressly required
- address is the address that will be recognized as "good" to evaluate correct destination.
Now, you'd probably want to add addresses that you're used to receive mail from (this could also be done later), in order to spare time when evaluating mail: just copy lines starting with <SENDER> in <ADDRESSBOOK> and add your own between <SENDER> and </SENDER> tags. If you've multiple account, you can choose if you'll do that at a global level (the default.xml file) or account level (in the example above, the myuser.xml file).
Other options can be configured, both at a global and an account level: to look at these, consult the separate XML Format Reference
The last step is to tell your e-mail software to go search for e-mail from PostArmor instead of the e-mail server. To do this
- Change the server to check from the original one to localhost (if your are running PostArmor on the same machine, it has to be typed exactly as spelled here) or to the address of the machine PostArmor is running on.
- If you were using a POP account, change the server port from 110 to 8110 (this is the default, for a confirmation just look at the same line as above): if you were using an IMAP server, you've also to change the type to POP, on some email clients this can mean you've to setup a new account with a different type.
NOTE: Some e-mail clients don't have the possibility to set the port: it is then necessary to launch PostArmor to use port 110: see the FAQs for instructions.
On Mac OS 9, the default is 110: no need to change the port then!
- If the User name and Account name configured above are not the same, change the User name to the value you used for Account name.
For example,let's assume you've an account myuser on myserver.com: you can set an account named myuser_filtered in PostArmor, with a user name myuser (so that PostArmor can go and check your mail). In the email client you've to report myuser_filtered as user name, as it has to check through PostArmor (that knows about myuser_filtered) , not directly the external server.
Below you can see the screenshots of a sample configuration for Apple's Mail application: other clients will have similar parameters to enter.
Now, you can go check your e-mail (don't forget to connect if you're on dial-up!) as always. You'll notice a delay after the login phase: this is when PostArmor does its job to look at e-mails. After this, mails will come in as before, but without spam: if messages were blocked, you can receive an optional report of what was blocked, with the relative score assigned (always positive values, negative values indicate "good" messages). Higher score means that the chances of message being spam are higher: refining the rules will let you block more and more spam and make less mistakes in evaluating them.
If you've the PostArmor application running in GUI mode, you can see a detail of the messages that are kept on the server. In yellow are the messages that are on hold, waiting for the period you specified to pass, in red are the messages that will be automatically deleted at the next check, and in green are the "good" messages that will go through when the e-mail client will do the next check. You can check the mail also from here, pressing the Check now! button, and tell PostArmor to check the mail automatically: a value of zero here means that no automatic check will be performed. Other options present in the window allow to select a message and mark it for retrieve (if the evaluation was wrong, for example), for immediate delete (if the mailbox is getting too full), to add the sender to your address book (so that all further messages from the same sender will go through) and to bounce it back to the server it was (allegedly) originated from. The last button presents a dialog similar to the one we've used before for global configuration: what's changed here will be reflected only when checking the mail for this particular user. In detail:
Check now! checks the mail immediately: if no password was given yet during this session, the password to access the account is required
Bounce! the selected message is immediately bounced to the sender, simulating a non-existing mailbox: if the bounce is successful, the message is deleted from the server, if it fails (as it happens quite often with spammers), it will not alert the user, but just abort silently
Report to SpamCop the selected message is sent to SpamCop for evaluation. The button is not enabled if the user has no valid SpamCop report address.
Mark messages for Delete marks the selected message for deleting at the next check, regardless of the date when it was recovered first.
Mark messages for Retrieve marks the selected message for retrieve, regardless of the evaluation score
Add Sender to approved addresses adds the sender of the selected message to the approved addresses of this user: this means that all the messages from this sender will not undergo checks, and will pass through regardless of their content
Add Sender to blocked addresses adds the sender of the selected message to the blocked addresses of this user: this means that all the messages from this sender will not undergo checks, and will be blocked regardless of their content
Account Settings presents the configuration dialog: the only difference with the global one is that changes are applied only to this user
Launching as a console application
While you can use all the time the GUI mode, this is not something very comfortable when PostArmor is used on a server to filter spam for a network of users. In that case, using it as a console background application is the best solution: users can receive report of the e-mail blocked, and alert the System Administrator if the criteria are too strong and some "good" mail gets catched. To do this, when you're on the command line, type
<Change to the .jar file directory>
java -cp PostArmor.jar com.postarmor.ArmorConsole<enter>
Some options you can pass to the software are
- -conf <conf-dir> Changes the configuration directory (default is filters)
- -pop <portNo> Changes the port the proxy will work on (default is 8110 on most systems, 110 on Mac OS 9, but it has no command line of course)
CAUTION: Low port numbers will require administrator privileges to run!
- -debug Will print out extended details on how the software is working.
Launching as a background application is something that depends on the operating system, your System Administrator must be familiar with this type of tasks, but some scripts are included with the distribution to ease this anyway
Where to go from here
A FAQ section has been compiled: it will grow up in time, following users' needs.
A complete description of all the parameters is given in the XML Format Guide included: while highly specialized, the reference allows to fine-tune all the possibilities of the software.
Requirements
PostArmor is written in Java: this insures it can work on a wide variety of different machines and operating systems.
Actually, whatever computer and operating system can run a Java Virtual Machine 1.1 (or later) with Swing 1.1.1 (or later) reasonably well can also run PostArmor in GUI mode: console mode is even less stringent in the requirements. A Java VM 1.2 (Java 2) or later is strongly suggested, however, as many improvements and bug fixes have been implemented, and will be a requirement for the (future) secure version. See the FAQs for system-specific issues. Contrary to the current belief, the use of an interpreted language like Java doesn't influence performance: most of the time is used for network communications, the internal engine can evaluate many messages per second!
License
PostArmor is free for personal use: you can use it on one computer for one e-mail account without the need to register. The registration and the payment of a fee (depending on how many servers you want to run, see below) are required if you want to use it with multiple accounts: this could mean you can either check multiple accounts of yourself or allow all the users in your network to have spam filtered. Of course, donations are welcome (programmers need to change computers now and then!), and will help keeping the upgrades going...
How to register
You must register PostArmor if:
- You've more than one e-mail account to check, but you'll run the software on one machine only: the license fee is US$15
- Your organization wants to use PostArmor with unlimited accounts on more servers at the same site: the license fee is US$150
- Your organization wants to use PostArmor in all their sites, wherever in the world they are: the license fee is US$ 900
To post an order, go to our pricing page and follow the instructions reported there.
Support
The author(s) offer e-mail support here: requests from non-registered users, though, will be considered only if related to a potential problem, not for the "how-do-I-..." questions, that are covered in this document and in the FAQ section.
New releases will be posted on the official site and properly announced on sites like VersionTracker
Known problems (and solutions)
PostArmor works as a proxy for your e-mail client: this means that it has to evaluate the messages before letting them through. This process takes time, especially on a slow dialup line and with network-intensive option like sender verification, that could take minutes searching for non-existing servers. Thus, it could happen that the e-mail client, having no response for some time during this evaluation, thinks that the line is down and interrupts the communication with PostArmor. A solution to this behaviour is to use as much as possible the autocheck feature, in order to have a fresh list in the buffer that has already been checked. In a dialup system, the use of sender verification option without autochecking isn't a good idea, as long delays can't be avoided.
Future enhancements
PostArmor is just at the first release: there are many things that can be added/improved. For example, in no particular order
- Remote administration
- Automatic update, for registered users, of new filters when available
- Extended IMAP servers support
- SSL Support (will require at least Java 2 with JSSE or Java 2 rel. 1.4)
- We're also keeping an eye on Sieve (RFC 3028): if it will ever become a widely supported standard, there will be a way to exchange filters with PostArmor.
The authors are committed to make PostArmor a complete product: from you, the users, feedback and suggestions are always well accepted.
Acknowledgments
Portions of the software are:
- © 2000-2002 Marc De Scheemaecker (NanoXML-Lite)
- © 1999 The Apache Software Foundation (Jakarta-RegExp)
- © 1999 Brian Wellington (FindServer class - modified)
- © 1998 Manish Pandit (POP3Client - modified)
- © Santeri Paavolainen (MD5 class)
Disclaimer
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
In particular:
The software cannot, and will not, guarantee that relevant messages will not be lost accidentally, as a result of any operation that involves the software itself. Therefore, the author(s) cannot in any case be held responsible for such an occurrence.
$Id:$