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


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: 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: 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:

Main

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.

Detail

Clicking on "Add" or "Modify" will bring up a dialog to enter details of the account

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

Options panel

The Options tab shows generic preferences:

Filters

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
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

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

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

Configuring and using your e-mail client


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
Below you can see the screenshots of a sample configuration for Apple's Mail application: other clients will have similar parameters to enter.

Mail Account Info


Mail Account Options


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:

Messages


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

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, any computer and operating system that 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 any use: you can use it on any number of computers and e-mail accounts without the need to register. Of course, donations are welcome (programmers need to update computers now and then!), and will help keeping the upgrades going...

Support

The author(s) offer e-mail support here: requests, 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 a mature product: there are however many things that can be added/improved. For example, in no particular order The authors are committed to maintain PostArmor as a complete product: from you, the users, feedback and suggestions are always well accepted.

Acknowledgments

Portions of the software are:

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: readme.html,v 1.11 2003/09/28 09:48:45 pmanna Exp $