OQMGR(8postfix)

📦 version 3.8.6, in debian bookworm, ubuntu jammy, ubuntu noble

✨ OQMGR — old Postfix queue manager ✨

okay bestie, welcome to the oqmgr(8postfix) page 💖 this is the manual for the old Postfix queue manager, and yes we're reading the whole thing together, no skimming, no cap.

🎀 NAME 🎀

oqmgr — old Postfix queue manager 🦋

🌸 SYNOPSIS 🌸

oqmgr [generic Postfix daemon options]

💅 DESCRIPTION 💅

so the oqmgr(8) daemon just… sits there, patiently, waiting for incoming mail to show up 🌸 and then it arranges for that mail to actually get delivered via Postfix delivery processes. the actual mail routing strategy? not its problem, it's delegated to the trivial-rewrite(8) daemon. and this program expects to be run from the master(8) process manager, periodt.

mail that's addressed to the local double-bounce address gets logged and then discarded 🗑️ — and honestly that's iconic of it, because it stops potential loops caused by undeliverable bounce notifications. no infinite bounce spirals here, we don't do that 💀

👑 MAIL QUEUES 👑

the oqmgr(8) daemon maintains these queues, and they each have a whole personality:

  • incoming — inbound mail from the network, or mail picked up by the local pickup(8) agent from the maildrop directory 📥
  • active — messages that the queue manager has opened for delivery. only a limited number of messages is allowed to enter the active queue (leaky bucket strategy, for a fixed delivery rate) 🔥
  • deferred — mail that could not be delivered upon the first attempt. the queue manager implements exponential backoff by doubling the time between delivery attempts 😭
  • corrupt — unreadable or damaged queue files get moved here for inspection. it's giving evidence locker 🙈
  • hold — messages that are kept "on hold" are kept here until someone sets them free 🫶

💖 DELIVERY STATUS REPORTS 💖

the oqmgr(8) daemon keeps an eye on per-message delivery status reports in these directories. each status report file has the same name</> as the corresponding message file:

  • bounce — per-recipient status information about why mail is bounced. these files are maintained by the bounce(8) daemon 💅
  • defer — per-recipient status information about why mail is delayed. these files are maintained by the defer(8) daemon ⏳
  • trace — per-recipient status information as requested with the Postfix "sendmail -v" or "sendmail -bv" command. these files are maintained by the trace(8) daemon 🔍

and the oqmgr(8) daemon is the one responsible for asking the bounce(8), defer(8) or trace(8) daemons to send delivery reports. it's the group chat admin of delivery receipts fr fr 📬

🌈 STRATEGIES 🌈

the queue manager implements a variety of strategies for either opening queue files (input) or for message delivery (output). yes, it has range:

  • leaky bucket — this strategy limits the number of messages in the active queue and prevents the queue manager from running out of memory under heavy load 🪣
  • fairness — when the active queue has room, the queue manager takes one message from the incoming queue and one from the deferred queue. this prevents a large mail backlog from blocking the delivery of new mail ⚖️
  • slow start — this strategy eliminates "thundering herd" problems by slowly adjusting the number of parallel deliveries to the same destination 🐢
  • round robin — the queue manager sorts delivery requests by destination. round-robin selection prevents one destination from dominating deliveries to other destinations 🔄
  • exponential backoff — mail that cannot be delivered upon the first attempt is deferred. the time interval between delivery attempts is doubled after each attempt 📈
  • destination status cache — the queue manager avoids unnecessary delivery attempts by maintaining a short-term, in-memory list of unreachable destinations 🧠

⚡ TRIGGERS ⚡

on an idle system, the queue manager waits for the arrival of trigger events, or it waits for a timer to go off ⏰ a trigger is a one-byte message. depending on the message received, the queue manager performs one of the following actions (the message is followed by the symbolic constant used internally by the software):

  • D (QMGR_REQ_SCAN_DEFERRED) — start a deferred queue scan. if a deferred queue scan is already in progress, that scan will be restarted as soon as it finishes 🔁
  • I (QMGR_REQ_SCAN_INCOMING) — start an incoming queue scan. if an incoming queue scan is already in progress, that scan will be restarted as soon as it finishes 📨
  • A (QMGR_REQ_SCAN_ALL) — ignore deferred queue file time stamps. the request affects the next deferred queue scan 🕰️
  • F (QMGR_REQ_FLUSH_DEAD) — purge all information about dead transports and destinations 💀
  • W (TRIGGER_REQ_WAKEUP) — wakeup call, this is used by the master server to instantiate servers that should not go away forever. the action is to start an incoming queue scan ☀️

the oqmgr(8) daemon reads an entire buffer worth of triggers. multiple identical trigger requests are collapsed into one, and trigger requests are sorted so that A and F precede D and I. so, in order to force a deferred queue run, one would request A F D; in order to notify the queue manager of the arrival of new mail one would request I. iykyk 💅

📜 STANDARDS 📜

🔒 SECURITY 🔒

