mimedefang-notify(7)

1MIMEDEFANG-NOTIFY(7)   Miscellaneous Information Manual   MIMEDEFANG-NOTIFY(7)
2
3
4

NAME

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

DESCRIPTION

11       If you supply the -O option to mimedefang-multiplexor, then  it  allows
12       external  programs  to  connect  to a socket and be notified of certain
13       state changes in the multiplexor.  The external programs can  react  in
14       whatever  way they choose to these state changes.  The external program
15       that listens for state changes is referred to as a listener.
16
17

NOTIFICATION OVERVIEW

19       From the point of view of a listener, notification works like this:
20
21       1) The listener connects to a TCP or UNIX-domain socket.
22
23       2) The listener informs mimedefang-multiplexor of the message types  it
24       is interested in.
25
26       3) The listener loops, reading messages from the socket and reacting to
27       them.
28
29

MESSAGES

31       Each message from the multiplexor normally consists of a single  upper-
32       case  letter, possibly followed by a space and some arguments, and then
33       followed by a newline.
34
35       Two special messages are "*OK" followed by a newline, which  is  issued
36       when  a listener first connects, and "*ERR" followed by some text and a
37       newline, which is issued when an error occurs.
38
39       The normal messages are:
40
41
42       B      This message is issued whenever a worker is killed because of  a
43              busy timeout.
44
45
46       F n    This  message  is  issued  whenever  the  number of free workers
47              changes.  The parameter n is the number of free workers.
48
49
50       R      This message is issued whenever  someone  has  forced  a  filter
51              reread.
52
53
54       S n nmsg
55              This  message  is issued whenever worker n's status tag changes.
56              The status tag is a string indicating what the  worker  is  cur‐
57              rently  doing;  the -Z option to the multiplexor allows the Perl
58              code to update the status tag so you have a good idea what  each
59              worker is doing.
60
61
62       U      This message is issued whenever a worker has died unexpectedly.
63
64
65       Y      This  message  is  issued  whenever  the  number of free workers
66              changes from zero to non-zero.
67
68
69       Z      This message is issued whenever the number of free workers falls
70              to zero.
71
72

EXPRESSING INTEREST

74       A  listener does not receive any messages until it has expressed inter‐
75       est in various message types.  To express interest, the listener should
76       send  a  question  mark  ("?")  followed by the types of messages it is
77       interested in, followed by a newline over the socket.  For  example,  a
78       listener interested in the R and F messages would send this line:
79
80            ?RF
81
82       A listener interested in every possible message type should send:
83
84            ?*
85
86       Once  a listener has expressed interest, it may receive messages at any
87       time, and should monitor the socket for messages.
88
89       Note that a listener always receives the  special  messages  "*OK"  and
90       "*ERR", even if it has not expressed interest in them.
91
92

EXAMPLE

94       The following Perl script implements a listener that, on Linux, rejects
95       new SMTP connections if all workers are busy, and  accepts  them  again
96       once  a  worker  is free.  Existing SMTP connections are not shut down;
97       the system merely refuses new connections if all the workers are busy.
98
99       This script assumes that you have  used  the  -O  inet:4567  option  to
100       mimedefang-multiplexor.
101
102       #!/usr/bin/perl -w
103       #
104       # On Linux, prepare to use this script like this:
105       #     /sbin/iptables -N smtp_connect
106       #     /sbin/iptables -A INPUT --proto tcp --dport 25 --syn -j smtp_connect
107       # Then run the script as root.
108
109       use IO::Socket::INET;
110
111       sub no_free_workers {
112           print STDERR "No free workers!\n";
113           system("/sbin/iptables -A smtp_connect -j REJECT");
114       }
115
116       sub some_free_workers {
117           print STDERR "Some free workers.\n";
118           system("/sbin/iptables -F smtp_connect");
119       }
120
121       sub main {
122           my $sock;
123
124           $sock = IO::Socket::INET->new(PeerAddr => '127.0.0.1',
125                                         PeerPort => '4567',
126                                         Proto => 'tcp');
127           # We are only interested in Y and Z messages
128           print $sock "?YZ\n";
129           $sock->flush();
130           while(<$sock>) {
131               if (/^Z/) {
132                   no_free_workers();
133               }
134               if (/^Y/) {
135                   some_free_workers();
136               }
137           }
138
139           # EOF from multiplexor?? Better undo firewalling
140           system("/sbin/iptables -F smtp_connect");
141       }
142
143       main();
144
145

NAME

DESCRIPTION

NOTIFICATION OVERVIEW

MESSAGES

EXPRESSING INTEREST

EXAMPLE

SEE ALSO