Configuration reference

The default file is /etc/fail2zig/config.toml. Use the worked example as a starting point and validate before starting or reloading. This reference describes 0.4.8 native operation.

File format and permissions

The parser accepts a strict TOML subset: [global], [defaults] and [jails.<name>]. Unknown keys/sections, duplicate keys, mixed array types and invalid values are rejected. Use section headers, not dotted keys on the left. Comments begin with #; strings must be quoted. Jail names use ASCII letters, digits, hyphens or underscores.

Keep configuration administrator-owned and readable by the service. World-writable or non-root-group-writable configuration is refused. A non-root owner warns. The installer preserves existing operator configuration; check its permissions when changing the service group.

Duration strings

bantime, findtime, bantime_increment_max_bantime, bantime_increment_jitter, bantime_increment_decay and ignoretime accept integer seconds or quoted durations in both defaults and jail overrides. The duration part of a banip or ignoreip entry uses the same terms as one word inside the entry string, for example "198.51.100.0/24 1d".

[defaults]
bantime = "1h30m"
findtime = "10m"
bantime_increment_max_bantime = "1w"
bantime_increment_jitter = "30s"
bantime_increment_decay = "30d"

Months and years are fixed intervals, not calendar arithmetic. Each term is a nonnegative integer followed by a unit; terms can touch or have intervening whitespace ("1h 30m"). Fractions, signed terms, arithmetic, unknown units and overflow are rejected. Bare 24h is not valid TOML.

Finite bantime, findtime and the escalation cap must be positive. Jitter permits zero and must not exceed the cap. 0 disables bantime_increment_decay and makes ignoretime permanent. An entry’s duration must be finite, at least 1s and at most 100 × 366 days. Only bantime accepts "permanent". On the command line, ban --duration and ignore add --for accept seconds or this syntax; --timeout and migration window arguments remain numeric.

[global]

Logging and administration

The socket is mode 0660. The configured service/monitor group has read-only access. Mutations require root or the daemon UID, verified with peer credentials. Every mutation writes one audit line to the daemon log with the command, target, caller UID and outcome. Use fail2zig --socket <path> status when overriding the default socket.

State and resource limits

The database and its parent must belong to the daemon UID. The historical .bin extension does not make it the legacy binary format. Native startup refuses corrupt, incompatible or inaccessible required state instead of starting empty. The file cannot grow past 1 GiB; a file already past that size is refused at startup. When a commit finds the file full, ingestion pauses and retries while rules already in the kernel stay enforced. The file never shrinks; rows removed by retention free pages for reuse inside it, and status shows the size and page use. A configuration that sets native_memory_ceiling_mb = 256 explicitly must raise it or the daemon refuses with NativeMemoryAdmission. Storage failure pauses affected ingestion and reports degraded health while retaining protection. Preserve the database and WAL/SHM coherently; do not delete them to clear an error. See upgrades and the memory model.

HTTP and WebSocket

Endpoints are /metrics, /api/status, /api/bans, /api/health and /events. Health reports readiness with HTTP 200/503. HTTP shares the privileged daemon process. Keep external access controlled or disable it if unused. The per-jail metric names are listed in the administration reference.

Firewall

firewall is a global string, default "auto".

An explicit backend never silently switches to another. With existing state, auto keeps the recorded backend across restarts, including when no bans are active. An explicit backend or namespace selector that conflicts with the saved installation is rejected rather than migrating ownership. Restore the recorded setting or use auto; do not delete the database to switch backends. Jail enforce selects enforcement policy, not a backend. If every enabled jail is log-only, enforcement backend detection is skipped.

on_no_backend is "fail-closed" by default: unusable required enforcement causes startup refusal. "log-only" explicitly permits degraded observe-only operation; status reports the cause. It does not install protection.

firewall_namespace is an ownership anchor, not a request to enter another namespace. Effects remain in the daemon’s current network namespace. Custom selectors and unit overrides that move the daemon between namespaces are unsupported; leave this setting at its built-in default.

DNS and timezone data

dns_server is an optional resolver IP; dns_port defaults to 53 and accepts 1–65535. Native hostname rules use bounded resolution and retain retry state; a hostname is not an arbitrary command. timezone_root defaults to "/usr/share/zoneinfo" for named timezone data. Leave these defaults unless the chosen input contract requires an explicit deployment setting.

[defaults]

Prefer enforce = true/false in new configurations. banaction remains accepted for compatibility and emits a deprecation warning when explicitly set. Do not combine the two in one section. Neither setting selects the firewall backend or enables arbitrary shell actions.

Configured bans and exclusions

