llms.txt
Compare with other sites' llms.txt files →# fail2zig
> Log-based intrusion prevention for Linux. One static executable combines the daemon, administration, rule testing and migration. Native SQLite persistence keeps source progress and protection state durable.
## Identity
- Name: fail2zig
- Current release: v0.4.8 (2026-10-22)
- Release notes: https://github.com/ul0gic/fail2zig/releases/tag/v0.4.8
- Language: Zig application code plus embedded SQLite C
- License: AGPL-3.0-or-later; bundled dependency and derived-data notices ship with the release
- Repository: https://github.com/ul0gic/fail2zig
- Website: https://fail2zig.com/
- Minimum supported release: v0.4.7, the only supported upgrade source; use v0.4.8 for new installs and upgrades. A v0.4.6 state upgrades through v0.4.7 first. Releases before v0.4.7, their downloads and Git tags are retired; installation and rollback to them are unsupported.
## Runtime and protection
- One static musl executable per target; no Python runtime, SQLite service, SQLite CLI or shared SQLite library required.
- Journal input uses journald/journalctl. iptables/ipset use host tools with structured arguments. nftables uses direct netlink.
- Native SQLite stores receipts, checkpoints, retry state, protection owners, effect intent and confirmed history.
- Intent is durable before dispatch; owned-kernel readback confirms installed protection. Decisions and uncertain effects are distinct from installed bans.
- Explicit limits bound records, queues, retries, storage and administration: one shared pool of 65,536 tracked addresses and 65,536 live bans across all jails, a 1 GiB state file that never shrinks, 128 ignore entries per jail. Live bans are never evicted; critical receipts, owners and unresolved intent are not evicted to make room. No whole-daemon zero-allocation or RSS guarantee.
- Sixteen compiled built-in filter names: fifteen external-service filters plus internal recidive. Bounded native JSON custom rules use rule_files. Offline evaluation uses fail2zig rule-test.
- No arbitrary imported fail2ban regex execution, Python plugins, shell actions or complete fail2ban parity claim.
- Finite, permanent and escalating bans with decay; configured ban lists (banip) and timed entries; every ban carries an origin: detection, manual or config. Ignore policy includes ignoreip, runtime exclusions, ignoreself and ignoretime. Jail lifecycle and confirmed history.
- global.firewall selects one daemon backend. Explicit selection never silently falls back. enforce selects enforcement versus log-only policy; banaction is a deprecated compatibility spelling.
- Effects stay in the current network namespace; custom namespace selectors and overrides that move the daemon between namespaces are unsupported.
PortSentry support targets v2.0.7 history files with timestamp=iso8601 and sensor response disabled. --connect was qualified in 0.4.3 and --stealth -m pcap (TCP SYN, FIN, NULL and XMAS scans, and UDP) in 0.4.7, each on Debian 13 with IPv4/IPv6 nftables bans, blocking while banned, expiry and restored connectivity. PortSentry recreates its history file at every start; the jail's on_truncation policy decides whether the source pauses for repair-source or resumes and records the loss. Ignored, pre-threshold and sensor-blocked records are excluded. Legacy 1.2, other 2.x versions and alternate log envelopes are unqualified; legacy same-name Fail2ban migration is unsupported. Automatic bans cover the source across host ports/protocols, not individual service ports. Host INPUT rules do not establish Docker forwarded-traffic protection.
## Administration and monitoring
Use fail2zig <command>; fail2zig-client is retired in 0.4.0. Every command has help <command> or --help. Configuration edits apply through supported live reload or return a restart-required outcome; literal ignoreip and banip edits and adding or removing a jail are live. fail2ban's runtime mutation API and socket protocol are not supported.
Runtime exclusions: ignore add, ignore remove and ignore list manage per-jail entries that survive restart and reload; ignore add --for gives an entry a life; an exclusion never unbans by itself unless --unban is given. ban --duration accepts seconds or duration syntax; ban refuses a loopback, host or SSH-peer address unless --force is given. list --origin filters bans by origin. repair-source runs online through the daemon's socket while it is running. A healthy stop leaves installed rules in the kernel; firewall withdraw removes them and holds enforcement off until the next start. support-bundle writes one redacted JSON file for a bug report. jails shows source health: ok, missing (FileNotFound), waiting, paused or broken; missing is a healthy state and is not yet shown by status. Use status --output json, not status --json.
fail2zig firewall show reports the daemon's latest retained observation of fail2zig-owned kernel protection. It is read-only and does not refresh, repair or enumerate another application's firewall state. list reports ban intent and confirmation; firewall show reports a sampled kernel observation. Neither proves packet reachability. Native nftables observation uses netlink and does not require the nft executable. At most 256 entries are retained; pages default to 64 and cursors expire after 60 seconds or when the observation changes.
The --details flag expands table output for status, jails, list, stats and firewall show. It does not change plain or JSON output. list --sort orders addresses numerically, IPv4 before IPv6, across table, plain and JSON; the default order is unchanged. stats reads a published worker snapshot with snapshot/readback ages and counters cumulative since daemon start. Jail MODE is configured enforcement and PROTECTION is observed protection; unknown plain counts use -, while known zero uses 0. Detailed jail output remains complete on narrow terminals. History means retained confirmations, not lifetime bans.
The shipped unit runs as a non-login fail2zig account with NET_ADMIN, NET_RAW and DAC_READ_SEARCH. Monitoring-group members are read-only; mutations require root or the daemon UID. HTTP shares daemon privileges and defaults to loopback. metrics_enabled = false disables HTTP/WebSocket while IPC remains available.
HTTP endpoints: /metrics, /api/status, /api/bans, /api/health and /events. Health is readiness (200 when ready, 503 otherwise), not just connection liveness. Per-jail metrics: fail2zig_jail_bans_active, fail2zig_jail_bans_total, fail2zig_jail_failures_counted_total, fail2zig_jail_ignored_detections_total, fail2zig_jail_source_state, fail2zig_jail_pool_evictions_total; daemon-wide fail2zig_state_file_bytes and fail2zig_state_file_pages. Every mutation writes one audit line; log_format = "json" writes JSON log lines. The demo's deployed version is separate from the published release.
## Configuration and upgrades
bantime, findtime, bantime_increment_max_bantime, bantime_increment_jitter, bantime_increment_decay and ignoretime accept integer seconds or quoted durations such as "1h30m"; banip and ignoreip entries take an optional duration ("198.51.100.0/24 1d") whose period runs once from first apply. Only bantime accepts "permanent". On the CLI, ban --duration and ignore add --for accept duration syntax; --timeout remains numeric. Escalation inherits field by field. on_truncation (refuse or restart) is per file jail only. native_memory_ceiling_mb defaults to 512; log_format selects text or JSON daemon logs.
There is no automatic converter from fail2zig 0.3.0 binary state to native SQLite. Plan an explicit protection transition; rollback to a pre-v0.4.7 release is unsupported. Compatible native SQLite ownership transitions are offline and limited to verified default paths; custom paths need explicit handling. The installer never starts or restarts services.
Supported fail2ban schema-4 migration is separate: inspect, snapshot, plan, validate, cutover, status and rollback. Admitted owners, original deadlines and history can transfer. Unsupported enabled protection blocks activation. Partial matches, in-window counters and multiline correlation do not transfer; fail2ban has no saved journal cursor. File continuity and reset/replay losses must be reviewed explicitly.
Built-in SSH journal jails discover trusted standard executable paths when journal_executables is omitted. Explicit profiles remain exact overrides; custom journal rules require one.
Version 0.4.8 upgrades schema 25 to 26 on first start after writing <state_file>.pre26-backup; v0.4.7 is the only supported upgrade source and v0.4.7 and older binaries refuse schema 26. It shares one tracking pool across jails, adds banip, origins, timed entries, ignoreself, ignoretime, bantime_increment_decay, log_format, online repair-source, jail add and remove on reload, firewall withdraw, support-bundle and per-jail metrics, and leaves installed rules in the kernel at a healthy stop. Measurements on the lab host (Debian 13, 8 vCPU, 16 GiB): readiness in 373 s with 65,536 installed bans, idle 12 % of one core at that size. Version 0.4.7 upgraded schema 24 to 25 (pre25-backup), added on_truncation and the ignore commands, qualified PortSentry stealth and UDP, and cut idle CPU at 2,000 bans to a 2.61 % mean on a one-vCPU, 4 GiB host. Figures are measurements, not guarantees.
## Qualification
Release targets: x86_64-linux-musl, aarch64-linux-musl, arm-linux-musleabihf, mips-linux-musleabi and mipsel-linux-musleabi.
Selected live-kernel release qualification is Debian 13 x86_64. The five static targets are cross-built and checked with platform-appropriate evidence; the other four targets have emulated command checks. The PortSentry recipe qualified Debian 13 IPv4/IPv6 connect-mode (0.4.3) and stealth-mode TCP and UDP (0.4.7) events through nftables ban, expiry and restored connectivity. Live qualification is x86_64 only. See the release notes and artifact-verification guide for exact scope.
## Documentation
- [Features](https://fail2zig.com/features)
- [Integrations](https://fail2zig.com/integrations)
- [Docs](https://fail2zig.com/docs)
- [0.4.8 release notes](https://github.com/ul0gic/fail2zig/blob/v0.4.8/RELEASE_NOTES.md)
- [0.4.7 release notes](https://github.com/ul0gic/fail2zig/blob/v0.4.7/RELEASE_NOTES.md)
- [Upgrade to 0.4.8](https://fail2zig.com/docs/guides/upgrading-to-0-4-8)
- [Log file lifecycle](https://fail2zig.com/docs/guides/log-lifecycle)
- [PortSentry setup](https://fail2zig.com/docs/guides/portsentry)
- [Migrate from fail2ban](https://fail2zig.com/docs/guides/migration-from-fail2ban)
- [Configuration](https://fail2zig.com/docs/reference/config)
- [Daemon and offline commands](https://fail2zig.com/docs/reference/cli-fail2zig)
- [Administration](https://fail2zig.com/docs/reference/cli-fail2zig-client)
- [Filters and rules](https://fail2zig.com/docs/reference/filters)
- [Runtime dependencies](https://fail2zig.com/docs/architecture/zero-dependencies)
- [Threat model](https://fail2zig.com/threat-model)
- [Engine threat model document](https://github.com/ul0gic/fail2zig/blob/v0.4.8/docs/security/threat-model.md)
- [Artifact verification](https://fail2zig.com/docs/guides/verifying-zero-dependencies)
- [Changelog](https://fail2zig.com/changelog)
- [Demo](https://fail2zig.com/demo)
- [Privacy](https://fail2zig.com/privacy)
- [Terms](https://fail2zig.com/terms)
Report vulnerabilities through [GitHub Private Security Advisories](https://github.com/ul0gic/fail2zig/security/advisories/new).