Advanced Topics Manual for LISTSERV 17.0

This “exit point” allows you to use a third-party spam filter to scan messages processed by LISTSERV. Although this hook can in principle be used with any spam scanning product, all the examples and step-by-step instructions in this section will relate to SpamAssassin, a popular freeware spam filter that can be downloaded from https://spamassassin.apache.org. 

4.4.1 Formal documentation

SPAM_EXIT is a standard LISTSERV exit, with all that this entails. The same OS-specific naming requirements used for regular LISTSERV exit points are enforced for the SPAM_EXIT exit point. However, SPAM_EXIT is defined separately in the site configuration file as it is a server-level exit rather than a list-level exit.

LISTSERV scans messages in the following sequence:

Virus scan -> SPAM_MAXSIZE test -> whitelist/blacklist -> SPAM_EXIT -> future L-Soft supplied tests

The rationale for doing things in this order is that viruses are far more dangerous than spam, so LISTSERV wants to identify them as quickly as possible, and in particular before any whitelist rule has had the opportunity to accept them. Besides, virus scans are much faster than spam scans.

The exit is formally defined as follows:

Name: SPAM_EXIT

Parameters: One; SCAN [listname] | REPORT 
Return code: 0=Accept, 1=Local whitelist, 2=Reject

Its primary input is the file spam.tmp in the D directory (typically, unix, ~listserv/tmp ; Windows, \LISTSERV\TMP . This contains a copy of the whole message, header and body. 

When using the SCAN parameter, the exit returns:

• 0: continue normally, per the LISTSERV exit standard. Currently, this means the message is always accepted in practice, but future L-Soft supplied tests would run.
• 1: local whitelist. Accept the message; do NOT run any further tests.
• 2: reject the message. The exit string must then contain an error message to be reported to the sender. LISTSERV will use a standard message if no exit string is supplied, but this standard message is vague since LISTSERV does not know what the exit does.

When using this exit, it is very important to test things carefully, since a mistake could mean that every message is rejected. If for instance the script is not found by the operating system due to a misspelling, and the operating system happens to return 2 in that case, then the message will be automatically rejected even though the message was never scanned. (Because Windows returns 1 for a misspelled exit name, we chose 2=reject instead of the usual 1=reject.)

Once configured, spam scans take place whenever a virus scan takes place and no virus was detected, with two exceptions:

• When downloading binary attachments via WA (virus scan only – spam filters are unlikely to do something meaningful with an .EXE file)
• For the DISTRIBUTE AV=YES programming interface.

The minimum implementation for the REPORT call is to do the same as SCAN does. In addition, it is desirable to create an output file called spam.report in the same directory where the input file spam.tmp is located. There is no special format for this output file, but it is a good idea to start with a line saying whether or not the message was identified as spam, and give the score if the spam filter uses a score system. LISTSERV does not process the report, it just ends up being shown to a human. If no spam.report file is created by the exit, LISTSERV will use the exit string as a one-line report. If there is no exit string, LISTSERV will generate a hard-coded message.

4.4.2 Practical Application

To enable spam filtering in LISTSERV, you must install the third-party spam filter, provide a script that will scan messages using the third-party filter (if using SpamAssassin, you can use one of the L-Soft supplied scripts), and activate this script by making changes to the LISTSERV configuration. LISTSERV will then scan every message it processes, with a few exceptions, and reject messages identified as spam.

Optionally, you can also activate LISTSERV’s built-in blacklist/whitelist functionality (see the release notes for version 14.3 for more information). This feature provides an additional level of spam filtering and can also improve performance significantly, because spam filters like SpamAssassin can take up to 5-20 seconds to scan a message.

4.4.2.1. Step-by-Step Instructions

This section contains step-by-step instructions for configuring LISTSERV to use SpamAssassin using one of the L-Soft supplied scripts. Throughout this section, we will make the following assumptions:

• SpamAssassin has already been installed and configured on a server that we will call spamd.example.com. This can, but does not have to be, the machine on which LISTSERV is installed. In particular, you can run LISTSERV on Windows and SpamAssassin on unix, and vice-versa.
• spamd has been started and is configured to accept incoming requests from the machine on which LISTSERV is installed.
• You have a test message file at your disposal to verify the operation of spamc/spamd. We will call this file testmsg.txt.

Step 1 of 4: Install and test SpamAssassin client.

Unix: Compile spamc on the LISTSERV host, then copy it to a directory in LISTSERV’s path. To test it, use a command similar to the following:

$ spamc -c -d spamd.example.com < testmsg.txt
3.8/5.0

The flags you need to use may vary depending on your version of SpamAssassin and configuration. The response must be two numbers as shown above, but the numbers can be different than in the example (they are the SpamAssassin score of the test message). Any other response indicates an error. Refer to the spamc and spamd man pages for more information.

Windows: Download and install the spamc.exe executable from L-Soft, and place it in a directory in LISTSERV’s path – for instance, the LISTSERV\MAIN directory. 

To test the client, issue the following command:

C:\> spamc -c -d spamd.example.com < testmsg.txt
3.8/5.0

The response must be two numbers as shown above, but the numbers can be different than in the example (they are the SpamAssassin score of the test message). Any other response indicates an error. In that case, make sure that spamd is configured to allow connections from the LISTSERV host.

Step 2 of 4: Install Perl or REXX (if not already available).

Unix: Install perl on the LISTSERV host, if not already installed.

Windows: Install a REXX interpreter, such as Regina REXX (https://regina-rexx.sourceforge.io/, Windows kit download available at https://sourceforge.net/projects/regina-rexx/files/regina-rexx/ .  When prompted to register .REXX as a path extension, you should do so. Alternatively, you can simply download REXX.EXE from L-Soft and place it in the same directory where you saved spamc.exe. 

Step 3 of 4: Install and configure SAEXIT script.

• Download the L-Soft supplied sample script at one of the following URLs:

Unix: https://ftp.lsoft.com/LISTSERV/UNIX/CONTRIB/SAEXIT.PL.gz

Windows: https://ftp.lsoft.com/LISTSERV/Windows/CONTRIB/saexit.zip

• Edit the script to configure, at a minimum, the address of your SpamAssassin server. You may also want to change the other parameters.
• Make any other changes that you deem appropriate.
• Save the script in LISTSERV’s main directory (on unix, set execute permissions):

Unix: ~listserv/home

Windows: C:\LISTSERV\MAIN

• You can call the script anything you want, but in this example we will assume that you have left the name unchanged (SAEXIT).
• Windows: if you have not registered .REXX as a path extension when installing it in step 2 or if you downloaded it from the L Soft ftp site instead of installing the full kit, you will need to create a script called saexit.cmd in the C:\LISTSERV\MAIN directory containing the following three lines:

@echo off
rexx saexit.rexx %*
exit %ERRORLEVEL%

Note:  For convenience, the saexit.cmd file is included in saexit.zip (see link above).

Step 4 of 4: Enable the saexit script.

To enable the script, add the following lines to LISTSERV’s configuration:

Unix:        SPAM_EXIT="saexit"
       export SPAM_EXIT

Windows: SPAM_EXIT=SAEXIT

Restart LISTSERV to make the change take effect, then mail a spam message to a test list to confirm that everything is working as it should.

Restrictions:

• The spam exit is a feature of LISTSERV Classic and HPO, and is not available with LISTSERV Lite. Current maintenance for LISTSERV is required.
• If you are using L-Soft’s Anti-Virus Station (AVS) to provide virus protection to a server for which F-Secure Anti-Virus is not available, the spam exit must be installed on the AVS server, not on the primary LISTSERV server. This is because message scanning is bypassed on a server that uses the AVS for this purpose.
• The spam exit is implemented within LISTSERV’s message scanner, which is informally known as the “virus scanner,” because this was its original purpose. If the message scanner is disabled, for instance by setting the ANTI_VIRUS configuration parameter to 0, or by failing to install the maintenance LAK, both virus scanning and spam scanning are disabled. If ANTI_VIRUS is unset, LISTSERV will enable the message scanner if either virus scanning or spam scanning is configured and available.

z/VM

The spam exit is also available on z/VM, but there is no version of spamc for this system. Since z/VM hosts normally use the AVS for message scanning, spam protection can be provided by simply installing the spam exit on the AVS server.

Advanced Configuration

At the list level, "Misc-Options= NO_SPAM_CHECK" can be used to disable spam scans for a particular list and its associated xxx-request address.

New statistical counters have been added for spam scans. They work just the same way as the virus counters.

The configuration parameter SPAM_MAXSIZE can be used to automatically accept messages larger than a certain size without wasting cycles scanning them. The rationale is that spam filters can take minutes to process very large messages, whereas spam messages are almost always very small. The following example sets the threshold to 512k:

z/VM:         SPAM_MAXSIZE = 512

unix:         SPAM_MAXSIZE=512
               export SPAM_MAXSIZE

Win:        SPAM_MAXSIZE=512

The default value is 256k. If set to 0, all messages will be scanned, which again could take considerable time. Messages that are not scanned do not count as a spam scan in the LISTSERV statistics.