A banip entry is a live ban with origin config in that jail, permanent for a permanent entry and ending at the stored deadline for a timed one. It takes over an existing ban of the same address in the jail and replaces its expiry with its own. Removing an entry and reloading lifts its ban at once. While a config ban is live, fail2zig ban or unban of the address is refused with banned by config: edit banip. A jail holds at most 1,024 effective banip entries. Host names are not accepted.

An address in both the effective ignoreip and the effective banip of one jail, as equal entries or one containing the other, is a configuration error: the daemon refuses to start, and reload reports rejected naming the jail and the address.

ignoreself reads the host’s addresses from the kernel at start and at every reload; an address assigned later counts from the next reload. self entries do not count against the 128-entry ignore limit. A jail list for ignoreip or banip replaces, rather than appends to, the [defaults] list.

ignoretime is unset or 0 for permanent. A jail value overrides [defaults], and 0 in a jail restores permanent under a [defaults] value. A duration written on the entry, or ignore add --for, wins. A non-zero value on a rule_files jail is refused.

Timed entries

A banip or ignoreip entry written with a duration, and an ignoreip entry that takes ignoretime, is timed. The period starts when the daemon first applies the entry, at start or at a reload, and runs once: a reload or a restart does not restart it. Changing the entry’s duration, or the ignoretime it takes, starts a fresh period, as does removing the entry, reloading and adding it back. When the period runs out the entry stays in the file and does nothing; list or ignore list shows it as expired until it is removed from the file. A timed ignoreip entry is refused on a jail with rule_files.

Escalation

Linear uses bantime × multiplier × (1 + factor × n); exponential uses bantime × multiplier × factor^n, where n is the prior ban count used by the policy. For doubling with no jitter, set multiplier 1, factor 2 and formula "exponential". A multiplier of 2 alone does not select doubling growth.

Decay is measured from the end of the last ban, not its start, so nothing decays during a live ban and a permanent ban never decays. The reset is complete, never a step down; 0 disables it. After a manual unban, failures count from zero again while the escalation count is kept.

Escalation settings inherit field by field. A jail overrides only the keys it explicitly sets; omitted keys retain [defaults] values.

[jails.<name>]

A jail declares a source, matcher and policy. Enabled jails must have admitted protection; unknown built-in filters without native rule files fail validation.

on_truncation applies to every logpath of the jail and covers a file truncated in place, a rotated-out file removed with unread bytes, and a log replaced by a different file. refuse pauses the source until repair-source acknowledges the loss; the daemon keeps running and other jails enforce. restart resumes and records a continuity-loss event. The diagnostics are InvalidTruncationPolicy, TruncationPolicyNotFileSource and TruncationPolicyNotAllowedInDefaults. A change is restart-only. Neither value recovers records that were never read.

Source and time contracts

[jails.sshd]
filter = "sshd"
source = "journald"
journal_executables = ["/usr/sbin/sshd", "/usr/lib/openssh/sshd-session"]

auto resolves the configured source at startup. file reads declared paths; journald requires journalctl and admitted origins; internal is the confirmed-ban feed for recidive. Internal recidive does not use log paths or custom rule files. A built-in SSH jail with no journal_executables setting discovers available root-owned executables from a bounded catalog of standard SSH paths. Discovery rejects unsafe path ownership or permissions. An explicit nonempty list remains an exact override; an empty list is invalid, and custom journal rules require an explicit profile. A source is healthy only after its runtime checks pass; configuration validation alone is not that check. A missing log file is reported as missing (FileNotFound) by jails and is not a failure. See log watching and the log file lifecycle.

For PortSentry v2.0.7, use filter = "portsentry", source = "file" and timestamp = "iso8601" with the history file. Follow the sensor and jail setup; this is not a generic syslog or legacy PortSentry input. PortSentry recreates its history file at every start, so choose on_truncation for that jail deliberately. File encoding replacement is described under log watching.

Deprecated and migration-managed settings

backend is a deprecated source alias accepted in defaults/jails: systemd maps to journald; auto, polling, pyinotify and gamin map to auto. Using both source and backend in one section is an error. It never chooses the firewall backend.

native_ingestion defaults to true; disabling native operation is not a supported deployment route. compatibility_manifest and compatibility_pending are migration-managed admission metadata. Do not clear blockers by hand to force an unsupported imported jail into service.

Validation and reload

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

Diagnostics identify file, line, column, section and key when available. Unreadable files and permission failures can be positionless. Validation summarizes configured sources and prints on_truncation=<value> for each file jail; an auto source is resolved when the daemon starts. Inspect the actual source and readiness through fail2zig jails and fail2zig status.

Some settings apply through fail2zig reload; others return restart_required. Adding a jail to the file and removing one are live changes. See the reload table. Neither successful syntax validation nor a reload request establishes installed firewall protection.

The tagged parser, shipped example and fail2zig.toml(5) define the release’s accepted configuration.