MM-MX-CTRL(8)

📦 version 3.20, in alpine 3.24

💅 MM-MX-CTRL(8) — like, the manual page, but make it make sense

okay so first things first: this is the page for mm-mx-ctrl, and it lives in that "User Contributed Perl Documentation" corner of your man pages (yes, that corner 💀). It's a section 8 page, so you know it's the sysadmin-flavoured kind. Buckle up bestie, we're talking to a multiplexor.

✨ NAME ✨

mm-mx-ctrl — the tool that lets you control mailmunge-multiplexor. That's it. That's the whole vibe.

🌸 SYNOPSIS 🌸

mm-mx-ctrl [options] command

🦋 DESCRIPTION 🦋

mm-mx-ctrl is a command-line tool for communicating with mailmunge-multiplexor. That's literally the whole job. You say something, the multiplexor hears it. Iconic behaviour, no notes. 💅

🎀 OPTIONS 🎀

  • -h — shows you the usage info. the "help me help you" flag fr fr.
  • -s path — tells it where the mailmunge-multiplexor socket lives. If you don't say anything, it defaults to /var/spool/mailmunge/mailmunge-multiplexor.sock. default queen behaviour 👑
  • -i — this flag makes mm-mx-ctrl sit in a loop, reading commands on standard input and printing results to standard output. It's meant to be used by a monitoring program, like watch-multiple-mailmunges. very "I'm the subprocess now" of it.
  • -b — this flag makes mm-mx-ctrl print a less-than sign on a line by itself before its usual output, and a greater-than sign on a line by itself after the usual output. why? so programs that run mm-mx-ctrl -i as a subprocess can tell when the output from the most recent command has ended. little < and > breadcrumbs, we stan a boundary marker 🫶

🔥 COMMANDS 🔥

here's the menu, bestie. the following commands are available:

  • status — prints the status of all worker Perl processes in human-readable format. nice and chill, for your eyeballs.
  • rawstatus — prints the status of all worker Perl processes in a format easy to parse by computer. The result is a single line with six words on it. The words are separated by a single space character. let's break down what those six words are, because this is the main-character section:
    • Each character in the first word corresponds to a worker, and is I for an idle worker, B for a busy worker, S for a worker which is not running, and K for a worker which has been killed, but has not yet exited. A worker is "idle" if there is a running Perl process waiting to do work. "Busy" means the Perl process is currently filtering a message. S means there is no associated Perl process with the worker, but one can be started if the load warrants. Finally, K means the worker Perl process has been killed, but has yet to terminate. alphabet soup but make it diagnostics 🍓
    • The second word is the total number of messages processed since the multiplexor started up.
    • The third word is the total number of workers which have been activated since the multiplexor started up. (That is, it's a count of the number of times the multiplexor has forked and exec'd the Perl filter.)
    • The fourth word is the size of the queue for request queuing, and the fifth word is the actual number of requests in the queue.
    • The sixth word is the number of seconds elapsed since the multiplexor was started.
  • barstatus — prints the status of busy workers and queued requests in a nice "bar chart" format. This lets you keep an eye on things with a script like this:
while true ; do
    mm-mx-ctrl barstatus
    sleep 1
done

chart go brrr 📊

  • histo — prints a histogram showing the number of workers that were busy each time a request was processed. A single line is printed for the numbers from 1 up to the maximum number of workers. Each line contains the count of busy workers (1, 2, 3 up to MX_MAXIMUM), a space, and the number of times that many workers were busy when a request was processed. data girlie 💜
  • load — prints a table showing "load averages" for the last 10 seconds, 1 minute, 5 minutes and 10 minutes.

Each row in the table corresponds to a time interval, displayed in the first column. The remaining columns in the table are:

  • Msgs: — the number of messages scanned within the row's time interval.
  • Msgs/Sec: — the average number of messages scanned per second within the row's time interval.
  • Avg Busy Workers: — the average number of busy workers whenever a message was scanned. (If you are processing any mail at all, this number will be at least 1, because there is always 1 busy worker when a message is scanned.)

If you have the watch command on your system, you can keep an eye on the load with this command:

watch -n 10 mm-mx-ctrl load

If you do not have watch, the following shell script is a less fancy equivalent:

#!/bin/sh
while true; do
    clear
    date
    mm-mx-ctrl load
    sleep 10
