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.3, released 30 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).
As of Version 1.0.3, CGPSA is known to work on Windows 2000 with ActiveState Perl 5.6.1. It is likely that it will work on other Win32 operating systems as well. Throughout the following steps, there are special instructions for Win32 systems.
RES_NAMESERVERS to your system environment
variables to enable DNS lookups under Perl (this is discussed in the installation instructions for SpamAssassin).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. On Win32, this step is not required.$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. On Win32, specify the location with a drive letter, using forward slashes (not backslashes) as separators: for example, C:/CommuniGate Files/ (the default base directory on Win32).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 on UNIX) - 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 create an account for PWD access.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./var/CommuniGate/cgpsa - see step 4). For the Program Path
on Win32, enter perl followed by the full path to the
filter (example: perl C:/CommuniGate Files/cgpsa. Set the
Log level to "Low Level" or "All Info" (for now). Leave "Time-out" and
"Auto-Restart" set to "Disabled" unless you experience problems with the
filter (be optimistic for the time being). Finally, enable the filter
and save your changes.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).
It is possible that CGPSA contains bugs, although it has already been in use for months in production systems and we consider it relatively stable. 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.