QSHAPE(1)

✨ NAME ✨

qshape — the little tool that prints out your Postfix queue's domain and age distribution 💖 like a glow-up report card for your mail spool.

🌸 SYNOPSIS 🌸

qshape [-s] [-p] [-m min_subdomains]
        [-b bucket_count] [-t bucket_time]
        [-l] [-w terminal_width]
        [-N batch_msg_count] [-n batch_top_domains]
        [-c config_directory] [queue_name ...]

💖 DESCRIPTION 💖

Okay bestie, so qshape is the program that helps an administrator actually understand the Postfix queue — like, what messages are sitting there, how old they are, and which sender domain or recipient domain they belong to. It breaks the whole thing down by time and by domain, which is genuinely so useful it's not even funny.

Here's the catch though, and it's a real one: the program needs read access to the queue directories and the queue files. So it has to run as the superuser or as the mail_owner specified in main.cf (which is typically postfix). No sneaking around that, sorry babe. 🙈

🎀 Options

• -s — show the sender domain distribution instead of the recipient domain distribution. By default you get the recipient distribution. Lowkey important nuance: there can be more recipients than messages, but since every message has exactly one sender, the sender distribution is a message distribution. Slay. 💅
• -p — generate aggregate statistics for parent domains. Top level domains are not shown, and neither are domains with fewer than min_subdomains subdomains. Parent domain names show up with a leading dot, like .example.com. Cute, right?
• -m min_subdomains — when you use it with the -p option, this sets the minimum subdomain count needed to show a separate line for a parent domain. The default is 5.
• -b bucket_count — the age distribution gets chopped up into a sequence of geometrically increasing intervals. This option sets the number of intervals, aka "buckets". Each bucket has a maximum queue age that is twice as large as the previous bucket's. And the last bucket? No age limit at all. Main character energy, honestly. 👑
• -t bucket_time — the age limit, in minutes, for the first time bucket. Default is 5, meaning the first bucket counts messages between 0 and 5 minutes old.
• -l — instead of a geometric age sequence, use a linear age sequence. In other words: simple multiples of bucket_time.

This feature is available in Postfix 2.2 and later. ✨

• -w terminal_width — the output is right justified, with the counts for the last bucket shown on the 80th column. You can adjust terminal_width for wider screens, which lets more buckets display without truncating the domain names on the left. Now here's the tea: when a row for a full domain name and its counters doesn't fit in the specified number of columns, only the last 17 bytes of the domain name are shown, with the prefix replaced by a '+' character. Truncated parent domain rows show as '.+' followed by the last 16 bytes of the domain name. And if it's still too narrow to show the domain name and all the counters? Then the terminal_width limit gets violated. It just does. 💀
• -N batch_msg_count — when the output device is a terminal, intermediate results get shown every "batch_msg_count" messages. This gives you usable results in a reasonable time even when the deferred queue is enormous (which, bestie, it sometimes is 😭). The default is to show intermediate results every 1000 messages.
• -n batch_top_domains — when reporting intermediate or final results to a terminal, report only the top "batch_top_domains" domains. The default limit is 20 domains.
• -c config_directory — the main.cf configuration file lives in the named directory instead of the default configuration directory.

🎀 Arguments

• queue_name — by default qshape displays the combined distribution of the incoming and active queues. Wanna look at a different set of queues? Just list their directory names on the command line. Absolute paths are used as is; other paths are taken relative to the main.cf queue_directory parameter setting. And here's the ✨ gotcha ✨: while main.cf supports the use of $variable expansion in the definition of the queue_directory parameter, the qshape program does not. So if you must use variable expansions in the queue_directory setting, you have to specify an explicit absolute path for each queue subdirectory — even if all you want is the default incoming and active queue distribution. No shortcuts, fr fr.

🦋 SEE ALSO 🦋

• mailq(1) — List all messages in the queue.
• QSHAPE_README — Examples and background material.

🌈 FILES 🌈

• $config_directory/main.cf — Postfix installation parameters.
• $queue_directory/maildrop/ — local submission directory.
• $queue_directory/incoming/ — new message queue.
• $queue_directory/hold/ — messages waiting for tech support.
• $queue_directory/active/ — messages scheduled for delivery.
• $queue_directory/deferred/ — messages postponed for later delivery.

👑 LICENSE 👑

The Secure Mailer license must be distributed with this software. Periodt. 🫶

💜 AUTHOR(S) 💜

• Victor Duchovni
• Morgan Stanley

and that's the whole page, bestie!! this was QSHAPE(1) from the General Commands Manual — go forth, read your queue, and understand it. iykyk 🎀💖✨