bongo/docs/architecture.md

Architecture

Bongo is an integrated but modular mail, calendar, and contact server. A small manager supervises specialised agents which share the Bongo Store and Queue instead of combining every protocol in one process.

Message flow

A typical Internet message follows this path:

1. bongosmtp accepts SMTP and applies listener, relay, TLS, authentication, and message-size policy.
2. bongoqueue records and routes the message through enabled filtering agents.
3. SPF, DKIM, DMARC, SRS, SpamAssassin, ClamAV, and Sieve processing run where configured.
4. Local delivery commits the message through bongostore; remote delivery is performed by bongosmtpc or a configured LMTP/SMTP transport.
5. Users read the same stored data through IMAP, POP3, or the Web interface.

External account collection enters the same delivery path: bongocollector fetches a user's remote POP3 or IMAP account and submits the message to the mailbox selected by that user. Sending with a matching external identity is handled by the authenticated outbound SMTP path.

Components

Component	Responsibility
bongo-manager	Starts the Store first, then enabled agents in priority order.
bongostore	Owns per-user mail, calendar, contact, and metadata storage.
bongoqueue	Spools, filters, and routes messages.
bongosmtp	Receives SMTP, submission, and trusted-device relay traffic.
bongosmtpc	Sends SMTP and LMTP deliveries.
bongoimap	Provides IMAP4rev2, IMAP4rev1, and legacy IMAP4 access.
bongopop3	Provides POP3 and POP3S access.
bongosieve	Provides the ManageSieve protocol.
bongorules	Executes Sieve filtering and vacation actions.
bongocollector	Fetches user-configured external accounts.
bongoantispam	Connects to SpamAssassin when enabled.
bongoavirus	Connects to ClamAV when enabled.
Bongo Web	Python 3 Webmail, account settings, CalDAV, and CardDAV.
bongo-setup / bongo-admin	Guided initial setup and validated administration.

Protocol and component details are maintained in smtp.md, imap.md, pop3.md, sieve.md, queue.md, web.md, and dav.md.

Agents use common C libraries for configuration, logging, authentication, TLS, protocol I/O, Store access, and Queue access. GNU GSASL is shared by the mail protocols; its direct Bongo verification callback does not create or consult a second user database.

Agents which bind a privileged listener start with the manager's restricted credentials, bind, and permanently change their real/effective/saved UID and GID to bongo before accepting clients. Non-listener agents do the permanent drop immediately. The manager itself normally has effective UID bongo but retains a bounded supervisor identity so a crashed listener can be replaced. bongoworker has the same inactive exception solely for the short atomic ACME certificate deployment step. systemd restricts both to CHOWN, DAC_OVERRIDE, FOWNER, SETGID, SETUID, and NET_BIND_SERVICE; active and ambient capabilities are empty while idle. Moving ACME deployment into a smaller dedicated privileged helper remains a future hardening improvement.

The systemd service additionally uses a strict read-only filesystem view with explicit write access only to Bongo state, runtime PID files, synchronized configuration, and TLS deployment paths. Kernel, control-group, device, hostname, realtime, SUID/SGID-creation, and non-Internet/non-Unix address families are isolated. Required state and configuration mounts and systemd-tmpfiles setup are ordered before the manager starts.

Internal interfaces

The Store protocol on TCP 689 and Queue protocol on TCP 8670 are private service interfaces. They are not substitutes for IMAP, SMTP, or a public API and must not be exposed to untrusted networks. The manager and local tools use them to coordinate the agents.

The Web process talks to the maintained Python 3 bindings and Store services. Its HTTP listener defaults to loopback because TLS is normally terminated by Apache, nginx, or another trusted reverse proxy. This does not hard-code an external http:// URL: public_base_url, forwarded-address trust, and HTTPS status are explicit deployment settings.

Direct HTTPS is also supported. The Web agent binds port 443, loads the configured certificate and private key, binds port 80 for an HTTPS-only redirect, and then permanently changes its real and effective UID/GID to the configured bongo service account before accepting either HTTP listener.

Configuration model

Agent settings are operative suffixless JSON Store documents such as smtp, imap, queue, web, authentication, and manager. Their declarative counterparts live below /etc/bongo/config.d; alias fragments live below /etc/bongo/aliases.d. The manager validates and imports the files only after the Store starts, so agents always consume one coherent Store-facing model and never fall back to a second runtime configuration source.

bongo-admin config reads the Store and writes Store plus files as one rollback-capable operation. Use bongo-admin config check for a read-only file validation and bongo-admin config sync after direct or automated file changes. Pre-0.7 layouts require the explicit one-time migration command.

Design direction

The original Dragonfly artwork and layout remain the visual basis for the 0.7 Web interface. The implementation is maintained Python 3 and JavaScript; no Ruby runtime or Ruby rewrite is planned. A later responsive redesign should preserve the simple integrated product rather than introduce a second server stack.

For 0.9, JMAP becomes the canonical public object and synchronisation model, while bongostore remains the only durable data owner. IMAP, POP3, ManageSieve, CalDAV, CardDAV, SMTP/LMTP delivery, and the Web interface map to the same internal objects and compatibility metadata; they do not maintain parallel databases. See JMAP and the Bongo Store.