External Filters

Starting the External Filter Using the External Filter 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 Stalker Software 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 the External Filter

After you have installed an External Filter program, or built your own one, you should tell CommuniGate Pro to start that Filter Program and to establish a communication link with it. Open the General page in the Settings section of the WebAdmin Interface, and click the Helpers link. The Helpers page is displayed:

To use an External Filter program, open the General page in the Settings section of the WebAdmin Interface and click the Helpers link. The Helpers page is displayed:

Content Filtering
Use Filter: Log: Crashes OnlyFailuresMajor & FailuresProblemsLow LevelAll Info Program Path: Time-out: disabled15 seconds30 secondsminute2 minutes3 minutes5 minutes10 minutes15 minutes30 minuteshour Auto-Restart: disabled5 seconds7 seconds10 seconds15 seconds30 secondsminute2 minutes3 minutes5 minutes10 minutes15 minutes30 minuteshour2 hours3 hours6 hours
Use Filter: Log: Crashes OnlyFailuresMajor & FailuresProblemsLow LevelAll Info Program Path: Time-out: disabled15 seconds30 secondsminute2 minutes3 minutes5 minutes10 minutes15 minutes30 minuteshour Auto-Restart: disabled5 seconds7 seconds10 seconds15 seconds30 secondsminute2 minutes3 minutes5 minutes10 minutes15 minutes30 minuteshour2 hours3 hours6 hours
Use Filter: Log: Crashes OnlyFailuresMajor & FailuresProblemsLow LevelAll Info Program Path: Time-out: disabled15 seconds30 secondsminute2 minutes3 minutes5 minutes10 minutes15 minutes30 minuteshour Auto-Restart: disabled5 seconds7 seconds10 seconds15 seconds30 secondsminute2 minutes3 minutes5 minutes10 minutes15 minutes30 minuteshour2 hours3 hours6 hours

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 it into the Use Filter name field. You will use this name when you specify the ExternalFilter Rule conditions. Enter the program path and other options, and click the Update button.

To remove an External Filter program, enter an empty stirng 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 CommuniGatePro base directory, you can use the relative path (CGPMcAfee\CGPMcAfee.exe, for example). Otherwise, use the full path (such as D:\Programs\CGPMcAfee\CGPMcAfee.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.

Select the check box 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 Disabled, 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 Disabled, you need to open the Helpers WebAdmin page and click the Update button to force the Server to restart the External program.

Using the External Filter

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 checkbox next to the Filter name is selected. You may want to unselect the checkbox to let messages bypass this External Filter program. If the filterName checkbox is not selected, 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 McAfee External Filter program to scann only those messages that are larger than the specified limit:

Data Operation Parameter ---FromSenderReturn-PathToCcAny To or CcEach To or CcReply-To'From' NameSubjectMessage-IdMessage SizeTime Of DayCurrent DateCurrent DayHuman GeneratedHeader FieldAny RecipientEach RecipientAny RouteEach Route isis notinnot ingreater thanless than ---FromSenderHuman Generated isis notinnot ingreater thanless than

Action Parameters ---Write To LogExecuteFingerNotifyExternalFilterRedirect toForward toMirror toReply withReply to All withReact withStore inMarkAdd HeaderReject withDiscardStop Processing McAfee ---Write To LogExecuteFingerNotifyExternalFilterReply to All with

External Filters are contacted from the Server ENQUEUER threads. Since it can take serveral seconds to process a large message, increase the number of ENQUEUER processors (threads) using the Queue page in the WebAdmin Settings section. This allows the CommuniGate Pro Server to continue message enqueueing even when a large message scan is in progress.