the oqmgr(8) daemon is not security sensitive 🫶 it reads single-character messages from untrusted local users, and thus may be susceptible to denial of service attacks 😭 but listen — the oqmgr(8) daemon does not talk to the outside world, and it can be run at fixed low privilege in a chrooted environment. cozy, contained, protected 🧚

🩺 DIAGNOSTICS 🩺

problems and transactions are logged to the syslogd(8) or postlogd(8) daemon 📝 corrupted message files are saved to the corrupt</> queue for further inspection 🔍

depending on the setting of the notify_classes parameter, the postmaster is notified of bounces and of other trouble 📣

🐛 BUGS 🐛

a single queue manager process has to compete for disk access with multiple front-end processes such as cleanup(8). a sudden burst of inbound mail can negatively impact outbound delivery rates 😭 it's giving one person doing the whole group project, no cap.

⚙️ CONFIGURATION PARAMETERS ⚙️

changes to main.cf are not picked up automatically, as oqmgr(8) is a persistent process. use the command "postfix reload" after a configuration change 🔁

the text below provides only a parameter summary. see postconf(5) for more details including examples 📖

in the text below, transport is the first field in a master.cf entry.

🎀 COMPATIBILITY CONTROLS 🎀

available before Postfix version 2.5:

  • allow_min_user (no) — allow a sender or recipient address to have - as the first character.

available with Postfix version 2.7 and later:

  • default_filter_nexthop (empty) — when a content_filter or FILTER request specifies no explicit next-hop destination, use $default_filter_nexthop instead; when that value is empty, use the domain in the recipient address.

💅 ACTIVE QUEUE CONTROLS 💅

  • qmgr_clog_warn_time (300s) — the minimal delay between warnings that a specific destination is clogging up the Postfix active queue 🚧
  • qmgr_message_active_limit (20000) — the maximal number of messages in the active queue 📦
  • qmgr_message_recipient_limit (20000) — the maximal number of recipients held in memory by the Postfix queue manager, and the maximal size of the short-term, in-memory "dead" destination status cache 💀

🔥 DELIVERY CONCURRENCY CONTROLS 🔥

  • qmgr_fudge_factor (100) — obsolete feature: the percentage of delivery resources that a busy mail system will use up for delivery of a large mailing list message 🫠
  • initial_destination_concurrency (5) — the initial per-destination concurrency level for parallel delivery to the same destination 🚀
  • default_destination_concurrency_limit (20) — the default maximal number of parallel deliveries to the same destination 🏁
  • transport_destination_concurrency_limit ($default_destination_concurrency_limit) — a transport-specific override for the default_destination_concurrency_limit parameter value, where transport is the master.cf name of the message delivery transport.

available in Postfix version 2.5 and later:

  • transport_initial_destination_concurrency ($initial_destination_concurrency) — a transport-specific override for the initial_destination_concurrency parameter value, where transport is the master.cf name of the message delivery transport.
  • default_destination_concurrency_failed_cohort_limit (1) — how many pseudo-cohorts must suffer connection or handshake failure before a specific destination is considered unavailable (and further delivery is suspended) 🚫
  • transport_destination_concurrency_failed_cohort_limit ($default_destination_concurrency_failed_cohort_limit) — a transport-specific override for the default_destination_concurrency_failed_cohort_limit parameter value, where transport is the master.cf name of the message delivery transport.
  • default_destination_concurrency_negative_feedback (1) — the per-destination amount of delivery concurrency negative feedback, after a delivery completes with a connection or handshake failure 📉
  • transport_destination_concurrency_negative_feedback ($default_destination_concurrency_negative_feedback) — a transport-specific override for the default_destination_concurrency_negative_feedback parameter value, where transport is the master.cf name of the message delivery transport.
  • default_destination_concurrency_positive_feedback (1) — the per-destination amount of delivery concurrency positive feedback, after a delivery completes without connection or handshake failure 📈
  • transport_destination_concurrency_positive_feedback ($default_destination_concurrency_positive_feedback) — a transport-specific override for the default_destination_concurrency_positive_feedback parameter value, where transport is the master.cf name of the message delivery transport.
  • destination_concurrency_feedback_debug (no) — make the queue manager's feedback algorithm verbose for performance analysis purposes 🔬

🌸 RECIPIENT SCHEDULING CONTROLS 🌸

  • default_destination_recipient_limit (50) — the default maximal number of recipients per message delivery 👥
  • transport_destination_recipient_limit ($default_destination_recipient_limit) — a transport-specific override for the default_destination_recipient_limit parameter value, where transport is the master.cf name of the message delivery transport.

to be continued bestie… part 2 is loading ✨

🦋 OTHER RESOURCE AND RATE CONTROLS 🦋

