0
Fork 0
mirror of https://github.com/oblien/openship.git synced 2026-11-18 06:55:56 +00:00
openship/docs/mail-engine-state.md
Saim Shafique ea0d015b86
Preserve mail logs and ban history safely across engine updates (#1705)
* fix(mail): persist mail logs, fail2ban database and ignoreip across engine updates

Mail engine updates recreate the container (docker rm -f + docker run),
so anything not on a bind mount is lost: /var/log (mail.log, dovecot and
fail2ban logs), fail2ban's SQLite database, and operator ignoreip
customisations in /etc/fail2ban.

- Bind-mount /var/log and /var/lib/fail2ban from the host mail state dir.
  Deliberately not /etc/fail2ban: a seed-once mount would hide later image
  changes (same trap as #392's master.cf).
- Render operator ignoreip additions (OPENSHIP_MAIL_F2B_IGNOREIP, passed
  through engine.env) into a jail.d override on every boot, as baked
  jail.local value + operator value, so image defaults are never dropped.
- Run cron under supervisord so logrotate's daily job actually fires for
  the now-persisted logs; logrotate is installed explicitly (only a
  Recommends of rsyslog) and build-gated.

Fixes #1701

* Preserve existing mail state before replacement and repair supervised log rotation

---------

Co-authored-by: Hydra <abdelhamedmo59@gmail.com>
2026-11-11 16:54:11 +02:00

2.1 KiB

Mail engine state during updates

Mail logs and fail2ban's SQLite history are retained under /var/lib/openship/mail/logs and /var/lib/openship/mail/fail2ban. The PostgreSQL sidecar, mailbox data, mail queue, DKIM keys and existing configuration retain their established mounts.

The first update from an older container preserves its writable-layer logs and SQLite database before removing it. OpenShip obtains the replacement image first, stops the old engine to get a consistent snapshot, copies both directories, then publishes the host directories. Subsequent updates reuse these mounts without copying or stopping the container during preservation checks.

If preservation fails, the original container is retained and its previous run state is restored. Existing nonempty host data and custom mounts are never merged or replaced automatically; the update reports the conflicting path for an operator to reconcile. The existing image rollback uses the same retained data.

The entrypoint creates daemon log directories on every boot, including ClamAV's directory, and repairs their service ownership after image UID changes. Native logrotate policies are run by cron. Rsyslog and Freshclam reopen their logs through Supervisor rather than relying on systemd or Debian's service-start policy.

Operator fail2ban exclusions

OPENSHIP_MAIL_F2B_IGNOREIP extends the image's default ignoreip list. For a new installation, an operator may set it in the API environment before mail setup. For an existing server, set the single-line value in that server's retained /var/lib/openship/mail/engine.env, then update/recreate the engine. Different servers can retain different exclusions. The file contains credentials and must remain private.

Move existing manual ignoreip edits from the old container into this setting before the first update. Arbitrary files under /etc/fail2ban are not persisted; retaining the entire directory would hide fixes in newer images. The entrypoint renders the supported exclusions on each boot while retaining the baked defaults. Newlines, shell substitutions and configuration section delimiters are rejected.