# fail2ban jail options reference

> Reference for every fail2ban jail option: enabled, logpath, backend, port, banaction, bantime, ignoreip, usedns and more, with type, default and an example.
>
> Source: https://fail2ban.dev/config/jail-options/ · Updated 2026-10-25 · Checked against fail2ban 1.1.1
> fail2ban.dev is an independent guide, not the official fail2ban project.

A fail2ban jail combines a **filter** (what counts as a failure), a **log source** (`logpath` or the journal), **thresholds** (`maxretry` failures within `findtime` cause a ban of `bantime`) and **actions** (how to ban). Set any option in `[DEFAULT]` to apply it to every jail, or in a jail section such as `[sshd]` to override it for that jail. The stock defaults are `bantime = 10m`, `findtime = 10m`, `maxretry = 5`, `backend = auto` and `enabled = false`.

```ini
[sshd]
enabled  = true          ; turn the jail on
port     = ssh           ; ports to block
backend  = systemd       ; read the journal instead of a file
maxretry = 3             ; failures…
findtime = 10m           ; …within this window…
bantime  = 1h            ; …ban for this long
```

## Core jail options

| Option | Type | Default | What it does |
|---|---|---|---|
| `enabled` | bool | `false` | Turns the jail on. Every stock jail is off until you set `enabled = true`. |
| `filter` | name[opts] | `%(__name__)s[mode=%(mode)s]` | Filter file in `filter.d/` without extension. Defaults to the jail name, so `[sshd]` uses `sshd.conf`. One filter per jail. |
| `mode` | string | `normal` | Filter mode passed to filters that support modes, e.g. `sshd`: `normal`, `ddos`, `extra`, `aggressive`. |
| `logpath` | path(s) | from `paths-*.conf` | Log file(s) to read. Globs allowed; one path per line. Ignored with `backend = systemd`. |
| `backend` | string | `auto` | How logs are read: `auto`, `pyinotify`, `polling` or `systemd[...]`. See [backends](/config/backend/). |
| `journalmatch` | string | from filter | systemd journal filter, e.g. `_SYSTEMD_UNIT=sshd.service + _COMM=sshd`. Only used by the systemd backend (and needed for the auto switch to it). |
| `port` | list | `0:65535` | Ports the action blocks: names from `/etc/services` or numbers, comma-separated, ranges with `:`. |
| `protocol` | string | `tcp` | Protocol for the firewall rule: `tcp`, `udp`, or `all` (supported by the nftables and iptables actions). |
| `skip_if_nologs` | bool | `false` | If no file matches `logpath`, skip this jail with a warning instead of failing the whole start (1.1.1+). |
| `systemd_if_nologs` | bool | `true` | With `backend = auto`, switch to the systemd backend when no log file is found and a `journalmatch` exists (1.1.1+). |

### logpath examples

```ini
enabled = true
logpath = /var/log/nginx/error.log
          /var/log/nginx/sites/*-error.log

[myapp]
# read from the end of the file only (skip old lines on start)
logpath = /var/log/myapp.log tail
```

## Ban timing options

| Option | Type | Default | What it does |
|---|---|---|---|
| `bantime` | time | `10m` | Ban duration. `-1` = permanent. With incremental bans, the first ban's length. |
| `findtime` | time | `10m` | Window in which failures are counted. |
| `maxretry` | int | `5` | Failures within `findtime` that trigger a ban. |
| `maxmatches` | int | `%(maxretry)s` | Matched log lines kept per IP in memory (what `<matches>` shows in emails). |

How these three interact, recommended values and the `-1` / `0` edge cases: [bantime, findtime and maxretry](/config/bantime-findtime-maxretry/).

### Incremental ban options

All are unset (off) by default. Details and worked examples are on [incremental bans](/config/bantime-increment/).

