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

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:

```sh
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:

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