# 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: ```sh 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: ```sh 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: ```sh 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: ```json { "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: ```sh 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](quotas.md). 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: ```sh 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](storage.md) for backup scope, [ports.md](ports.md) before changing firewall rules, and the protocol-specific documents before enabling legacy compatibility.