MIMEDEFANG-NOTIFY(7)

💖 NAME 💖

okay so bestie, mimedefang-notify — it's literally the conventions that mimedefang-multiplexor(8) uses to tell an external program that stuff changed. state changes, notification vibes, the whole thing. 🦋

🌸 DESCRIPTION 🌸

so here's the tea. if you hand the -O option to mimedefang-multiplexor, it will let external programs connect to a socket and get pinged whenever certain state changes happen inside the multiplexor. ✨

and those external programs? they can react however they want. no rules, main character energy. the external program that sits there listening for state changes is called a listener. periodt.

🎀 NOTIFICATION OVERVIEW 🎀

from the listener's point of view, the whole thing goes like this:

1. the listener connects to a TCP or UNIX-domain socket. 🔌
2. the listener tells mimedefang-multiplexor which message types it's interested in. 👀
3. the listener loops forever, reading messages off the socket and reacting to them. 🔁

💅 MESSAGES 💅

each message from the multiplexor is normally just one uppercase letter, maybe followed by a space and some arguments, then a newline. simple. clean. iconic.

two special messages exist, and they're giving very much "system announcement":

• *OK followed by a newline — this one shows up when a listener first connects. 🫶
• *ERR followed by some text and a newline — this one shows up when an error happens. 😭

and now the normal messages, bestie:

• B — issued whenever a worker gets killed because of a busy timeout. 💀
• F n — issued whenever the number of free workers changes. the parameter n is the number of free workers. 🧮
• R — issued whenever someone has forced a filter reread. 🔄
• S n nmsg — issued whenever worker n's status tag changes. the status tag is a string saying what the worker is currently doing; the -Z option to the multiplexor lets the Perl code update the status tag, so you get a good idea what each worker is up to. 👑
• U — issued whenever a worker has died unexpectedly. 🙈
• Y — issued whenever the number of free workers changes from zero to non-zero. 📈
• Z — issued whenever the number of free workers falls to zero. 📉

🦋 EXPRESSING INTEREST 🦋

okay important: a listener gets zero messages until it has expressed interest in the message types it wants. no interest, no gossip. 💬

to express interest, the listener sends a question mark (?) followed by the types of messages it's interested in, followed by a newline, over the socket.

so for example, a listener that's into the R and F messages would send this line:

?RF

and a listener that wants every possible message type should send:

?*

once a listener has expressed interest, it may receive messages at literally any time, so it should be monitoring the socket for messages. 👀✨

ngl this part matters: a listener always receives the special messages *OK and *ERR, even if it never expressed interest in them. no opting out, bestie. 💖

⭐ 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 you 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_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();

🌈 SEE ALSO 🌈

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

and that's the whole page, bestie!! 💖 this one's from the 4th Berkeley Distribution, dated 8 February 2005 — vintage but still slaying, no cap. go forth and listen to your sockets. 🎀✨