Ubuntu Manpage: jail.conf - configuration for the fail2ban server

NAME

       jail.conf - configuration for the fail2ban server

SYNOPSIS

       fail2ban.conf fail2ban.d/*.conf fail2ban.d/*.local

       jail.conf / jail.local

       action.d/*.conf action.d/*.local

       filter.d/*.conf filter.d/*.local

DESCRIPTION

Fail2ban has three configuration file types. Action files are the commands for banning and
unbanning of IP address, Filter files tell fail2ban how to detect authentication failures,
and Jail configurations combine filters with actions into jails.

There are *.conf files that are distributed by fail2ban and *.local file that contain user
customizations. It is recommended that *.conf files should remain unchanged. If needed,
customizations should be provided in *.local files. For instance, if you would like to
customize the [ssh-iptables-ipset] jail, create a jail.local to extend jail.conf (the
configuration for the fail2ban server). The jail.local file will be the following if you
only need to enable it:

jail.local
[ssh-iptables-ipset]

enabled = true

Override only the settings you need to change and the rest of the configuration will come
from the corresponding *.conf file.

*.d/
In addition to .local, for any .conf file there can be a corresponding .d/
directory to contain additional .conf files that will be read after the appropriate
.local file. Last parsed file will take precidence over identical entries, parsed
alphabetically, e.g.

jail.d/01_enable.conf - to enable a specific jail
jail.d/02_custom_port.conf - containing specific configuration entry to
change the port of the jail specified in the configuration
fail2ban.d/01_custom_log.conf - containing specific configuration entry to
use a different log path.

The order jail configuration is parsed is:

jail.conf , jail.d/*.conf (in alphabetical order), jail.local, followed by jail.d/*.local
(in alphabetical order).

Likewise for fail2ban configuration.

Comments: use '#' for comment lines and ';' (following a space) for inline comments

DEFAULT

       The  following  options  are  applicable  to  all jails. Their meaning is described in the
       default jail.conf file.

       ignoreip

       bantime

       findtime

       maxretry

       backend

       usedns

ACTION FILES

       Action files specify which commands are executed to ban and unban an IP address. They  are
       located under /etc/fail2ban/action.d.

       Like  with  jail.conf files, if you desire local changes create an [actionname].local file
       in the /etc/fail2ban/action.d directory and override the required settings.

       Action files are ini files that have two sections, Definition and Init .

       The [Init] section allows for action-specific settings. In jail.conf/jail.local these  can
       be overwritten for a particular jail as options to the jail.

       The following commands can be present in the [Definition] section.

       actionstart
              command(s) executed when the jail starts.

       actionstop
              command(s) executed when the jail stops.

       actioncheck
              the  command  ran  before any other action. It aims to verify if the environment is
              still ok.

       actionban
              command(s) that bans the IP address after maxretry log lines  matches  within  last
              findtime seconds.

       actionunban
              command(s) that unbans the IP address after bantime.

              Commands  specified in the [Definition] section are executed through a system shell
              so shell redirection and process control is allowed. The commands should return  0,
              otherwise  error would be logged.  Moreover if actioncheck exits with non-0 status,
              it is taken as indication that firewall status has changed and  fail2ban  needs  to
              reinitialize itself (i.e. issue actionstop and actionstart commands).

              Tags  are enclosed in <>.  All the elements of [Init] are tags that are replaced in
              all action commands.  Tags can be added by the fail2ban-client  using  the  setctag
              command. <br> is a tag that is always a new line (\n).

              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 two commands to be executed.

               actionban = iptables -I fail2ban-<name> --source <ip> -j DROP
                           echo ip=<ip>, match=<match>, time=<time> >> /var/log/fail2ban.log

   Action Tags
       The  following  tags  are  substituted in the actionban, actionunban and actioncheck (when
       called before actionban/actionunban) commands.

       ip     An IPv4 ip address to be banned. e.g. 192.168.0.2

       failures
              The number of times the failure occurred in the log file. e.g. 3

       time   The unix time of the ban. e.g. 1357508484

       matches
              The concatenated string of the log file lines of the  matches  that  generated  the
              ban. Many characters interpreted by shell get escaped.

FILTER FILES

       Filter definitions are those in /etc/fail2ban/filter.d/*.conf and filter.d/*.local.

       These  are used to identify failed authentication attempts in logs and to extract the host
       IP address (or hostname if usedns is true).

       Like action files, filter files are ini  files.  The  main  section  is  the  [Definition]
       section.

       There are two filter definitions used in the [Definition] section:

       failregex
              is  the  regex (regular expression) that will match failed attempts. The tag <HOST>
              is used as part of the  regex  and  is  itself  a  regex  for  IPv4  addresses  and
              hostnames. fail2ban will work out which one of these it actually is.

       ignoreregex
              is  the  regex  to identify log entries that should be ignored by fail2ban, even if
              they match failregex.

              Using Python "string interpolation" mechanisms, other definitions are  allowed  and
              can later be used within other definitions as %(defnname)s. For example.

               baduseragents = IE|wget
               failregex = useragent=%(baduseragents)s

       Filters  can  also  have  a  section  called  [INCLUDES].  This  is  used  to  read  other
       configuration files.

       before indicates that this file is read before the [Definition] section.

       after  indicates that this file is read after the [Definition] section.

AUTHOR

       Fail2ban was originally written by Cyril  Jaquier  <cyril.jaquier@fail2ban.org>.   At  the
       moment   it   is   maintained   and   further   developed   by   Yaroslav   O.   Halchenko
       <debian@onerussian.com> and a number  of  contributors.   See  THANKS  file  shipped  with
       Fail2Ban for a full list.  Manual page written by Daniel Black and Yaroslav Halchenko.

REPORTING BUGS

       Report bugs to https://github.com/fail2ban/fail2ban/issues

COPYRIGHT

       Copyright © 2013 Daniel Black
       Copyright  of  modifications  held  by  their  respective authors.  Licensed under the GNU
       General Public License v2 (GPL).