CGPSA works in concert with SpamAssassin™ software to scan email messages distributed by a CommuniGate® Pro server. The filter works efficiently, by directly using the SpamAssassin API. It does not rely on a daemon process such as spamd or on the execution of shell scripts (as the usual process for utilizing SpamAssassin with CommuniGate servers does). It can safely be used with multiple CommuniGate Pro enqueuer threads.
CGPSA supports all features of SpamAssassin, including such functionality as the use of Razor, DCC, Bayesian learning (with SpamAssassin 2.5 or higher), and auto-whitelists. All these features are controlled through SpamAssassin's regular configuration files. For more information on SpamAssassin features and configuration, see the SpamAssassin documentation.
The most current (release) version of CGPSA can always be downloaded from http://www.tffenterprises.com/cgpsa/cgpsa.tgz. The current (release) version is 1.0.1, released 27 March 2003.
There is no beta version available at this time.
This documentation consists of the following sections:
CGPSA has two basic operating modes, "full-featured" and "headers-only".
Full-featured mode uses CommuniGate Pro's PIPE functionality to resubmit messages to the server after scanning, and can also use the CommuniGate Pro CLI to determine information about message recipients. In this mode, email is scanned only for the recipients on the local system, and email for remote systems is always left unaltered. This is good, because SpamAssassin headers added according to your local policy may interfere with the spam filtering policy of a remote system. If a particular message is destined for both local and remote users, the local users receive a scanned copy and the remote users an unaltered one. Scanned email is treated exactly as SpamAssassin would treat it; for instance, if the SpamAssassin preferences say to rewrite the subject line of spam, a scanned spam will have a rewritten subject line.
Other advanced functionality, such as the use of individual
SpamAssassin preference files and state files for particular users
(e.g. auto-whitelist, Bayes database), is available in full-featured
mode. At this time, there is no user interface to configure individual
SpamAssassin preferences; however, system administrators with access
to the CommuniGate Pro directory may take advantage of these features
for their own use. Individual user preferences are located in a
.spamassassin directory inside the CommuniGate Pro
account directory corresponding to the account
(username.macnt).
Headers-only mode does not use CommuniGate Pro's CLI or PIPE functionality. Instead, it adds headers to messages directly through CommuniGate's external filter interface. This has the benefit of being more efficient than using PIPE, because it does not require resubmission and reprocessing of messages. However, it also eliminates much of the advanced functionality, such as the use of individual preference and state files, and the ability to distribute unaltered messages to remote servers.
Installation of CGPSA takes several steps. The following step-by-step instructions should enable you to get the filter working on your system. If you can't get it working, ask for help (as described below in Bug Reports, Feature Requests and the Like).
Note that CGPSA has not been tested on Windows - not even a little bit. I have no idea if it will work, or how these steps will have to be changed in order to install it on Windows. If anybody tries - especially if anybody succeeds - please let me know what happens and how you installed it, so I can incorporate that information to a future version of this documentation.
cgpsa
script points to the Perl executable on your system. If you have Perl
in a different location (such as /usr/local/bin/perl or
/opt/bin/perl), change the line accordingly.$cgp_base variable (listed under
"Customizable Variables" near the top of the cgpsa
script) contains the correct path to your CommuniGate Pro Base
Directory (hereafter referred to as "CommuniGate directory"). The
default path is /var/CommuniGate on most systems.cgpsa script inside your CommuniGate
directory, and make sure it is executable. You can create a new
subdirectory for it, or just put it at the top level; it doesn't
really matter where it is, but make sure you know the full path to it
(/var/CommuniGate/cgpsa, if it is at the top level of a
default CommuniGate directory) - you'll need the path
later.cgpsa.conf configuration file into the
Settings subdirectory of your CommuniGate
directory. Modify any of the settings you want to change - they are
all well documented in the configuration file itself.CLI.pm. A version of CLI.pm is included with the CGPSA distribution. You can copy it to any of your system's Perl @INC directories, or just place it in the directory where you've installed cgpsa. CLI.pm requires the Digest::MD5 Perl module; if you do not have it installed on your system, download and install it (or use the CPAN module to install it). If you have installed other scripts on your system that require the CommuniGate Pro CLI, you may already have installed CLI.pm; you do not need to reinstall it for CGPSA, though you should ensure that it's a recent version. If you are running in headers-only mode, or in full-featured mode without the CLI, you need not install CLI.pm for CGPSA to function.cgpsa.conf. Enable a sufficient number
of PWD connections for the number of enqueuer threads used by your
server. See the configuration file for details. If you are running in headers-only mode, or in full-featured mode without the CLI, you need not install the CLI module.cgpsa.conf). This is where the
default SpamAssassin preferences and state files will be stored - that
is, those that are used in the absence of individual user
preferences.local.cf file (usually in
/etc/mail/spamassassin/) to set up SpamAssassin's
preferences. Otherwise, create a .spamassassin
subdirectory inside the default home directory, containing a
user_prefs file with the SpamAssassin preferences to be
used by CGPSA.If all went well, CGPSA is running and you're done. Send a test message to yourself and examine its headers to see whether it has been scanned. You may want to change the log level after running CGPSA for a while, because it does generate quite a lot of output (it's pretty interesting output, but if you aren't writing/debugging the filter, much of it isn't too useful).
This is the first public release of CGPSA. As such it is possible that it contains bugs, although it has already been in use for months in production systems. Any bugs that might exist in CGPSA are unlikely to cause the loss of email, because CommuniGate Pro is very intelligent about how it works with external filters - when a filter fails, the message stays enqueued. However, it is possible that email could be lost. There is no warranty, express or implied, associated with CGPSA; we will not be liable for any lost email. Use at your own risk.
The final licensing model for CGPSA has not been determined. It has very similar functionality to some existing commercial products, and significant effort has been put into it; it would thus be good to receive something in return. However, charging licensing fees even remotely similar to those charged for the aforementioned products makes no sense. Currently, I'm leaning toward some sort of shareware/donationware model. If you have any suggestions in this regard (i.e., how much is the filter worth to you?), let me know.
In the meantime, CGPSA is not to be redistributed without explicit permission. Its source code may not be used in any other products, in verbatim or modified form, whether or not the product is open-source. You may of course modify the source code in any way you like for use on your own system.
Suggestions for feature improvements and bug fixes will gladly be
accepted. There is a mailing list for discussion about this filter,
cgpsa-discuss@tffenterprises.com; this mailing list is
the primary channel for support, discussion of feature requests and
bug fixes, etc. It's a standard CGP mailing list: you can join it by
emailing cgpsa-discuss-on@tffenterprises.com. I
expect it to be pretty low traffic; if you don't want to join the
list, though, send any questions, comments, rants, etc. to cgpsa@tffenterprises.com.
CGP/CLI.pm or just CLI.pm.I'd like a better name to replace "CGPSA". If anybody has any suggestions, I'd really appreciate hearing them...
A hypothetical future version of CGPSA will have a user interface to support individual auto-whitelists, Bayes databases, and SpamAssassin preferences for CommuniGate users. This hypothetical version of CGPSA will also be refactored to be somewhat more object-oriented and modular (because 1000-line Perl scripts are not the easiest things in the world to maintain).
CommuniGate is a registered trademark of Stalker Software, Inc. SpamAssassin is a registered trademark of Deersoft, Inc.