Mario Fetka
5897512fd9
Complete the current IMAP, POP3, SMTP and proxy protocol work; add the validated setup and administration UI, packaging examples, tests, and maintained roadmap/documentation for the 0.7 development line.
97 lines
3.3 KiB
Markdown
97 lines
3.3 KiB
Markdown
# 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.
|