Upgrading to 0.4.8

Version 0.4.8 shares one tracking pool across all jails, tells a missing log apart from a truncated one, adds configured ban lists with a visible origin on every ban, and leaves installed rules in the kernel at a healthy stop. Read the tagged release notes and follow the tagged installation guide for the install steps. This page covers what changes for an existing installation.

v0.4.7 is the minimum supported release and the only supported upgrade source. Releases, downloads and Git tags before v0.4.7 are retired; installation and rollback to them are unsupported.

From v0.4.6: through v0.4.7 first

A state last written by v0.4.6 (schema 24) is not an upgrade path for v0.4.8. Install the v0.4.7 release first and start it once. That start upgrades schema 24 to 25 after writing <state_file>.pre25-backup, needs free space of twice the database size plus 32 MiB, and resumes if interrupted. Confirm fail2zig version reports 0.4.7 and fail2zig status shows healthy storage before continuing to v0.4.8. States last written by v0.4.5 or earlier have no supported path; start them from a fresh state and plan the protection gap.

Released fail2zig 0.3.0 binary state has no converter to native SQLite. Plan an explicit protection transition; the installer refuses to reinterpret legacy state.

Preserve a usable rollback

Stop the daemon and every other state writer. Keep the current executable, configuration and a coherent copy of the database with its -wal and -shm siblings. The first v0.4.8 start upgrades schema 25 to 26 in one transaction after writing <state_file>.pre26-backup. The backup needs free space of twice the database size plus 32 MiB, and the daemon refuses to start if that file already exists; move an old backup aside only when it is not the one you need. An interrupted upgrade leaves schema 25. Every existing ban gets origin detection. The first start also rekeys saved detection generations once and logs that it did.

v0.4.7 and older binaries refuse schema 26 with UnsupportedSchema. To roll back, stop the daemon, restore the backup over the state file, remove the upgraded database’s -wal and -shm files and reinstall the v0.4.7 binary. Decisions made after the backup are lost. The upgrade was proven on a 65,536-ban state; its schema steps do not scan populated tables.

Review these settings before the first start

• native_memory_ceiling_mb now defaults to 512. A configuration that sets 256 explicitly must raise it or the daemon refuses with NativeMemoryAdmission. The plan for 65,536 live bans is about 337 MiB with two enforcing jails and 438 MiB with sixteen.
• The state file may grow to 1 GiB (was 256 MiB). The file never shrinks; freed pages are reused inside it. A file already past 1 GiB is refused at start.
• on_truncation keeps its shape, but rotation under "restart" no longer pauses the jail, and a missing log is reported as missing (FileNotFound) rather than as a truncation. See the log file lifecycle.
• ignoreself defaults to true: the host’s own addresses join every jail’s ignore list with source self. ban refuses a loopback, host or SSH-peer address unless --force is given.

Stop semantics changed

A healthy systemctl stop now leaves installed rules in the kernel with their timeouts; the next start reconciles them with durable state. A stop no longer unbans anyone. To stop with an empty table, run sudo fail2zig firewall withdraw first; status then reports DEGRADED (FirewallWithdrawn) until the next start.

Check protection after starting

sudo fail2zig version
sudo fail2zig status --details
sudo fail2zig jails
sudo fail2zig list --origin config
sudo fail2zig firewall show

status shows the state file size against the 1 GiB ceiling, the tracking pool against its limits, each paused source with its repair command and retained loss events. jails shows source health per jail; missing (FileNotFound) is a healthy state. list carries an ORIGIN column. A retained firewall observation is not proof of current packet reachability; use a controlled external check. See the administration reference.