.TH BONGO-SETUP 1 "July 2026" "Bongo @BONGO_V_STR@" "Bongo setup"
.SH NAME
bongo-setup \- guided initial setup for a Bongo server
.SH SYNOPSIS
.B bongo-setup
.br
.B bongo-setup scanners
.SH DESCRIPTION
.B bongo-setup
is a curses wizard for a new Bongo installation and must be run as root from
an interactive terminal.  It asks deployment-level questions and retains safe
defaults for individual protocol limits.
.PP
The wizard configures the server hostname, IPv4 listener, hosted domains, Web
deployment behind Apache, nginx, Nginx Proxy Manager or a direct LAN listener,
an optional HAProxy mail frontend, IMAP, POP3, submission and ManageSieve,
the optional rate-limited internal relay, LDAP authentication and legacy TLS
compatibility.
.PP
Automatic ACME is optional.  HTTP-01 is served by the Bongo Web challenge
endpoint.  DNS-01 supports wildcard names and offers native
.BR nsupdate /RFC 2136
with optional TSIG as the standard provider, plus a Cloudflare provider using
a zone-scoped API token.  Provider credentials are stored separately from the
Store configuration and are not placed in process arguments.
.PP
For each hosted domain it checks published SPF, DKIM and DMARC records.  It
reuses or imports a safe matching DKIM private key, or generates a new
2048-bit RSA key.  Required DNS changes are printed and added to the task list
of the account reached through that domain's
.B dmarc-reports
alias.
.PP
Local ClamAV and SpamAssassin services are probed with their harmless
.B PING
commands.  An installed but unreachable local scanner may be configured only
after explicit confirmation.  The wizard previews the detected Gentoo/OpenRC
or Debian/systemd configuration path, creates an adjacent one-time
.B .bongo-setup.bak
file, preserves unrelated settings, and restricts the scanner TCP listener to
loopback.  Enabling and restarting the scanner is a separate choice.  If it is
selected, the expected protocol response is required before Bongo setup is
committed.  A failed edit, service command, probe or later setup operation
restores scanner files and prior service state.  Remote scanners are never
edited.
.PP
The
.B scanners
maintenance mode performs scanner detection, preview, backup, service
management and verification without rerunning initial Bongo setup.  After the
expected protocol response, it enables the corresponding Bongo antispam or
antivirus agent, synchronizes the suffixless configuration documents with the
Store and reloads the manager.  An unverified endpoint remains disabled.  A
failed activation restores both scanner state and Bongo configuration.
.PP
When SpamAssassin has no installed rule set, the preview includes an initial
Apache signing-key download with complete fingerprint verification, a signed
.BR sa-update (1)
download followed by
.BR spamassassin (1)
lint validation.  Either command must succeed before scanner configuration is
changed.  Successfully installed rule data is retained as scanner update data.
.PP
The signed KAM channel
.B kam.sa-channels.mcgrail.com
and the unsigned Heinlein Support channel
.B spamassassin.heinlein-support.de
are offered independently and are disabled by default.  The complete KAM key
fingerprint is checked before import.  Heinlein requires an explicit warning
confirmation because its documented update command disables GPG verification.
Downloaded channels are never allowed to load SpamAssassin plugins.
.PP
A signing-key change does not replace current rules or restart the scanner.
The currently trusted and newly downloaded fingerprints are recorded as a
persistent warning and shown when the administrator opens
.BR bongo-admin (1)
configuration mode.
.SH SECURITY
The administrator password and initial JSON configuration bundle are passed
to
.BR bongo-config (1)
through anonymous inherited file descriptors.  Neither value is placed in the
process argument list and no named password file is created.
.PP
All generated documents are validated together before installation.  Store
configuration document names contain JSON but have no
.B .json
suffix.
.PP
The initial 3072-bit RSA self-signed TLS pair is created through GnuTLS and
stored below
.IR /etc/bongo/ssl.d .
An existing complete pair is validated and preserved.  Invalid, incomplete or
unsafe TLS/DKIM material stops installation instead of being overwritten.
.SH FILES
.TP
.I /etc/bongo/ssl.d
TLS certificate and protected private key.
.TP
.I /etc/bongo/dkim.d
Per-domain DKIM private keys and public DNS hints.
.TP
.I /etc/bongo/dmarc.d
Suffixless per-domain DNS check state and suggested policy.
.TP
.I /etc/bongo/acme.d/providers
Root-owned suffixless JSON containing DNS-01 provider credentials.  It is
installed with mode 0640 for the Bongo group.
.TP
.I /usr/share/bongo/examples/antispam
ClamAV and SpamAssassin configuration fragments.
.TP
.I /usr/share/bongo/examples/reverse-proxy
Apache, nginx, Nginx Proxy Manager and HAProxy examples.
.TP
.I /usr/share/bongo/examples/acme
Native nsupdate and Cloudflare DNS-provider examples.
.SH SEE ALSO
.BR bongo-config (1),
.BR bongo-admin (1),
.BR bongo-manager (1)