Ray's Mail Filter - Operation

Ray's Mail Filter - Operation Version 1.04/1.14
On this page:- Starting the Filter Re-reading the Configuration Files Stopping the Filter	Other pages:- Home Page Installation Configuration Utilities

The mail filter should be started before Sendmail is started, and stopped after Sendmail is stopped. The filter can be stopped and re-started while Sendmail is running, but Sendmail will either reject or temporarily fail (depending on the entry in sendmail.cf) all messages it receives while the filter is not available.

The mail filter does not have to be run by the root user, but the user who runs the filter must have sufficient rights to the relevant files in/usr/local/bin, /usr/local/etc/mail-filterand the filter's working directory. See the Installation page for details. (See also the remarks about sockets in the table of known bugs.)

A set of shell scripts are provided, which provide a convenient set of commands for stopping and starting the filter, and making a running filter re-read its configuration files. (Alternative ways of performing these actions are described in the notes at the end of this page.) If the /usr/local/bin directory is not included in the user's PATH, then /usr/local/bin/ must be prefixed to the following commands.

Starting the Filter

To start the filter, type the command:

% mail-filter start

This runs the mf-start script with the appropriate command-line arguments. The mf-start script checks for the existence of an old socket file (left over from a previous crash or re-boot) and deletes it if found. The script then runs the rays-filter binary (note 1).

If rays-filter crashes, mf-start will re-start it after a few seconds. If rays-filter crashes more than 10 times, after running for less than 30 seconds each time, mf-start will exit. mf-start records all its actions in mail-filter.log, e.g.:

29-Jun-2000 11:19:46 : Starting rays-filter; FAIL_COUNT = 0

The following messages should appear in the system log file:

rays-filter[999]: Program starting
rays-filter[999]: Read 3 header names from /usr/local/src/mail-filters/header_list.conf
rays-filter[999]: Read 48 strings from /usr/local/src/mail-filters/string_list.conf

The Unix ps command can also be used to verify that the two processes, mf-start and rays-filter, are running:

% ps -ef | grep mf-start % ps -ef | grep rays-filter

Re-reading the Configuration Files

If the configuration files are changed while the filter is running, the filter must be instructed to re-read the files for the changes to take effect. To do this, type the following command:

% mail-filter reset

This runs the mf-reset script with the appropriate command-line argument, which determines the filter's process ID and sends it a USR1 signal (note 2). It also makes an entry in mail-filter.log as follows:

03-Jul-2000 12:35:45 : Signalling rays-filter to read configuration files

The following messages should appear in the system log file:

rays-filter[999]: Received SIGUSR1; reading configuration files 
rays-filter[999]: Read 3 header names from /usr/local/src/mail-filters/header_list.conf
rays-filter[999]: Read 48 strings from /usr/local/src/mail-filters/string_list.conf

Stopping the Filter

To stop the filter, type the command:

% mail-filter stop

This runs the mf-stop script with the appropriate command-line arguments (note 3). This in turn carries out the following:-

Shuts down mf-start to stop it from re-startingrays-filter
Shuts down rays-filter. The script works on the basis that if there are any msg.* files in the rejects directory, then message processing is in progress. It therefore checks that directory once a second for up to 15 seconds, waiting for all such files to disappear before killing the filter process. If successful, a line will be written to mail-filter.log as follows:
29-Jun-2000 11:31:49 : Stopping rays-filter; WAIT = 6
If there are still any msg.* files in existence after 15 seconds, the script kills the filter process anyway, and any messages in progress are "dropped". This will be shown in the log file as:
29-Jun-2000 15:51:05 : Stopping rays-filter; WAIT = 15, messages dropped
If a file ("unix" or "local") socket has been used, the file is deleted.

The Unix ps command can be used to verify that the two processes, mf-start and rays-filter, have stopped:

% ps -ef | grep mf-start % ps -ef | grep rays-filter

Notes

```
mail-filter start
runs mf-start rays-filter socket
which runs rays-filter -p socket -d work_dir
```
If you try to run mf-start directly, it will politely refuse. If you can't or don't want to use the mail-filter script, then first check for the existence of a previously-used socket file and, if it exists, delete it:
```
% rm -f socket-file
```
Then run the binary directly using the -p switch to specify the socket and -d to specify the working directory:
```
rays-filter -p socket -d work_dir
```
```
mail-filter reset
runs mf-reset rays-filter
```
If you try to run mf-reset directly, it will politely refuse. If you can't or don't want to use the mail-filter script, the filter process id may be obtained by inspecting the output of a command such as
```
% ps -ef | grep rays-filter
```
The filter can then be made to re-read its configuration files by sending it a "USR1" signal:
```
% kill -USR1 process_id
```
Re-configuring the filter by this last method will not be recorded in mail-filter.log.
```
mail-filter stop
runs mf-stop rays-filter socket
```
If you try to run mf-stop directly, it will politely refuse. If you can't or don't want to use the mail-filter script, then obtain the process id's of the mf-start and rays-filter processes by inspecting the output from
```
% ps -ef | grep mf-start
% ps -ef | grep rays-filter
```
Then send a "KILL" signal to each process, starting with mf-start, followed by the rays-filter process(es).
```
% kill -KILL process_id
```
Finally, if a file socket has been used, delete the file.
```
% rm -f socket-file
```

Ray's Mail Filter Home Page
Installing the Filter
Filter Configuration
Utilities

butlerra@sbu.ac.uk

08 March 2001