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.

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 applies a validated file change through the running manager. 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.