Provided by: mimedefang_2.71-2build1_i386 bug

NAME

       mimedefang-notify  -  Conventions  used by mimedefang-multiplexor(8) to
       notify an external program of state changes.

DESCRIPTION

       If you supply the -O option to mimedefang-multiplexor, 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 listener.

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 mimedefang-multiplexor of the message types  it
       is interested in.

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

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:

       B      This message is issued whenever a slave is killed because  of  a
              busy timeout.

       F n    This  message  is  issued  whenever  the  number  of free slaves
              changes.  The parameter n is the number of free slaves.

       R      This message is issued whenever  someone  has  forced  a  filter
              reread.

       S n nmsg
              This  message  is  issued whenever slave n's status tag changes.
              The status  tag  is  a  string  indicating  what  the  slave  is
              currently  doing;  the  -Z  option to the multiplexor allows the
              Perl code to update the status tag so you have a good idea  what
              each slave is doing.

       U      This message is issued whenever a slave has died unexpectedly.

       Y      This  message  is  issued  whenever  the  number  of free slaves
              changes from zero to non-zero.

       Z      This message is issued whenever the number of free slaves  falls
              to zero.

EXPRESSING INTEREST

       A  listener  does  not  receive  any  messages  until  it has expressed
       interest 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 always receives the  special  messages  "*OK"  and
       "*ERR", even if it has not expressed interest in them.

EXAMPLE

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

       This script assumes that you have  used  the  -O  inet:4567  option  to
       mimedefang-multiplexor.

       #!/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_slaves {
           print STDERR "No free slaves!\n";
           system("/sbin/iptables -A smtp_connect -j REJECT");
       }

       sub some_free_slaves {
           print STDERR "Some free slaves.\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_slaves();
               }
               if (/^Y/) {
                   some_free_slaves();
               }
           }

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

       main();

SEE ALSO

       mimedefang.pl(8), mimedefang(8), mimedefang-multiplexor(8), mimedefang-
       filter(5)