CommuniGate Pro
Version 6.3
E-mail
 
 
Filters
 

External Filters

This section explains how CommuniGate Pro can employ External Filter programs to scan messages. This feature is used to implement virus protection and content filtering.

The CommuniGate Pro Filters provide a much more solid solution than various stand-alone SMTP-based "mail scanners":
  • Stand-alone "scanner" SMTP relays usually implement only the basic SMTP functions. Since all SMTP connections have to be established to those relays, and not to the CommuniGate Pro SMTP module, the CommuniGate Pro SMTP extended functionality becomes unavailable to users and other SMTP servers.
  • Stand-alone "scanner" SMTP relays usually provide much weaker performance and reliability than CommuniGate Pro Servers. When the "scanner" relay goes down, the CommuniGate Pro SMTP functionality becomes unavailable, too.
  • Stand-alone "scanner" SMTP relays usually cannot scan several messages simultaneously, so when a large message is being scanned, the SMTP traffic to the CommuniGate Pro Server stops.
  • Stand-alone "scanner" SMTP relays cannot scan messages not submitted via SMTP. For example, messages composed using the WebUser Interface and directed to a user on the same CommuniGate Pro Server are delivered without any SMTP transfer operations.

External Filters run alongside the CommuniGate Pro Server. They do not deal with message transfer protocols. Instead, the CommuniGate Pro Server passes them a message file right before the message is being enqueued into module queues. As a result, all messages can be scanned, not only the messages sent via a particular mail transfer protocol.

If the CommuniGate Pro ENQUEUER is configured to use several processors (threads), several messages can be scanned simultaneously. As a result, long messages that require several seconds of scanning time do not stop the message flow.

The third-party Plugins distributed by CommuniGate Systems usually require an additional License Key. Several Plugins are currently available.

The Helpers section specifies the information about the External Filters protocol. Read that section if you plan to design a new Plugin.

Starting External Filters

After you have installed an External Filter program, or built your own one, use the CommuniGate Pro WebAdmin Interface to configure the External Filters. Open the General pages in the Settings realm, and click the Helpers link.

Content Filtering
Log Level: Program Path:
Time-out: Auto-Restart:
Log Level: Program Path:
Time-out: Auto-Restart:
Log Level: Program Path:
Time-out: Auto-Restart:

To specify a new External Filter program to run, use the last element in this table. Assign some name to the Filter program and enter into the first field. You will use this name when you specify the ExternalFilter Rule actions.
Enter the program path and other options, and click the Update button.

To remove an External Filter program, enter an empty string into its Filter name field, and click the Update button.

Each External Filter program has the following options:
Log
Use this setting to specify the type of information the External Filter module should put in the Server Log. Usually you should use the Problems Log level (status change and non-fatal errors). But when you experience problems with the External Filter program, you may want to set the Log setting to Low-Level or All Info: in this case the inter-program protocol-level details will be recorded in the System Log as well.
The External Filter records in the System Log are marked with the EXTFILTER tag.
Program Path
Use this setting to specify the file name path for the External Filter program (with optional parameters). If the External Filter Software has been installed inside the CommuniGate Pro base directory, you can use the relative path (VirusScan\scan.exe, for example). Otherwise, use the full path (such as D:\Programs\VirusScan\scan.exe or /usr/sbin/myFilter).
Note: always use the backslash (\) path separators if the CommuniGate Pro Server runs on a Microsoft Windows platform.
Note: on Unix platforms, if you want to specify parameters that include spaces or other special symbols, enclose them into the quote (") symbols. On other platforms, use the platform-specific agreements for command line parameters.

Set the first option value to Enabled, and click the Update button to start the External Filter program. If the program cannot be started, an error message appears on the Helpers page.

Time-out
Certain conditions and/or errors in the External program code can make it enter a loop and stop responding to CommuniGate Pro Server requests. If a response for any of the Server requests is not received within the specified period of time, the Server sends a termination signal to the External Program.
Auto-Restart
Certain conditions and/or errors in the External program code can crash that program. Also, the Server itself can send a termination signal to the External program if the program does not respond to requests within the specified period of time (see above).
If the Auto-Restart parameter is not set to Never, the CommuniGate Pro server detects the External Program termination, waits for the specified period of time, and then restarts the External Program automatically. Then it resends all pending requests to the newly started External Program and resumes normal request processing.
If the Auto-Restart parameter is set to Never, you need to open the Helpers WebAdmin page and click the Update button to force the Server to restart the External program.

Using External Filters

An enabled External Filter is not used for scanning mail messages by default. If you have specified an External Filter program with the filterName name, you can scan all messages with that program by creating a Server-Wide Rule. Specify no condition for that Rule (so the Rule will apply to all messages the Server processes), and specify one Rule action - ExternalFilter filterName.

Messages are scanned only when the option next to the Filter name is set to Enabled. You may want set this option to Disabled to let messages bypass this External Filter program. If this option is set to Disabled, the ExternalFilter filterName Rule operation is a null operation (it does nothing).

If you want to scan only some messages, add condition(s) to this Rule. The following sample Rule check the size of a message, and uses the VirusScan External Filter program to scan only those messages that are larger than the specified limit:

Data Operation Parameter
Action Parameter

External Filters are contacted from the Server ENQUEUER threads. Since it can take several seconds to process a large message, increase the number of ENQUEUER processors (threads) using the Queue page in the WebAdmin Interface Settings realm.

Alternatively, you can disable the Enqueue Asynchronously option (on the same page), and make each submitting thread scan the messages during the submit process.

CommuniGate Pro Guide. Copyright © 2024, AO SBK