Introduction

This manual describes how to integrate spamd (spamassassin) with cgserver (communigate pro, by stalker inc) in order to filter spam with per-domain and per-user settings.

The first steps are not covered here: read other manuals on how to install and configure spamassassin, mysql, and webuserprefs. After you set them up and test them on the command line, you can use this manual to integrate them with cgserver.

Download

This is a script that accepts messages from cgserver via an execute action rule and invokes spamassassin.

http://www.buhacoff.net/2005/projects/cgpeasa/cgpeasa-0.41.tar.gz

http://www.buhacoff.net/2005/projects/cgpeasa/cgpeasa-0.41.zip

Unpack

Copy the file 'cgpeasa' from the archive to /usr/local/bin or wherever you like. The file 'cgpeasa.conf' is only an example file that you can use with the -c option.

Try `perldoc cgpeasa` or `perldoc /usr/local/bin/cgpeasa` to get more information about that script. The NOTES section is important.

Add the rule

Execute actions are available for site-wide, domain, and account rules. When these actions are processed, cgserver can pass to your script the name of the final destination. Voila, an easy way to know which settings to grab.

Go to your domain rules and add this rule:

Submit Address is SMTP*
Execute [ACCNT] /usr/local/bin/cgpeasa -m /var/spamassassin/cgpeasa --
Discard

The first line is the condition for the rule. It says to only execute the script if the email comes from the outside world. This is important because the actions, as you see, execute the script and then discard the email. The email will be re-inserted into the cgserver queue using the Submitted folder, and then it will have a non-SMTP submit address so the action will not be executed again for the same email.

The second line tells cgserver where the script is and allows you to send arguments to the script. The trailing -- is important because it separates the script's regular arguments from cgserver's way of passing arguments, which the script processes differently.

The third line tells cgserver to discard the email after running the script. If the script fails the email will not be discarded. When you first set up the rule you might want to omit the third line and get duplicate emails for a while (the second one will have the spam report on it) until you're confident with the system, then add the Discard action.

Server OS Integration

In order for CGP to execute the cgpeasa script, wherever you've installed it, you need to have working 'Server OS Integration' settings. If you use the default (*) then you need to have a real user for every mail account. If that's not the case for you, then you can just create one real user (something like 'cgpsosimailuser') and then name that user in the Domain -> Account Defaults management screen.

Cron Script

If you use a temporary maildir like /tmp/cgpeasa that has global write permissions, you'll need a process that runs as root to submit the messages to cgserver. Here's mine:

Junk folders

If the domain users have junk folders, you can add this rule to place junk email in them automatically:

Learning spam and ham

You will probably want to let your users create Learn Junk and Learn Not Junk folders so they can place messages in there for spamassassin to learn.

External filter vs. Execute action

cgserver provides two ways to pass incoming mail to external scripts: external filter and execute action.

External filters are available for system-wide rules only, and this is fine if you have rules that apply to all users in all domains on your server. I successfully managed such a setup for a long time. But then my users wanted personal whitelists, and some groups of users wanted to share their bayes database, and this becomes difficult. To implement per-domain and per-user settings with external filters means that the filter first has to identify the recipients of the email, then use cgserver's CLI module to determine the final destinations of the email, then run spamassassin on the message once per destination, using the destination account's settings.

If you want to go with external filters, you need CGPSA from http://www.tffenterprises.com/cgpsa/

Notes

Disadvantages of an execute action script is that cgserver starts one for each rule. This might add up to be a big performance hit for high volume servers. On the other hand the script is tiny and the spam assassin daemon stays running in the background so the process is pretty quick. The big cause of delays on my server is that I'm running the execute action script without privileges, using a temporary maildir, and then running a cronscript (as root) to submit those messages to CGP. The cronscript runs once a minute and actually copies messages at 15-second intervals 3 times... so every message is delayed at most 15 seconds. I'm thinking about changing this part in the future, but it won't affect any of the instructions above.

Also, I recommend a directory in /var for the messages and not in /tmp because some systems purge the /tmp directory on boot or at some other inconvenient time and if there were messages in there that didn't make it into CGP yet, they will be lost.