xenial (7) mimedefang-notify.7.gz

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)