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:

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