Mario Fetka
122 lines
5.0 KiB
Groff
122 lines
5.0 KiB
Groff
.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)
|