bongo/docs/setup-wizard.md

# Guided setup and configuration

Run `bongo-setup` (or `bongo-config wizard`) as root for a new installation.
The curses wizard asks deployment-level questions: server identity and hosted
domains, Web reverse proxy or direct-HTTPS mode, optional HAProxy mail
frontend, enabled mail protocols, internal port 26 relay, LDAP, legacy TLS
compatibility, mail authentication, and local mail scanners. Direct HTTPS
defaults to `/etc/bongo/ssl.d/server.crt` and `server.key`, listens on 443,
and reserves port 80 for the automatic HTTPS redirect. Individual protocol
limits retain safe defaults.

Automatic ACME is optional. HTTP-01 uses the built-in Web challenge endpoint;
the public reverse proxy must route `/.well-known/acme-challenge/` to Bongo.
DNS-01 supports wildcard certificates and asks for one provider per DNS zone.
The first provider choice is native `nsupdate`/RFC 2136 with optional TSIG;
Cloudflare with a zone-scoped API token is also included. Provider secrets are
stored in `/etc/bongo/acme.d/providers` as `0640 root:bongo` and never appear
in process arguments. The wizard enables the renewal worker only after the CA
terms have been accepted.

For every hosted domain the wizard queries the currently published SPF,
selector-specific DKIM, and DMARC TXT records. It reuses a valid local DKIM
key, can import an existing unencrypted RSA key, or creates a new 2048-bit key
with `opendkim-genkey`. Private keys are installed root-owned and readable by
the Bongo group only. The wizard prints the exact DNS records which still need
to be published and creates a warning task for the account reached through
that domain's `dmarc-reports` alias. DNS timeouts are reported as a task and do
not prevent a safe local installation.

The initial certificate is created directly through the GnuTLS API as a
3072-bit RSA self-signed server certificate. An
existing complete, safe, matching certificate/key pair is validated and kept;
an incomplete, invalid, or carelessly permissioned pair stops setup. ACME can
replace the pair later through a deploy hook.

The admin password and generated configuration bundle are passed to
`bongo-config` through inherited anonymous file descriptors. They do not
appear in process arguments and no named password file is created.

The wizard first probes clamd and spamd without changing either service. A
reachable scanner can be enabled immediately. If an installed local scanner is
unreachable, the administrator may explicitly opt into the scanner editor.
The editor recognizes the usual Gentoo/OpenRC, Debian/systemd and compatible
configuration locations, shows every path before making a change, preserves
unrelated package options, and restricts the TCP listener to loopback.

Before changing an existing scanner file it creates a one-time adjacent
`.bongo-setup.bak`. The administrator separately decides whether setup may
enable and restart the detected service. When service management is allowed,
setup requires a successful protocol `PONG` before it installs the Bongo
configuration. A failed write, service command, probe, or later Bongo setup
step restores the scanner files and their prior enabled/running state. If
service management is declined or no supported unit is found, setup edits only
the approved file and reports that a manual restart and check are required.
Remote scanners are never reconfigured. Loopback-only example fragments are
installed below `share/bongo/examples/antispam`; reverse proxy examples are
installed below `share/bongo/examples/reverse-proxy`.

An installation that contains SpamAssassin but no rules is detected before
the preview. With the administrator's scanner-edit confirmation, setup runs
the signed `sa-update` channel followed by `spamassassin --lint`. On a fresh
Gentoo installation it first obtains the Apache update key over HTTPS and
checks its complete fingerprint before import. A download or lint failure
happens before configuration files are edited. Successfully installed rule
data is retained as updated scanner data.

The scanner editor can additionally select the signed KAM rules or the
unsigned Heinlein Support rules. Both are off by default. KAM's complete
OpenPGP fingerprint is verified before key import. Heinlein is shown with an
explicit authenticity warning because its documented setup requires
`--nogpg`. Downloaded channels are never permitted to load plugins. On a
systemd installation, selecting either channel writes the protected
`/etc/bongo/spamassassin.d/channels` file and enables the hourly
`bongo-spamassassin-update.timer`. KAM and Heinlein are always updated in
separate processes so Heinlein's unsigned exception does not affect KAM.

`bongo-setup scanners` runs only this local scanner editor, service check, and
matching Bongo-agent activation. It is suitable after scanner package upgrades
and does not repeat initial Bongo setup. A verified SpamAssassin endpoint
enables `antispam.enabled` and `bongoantispam`; a verified ClamAV endpoint
enables `bongoavirus`. Both use loopback endpoints. The suffixless documents
below `/etc/bongo/config.d` and the operative Store are updated together, the
manager is reloaded, and every scanner and Bongo change is rolled back if a
later activation step fails.

The default scanner-health worker checks daily ClamAV signatures and the
presence of compiled SpamAssassin rules every six hours. It reports missing
data and stale ClamAV signatures in an administrator task. SpamAssassin rule
age is not treated as an error because upstream channels may legitimately
remain unchanged for months. For selected extra channels the Worker uses
`sa-update --checkonly`; its fast DNS serial lookup reports a genuinely
available update without modifying the rules. The Bongo systemd timer installs
KAM/Heinlein updates hourly, while the distribution's normal update mechanism
continues to own the official SpamAssassin channel and FreshClam.

For an installed server, use `bongo-admin config` to edit every Store, Web, and
LDAP configuration document. A save updates the operative Store and the
suffixless files below `/etc/bongo/config.d` together, serializes concurrent
admin changes, and rolls back prior writes if a later write fails.
`bongo-admin config check` validates files without changing the Store;
`bongo-admin config sync` transactionally writes validated file changes and
new template defaults to the Store, then asks the running manager to reload.
Alias and virtual-domain fragments are kept separately in
`/etc/bongo/aliases.d` and are synchronized by the same manager operation.

Configuration names such as `smtp`, `imap`, `antispam`, `antivirus`, `web`,
and `authentication` have no `.json` suffix, although their contents are
JSON. The source and installed template names follow the same convention.