CGPSA - A Spam Filter for CommuniGate® Pro
Version 1.8.2

Copyright © 2002-2023 TFF Enterprises
Written by Daniel M. Zimmerman

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, 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.

CGPSA also can also attempt to minimize backscatter from the CommuniGate Pro mailing list module, which lacks backscatter reduction features itself. See the documentation in the configuration file for more details.

Downloads

The most current (release) version of CGPSA can always be downloaded from https://www.tffenterprises.com/cgpsa/cgpsa.tgz. The current (release) version is 1.8.2, released 17 June 2023.

There is no current testing version of CGPSA.

Source code is available on GitHub.

Documentation

This documentation consists of the following sections:


Overview

CGPSA has two basic operating modes, "full-featured" and "headers-only".

Full-Featured Mode

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 and load separate CGPSA settings and SpamAssassin settings for individual CommuniGate Pro domains and individual users. In this mode, email is scanned only for the recipients on the local system for whom scanning is turned on, 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.

At this time, there is no user interface to configure CGPSA settings and SpamAssassin preferences for individual domains and users; however, system administrators with access to the CommuniGate Pro base directory may take advantage of these features for their own use and that of the domains they administer. Individual user SpamAssassin preferences and state files are located in a .spamassassin directory inside the web directory corresponding to the account (username.macnt/account.web), and individual user CGPSA preferences are located in a .cgpsa.conf file within the same directory; domain CGPSA preferences are located in a cgpsa.domainconf file inside the domain's Settings directory, which can, among other things, specify the location to find the domain's SpamAssassin preeferences and state files.

Headers-Only Mode

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.


System Requirements

