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-filter and 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:-

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

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

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

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