| Option | Type | Default | What it does |
|---|---|---|---|
| `bantime.increment` | bool | off | Make each repeat ban of an IP longer. Needs the database (`dbfile`). |
| `bantime.factor` | number | `1` | Coefficient used by the formula or multipliers. |
| `bantime.formula` | Python expr | `ban.Time * (1<<(ban.Count if ban.Count<20 else 20)) * banFactor` | How the next ban time is computed (1, 2, 4, 8… × bantime). |
| `bantime.multipliers` | list | unset | Explicit multipliers instead of the formula, e.g. `1 2 4 8 16 32 64`. |
| `bantime.maxtime` | time | unset | Upper limit for an increased ban. |
| `bantime.rndtime` | time | unset | Random extra seconds (0 to this value) added to each increased ban. |
| `bantime.overalljails` | bool | `false` | Count previous bans of the IP in all jails, not just this one. |

## Action options

| Option | Type | Default | What it does |
|---|---|---|---|
| `banaction` | action[opts] | `nftables` (Debian paths in 1.1.1); `iptables-multiport` before 1.1.1 | Firewall action used by the `action_*` shortcuts for per-port bans. |
| `banaction_allports` | action[opts] | `nftables[type=allports]`; `iptables-allports` before 1.1.1 | Same for all-port bans (used by `recidive`, `pam-generic`). |
| `action` | action list | `%(action_)s` | What happens on a ban. One action per line; several allowed. |
| `chain` | string | `<known/chain>` | Firewall chain for actions that take one. `<known/chain>` means "the action's own default" (`INPUT` for iptables, `f2b-chain` for nftables). |
| `destemail` | email | `root@localhost` | Recipient for the mail shortcuts. |
| `sender` | email | `root@<fq-hostname>` | From address for mail actions. |
| `mta` | string | `sendmail` | Mail action family: `sendmail` (sendmail-compatible binary) or `mail`. |
| `fail2ban_agent` | string | `Fail2Ban/%(fail2ban_version)s` | User agent string for reporting actions that call web APIs. |

The action shortcuts defined in `jail.conf`:

| Shortcut | Does |
|---|---|
| `%(action_)s` | Ban only (the default) |
| `%(action_mw)s` | Ban + email with whois report |
| `%(action_mwl)s` | Ban + email with whois report and matching log lines |
| `%(action_xarf)s` | Ban + X-ARF abuse report email to the IP's abuse contact |
| `%(action_cf_mwl)s` | Ban on Cloudflare (legacy API key) + email with log lines |
| `%(action_blocklist_de)s` | Report to blocklist.de (needs `blocklist_de_apikey`) |
| `%(action_abuseipdb)s` | Report to AbuseIPDB |

Combine them by listing several actions, one per line:

```ini
enabled = true
action  = %(action_)s
          abuseipdb[abuseipdb_apikey="YOUR_KEY", abuseipdb_category="18,22"]
```

## Ignore (whitelist) options

| Option | Type | Default | What it does |
|---|---|---|---|
| `ignoreip` | list | empty | IPs, CIDR ranges, hostnames or `file:/path` sets that are never banned. A jail value replaces the `[DEFAULT]` one. |
| `ignoreself` | bool | `true` | Never ban the server's own addresses (interface IPs, `localhost`, its hostname). |
| `ignorecommand` | command | empty | Script run for each candidate IP; exit code `0` means "don't ban". `<ip>` is substituted. |
| `ignorecache` | key/size/time | disabled | Caches ignore decisions, e.g. `key="<ip>", max-count=100, max-time=5m`. |

```ini
ignoreip = 127.0.0.1/8 ::1 192.168.1.0/24 home.example.net file:/etc/fail2ban/ignore.list
```

## Log parsing options