CGPSA requires the following in order to run:

  1. CommuniGate Pro version 4.0 or higher (4.1 or higher preferred)
  2. Perl version 5.6.1 or higher
  3. SpamAssassin version 3.0 or higher
  4. Additional Perl modules as required by the configuration options you choose for CGPSA and SpamAssassin (described in the installation steps below and in SpamAssassin's documentation).

Installation

Installation of CGPSA takes several steps. The following step-by-step instructions should enable you to get the filter working on your system (there are special instructions for Win32 systems throughout the steps). If you can't get it working, ask for help (as described below in Bug Reports, Feature Requests and the Like).

  1. Install SpamAssassin on your system. The way to do this is platform dependent - on FreeBSD, for example, you might use the FreeBSD Ports system. Also install any auxiliary programs you want SpamAssassin to use, such as Razor and DCC. Perl is a prerequisite for SpamAssassin. Instructions for installing SpamAssassin on Win32 operating systems are available here. On Win32, you must add RES_NAMESERVERS to your system environment variables to enable DNS lookups under Perl (this is discussed in the installation instructions for SpamAssassin).

  2. Verify that the path in the first line of the cgpsa script points to the Perl executable on your system. If you have Perl in a different location (such as /usr/bin/perl or /opt/bin/perl), change the line accordingly. On Win32, this step is not required.

  3. Verify that the $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).

  4. Install the 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.

  5. Install the 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.

  6. Install customized cgpsa.domainconf configuration files into the Settings subdirectories of all domains (e.g., /var/CommuniGate/Domains/mydomain.com/Settings) for which you want customized CGPSA settings. You can modify any settings you choose in this file, but only those that explicitly indicate that they can be overridden at the domain level will be used. Also note that domain settings will only be used if CLI usage is enabled (see the next step for details).

  7. If you are running CGPSA in its full-featured mode with CLI usage enabled, you must install the CommuniGate Pro CLI Perl Module, CGP::CLI. You can install it from CPAN directly, and it should take care of all its dependencies. Alternatively, 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 the cgpsa script. CGP::CLI 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 CGP::CLI; 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 CGP::CLI for CGPSA to function.

  8. If you are running CGPSA in its full-featured mode with CLI usage enabled, you must create a CommuniGate Pro account with PWD access (as described in the configuration file). Use the username and password specified in your cgpsa.conf. This user must have administrative access to all the domains for which you will be using CGPSA (the easiest way to do this is to give it access to "modify and monitor everything"; at minimum, it should have access to modify "server and module settings" and "all domains and accounts settings", but it needs access to "do everything" in order to modify the temporary blacklist). Enable a number of PWD connections greater than 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.

  9. If you are running CGPSA in its full-featured mode with CLI usage enabled, and your CommuniGate Pro setup has IP addresses specifically assigned to domains, make sure that either you have specified "127.0.0.1" as an address associated with one of your domains or you have changed the "cgp_hostname" setting in cgpsa.conf to refer to a hostname or IP address on which the CommuniGate server is listening.

  10. Create the "default home directory", whose path is set in the configuration file (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. If you have created customized settings for domains, and they have their own default home directory paths, create those directories as well.

  11. Create a SpamAssassin configuration in the default home directory, if necessary. If the CommuniGate Pro server is the only software on your system using SpamAssassin, you can just use SpamAssassin's 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. Repeat this step for the default home directories of any domains for which you want to use custom SpamAssassin preferences.

  12. In the CommuniGate Pro web administration interface, go to the "Helper Settings" page (under "Settings/General"). In an empty "Content Filtering" section, enter a name for the filter (such as "CGPSA"). For the Program Path on UNIX, enter the full path to the filter (example: /var/CommuniGate/cgpsa - see step 4). For the Program Path on Win32, enter perl followed by the full path to the filter in quotes(example: perl "C:\CommuniGate Files\cgpsa". Set the Log level to "Low Level" or "All Info" (for now). Leave "Time-out" set to "Disabled" unless you experience problems with the filter (be optimistic for the time being), and set "Auto-Restart" to a relatively small value (1 minute is reasonable). Finally, enable the filter and save your changes.

  13. Examine the CommuniGate Pro log for the current day, and search for the string you entered as the filter's name in the previous step. You should see a line that reads similar to the following: "* TFF Enterprises CGPSA Filter (Version) Ready". If you do not see this line, wait a few seconds and look again. If you still do not see it after a minute or so, something went wrong and there will likely be an error message in the log. If you can make sense of it and fix the problem, wonderful; if not, ask for help (as described below in Bug Reports, Feature Requests and the Like).

  14. Go to the "Server-Wide Rules" page of the CommuniGate Pro web administration interface ("Settings/Rules") and create a rule for CGPSA. The rule action should be "ExternalFilter CGPSA" (the name you assigned to the filter two steps ago). No rule conditions are necessary for proper operation, but greater efficiency will be attained with the following conditions: "Any Route is LOCAL*" and "Header Field is not X-TFF-CGPSA-Filter*" (or whatever you've changed the loop prevention header to). Note that omitting the first of these conditions means that mail distributed to remote servers will be scanned (which may not be a good idea - in full-featured mode with the CLI, CGPSA will automatically leave mail for remote servers alone, but in other modes, it scans every message passed to it).

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).


Upgrading

To upgrade from a previous version of CGPSA, perform the following steps:

  1. Copy the new cgpsa over the one you currently have installed.

  2. Compare the configuration file (cgpsa.conf) that came with the new CGPSA to the configuration file you currently have installed. If there are any new configuration options that you want to use, add them to your installed configuration file. Alternatively, you can add your own customizations to the new configuration file and copy it over the old one. When upgrading from a pre-1.3 version to 1.3 or higher, you may also want to create domain and user settings files as described in step 6 of the installation instructions and in the included cgpsa.conf file.

  3. Restart CGPSA. There are two ways to do this. If you have "Auto-Restart" enabled for CGPSA in the CommuniGate Pro "Helper Settings", you can manually kill the running CGPSA process(es); this is done with a command such as killall cgpsa (on Linux) or pkill cgpsa (on Solaris), or through a graphical interface such as macOS's "Activity Monitor" or Windows' "Task Manager". If you cannot kill the running CGPSA processes, you can restart CGPSA using the "Helper Settings" page of the CommuniGate Pro web administration interface. In the "Content Filtering" section you made for CGPSA, uncheck the checkbox by "Use Filter", and then click "Update". Then, re-check the checkbox by "Use Filter" and click "Update" again.

  4. Examine the CommuniGate Pro log for the current day. You should see a line that reads "* TFF Enterprises CGPSA Filter (Old Version Number) Done", and slightly later a line that reads "* TFF Enterprises CGPSA Filter (New Version Number) Ready". If you don't see this, and it doesn't show up after a reasonable amount of time, restart your CommuniGate server (using the startup/shutdown script installed with CommuniGate). If CGPSA still doesn't start, ask for help (as described below in Bug Reports, Feature Requests and the Like).


Disclaimer

It is possible that CGPSA contains bugs, although it has proven to be quite stable on 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.


License and Fees

CGPSA is non-commercial software, even though it has similar functionality to some existing commercial products. If you find it useful, feel free to send me something for it (email cgpsa@tffenterprises.com if you need information on how to do so). I also do CGPSA installations on a flat-fee basis.

CGPSA is licensed under the 3-Clause BSD License. See the LICENSE.md file for details.


Bug Reports, Feature Requests, and the Like

Suggestions for feature improvements and bug fixes are gladly 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.

When sending a bug report, be sure to include any relevant information from the CommuniGate Pro log and the cgpsa.err log (located in the same directory as your cgpsa.conf file).


Revision History

1.8.2 - 17 June 2023

Bug Fixes

1.8.1 - 22 January 2022

Bug Fixes

1.8 - 22 January 2022

Major Changes

Minor Changes

Bug Fixes

Known Issues

1.7 - 9 May 2010

Major Changes

Minor Changes

Bug Fixes

Known Issues

1.5 - 23 August 2006

Major Changes

Minor Changes

Bug Fixes

Known Issues

1.4 - 2 January 2005

Major Changes

Minor Changes

Known Issues

1.3.5 - 2 December 2004

Bug Fixes

1.3.4 - 5 August 2004

Changes

1.3.3 - 19 June 2004

Bug Fixes

1.3.2 - 24 April 2004

Changes

1.3.1 - 10 April 2004

Changes

Bug Fixes

1.3 - 28 March 2004

Major Changes

Minor Changes

Known Issues

1.2.8 - 12 February 2004

Bug Fixes

1.2.7 - 31 December 2003

Bug Fixes

1.2.6 - 26 December 2003

Bug Fixes

1.2.5 - 13 December 2003

Changes

Bug Fixes

1.2.4 - 3 December 2003

Changes

Bug Fixes

1.2.3 - 14 November 2003

Bug Fixes

1.2.2 - 14 November 2003

Changes

Bug Fixes

1.2.1 - 2 October 2003

Bug Fixes

1.2 - 17 September 2003

Changes

Known Issues

1.1 - 27 July 2003

Changes

Known Issues

1.0.8 - 18 June 2003

Bug Fixes

1.0.7 - 17 June 2003

Changes

Bug Fixes

1.0.6 - 5 May 2003

Changes

Bug Fixes

1.0.5 - 14 April 2003

Changes

Bug Fixes

1.0.4 - 2 April 2003

Changes

1.0.3 - 30 March 2003

Changes

Bug Fixes

1.0.2 - 27 March 2003

Bug Fixes

1.0.1 - 27 March 2003

Changes

1.0 - 23 March 2003

Initial Release Version


Future Plans

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 2700-line Perl scripts are not the easiest things in the world to maintain).


CommuniGate is a registered trademark of CommuniGate Systems.

CGPSA is licensed under the 3-clause BSD license; see the LICENSE.md file in the CGPSA distribution for more details.


Valid CSS! Valid XHTML 1.1! Last modified by Daniel M. Zimmerman on 22 January 2022