bongo/docs/queue.md

Queue, routing, and delivery

bongoqueue durably owns messages after SMTP or the external collector has accepted them and before every recipient has reached a final destination. It coordinates filtering, local Store delivery, remote SMTP, and LMTP; it is not a public submission protocol.

Message flow and durability

Queue data lives below /var/lib/bongo/spool. An accepted message remains there while a temporary scanner, Store, DNS, SMTP, LMTP, or quota-dependent delivery condition is retried. Permanent failures produce the configured delivery-status response or bounce. The Queue must not acknowledge a message to its upstream path before the payload and recipient state are durable.

Enabled filtering agents register for Queue stages. Antivirus, SpamAssassin, rules/Sieve, and final local or remote delivery therefore see a common envelope and message rather than independent copies. External POP3 or IMAP collection enters this same path and may delete a source message only after Bongo has committed it successfully.

The internal Queue protocol defaults to TCP 8670. Bind and firewall it as a private service interface. It does not authenticate arbitrary Internet clients and must never be exposed as an SMTP alternative.

Limits and failure handling

The suffixless queue document controls spool free-space reservation, message lifetime, retry interval, worker concurrency, trusted/hosted domains, and bounce policy. minimumfreespace prevents normal acceptance from consuming the filesystem's final space. Per-user Store quota is separate: a full mailbox defers or rejects that recipient without corrupting other recipient state.

A scanner outage is a delivery-policy decision, not permission to silently bypass inspection. ClamAV and SpamAssassin failures leave the message queued for the configured retry path. Likewise, a per-recipient LMTP temporary error must preserve only that recipient for retry and must not redeliver recipients which already returned a final success.

Administration and shutdown

Use bongo-queuetool to inspect and perform documented queue operations; do not edit spool files manually. A service stop first prevents new work and asks the managed agents to finish or abandon their current transaction safely. Queue and Store state must be included in a consistent backup.

The 0.7 release matrix exercises byte preservation, disk exhaustion, retry, expiry, bounce, hold/release, concurrency, invalid commands, quota mapping, and collector floods under STQ-02 through STQ-12. SMTP and LMTP rows add their protocol-specific recipient and retry cases.