| Option | Type | Default | What it does |
|---|---|---|---|
| `usedns` | string | `warn` | What to do with hostnames in logs: `yes` (resolve), `warn` (resolve and log a warning), `no` (only ban IPs), `raw` (use the matched value as-is, for non-IP IDs). |
| `logencoding` | string | `auto` | Log file encoding; `auto` uses the system locale. Set `utf-8` if you see decode errors. |
| `logtimezone` | string | server time zone | Time zone for log lines without one: `UTC`, `UTC+0200`, `GMT-0100`. |
| `datepattern` | pattern | from filter | Override how timestamps are found, e.g. `%%Y-%%m-%%d %%H:%%M:%%S` (note the doubled `%`). |
| `maxlines` | int | from filter (`1`) | Lines buffered for multi-line regexes. |
| `failregex` | regex(es) | from filter | Override or extend the filter's failure regexes from the jail. |
| `ignoreregex` | regex(es) | from filter | Lines matching these are never counted. |
| `prefregex` | regex | from filter | Common prefix every line must match before `failregex` runs. |

You can extend a stock filter's regexes from the jail with `%(known/failregex)s`:

```ini
enabled = true
ignoreregex = %(known/ignoreregex)s
              ^Connection closed by authenticating user deploy <HOST>
```

## Backend parameters

The `systemd` backend accepts parameters in brackets: `journalpath`, `journalfiles`, `journalflags`, `namespace` and `rotated` (1.1.1+, default off). Example:

```ini
```

## Variables you can use in values

| Variable | Value |
|---|---|
| `%(__name__)s` | Current jail (section) name |
| `%(fail2ban_version)s` | fail2ban version, e.g. `1.1.1` |
| `%(fail2ban_confpath)s` | Config directory, normally `/etc/fail2ban` |
| `%(default/option)s` | The `[DEFAULT]` value of `option` |
| `%(known/option)s` | The previously loaded value of `option` (to extend instead of replace) |
| `%(sshd_log)s`, `%(apache_error_log)s`, `%(nginx_access_log)s`… | Log paths from `paths-*.conf` |

## Change options at runtime

Many options can be changed on the running server without editing files (lost on restart or reload):

```text
$ sudo fail2ban-client set sshd bantime 86400
86400
$ sudo fail2ban-client get sshd maxretry
3
```

## Default jail.conf [DEFAULT] section

The stock `[DEFAULT]` section of fail2ban 1.1.1, with upstream comments. These values apply to every jail unless overridden:



## All predefined jails

Every jail defined in the stock `jail.conf`. All are disabled until you set `enabled = true` in `jail.local`. Each filter name links to its reference entry with the regexes and sample log lines:



## FAQ

### What are the default jail settings in fail2ban?

In the stock `jail.conf`: `bantime = 10m`, `findtime = 10m`, `maxretry = 5`, `backend = auto`, `usedns = warn`, `enabled = false`, `action = %(action_)s` (ban only) and `ignoreself = true`. Distributions add their own defaults in `/etc/fail2ban/jail.d/`, for example enabling the `sshd` jail.

### What is the default jail in fail2ban?

There is no single default jail. `jail.conf` defines nearly 100 jails, all disabled. Debian, Ubuntu and most other packages enable only `[sshd]` through a file in `/etc/fail2ban/jail.d/`. Run `sudo fail2ban-client status` to see which jails are running on your system.

### Can I set different settings per jail?

Yes. Put shared values in `[DEFAULT]` and override any option inside a jail section, for example `maxretry = 3` under `[sshd]`. A jail's value replaces the default completely; for lists like `ignoreip` use `%(default/ignoreip)s` to keep the default entries.

### How do I see the settings a jail is actually using?

Query the running server with `sudo fail2ban-client get <jail> <option>`, e.g. `get sshd maxretry` or `get sshd logpath`. To see the merged configuration from all files, run `sudo fail2ban-client -d`, which prints every resolved setting per jail.

### Which options can be set in [DEFAULT]?

Any jail option. In practice `[DEFAULT]` holds `bantime`, `findtime`, `maxretry`, `ignoreip`, `banaction`, `action`, `destemail` and the `bantime.*` options. Jail-specific options like `logpath`, `port` and `filter` belong in each jail.