On this page

fail2zig — daemon and offline commands

Run, validate, test rules, repair sources, collect support bundles and prepare migrations with the unified 0.4.8 executable.

One executable contains the daemon, administration, rule testing and migration tools. Use fail2zig <command>; the separate fail2zig-client executable was retired in 0.4.0. For status, bans, exclusions, history and reload, see the administration reference.

Run the daemon

fail2zig [daemon] [OPTIONS]

The shipped systemd service runs as the non-login fail2zig user. It retains CAP_NET_ADMIN, CAP_NET_RAW and CAP_DAC_READ_SEARCH for firewall and log access. HTTP runs in that same privileged process. An all-log-only deployment can run without firewall capability when its file, journal and state permissions allow it.

Option	Behavior
`--config <path>`	Read configuration; default `/etc/fail2zig/config.toml`.
`--foreground`	Run in foreground, the only supported mode.
`--validate-config`	Validate configuration and print the configured jail summary without starting the daemon. This does not prove live source or firewall readiness.
`--test-config`	Alias for `--validate-config`.
`--version`, `-V`	Print the local executable version.
`--help`, `-h`	Print usage; it lists the same commands as `fail2zig help`.

fail2zig --version
sudo fail2zig --validate-config --config /etc/fail2zig/config.toml

The current release reports fail2zig 0.4.8 from --version. Use fail2zig version to query the running daemon; replacing a file on disk does not upgrade a process already running.

Configuration inspection and projection

sudo fail2zig migrate inspect --source-dir /etc/fail2ban
sudo fail2zig --import-config /etc/fail2ban --import-output /tmp/fail2zig-review.toml
sudo fail2zig --validate-config --config /tmp/fail2zig-review.toml

--import-config [<source-dir>] defaults to /etc/fail2ban. --import-output <path> defaults to /etc/fail2zig/config.toml; use a separate review path to avoid replacing your working configuration. This projects supported configuration, not database state. Unsupported enabled protection needs an explicit disposition before activation. A familiar filter name does not establish matching equivalence.

For state transfer, use the separate migration workflow.

Offline rule testing

fail2zig rule-test --file /path/to/sample.log --service sshd --timestamp undated
fail2zig rule-test --file /path/to/sample.log --rule-file /path/to/rule.json

Rule testing needs no running daemon and installs no bans. Reports distinguish matched, missed, ignored and rejected records. Test representative failures and successful logins, not just one matching line. Native rules use a bounded JSON format; fail2ban regexes and arbitrary shell actions are not executed.

Use --timestamp to select the input time format, --tz-offset or --time-zone when required, and --output json for structured results. The undated example above tests message matching; choose the actual time contract for your logs. See filters and custom rules.

Migration commands

fail2zig migrate provides inspect, snapshot, plan, validate, cutover, status and rollback. It accepts supported fail2ban schema-4 SQLite input; it does not convert fail2zig 0.3.0 binary state. Follow the migration guide for ownership, continuity, activation and rollback requirements.

Signals and service readiness

Signal	Behavior
`SIGTERM`, `SIGINT`	Stop cleanly. Installed rules stay in the kernel with their timeouts; run `firewall withdraw` first for an empty table.
`SIGHUP`	Validate and apply a supported live configuration generation; report invalid or restart-required changes.
`SIGUSR1`	Reopen `log_target` after rotation.

The unit uses Type=notify. READY=1 follows admission of configuration, storage, every source that can resume and enforcing protection; RELOADING=1 and STOPPING=1 report transitions. A source that cannot resume is paused and does not hold back readiness. No socket-activation unit ships. See reload boundaries.

Exit classes

Code	Meaning
0	Success.
1	Valid request rejected, or a required object absent.
2	Usage, parsing or local validation failure.
3	Daemon or transport unavailable; migration can also be pending activation.
4	Partial durable effect; protection confirmation is incomplete.
5	Uncertain durable effect; the outcome could not be established.

Scripts must inspect the exit class and structured outcome. A command that could not confirm an effect must not be treated as a successful ban.

Files

Path	Purpose
`/etc/fail2zig/config.toml`	Administrator-owned configuration.
`/run/fail2zig/fail2zig.sock`	Local monitoring and administration socket.
`/var/lib/fail2zig/state.bin`	Native SQLite database despite the historical extension; preserve WAL/SHM siblings in coherent offline backups.

pid_file is deprecated and not written. Use systemctl show -p MainPID fail2zig. The installed manuals are man fail2zig and man 5 fail2zig.toml.

Source repair and support bundles

A file source that lost continuity under on_truncation = "refuse" pauses while the daemon keeps running; status prints the repair-source command to run. The command uses the daemon’s socket when it answers and otherwise runs offline on the stopped daemon’s state, which is the path for a daemon that cannot start. It records the loss; it cannot recover log entries that were never read. Do not delete native state to bypass a refusal. See the log file lifecycle and the tagged fail2zig(1) procedure.

fail2zig support-bundle writes one redacted JSON file for a bug report and also works while the daemon is stopped; see the administration reference.

Edit on GitHub →