1
.TH JAIL.CONF "5" "March 2013" "Fail2Ban" "Fail2Ban Configuration"
3
jail.conf \- configuration for the fail2ban server
5
.I jail.conf / jail.local
7
.I action.d/*.conf action.d/*.local
9
.I filter.d/*.conf filter.d/*.local
11
Fail2ban has three configuration file types. Action files are the commands for banning and unbanning of IP address,
12
Filter files tell fail2ban how to detect authentication failures, and Jail configurations combine filters with actions into jails.
14
There are *.conf files that are distributed by fail2ban and *.local file that contain user customizations.
15
It is recommended that *.conf files should remain unchanged. If needed, customizations should be provided in *.local files.
16
For instance, if you would like to customize the [ssh-iptables-ipset] jail, create a jail.local to extend jail.conf
17
(the configuration for the fail2ban server). The jail.local file will be the following if you only need to enable
27
Override only the settings you need to change and the rest of the configuration will come from the corresponding
32
In addition to .local, for any .conf file there can be a corresponding
33
\fI.d/\fR directory to contain additional .conf files that will be read after the
34
appropriate .local file. Last parsed file will take precidence over
35
identical entries, parsed alphabetically, e.g.
38
\fIjail.d/01_enable.conf\fR - to enable a specific jail
41
\fIjail.d/02_custom_port.conf\fR - containing specific configuration entry to change the port of the jail specified in the configuration
44
\fIfail2ban.d/01_custom_log.conf\fR - containing specific configuration entry to use a different log path.
49
The following options are applicable to all jails. Their meaning is described in the default \fIjail.conf\fR file.
65
Action files specify which commands are executed to ban and unban an IP address. They are located under \fI/etc/fail2ban/action.d\fR.
67
Like with jail.conf files, if you desire local changes create an \fI[actionname].local\fR file in the \fI/etc/fail2ban/action.d\fR directory
68
and override the required settings.
70
Action files are ini files that have two sections, \fBDefinition\fR and \fBInit\fR .
72
The [Init] section allows for action-specific settings. In \fIjail.conf/jail.local\fR these can be overwritten for a particular jail as options to the jail.
74
The following commands can be present in the [Definition] section.
77
command(s) executed when the jail starts.
80
command(s) executed when the jail stops.
83
the command ran before any other action. It aims to verify if the environment is still ok.
86
command(s) that bans the IP address after \fBmaxretry\fR log lines matches within last \fBfindtime\fR seconds.
89
command(s) that unbans the IP address after \fBbantime\fR.
91
Commands specified in the [Definition] section are executed through a system shell so shell redirection and process control is allowed. The commands should
92
return 0, otherwise error would be logged. Moreover if \fBactioncheck\fR exits with non-0 status, it is taken as indication that firewall status has changed and fail2ban needs to reinitialize itself (i.e. issue \fBactionstop\fR and \fBactionstart\fR commands).
94
Tags are enclosed in <>. All the elements of [Init] are tags that are replaced in all action commands. Tags can be added by the
95
\fBfail2ban-client\fR using the setctag command. \fB<br>\fR is a tag that is always a new line (\\n).
97
More than a single command is allowed to be specified. Each command needs to be on a separate line and indented with whitespaces without blank lines. The following example defines
98
two commands to be executed.
100
actionban = iptables -I fail2ban-<name> --source <ip> -j DROP
101
echo ip=<ip>, match=<match>, time=<time> >> /var/log/fail2ban.log
104
The following tags are substituted in the actionban, actionunban and actioncheck (when called before actionban/actionunban) commands.
107
An IPv4 ip address to be banned. e.g. 192.168.0.2
110
The number of times the failure occurred in the log file. e.g. 3
113
The unix time of the ban. e.g. 1357508484
116
The concatenated string of the log file lines of the matches that generated the ban. Many characters interpreted by shell get escaped.
120
Filter definitions are those in \fI/etc/fail2ban/filter.d/*.conf\fR and \fIfilter.d/*.local\fR.
122
These are used to identify failed authentication attempts in logs and to extract the host IP address (or hostname if \fBusedns\fR is \fBtrue\fR).
124
Like action files, filter files are ini files. The main section is the [Definition] section.
126
There are two filter definitions used in the [Definition] section:
130
is the regex (\fBreg\fRular \fBex\fRpression) that will match failed attempts. The tag <HOST> is used as part of the regex and is itself a regex
131
for IPv4 addresses and hostnames. fail2ban will work out which one of these it actually is.
135
is the regex to identify log entries that should be ignored by fail2ban, even if they match failregex.
138
Using Python "string interpolation" mechanisms, other definitions are allowed and can later be used within other definitions as %(defnname)s. For example.
140
baduseragents = IE|wget
141
failregex = useragent=%(baduseragents)s
144
Filters can also have a section called [INCLUDES]. This is used to read other configuration files.
148
indicates that this file is read before the [Definition] section.
152
indicates that this file is read after the [Definition] section.
155
Fail2ban was originally written by Cyril Jaquier <cyril.jaquier@fail2ban.org>.
156
At the moment it is maintained and further developed by Yaroslav O. Halchenko <debian@onerussian.com> and a number of contributors. See \fBTHANKS\fR file shipped with Fail2Ban for a full list.
158
Manual page written by Daniel Black and Yaroslav Halchenko.
160
Report bugs to https://github.com/fail2ban/fail2ban/issues
162
Copyright \(co 2013 Daniel Black
164
Copyright of modifications held by their respective authors.
165
Licensed under the GNU General Public License v2 (GPL).
added
removed
man/jail.conf.5
