bongo/docs/administration.md

Administration quick reference

This guide assumes a distribution installation with CMAKE_INSTALL_PREFIX=/usr. Such an installation stores configuration in /etc/bongo and persistent state in /var/lib/bongo.

Initial setup

Run the guided setup as root from an interactive terminal:

bongo-setup

The equivalent command is bongo-config wizard. The wizard asks only deployment-level questions and supplies conservative defaults for individual protocol limits. Review the resulting configuration before exposing a public listener.

Start and inspect the systemd service with:

systemctl enable --now bongo.service
systemctl status bongo.service
journalctl -u bongo.service

OpenRC installations use the installed bongo service. Agents are normally started by bongo-manager, never one by one from a login shell.

Configuration

Use the validated editor for normal changes:

bongo-admin config
bongo-admin config check
bongo-admin config sync

The Store is the operative configuration. The editor reads it and commits a validated transaction to both the Store and /etc/bongo/config.d. The latter is the administrator- and configuration-management-friendly representation. config check validates those local files without changing the Store; config sync validates them and asks the running manager to apply them. The manager reconciles the same mirror at startup. It uses the Store object's existing Unix modification time as the common revision: a valid local file whose whole-second timestamp is strictly newer is an intentional emergency edit and is imported, while a newer or equally dated Store document refreshes the file. This tie-break deliberately keeps the Store authoritative; use config sync to force a valid local edit made within the same timestamp second into the Store. Store mirror timestamps have zero nanoseconds. Listener changes still require the affected agents to be restarted.

If a local mirror is missing but its operative Store document still exists, config sync reconstructs the file from the Store before committing the validated set. Invalid or unreadable existing files are never replaced this way.

Aliases and virtual domains are split into suffixless JSON fragments below /etc/bongo/aliases.d. Every fragment may contain aliases, domains, or both. Their complete source set is stored operatively in the internal alias-fragments Store document; the directory is its editable mirror. Alias changes made by an administrative command update the Store and mirror as one transaction. At manager startup, only a strictly newer file or directory timestamp is treated as an emergency edit. An equally dated or newer Store source refreshes the directory, including additions and deletions. bongo-admin config sync explicitly selects a validated direct file edit even within the same timestamp second.

The required default_config supplies global aliases; a full source address overrides one domain only:

{
  "aliases": {
    "postmaster": "admin",
    "dmarc-reports": "admin",
    "dmarc-reports@example.org": "dmarc"
  },
  "domains": {
    "old.example.org": "example.org",
    "special.example.org": {
      "target": "example.org",
      "recipient_mapping": "full-address"
    }
  }
}

recipient_mapping accepts local-part, full-address, or domain-name. The normal local-part mode is implicit in the short string form. Internally the manager translates these names to the historical Store representation. It also resolves dmarc-reports independently for every hosted domain and maintains the DMARC-folder rule on the actual target account.

Configuration names such as smtp, imap, antispam, and the local web file contain JSON but deliberately have no .json filename suffix.

Pre-0.7 files are never loaded as runtime fallbacks. Import them explicitly once with bongo-admin migrate while the existing Store is reachable; the command writes the new layout and moves the consumed files below /etc/bongo/migration-backup/pre-0.7. Review the result before restarting the manager. If the old manager is already stopped, run only the Store for the duration of this offline administrative migration.

Accounts and authentication

Common account operations are:

bongo-admin user list
bongo-admin user add USER
bongo-admin user password USER
bongo-admin user info USER
bongo-admin user quota USER
bongo-admin user quota USER 10G
bongo-admin user rename OLD_NAME NEW_NAME

Passwords are prompted for without echo and are not accepted as command-line arguments. Renaming a user disconnects active sessions, moves the per-user data, and retains the old name as a login and delivery alias so clients can be migrated. The Web task list reports clients which still use the old name. The optional per-user mail limit is shared by SMTP delivery, IMAP, POP3, Web mail, and external collection; use unlimited to remove it. See Mail storage quotas.

LDAP can authenticate and auto-provision permitted directory users. Cached credentials keep mail access available for a bounded directory outage. During a confirmed outage an administrator can inspect and extend every existing cache entry:

bongo-admin ldap-cache status
bongo-admin ldap-cache extend-all 72

This does not provision new users and must not become a substitute for restoring the directory. Optional TOTP affects the interactive master login; service-scoped app passwords are the preferred credentials for IMAP, POP3, SMTP, and ManageSieve when two-factor authentication is enabled.

Routine checks

• Run bongo-admin config check and then bongo-admin config sync after editing files or applying an automation change.
• Check the system journal and Bongo authentication log for repeated errors.
• Confirm certificate and DKIM key expiry/rotation before it becomes urgent.
• Test SMTP submission, Internet receipt, outbound delivery, IMAP, and the Web login after protocol or reverse-proxy changes.
• Verify that SpamAssassin and ClamAV are reachable before enabling their agents; scanner failure policy must be deliberate. The Bongo worker checks extra-channel DNS serials but intentionally does not install updates. When KAM or Heinlein is selected, inspect the hourly updater with systemctl status bongo-spamassassin-update.timer and journalctl -u bongo-spamassassin-update.service.
• Keep Store and Queue ports private and audit trusted relay and proxy CIDRs.
• Test restores, not only backup creation.

See storage.md for backup scope, ports.md before changing firewall rules, and the protocol-specific documents before enabling legacy compatibility.