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

The check covers JSON types, ranges, paths, listener collisions, trusted proxies, relay networks, LDAP, scanners, DKIM, and SRS. Listener changes take effect after the affected agents are restarted. Keep a reviewed copy of the configuration outside the live server and protect all password, TLS, DKIM, and SRS key files.

Store configuration names such as smtp, imap, and antispam contain JSON but deliberately have no .json filename suffix. The local Web file is the exception and is named bongo-web.json.

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 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.

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 after package or configuration updates.
• 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.
• 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.