done
  • rawload — prints the load averages in computer-readable format. The format consists of twenty-nine space-separated numbers, and here's the whole map:
    • The first four are integers representing the number of messages scanned in the last 10 seconds, 1 minute, 5 minutes and 10 minutes.
    • The second four are floating-point numbers representing the average number of busy workers in the last 10 seconds, 1 minute, 5 minutes and 10 minutes.
    • The third four are floating-point numbers representing the average time per scan in milliseconds over the last 10 seconds, 1 minute, 5 minutes and 10 minutes.
    • The fourth four are the number of worker activations (new workers started) over the last 10 seconds, 1 minute, 5 minutes and 10 minutes.
    • The fifth four are the number of workers reaped (workers that have exited) over the last 10 seconds, 1 minute, 5 minutes and 10 minutes.
    • The sixth four are the number of busy, idle, stopped and killed workers.
    • The seventh four are the number of messages processed, the number of worker activations, the size of the request queue, and the number of requests actually on the queue.
    • The final number is the number of seconds since the multiplexor was started.

29 numbers, no cap. 🔢

  • load-relayok — similar to load, but shows timings for filter_relay calls.
  • load-senderok — similar to load, but shows timings for filter_sender calls.
  • load-recipok — similar to load, but shows timings for filter_recipient calls.
  • rawload-relayok — similar to rawload, but shows timings for filter_relay calls. Note that the worker activation and reap statistics are present, but always 0. They are only valid in a rawload command.
  • rawload-senderok — similar to rawload, but shows timings for filter_sender calls. Note that the worker activation and reap statistics are present, but always 0. They are only valid in a rawload command.
  • rawload-recipok — similar to rawload, but shows timings for filter_recipient calls. Note that the worker activation and reap statistics are present, but always 0. They are only valid in a rawload command.
  • load1 nsecs — the load1 command displays the load for various commands over the last nsecs seconds, where nsecs is an integer from 10 to 600. The load1 command combines the output of load, load-relayok, load-senderokf and load-recipok into one display. (yes, load-senderokf — that f is right there in the page, we don't make the rules 🙈)

You might use the command like this:

watch -n 10 mm-mx-ctrl load1 60
  • rawload1 nsecs — returns the load1 data in human-readable format. The result is a line containing twenty-six space-separated numbers:
    • The first three numbers are the number of scans performed in the last nsecs seconds, the average number of busy workers when a scan was initiated and the average number of milliseconds per scan.
    • The second three are the same measurements for filter_relay calls.
    • The third three are the same measurements for filter_sender calls.
    • The fourth three are the same measurements for filter_relay calls. (that's what it says, bestie — filter_relay, again 🫠)
    • The thirteenth through sixteenth numbers are the number of busy, idle, stopped and killed workers, respectively.
    • The seventeenth number is the number of scans since mailmunge-multiplexor was started.
    • The eighteenth number is the number of times a new worker has been activated since program startup.
    • The nineteenth number is the size of the request queue and the twentieth number is the actual number of queued requests.
    • The twenty-first number is the time since program startup and the twenty-second number is a copy of nsecs for convenience.
    • The twenty-third through twenty-sixth numbers are the number of workers currently executing a scan, relayok, senderok and recipok command respectively.

26 numbers this time. still slaying the counting 😭

  • workers — displays a list of workers and their process IDs. Each line of output consists of a worker number, a status (I, B, K, or S), and for idle or busy workers, the process-ID of the worker. For busy workers, the line may contain additional information about what the worker is doing. nosy but useful 💅
  • busyworkers — similar to workers, but only outputs a line for each busy worker. we love a filtered list.
  • workerinfo n — displays information about worker number n. pick your fave.
  • reread — forces mailmunge-multiplexor to kill all idle workers, and terminate and restart busy workers when they become idle. This forces a reread of filter rules. glow-up for your ruleset ✨
  • reload — a synonym for reread. same energy, different spelling.
  • msgs — prints the total number of messages scanned since the multiplexor started.

🌈 ADDITIONAL COMMANDS 🌈

plot twist: you can supply any other command and arguments to mm-mx-ctrl. It percent-encodes each command-line argument, glues the encoded arguments together with a single space between each, and sends the result to the multiplexor as a command. This allows you to send arbitrary commands to your Perl workers. See unknown_command in Mailmunge::Filter for additional details. go off, custom command bestie 🫶

👑 PERMISSIONS 👑

mm-mx-ctrl uses the multiplexor's socket; therefore, it probably needs to be run as root or the same user as mailmunge-multiplexor. so like… check your user before you start drama with a permission error 💀

💖 SEE ALSO 💖

  • mailmunge-multiplexor
  • mailmunge-protocol
  • watch-multiple-mailmunges

go read those next, iykyk 🦋

🌸 AUTHOR 🌸

mm-mx-ctrl was written by Dianne Skoll <dianne@skollsoft.com>. legend behaviour, fr fr 👑

🎀 LICENSE 🎀

This code is licensed under the terms of the GNU General Public License, version 2. copy that, don't come for me 🫶

ok that's the whole page, bestie. this was MM-MX-CTRL(8) from the User Contributed Perl Documentation section — page generated under perl v5.42.2, dated 2025-10-05. now go talk to your multiplexor, she's waiting 💅✨
📦 where this page comes from