Mario Fetka
95 lines
4.7 KiB
Markdown
95 lines
4.7 KiB
Markdown
# Directory layout
|
|
|
|
Bongo follows FHS-style paths for distribution installs. Configure a package
|
|
build with `CMAKE_INSTALL_PREFIX=/usr`; CMake then deliberately keeps host
|
|
configuration under `/etc`, not `/usr/etc`.
|
|
|
|
## Distribution installation
|
|
|
|
| Path | Contents |
|
|
| --- | --- |
|
|
| `/etc/bongo` | Administrator-managed configuration and protected key directories. |
|
|
| `/etc/bongo/config.d` | Suffixless JSON mirrors for every operative Store configuration document. |
|
|
| `/etc/bongo/aliases.d` | Editable mirror of the Store-authoritative, mergeable suffixless alias and virtual-domain fragments. |
|
|
| `/etc/bongo/ssl.d` | TLS certificates and private keys managed by setup or an ACME deploy hook. |
|
|
| `/etc/bongo/dkim.d` | Per-domain DKIM keys and related material. |
|
|
| `/etc/bongo/dmarc.d` | DMARC setup state and report-processing policy. |
|
|
| `/etc/bongo/acme.d` | Root-owned ACME DNS-provider credentials and policy. |
|
|
| `/etc/bongo/migration-backup` | Files consumed by an explicit one-time legacy migration. |
|
|
| `/var/lib/bongo` | Persistent Bongo state. |
|
|
| `/var/lib/bongo/users` | Per-user stores and message documents. |
|
|
| `/var/lib/bongo/system` | System Store and Store configuration documents. |
|
|
| `/var/lib/bongo/spool` | Queue spool. |
|
|
| `/var/lib/bongo/dbf` | Account database, random seed, protocol parameters, and runtime credentials. |
|
|
| `/var/lib/bongo/web` | Web session, task, and identity databases. |
|
|
| `/var/lib/bongo/work` | Persistent diagnostics, traces, and recovery data. |
|
|
| `/var/lib/bongo/cache` | Regenerable caches. |
|
|
| `/var/spool/bongo/maildrop` | Protected setgid hand-off for unprivileged local mail submission. |
|
|
| `/run/bongo` | Volatile PID and agent recovery files. |
|
|
| `/usr/sbin` | Server agents and administration programs. |
|
|
| `/usr/libexec/bongo` | Private administration helpers. |
|
|
| `/usr/share/bongo` | Web assets, providers, zone snapshot, templates, and examples. |
|
|
| `/usr/share/man` | Manual pages. |
|
|
| `/usr/lib/systemd/system` | systemd service unit. |
|
|
| `/usr/lib/tmpfiles.d` | Runtime-directory declaration. |
|
|
| `/usr/lib/sysusers.d` | Distribution-neutral service account declaration. |
|
|
| `/etc/fail2ban` | Bongo filter and disabled jail template, when enabled at build time. |
|
|
|
|
Distribution packaging may override the systemd, tmpfiles, sysusers, and
|
|
Fail2ban destinations with the documented CMake cache variables.
|
|
|
|
## Other prefixes
|
|
|
|
A self-contained install with `CMAKE_INSTALL_PREFIX=/usr/local` uses
|
|
`/usr/local/etc/bongo`. Executables, data, and libraries follow the selected
|
|
prefix, while persistent state remains `/var/lib/bongo` unless
|
|
`BONGO_STATE_DIR` is explicitly changed.
|
|
|
|
Useful configure-time overrides include:
|
|
|
|
```sh
|
|
cmake -S . -B build \
|
|
-DCMAKE_INSTALL_PREFIX=/opt/bongo \
|
|
-DSYSCONF_INSTALL_DIR=/etc \
|
|
-DBONGO_CONFIG_DIR=/etc/bongo \
|
|
-DBONGO_STATE_DIR=/srv/bongo \
|
|
-DBONGO_RUNTIME_DIR=/run/bongo \
|
|
-DBONGO_MAILDROP_DIR=/var/spool/bongo/maildrop
|
|
```
|
|
|
|
Absolute paths are compiled into agents and generated service/configuration
|
|
files. Do not move an installed state tree without reconfiguring and rebuilding
|
|
or supplying matching package overrides.
|
|
|
|
## Runtime directories
|
|
|
|
Packages should not ship a populated `/var/run` or `/run` tree.
|
|
systemd-tmpfiles or the service script creates `/run/bongo` at boot.
|
|
Persistent empty directories below `/var/lib/bongo` and the protected local
|
|
submission path below `/var/spool/bongo` are created during setup or package
|
|
installation with the appropriate owner.
|
|
|
|
TLS, DKIM, DMARC and SRS material below `/etc/bongo` must be included in backup
|
|
and permission reviews. ACME deployments may point configuration at paths
|
|
managed by their deploy hook instead. Runtime credentials required to access
|
|
the Store remain protected state below `/var/lib/bongo`.
|
|
|
|
## Package removal and upgrades
|
|
|
|
Distribution upgrades and same-version reinstalls preserve all
|
|
administrator-created configuration and key material below `/etc/bongo` and
|
|
all persistent mail, Store, queue, account, Web, and worker state below
|
|
`/var/lib/bongo`. Accepted local submissions below `/var/spool/bongo` are
|
|
preserved as well.
|
|
|
|
On Debian, a normal package removal deletes Bongo programs and service units
|
|
but retains package-owned conffiles as well as both Bongo trees. A purge also
|
|
deletes the package-owned Fail2ban filter and disabled jail template. It still
|
|
does **not** delete `/etc/bongo` or `/var/lib/bongo`: destroying keys, server
|
|
configuration, queued messages, or user mail as a side effect of package
|
|
removal would be unsafe. The same rule applies to `/var/spool/bongo`. Remove
|
|
these trees explicitly only after making and verifying any required backup.
|
|
|
|
`/run/bongo` contains no persistent state. Its contents can remain until the
|
|
next boot after a package removal and must never be relied upon for recovery.
|