okay bestie, these are the knobs that control how often and how fast the queue manager pokes at stuff. no cap, they matter. 💅

  • minimal_backoff_time (300s) — the smallest amount of time between attempts to deliver a deferred message. fun fact: before Postfix 2.4, the default was 1000s. glow-up era.
  • maximal_backoff_time (4000s) — the biggest amount of time between attempts to deliver a deferred message. like, after this it stops growing. periodt.
  • maximal_queue_lifetime (5d) — if delivery fails with a temporary error, and the message has been in the queue for this long, it's considered undeliverable. bye bestie. 💀
  • queue_run_delay (300s) — how long between deferred queue scans by the queue manager. another glow-up: before Postfix 2.4, this default was 1000s.
  • transport_retry_time (60s) — how long the Postfix queue manager waits between attempts to contact a malfunctioning message delivery transport. like it's checking if the transport got its life together. 😭

Available in Postfix version 2.1 and later: ✨

  • bounce_queue_lifetime (5d) — if delivery fails with a temporary error, and a bounce message has been in the queue for this long, it's considered undeliverable. yes, bounces can bounce. 💀

Available in Postfix version 2.5 and later: ✨

  • default_destination_rate_delay (0s) — the default delay inserted between individual message deliveries to the same destination and over the same message delivery transport. it's giving throttle but make it default. 🫶
  • transport_destination_rate_delay ($default_destination_rate_delay) — a transport-specific override for the default_destination_rate_delay value. here, transport is the master.cf name of the message delivery transport. iykyk.

Available in Postfix version 3.1 and later: ✨

  • default_transport_rate_delay (0s) — the default delay inserted between individual message deliveries over the same message delivery transport, regardless of destination. no destination discrimination, just vibes. 💅
  • transport_transport_rate_delay ($default_transport_rate_delay) — a transport-specific override for the default_transport_rate_delay value. the initial transport in the parameter name is the master.cf name of the message delivery transport. yes, the name says transport twice. iconic. 👑

🛡️ SAFETY CONTROLS 🛡️

  • qmgr_daemon_timeout (1000s) — how much time a Postfix queue manager process may take to handle a request before a built-in watchdog timer terminates it. the watchdog said times up bestie. ⏰
  • qmgr_ipc_timeout (60s) — the time limit for the queue manager to send or receive information over an internal communication channel. don't leave it on read. 💀

Available in Postfix version 3.1 and later: ✨

  • address_verify_pending_request_limit (see postconf -d output) — a safety limit that prevents address verification requests from overwhelming the Postfix queue. protective queen behavior. 🫶

🎀 MISCELLANEOUS CONTROLS 🎀

  • config_directory (see postconf -d output) — the default location of the Postfix main.cf and master.cf configuration files. where the receipts live. 📁
  • defer_transports (empty) — the names of message delivery transports that should not deliver mail unless someone issues sendmail -q or equivalent. not me putting the mail on do not disturb. 🙈
  • delay_logging_resolution_limit (2) — the maximal number of digits after the decimal point when logging sub-second delay values. precision but make it cute. ✨
  • helpful_warnings (yes) — log warnings about problematic configuration settings, and provide helpful suggestions. it's giving supportive bestie. 🫶
  • process_id (read-only) — the process ID of a Postfix command or daemon process. yes, read-only. don't try it. 💅
  • process_name (read-only) — the process name of a Postfix command or daemon process. also read-only. periodt.
  • queue_directory (see postconf -d output) — the location of the Postfix top-level queue directory. the queue's home address. 🏠
  • syslog_facility (mail) — the syslog facility of Postfix logging. classic. 📝
  • syslog_name (see postconf -d output) — a prefix that is prepended to the process name in syslog records, so that, for example, "smtpd" becomes "prefix/smtpd". it's giving name tag at a party. 🎀

Available in Postfix version 3.0 and later: ✨

  • confirm_delay_cleared (no) — after sending a "your message is delayed" notification, inform the sender when the delay clears up. closure? we love to see it. 🫶

Available in Postfix 3.3 and later: ✨

  • service_name (read-only) — the master.cf service name of a Postfix daemon process. read-only, bestie. don't touch. 💅

Available in Postfix 3.5 and later: ✨

  • info_log_address_format (external) — the email address form that will be used in non-debug logging (info, warning, etc.). so info logs get the external format. slay. ✨

📂 FILES 📂

  • /var/spool/postfix/incoming — incoming queue
  • /var/spool/postfix/active — active queue
  • /var/spool/postfix/deferred — deferred queue
  • /var/spool/postfix/bounce — non-delivery status
  • /var/spool/postfix/defer — non-delivery status
  • /var/spool/postfix/trace — delivery status

👀 SEE ALSO 👀

📚 README FILES 📚

use postconf readme_directory or postconf html_directory to locate this information.

  • QSHAPE_README, Postfix queue analysis

📜 LICENSE 📜

the Secure Mailer license must be distributed with this software. periodt. 💅

👑 AUTHOR(S) 👑

  • Wietse Venema IBM T.J. Watson Research P.O. Box 704 Yorktown Heights, NY 10598, USA
  • Wietse Venema Google, Inc. 111 8th Avenue New York, NY 10011, USA

and that's the whole OQMGR(8postfix) page, bestie. source/version: OQMGR(8postfix). date: whatever your local manpage footer says — i'm not gonna copy the line, that's not the vibe. now go queue something iconic. 💖✨

📦 where this page comes from