Introduction

The amount of unsolicited commercial e-mail ("spam") circulating in the Internet today has become unbearable for most people. Many approaches have been proposed to stop this junk from filling up your mailboxes, such as the Real-time blackhole list, Teergruben, or procmail-based anti-spam recipts.

mapSoN is another anti-spam system, but it uses an approach entirely different than those systems named before. Instead of trying to recognize spam by the IP address of the SMTP dialag's peer or by certain patters in the mail's body, mapSoN uses the sender's e-mail address to decide whether the e-mail is delivered to your mailbox or not: Any e-mail that comes from a "known" address may pass, any e-mail that comes from an e-mail address seen for the first time needs special confirmation, before it may pass.

"Special confirmation" means that mapSoN will generate an MD5 checksum of the to-be-confirmed mail and stores the mail in a temporary spool directory. Then it sends an request for confirmation to the address from which the mail was coming from. In this request, it will include the MD5 checksum and ask the recipient to reply back and to quote that MD5 hash. Once mapSoN sees that MD5 hash again, it considers that a confirmation of the original mail, delivers the deferred mail from the spool to your mailbox, and adds the sender's address to the database of known addresses, so that the next time he tries to contact you, his mail will pass through mapSoN immediately..

This heuristic catches almost any spam mail, because spammers have to fake their sender addresses in order to avoid being held responsible for their abuse. Hence, their address will most likely not be in the database of known addresses, nor will they ever receive the request for confirmation mail!

This manual describes how to compile, install, and configure mapSoN in various setups.

Building mapSoN

Compiling the software should be pretty straight forward; all you'll have to do is the usual routine:

    ./configure
    make
    make install

The last step may require super-user privileges, so have the root password ready if you're going for a system-wide installation.

Be adviced that mapSoN needs a fairly recent C++ compiler because it make full use of the new ISO C++ language features. If you're using the GNU C Compiler version 2.95 or later, you won't have any problems. But other compilers are known not to be ISO C++ compatible. If you're having trouble, send me an e-mail and I'll see what I can do.

The configure script is a standard GNU Autoconf script, which supports all the usual options. If you are not familiar with these scripts, please refer to the "Running configure Scripts" section of the Autoconf user manual, which is available at:

The following list will show only those options that are specific to mapSoN.

Any of the paths you configure here are only used as defaults. You can override them at run-time in the configuration file mapSoN reads at startup.

Command Line Syntax

mapSoN understans severel optional parameters an the command line, which allow you to override the compiled-in default or the settings in the config file. The standard Unix synopsis line is:

mapson [-d | --debug] [-c config | --config-file config] [mail...]

Here is a list of all options together with a short description of what the respective option does:

The mapSoN Configuration File

The configuration file may contain the following directives:

In order to make the contents of the configuration file as independent from the system's directory structure as possible, mapSoN provides a set of environment variables, which are guaranteed to be defined. You can use them anywhere in the data part of a configuration directive, and you can use the usual manipulations on them.

Envirenment variables are looked-up case-sensitive, so $home is not the same thing as $HOME. This behavior is different in the request-for-confirmation template, where you can spell the variables upper- or lower-case as you wish. That's because the variables there are not coming from the environmnet, but are mapSoN's internal variables. So be sure not to confuse that, because an undefined variable in this file will cause mapSoN to abort with an error.

mapSoN will not overwrite already existing variables, though! If your system defines, for example, the $HOME variable, then you'll get the value from the system's variable.

Here is the complete list:

The Request-for-Confirmation File

The request-for-confirmation mail is created by loading the configured template file and exanding the variables contained in it. The result is then piped into the command, you have configured as MTA.

The following variables are provided in the request-for-confirmation mail template file:

In addition to those, the following arrays are provided:

How to Activate mapSoN

Before you can activate mapSoN you have to make sure that all required directories exist and that all required files can be created. mapSoN will try to create the address database file, for instance, but the default setting is that this database is located at $HOME/.mapon/address-db, and mapSoN will not create the $HOME/.mapson directory.

The same applies to the mail spool directory, where mapSoN stores those mails that need a confirmation before they are delivered. The default location is $HOME/.mapson/spool, and mapSoN will create the spool directory itself, but it won't create the $HOME/.mapson directory.

The cut a long story short: Create the directory .mapson in your home directory before you try to use mapSoN. If you changed the configuration, though, the locations may vary.

Once that's out of the way, you need to create a template file that mapSoN will use to generate the request-for-confirmation mail. The installation process has created you a sample file for this purpose to /usr/local/share/mapson/reqmail.template-sample, so thats probably a good starting point.

Then, all that's left to do is to hook mapson into your mail system so that incoming e-mails are no longer delivered to your mailbox directly but are piped into mapSoN. How you can do this depends on the setup you have. The following sections will give you detailed instructions for the different scenarios.

Expiring the Mail Spool

Importing Addresses From a Mail Archive

Of course it would be unpolite to have mapSoN send out requests for confirmation to people who you have been communicating with you for months or years, just because you installed a new tool. If you were wise enough to archive your old e-mails, there's a simple way to avoid that happening: Import their addresses into mapSoN's database.

Unfortunately, most mail readers archive old mails in one single file: Each new mail is just appended at the end, just like the mailbox format itself. Currently, mapSoN can not deal with those files. The current version can import addresses only from an archive where a each mail is stored in a separate file, like the archives maintained by the Gnus software, that is part of Emacs, for example.

In this case, though, it's simple enough: Just start mapSoN and give it the file names as parameters on the command line. You might want to enable debugging by giving it the -d flag, so that you can see what's going on:

simons@peti:~/mail-archive$ mapson -d *
1:
12:
    simons@peti.gmd.de................................. new
16:
    simons@peti.gmd.de................................. known
17:
    th@example.com..................................... new
    th@example.com..................................... known
    th@example.com..................................... known
19:
    bscw@cscwmail.example.org.......................... new
    manfred.bogen@gmd.example.org...................... new
53:
    pakhomenko@example.com............................. new
    pakhomenko@example.com............................. known

Depending on the size of your mail archive, this may take a while, but usually mapSoN is pretty quick.

Once that's finished, you'll have a pretty good database to start with, and it's highly unlikely that someone, who has been in contact with you before, will be bothered with an request-for-confirmation mail.