On this page

fail2zig — administration

Status, bans, history, jail controls, reload outcomes and monitoring permissions in 0.4.0.

Administration now uses the same fail2zig executable as the daemon. This page keeps its existing URL so bookmarks continue to work. For 0.3.0 instructions, consult the versioned manual.

Synopsis

fail2zig [--socket <path>] [--output table|json|plain] [--no-color] [--timeout <ms>] <command> [args]

The default socket is /run/fail2zig/fail2zig.sock; the default timeout is 5000 ms. table is for people, json for scripts and plain is tab-separated. CLI durations and timeouts remain integers; quoted configuration durations do not change them.

The socket is mode 0660. Members of the configured service/monitor group can read status. Root or the daemon UID can mutate protection, authenticated through SO_PEERCRED. Group membership alone does not grant ban, unban or reload authority. The shipped service uses fail2zig:fail2zig; the installer supports a custom group.

Status and inspection

fail2zig status
fail2zig jails
fail2zig list --jail sshd
fail2zig --output json history --jail sshd --limit 20
fail2zig config
fail2zig version

Command	What it reports
`status`	Version, protection, storage, backend, generation, counters and worker/clock health.
`jails`	Enabled/paused state, source, health, enforcing policy, thresholds and active bans.
`list [--jail <name>]`	Active bans, optionally restricted to one jail.
`history [--jail <name>] [--limit 1..256] [--cursor <token>]`	Confirmed history with bounded pagination.
`config`	Effective configuration; paths and address lists are redacted for non-administrators.
`version`	Running daemon version. `--version` instead reports the local executable.

A policy decision, installed protection and an uncertain effect are different states. Inspect storage and enforcement causes when the daemon is degraded.

Ban and unban

sudo fail2zig ban 203.0.113.7 --jail sshd --duration 600
sudo fail2zig unban 203.0.113.7 --jail sshd

Both commands require exactly one jail. --scope host is the default; --scope net <cidr> requires nftables or ipset. Unsupported scope is rejected. A manual ban on a log-only jail is rejected rather than recorded as installed. Removing one jail’s owner does not remove protection still owned by another jail.

JSON mutation reports include outcome, enforced, generation/revision and reasons. Exit 4 means partial and exit 5 means uncertain; neither is success. There is no unban --all command. Review list --output json and unban specific address/jail owners deliberately.

Jail controls and history

sudo fail2zig jail pause sshd
sudo fail2zig jail resume sshd
sudo fail2zig jail disable sshd
sudo fail2zig jail enable sshd
sudo fail2zig history reset 203.0.113.7 --jail sshd

Use pause/resume for processing control and enable/disable for jail state. Inspect the returned outcome and current owners; do not assume a control command is an unban. history reset <ip> --all resets that address’s history across jails. History reset is separate from removing active protection.

Reload

sudo fail2zig reload

Reload validates a complete proposed generation before publishing it. An invalid proposal leaves the running generation intact. Outcomes are noop, applied, rejected or restart_required, with reasons identifying the boundary.

Live changes	Require restart
Per-jail maxretry, bantime/permanent policy and escalation; global log level; contents of a custom jail’s ignore file	Findtime, literal ignore lists, source/filter/log paths, timestamp/timezone settings, journal executable list, rule files, log target and policy edits on disabled jails

Edit configuration for policy changes. fail2ban’s runtime set API, arbitrary regex mutation and dynamic actions are not supported. SIGHUP uses the same reload boundary. A restart-required outcome is not confirmation that your edit has taken effect.

Exit classes

Code	Class	Operator meaning
0	success	Operation completed; claimed effects were observed.
1	rejected	Valid request refused or object absent.
2	usage	Invalid arguments or local validation failure.
3	unavailable	Socket missing, refused or timed out.
4	partial	Durable effect applied but confirmation incomplete.
5	uncertain	Effect may have applied; outcome not established.

Use JSON for automation and branch on these classes, not formatted table text. Run fail2zig help <command> for command-specific arguments.

Prometheus and HTTP alternatives

HTTP defaults to 127.0.0.1:9100 and is read-only. It shares daemon privileges; loopback binding is not authentication. Keep remote access behind appropriate controls. metrics_enabled = false disables HTTP and WebSocket together while IPC remains available.

Endpoint	Purpose
`/metrics`	Native storage, worker, clock and expiry metrics.
`/api/status`	JSON operational status.
`/api/bans`	Ban snapshot.
`/api/health`	Readiness: HTTP 200 when ready, 503 when a component withholds readiness.
`/events`	WebSocket event stream.

Readiness covers configuration, storage, sources, clock, enforcement and admin components. An open connection or a recent metrics frame proves neither readiness nor recent attack activity.

curl --fail http://127.0.0.1:9100/api/health

Shell completions

fail2zig completions bash
fail2zig completions zsh
fail2zig completions fish

These print completion scripts. Install the output in your shell’s completion location under the fail2zig name.

Edit on GitHub →