mimedefang-notify.7.in

.\" $Id$
.\""
.TH MIMEDEFANG-NOTIFY 7 "8 February 2005"
.UC 4
.SH NAME
mimedefang-notify \- Conventions used by \fBmimedefang-multiplexor\fR(8) to
notify an external program of state changes.

.SH DESCRIPTION
If you supply the \fB\-O\fR option to \fBmimedefang-multiplexor\fR, then
it allows external programs to connect to a socket and be notified
of certain state changes in the multiplexor.  The external programs
can react in whatever way they choose to these state changes.
The external program that listens for state changes is referred to
as a \fIlistener\fR.

.SH NOTIFICATION OVERVIEW
From the point of view of a listener, notification works like this:

1) The listener connects to a TCP or UNIX-domain socket.

2) The listener informs \fBmimedefang-multiplexor\fR of the
\fImessage types\fR it is interested in.

3) The listener loops, reading messages from the socket and reacting to
them.

.SH MESSAGES
Each message from the multiplexor normally consists of a single
upper-case letter, possibly followed by a space and some arguments, and then
followed by a newline.

Two special messages are "*OK" followed by a newline, which is issued when
a listener first connects, and "*ERR" followed by some text and a newline,
which is issued when an error occurs.

The normal messages are:

.TP
\fBB\fR
This message is issued whenever a worker is killed because of a busy
timeout.

.TP
\fBF\fR \fIn\fR
This message is issued whenever the number of free workers changes.
The parameter \fIn\fR is the number of free workers.

.TP
\fBR\fR
This message is issued whenever someone has forced a filter reread.

.TP
\fBS\fR \fIn\fR \fInmsg\fR
This message is issued whenever worker \fIn\fR's status tag
changes.  The status tag is a string indicating what the worker
is currently doing; the \fB\-Z\fR option to the multiplexor
allows the Perl code to update the status tag so you have a good
idea what each worker is doing.

.TP
\fBU\fR
This message is issued whenever a worker has died unexpectedly.

.TP
\fBY\fR
This message is issued whenever the number of free workers changes from
zero to non-zero.

.TP
\fBZ\fR
This message is issued whenever the number of free workers falls to zero.

.SH EXPRESSING INTEREST
A listener does not receive any messages until it has \fIexpressed interest\fR
in various message types.  To express interest, the listener should send
a question mark ("?") followed by the types of messages it is interested in,
followed by a newline over the socket.  For example, a listener interested
in the R and F messages would send this line:

	?RF

A listener interested in every possible message type should send:

	?*

Once a listener has expressed interest, it may receive messages at
any time, and should monitor the socket for messages.

Note that a listener \fIalways\fR receives the special messages
"*OK" and "*ERR", even if it has not expressed interest in them.

.SH EXAMPLE

The following Perl script implements a listener that, on Linux,
rejects new SMTP connections if all workers are busy, and accepts them
again once a worker is free.  Existing SMTP connections are not shut down;
the system merely refuses new connections if all the workers are busy.

This script assumes that you have used the \fB\-O inet:4567\fR option
to \fBmimedefang-multiplexor\fR.

.nf
#!/usr/bin/perl -w
#
# On Linux, prepare to use this script like this:
#     /sbin/iptables -N smtp_connect
#     /sbin/iptables -A INPUT --proto tcp --dport 25 --syn -j smtp_connect
# Then run the script as root.

use IO::Socket::INET;

sub no_free_workers {
    print STDERR "No free workers!\\n";
    system("/sbin/iptables -A smtp_connect -j REJECT");
}

sub some_free_workers {
    print STDERR "Some free workers.\\n";
    system("/sbin/iptables -F smtp_connect");
}

sub main {
    my $sock;

    $sock = IO::Socket::INET->new(PeerAddr => '127.0.0.1',
                                  PeerPort => '4567',
                                  Proto => 'tcp');
    # We are only interested in Y and Z messages
    print $sock "?YZ\\n";
    $sock->flush();
    while(<$sock>) {
        if (/^Z/) {
            no_free_workers();
        }
        if (/^Y/) {
            some_free_workers();
        }
    }

    # EOF from multiplexor?? Better undo firewalling
    system("/sbin/iptables -F smtp_connect");
}

main();
.fi

.SH SEE ALSO
mimedefang.pl(8), mimedefang(8), mimedefang-multiplexor(8), mimedefang-filter(5)