Introduction

ASSP stands for Anti-Spam SMTP Proxy and that’s exactly what it is. You install it as a proxy between the internet and your mailserver and it filters out spam for you. For more information on ASSP check out my previous article on ASSP, which is much more verbal and also discusses in some detail how to operate your ASSP installation.

This article explains how to set up ASSP on Debian 8 “Jessie”. It will most probably work on any Debian derevative as well, like Ubuntu or Linux Mint.

Update: added notes for installing on Ubuntu 16.04.1.
Update 2: updated to work with Debian 9; added workaround for Perl bug

Ubuntu doesn’t have aptitude installed by default so if you’re running Ubuntu you must either install it (# apt-get install aptitude) or substitute aptitude for apt-get in this article.

Backends
ASSP can use a number of database backends, including:
– flat text files (this is the default)
– BerkeleyDB (easy to set up but not managed)
– MySQL (a bit more complicated to set up but works better in the long run)
– many other databases

We’ll start out with text files and migrate to MySQL once everything is running.

Mailserver
You will need to set up your own mailserver (e.g. Exchange, Domino, Postfix) and have it relay outgoing mail through the ASSP server. We’ll set up ASSP on a separate machine. It’s perfectly possible to run ASSP on your mailserver itself but isolating it on a separate machine makes for easier troubleshooting.

System requirements
During setup ASSP may complain that it needs at least four processors and two DNS servers. It will work with less but the complaints are valid: in order to secure smooth operations you *will* need a decent server. Also the DNS servers need to be servers on your LAN, not on the internet. External DNS servers may return non-standard replies to dnsbl queries and even if they don’t they may start doing so in the future without warning. For this test setup I’m using just one DNS server but in a corporate environment in which you’re depending on DNS for your daily network operations (say Active Directory or any type of LDAP based network) your DNS server(s) must be sufficiently responsive to service both LDAP and ASSP queries.

Why not use Exim4 instead of Postfix? Because I am more familiair with Postfix. Use Exim4 if you like.

Network lay-out
For this article I will be using three machines:
192.168.1.1 – router
192.168.1.2 – ASSP + Postfix
192.168.1.3 – mailserver (Postfix) to which the end-users connect
Domain: testnet.lab
User: vorkbaard – but feel free to add your own

Do keep the IP addresses in mind when copying and pasting example code into your own server.

Versions
– Debian 8.6
– ASSP 2.5.1 16177

Installing the server

When installing Debian you’ll be asked which server roles you would like to install. Ubuntu and other derevatives may differ from Debian itself but in any case you do not need to select anything in particular. SSH will be handy and the so-called standard system utilities.

No particular software collections necessary:
[*] SSH Server
[*] Standard system utilities

Note for Ubuntu 16: you may install the Mailserver role here, which will install Postfix.

Debian Jessie's Task Selector

Debian Jessie’s Task Selector

If you’re using a VM it is advisable to install ntpdate so your mail and logs will use the correct time stamps:

# aptitude install ntpdate ntp
# service ntp stop && ntpdate 2.debian.pool.ntp.org && service ntp start

After exporting or importing the VM do

# ntpdate 2.debian.pool.ntp.org

to sync the time.
(Pick a close ntp server from the list at http://www.pool.ntp.org.)

Postfix

# aptitude install postfix

If asked to replace Exim, choose Yes. Type of server: Internet Site. System mail name: like the explanation on-screen says: if a mail address on the local host is foo@example.org, the value would be example org.

In the file /etc/postfix/master.cf find:

smtp    inet    n   -   -   -   -   smtpd

and change it to:

125     inet    n   -   -   -   -   smtpd

Set message size limit
We need to take a careful look at the maximum allowed e-mail size because if ASSP and Postfix are not using the same size strange errors may occur. I have had mails stuck in the queue indefinitely because Postfix’s maximum size was smaller than ASSP’s.

For this article we’ll be going with a 20MB e-mail limit.

In the file /etc/postfix/main.cf change the following value (or add it if it doesn’t exist):

message_size_limit = 26214400

Secure so only the ASSP server may use Postfix: in /etc/postfix/main.cf change mynetworks to:

mynetworks = 127.0.0.0/8 192.168.1.2/32 [::ffff:127.0.0.0]/104 [::1]/128

Take care to use your own server’s address in the above line where I wrote 192.168.1.2.
At the end of the file add:

smtpd_client_restrictions = permit_mynetworks, reject
smtpd_delay_reject = no
transport_maps = hash:/etc/postfix/transport

This tells Postfix:
– to allow the addresses in the mynetworks value
– to reject immediately if not allowed
– to use a hash of the file /etc/postfix/transport to look for routing instructions.

Look for the value of mydestination and remove your mail domain (note: this is already done in Ubuntu 16):
From

mydestination = example.com, assp.testnet.lab, localhost.testnet.lab, localhost

To:

mydestination = assp.testnet.lab, localhost.testnet.lab, localhost

If you don’t do this Postfix will assume it is the final recipient of incoming mail for your domain, which it isn’t: it must be routed through ASSP and delivered to your ‘real’ mailserver.

Create the file /etc/postfix/transport and add to it:

example.com smtp:192.168.1.3

This tells Postfix that mail to the example.com domain should be routed to 192.168.1.3 using the smtp protocol. Again, use your own domain name and mailserver IP address.

Load the transport file in Postfix and reload Postfix:

# postmap /etc/postfix/transport
# postfix reload

The postmap command creates a hash file for the /etc/postfix/transport. Our file contains only one entry but if there a lot more the hashing would make it easier to read for the computer, thus faster. It’s just the way Postfix does things.

Note that if you change the transport file you need to rehash it by rerunning the above postmap command.

Perl modules from Debian’s repositories

A lot of Perl modules exist in Debian’s repositories. The format is usually: net::dns::perl becomes libnet-dns-perl. To install the lot of them:

# apt-get install libnet-dns-perl libauthen-sasl-perl libmail-spf-perl \
          libregexp-optimizer-perl libfile-readbackwards-perl \
          libnetaddr-ip-perl libnet-cidr-lite-perl libmail-dkim-perl \
          libnet-ldap-perl libunicode-string-perl \
          libemail-mime-perl libtext-unidecode-perl \
          liblingua-stem-snowball-perl libsys-cpu-perl libthreads-perl \
          libschedule-cron-perl libdigest-sha-perl libmime-types-perl \
          libclamav-client-perl libarchive-zip-perl libberkeleydb-perl \
          liblingua-identify-perl libsys-cpuload-perl \
          libthreads-shared-perl libunicode-linebreak-perl

Dependencies

We’ll be installing as many Perl modules as possible from Debian’s repositories. This ensures they will play nice with the rest of the OS and be updated automatically.

Some modules have dependencies that need to be fulfilled first.

Module:				   Included in package:
OCR modules:                       libgd2-xpm-dev
Crypt::OpenSSL::AES:               libssl-dev					
Image::OCR::Tesseract:             tesseract-ocr and imagemagick
PDF::OCR and PDF::OCR2:            xpdf
installing Perl modules from CPAN: make and build-essential
# aptitude install make build-essential libgd2-xpm-dev libssl-dev tesseract-ocr imagemagick xpdf

Perl modules

Some Perl modules are not available as a Debian repository package. We need to install those with CPAN.

First, upgrade CPAN:

# cpan
Would you like to configure as much as possible automatically? [yes]
CPAN> install CPAN
CPAN> reload cpan

Now let’s install the modules.

cpan> install Digest::SHA1 LWP::Simple Net::IP::Match::Regexp Net::SMTP Net::SenderBase Net::Syslog Thread::State File::PathInfo LEOCHARRE::DEBUG LEOCHARRE::CLI Tie::RDBM Sys::CpuAffinity Sys::MemInfo Unicode::GCString Mail::DKIM::Verifier PDF::GetImages Crypt::OpenSSL::AES Image::OCR::Tesseract PDF::OCR PDF::OCR2 Email::Send

This may take a while. Get coffee.

LWP will ask if you want to run tests. Answer it No. Get more coffee.

Installing PDF::Burst
PDF::Burst was written by the artist Leo Charre who is no longer updating his code. PDF::Burst will not install without a fight. To install it:

# cpan
cpan> install PDF::Burst (this will fail)
cpan> look file PDF::Burst
cpan> exit
# vi lib/PDF/Burst.pm

Replace the line that reads

defined %dat or warn("had nothing in '$doc_dat'?") and return;

with

%dat or warn("had nothing in '$doc_dat'?") and return;

[Source: https://rt.cpan.org/Public/Bug/Display.html?id=103188]

Save the file

# make test
# make install

# exit
> quit

SPF
Mail::SPF::Query is used for upgrade compatibility with ASSP V1. V2 only uses Mail::SPF. It is possible to force install Mail::SPF::Query and it will work but unless you’re upgrading from V1 (which we’re not; this is a clean install) it is better to disable useMailSPFQuery, not install Mail::SPF::Query and instead enable useMailSPF and install libmail-spf. Enabling and disabling these options can be done in ASSP’s web interface later on.

If useMailSPFQuery:=0 ASSP may become unstable, at least that’s what happens when I install it. Force install Mail::SPF::Query and leave useMailSPFQuery:=1. I went with

cpan> force install Mail::SPF::Query

If you’re going to use ClamAV for virus scanning, do

cpan> force install File::Scan::ClamAV

(My previous article explains in more detail how to set up ClamAV with ASSP.)

cpan> quit

Installing ASSP

# aptitude install unzip
$ wget -O assp.zip http://sourceforge.net/projects/assp/files/latest/download

Extract to /usr/share/assp/. You could put it anywhere but I’m using this path.

# unzip -d /usr/share assp.zip

Make the Perl scripts executable:

# chmod +x /usr/share/assp/*.pl

Create a dedicated system user for assp:

# useradd assp -r

Set file permissions

# chown -R assp:assp /usr/share/assp

ASSP will change the permissions a bit. That’s ok. It’s started as root and its code changes it to the assp user.

Start ASSP:

# perl /usr/share/assp/assp.pl &

Press Ctrl + C to fork the process to the background to free your console.
Watch for errors and warnings in /usr/share/assp/logs/maillog.txt.
Point your browser to http://192.168.1.2:55555. The default username is root and the password is nospam4me.

Configuring ASSP

The bare minimum to getting ASSP running:

[Network Setup / Incoming MailNetwork Flow]
SMTP Listen Port (listenPort): 25
SMTP Destination (smtpDestination): 125

[Relaying / Outgoing and Local Mailrelaying not allowed]
Relay Host (relayHost): 127.0.0.1:125 (this is Postfix we set up earlier!)
Relay Port (relayPort): 225
Allow Relay Connection from these IP’s (allowRelayCon): 192.168.1.3

[SMTP Session Limits]
Max Size of Local Message (maxSize): 20971520
Max Size of External Message (maxSizeExternal): 20971520

[Recipients/Local Domains/Transparent Recipients and Domains ]
Local Domains (localDomains): example.com

[Delaying/Greylisting]
[ ] Enable Delaying/Greylisting (in any case for now while we’re testing)

[TestModes]
Prepend Spam Subject (spamSubject): [SPAM]
[v] Prepend Spam Tag (spamTag)
[v] All Test Mode ON (allTestMode)

[Logging]
Notification Email To (Notify): helpdesk@example.com

[DNS Setup]
[v] Use Local DNS (UseLocalDNS)
DNS Name Servers (DNSServers): 192.168.1.1
Use at least two dns servers for production environments. Using one dns server will result in an error message ‘incorrect ‘DNSServers’ – possibly unchanged’. It will still work.

[Server Setup]
Run as UID (RunAsUser): assp
Run as GID (RunAsGroup): assp
My Name (myName): mail.example.com
My Helo (myHelo): SENDERHELO – IP – MYNAME – FQDN | MYNAME
Override the Server SMTP Greeting (myGreeting): MYNAME
[v] Set ASSP File Permission on Startup (setFilePermOnStart)
[v] Check ASSP File Permission on Startup (checkFilePermOnStart)

Do not forget to press Apply Changes after making changes. If you need to restart ASSP scroll all the way up and click Shutdown/Restart. Click the Proceed button and be patient. You can follow the shutdown process from your terminal.

If your browser says the page cannot be found ASSP has stopped and you may restart it.

Now is a good time to test connectivity. Tell your mailserver to relay outgoing mail to 192.168.1.2:225 and verify that incoming and outgoing mail is working. In case of problems check /var/log/mail.log and /usr/share/assp/logs/maillog.txt.

Migrating the databases to MySQL

Install mySql:

# aptitude install mysql-server mysql-client

The installer will ask you for a password. Choose a hard password and remember it.

Set up a database and a user for assp:

# mysql -u root -p
mysql> create database assp;
mysql> create user 'assp'@'127.0.0.1' identified by 'pwd';
mysql> GRANT ALL PRIVILEGES ON `assp`.* TO 'assp'@'127.0.0.1';
mysql> quit

Enable [Network Setup / Incoming Mail] > Disable all new SMTP and Proxy Network Connections (DisableSMTPNetworking). So check the checkbox.
[Apply Changes]

Monitor the ASSP database for changes:

# watch mysql -u root -pMySqlPassword -e \'show tables\' assp

If your MySql root password is pwd do

# watch mysql -u root -ppwd -e \'show tables\' assp

Initially this will not show any output because ASSP has not made any tables yet.

Set all needed DB parameters [File Paths and Database]
database hostname or IP (myhost): 127.0.0.1
database driver name (DBdriver): mysql
database name (mydb): assp
database username (myuser): assp
database password (mypassword): pwd (use the assp user’s database’s password here)

[Apply Changes], verify that ASSP is not throwing errors and that the database settings remain set in the web interface.

Set Email Whitelist Database File (whitelistdb) to: DB:
Press [Apply Changes].

Restart ASSP and verify that the watch command now shows the whitelist table (can take a few seconds).

If that works correctly then ASSP is working well with MySQL and you can set the other lists to DB: as well:
Email Redlist Database File (redlistdb)
Personal Blacklist Database File (persblackdb)
Delaying Database (delaydb)
LDAP Database (ldaplistdb)

[Shutdown/Restart]
Start assp

Uncheck the DisableSMTPNetworking checkbox.

Tips and tricks

* Subscribe to the ASSP mailing list.
* Troubleshooting Postfix:
– Postfix logs to /var/log/mail.log
– ASSP logs to /usr/share/assp/logs/maillog.txt and /usr/share/assp/logs/bmaillog.txt (errors). That is, if you installed ASSP in /usr/share/assp.
– # postconf -n shows all non-default settings in Postfix’s configuration
– Do not start the line ‘125 inet n – – – – smtpd’ with one or more spaces.
– Postfix does not care about the order of the directives in main.cf.
* Check my previous article on ASSP for a more elaborate discussion of the software.