xenial (1) jail.conf.10.gz

Provided by: fail2ban_0.9.3-1_all bug

NAME

       jail.conf - configuration for the fail2ban server

SYNOPSIS

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

       jail.conf jail.d/*.conf jail.local jail.d/*.local

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

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

DESCRIPTION

       Fail2ban has four configuration file types:

       fail2ban.conf
              Fail2Ban global configuration (such as logging)

       filter.d/*.conf
              Filters specifying how to detect authentication failures

       action.d/*.conf
              Actions defining the commands for banning and unbanning of IP address

       jail.conf
              Jails defining combinations of Filters with Actions.

CONFIGURATION FILES FORMAT

       *.conf files are distributed by Fail2Ban.  It is recommended that *.conf files should remain unchanged to
       ease upgrades.  If needed, customizations should be provided in *.local files.  For example, if you would
       like to enable the [ssh-iptables-ipset] jail specified in jail.conf, create jail.local containing

       jail.local
              [ssh-iptables-ipset]

              enabled = true

       In .local files specify only the settings you would like to change and the rest of the configuration will
       then come from the corresponding .conf file which is parsed first.

       jail.d/ and fail2ban.d/

              In addition to .local, for jail.conf or fail2ban.conf  file  there  can  be  a  corresponding  .d/
              directory containing additional .conf files. The order e.g. for jail configuration would be:

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

              i.e.  all  .local  files are parsed after .conf files in the original configuration file and files
              under .d directory.  Settings in the file parsed later take precedence over identical  entries  in
              previously parsed files.  Files are ordered alphabetically, e.g.

              fail2ban.d/01_custom_log.conf - to use a different log path
              jail.d/01_enable.conf - to enable a specific jail
              jail.d/02_custom_port.conf - to change the port(s) of a jail.

       Configuration files have sections, those specified with [section name], and name = value pairs. For those
       name items that can accept multiple values, specify the values separated by spaces, or in separate  lines
       space indented at the beginning of the line before the second value.

       Configuration  files  can  include  other (defining common variables) configuration files, which is often
       used in Filters and Actions. Such inclusions are defined in a section called [INCLUDES]:

       before indicates that the specified file is to be parsed before the current file.

       after  indicates that the specified file is to be parsed after the current file.

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

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

       Comments:  use  '#'  for  comment  lines  and  ';  ' (space is important) for inline comments. When using
       Python2.X '; ' can only be used on the first line due to an Python library bug.

FAIL2BAN CONFIGURATION FILE(S) (fail2ban.conf)

       These files have one section, [Definition].

       The items that can be set are:

       loglevel
              verbosity level of log output: CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG. Default: ERROR

       logtarget
              log target: filename, SYSLOG, STDERR or STDOUT. Default: STDERR . Only a single log target can  be
              specified.   If  you  change  logtarget from the default value and you are using logrotate -- also
              adjust or disable rotation in the corresponding configuration file (e.g. /etc/logrotate.d/fail2ban
              on Debian systems).

       socket socket  filename.  Default: /var/run/fail2ban/fail2ban.sock .  This is used for communication with
              the fail2ban server daemon. Do not remove this file when Fail2ban  is  running.  It  will  not  be
              possible to communicate with the server afterwards.

       pidfile
              PID  filename.   Default: /var/run/fail2ban/fail2ban.pid.  This is used to store the process ID of
              the fail2ban server.

       dbfile Database filename. Default: /var/lib/fail2ban/fail2ban.sqlite3 This defines where  the  persistent
              data  for  fail2ban  is  stored.  This  persistent  data allows bans to be reinstated and continue
              reading log files from the last read position when fail2ban is restarted. A value of None disables
              this feature.

       dbpurgeage
              Database  purge age in seconds. Default: 86400 (24hours) This sets the age at which bans should be
              purged from the database.

JAIL CONFIGURATION FILE(S) (jail.conf)

       The following options are applicable to any jail. They appear in a section specifying the jail name or in
       the [DEFAULT] section which defines default values to be used if not specified in the individual section.

       filter name  of  the filter -- filename of the filter in /etc/fail2ban/filter.d/ without the .conf/.local
              extension. Only one filter can be specified.

       logpath
              filename(s) of the log files to be monitored, separated by new lines. Globs -- paths containing  *
              and  ?  or  [0-9]  -- can be used however only the files that exist at start up matching this glob
              pattern will be considered.

              Optional space separated option 'tail' can be added to the end of the path to cause the  log  file
              to be read from the end, else default 'head' option reads file from the beginning

              Ensure syslog or the program that generates the log file isn't configured to compress repeated log
              messages to "*last message repeated 5 time*s" otherwise it will fail to  detect.  This  is  called
              RepeatedMsgReduction in rsyslog and should be Off.

       logencoding
              encoding of log files used for decoding. Default value of "auto" uses current system locale.

       action action(s) from /etc/fail2ban/action.d/ without the .conf/.local extension. Arguments can be passed
              to actions to override the default values from the [Init] section in the  action  file.  Arguments
              are specified by:

                     [name=value,name2=value,name3="values,values"]

              Values  can  also  be  quoted  (required  when  value includes a ","). More that one action can be
              specified (in separate lines).

       ignoreip
              list of IPs not to ban. They can include a CIDR mask too.

       ignorecommand
              command that is executed to determine if the current  candidate  IP  for  banning  should  not  be
              banned.  IP  will not be banned if command returns successfully (exit code 0).  Like ACTION FILES,
              tags like <ip> are can be included in the ignorecommand  value  and  will  be  substituted  before
              execution. Currently only <ip> is supported however more will be added later.

       bantime
              effective ban duration (in seconds).

       findtime
              time interval (in seconds) before the current time where failures will count towards a ban.

       maxretry
              number of failures that have to occur in the last findtime seconds to ban then IP.

       backend
              backend  to  be  used  to  detect  changes  in  the  logpath. It defaults to "auto" which will try
              "pyinotify", "gamin", "systemd" before "polling". Any of these can be  specified.  "pyinotify"  is
              only  valid  on  Linux systems with the "pyinotify" Python libraries. "gamin" requires the "gamin"
              libraries.

       usedns use DNS to resolve HOST names that appear in the logs. By default it is "warn" which will  resolve
              hostnames  to  IPs  however  it  will  also  log a warning. If you are using DNS here you could be
              blocking the wrong IPs due to the asymmetric nature of reverse DNS (that the application  used  to
              write  the  domain name to log) compared to forward DNS that fail2ban uses to resolve this back to
              an IP (but not necessarily the same one). Ideally you should configure your applications to log  a
              real IP. This can be set to "yes" to prevent warnings in the log or "no" to disable DNS resolution
              altogether (thus ignoring entries where hostname, not an IP is logged)..

       failregex
              regex (Python regular expression) to be added to the filter's failregexes. If this is  useful  for
              others  using your application please share you regular expression with the fail2ban developers by
              reporting an issue (see REPORTING BUGS below).

       ignoreregex
              regex which, if the log line matches, would cause Fail2Ban not consider that line.  This line will
              be ignored even if it matches a failregex of the jail or any of its filters.

   Backends
       Available options are listed below.

       pyinotify
              requires  pyinotify  (a  file  alteration monitor) to be installed. If pyinotify is not installed,
              Fail2ban will use auto.

       gamin  requires Gamin (a file alteration monitor) to be installed. If Gamin is  not  installed,  Fail2ban
              will use auto.

       polling
              uses a polling algorithm which does not require external libraries.

       systemd
              uses  systemd  python  library  to access the systemd journal. Specifying logpath is not valid for
              this backend and instead utilises journalmatch from the jails associated filter config.

   Actions
       Each jail can be configured with only a single filter, but may have multiple  actions.  By  default,  the
       name  of  a action is the action filename, and in the case of Python actions, the ".py" file extension is
       stripped. Where multiple of the same action are to be used, the actname option can  be  assigned  to  the
       action to avoid duplication e.g.:

       [ssh-iptables-ipset]
       enabled = true
       action = smtp.py[dest=chris@example.com, actname=smtp-chris]
                smtp.py[dest=sally@example.com, actname=smtp-sally]

ACTION CONFIGURATION FILES (action.d/*.conf)

       Action files specify which commands are executed to ban and unban an IP address.

       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 have two sections, Definition and Init .

       The [Init] section enables action-specific settings. In jail.conf/jail.local these can be overridden  for
       a particular jail as options of the action's specification in that 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
              command(s) 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.

       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 are special tags which  can  be  set  in  the
       [Init] section:

       timeout
              The maximum period of time in seconds that a command can executed, before being killed.

       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 "set <JAIL> action <ACT>" 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 whitespace(s) 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     IPv4 IP address to be banned. e.g. 192.168.0.2

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

       ipfailures
              As per failures, but total of all failures for that ip address across all jails from the  fail2ban
              persistent database. Therefore the database must be set for this tag to function.

       ipjailfailures
              As per ipfailures, but total based on the IPs failures for the current jail.

       time   UNIX (epoch) time of the ban. e.g. 1357508484

       matches
              concatenated  string  of the log file lines of the matches that generated the ban. Many characters
              interpreted by shell get escaped to prevent injection, nevertheless use with caution.

       ipmatches
              As per matches, but includes all lines for the IP which are contained with the fail2ban persistent
              database. Therefore the database must be set for this tag to function.

       ipjailmatches
              As per ipmatches, but matches are limited for the IP and for the current jail.

PYTHON ACTION FILES

       Python  based actions can also be used, where the file name must be [actionname].py. The Python file must
       contain a variable Action which points to Python class. This class must implement a minimum interface  as
       described by fail2ban.server.action.ActionBase, which can be inherited from to ease implementation.

FILTER FILES (filter.d/*.conf)

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

       These are used to identify failed authentication attempts in log files 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 if usedns). Fail2Ban will
              work out which one of these it actually is.  For multiline regexs the tag  <SKIPLINES>  should  be
              used to separate lines. This allows lines between the matched lines to continue to be searched for
              other failures. The tag can be used multiple times.

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

       Similar  to  actions, filters have an [Init] section which can be overridden in jail.conf/jail.local. The
       filter [Init] section is limited to the following options:

       maxlines
              specifies the maximum number of lines to buffer to match multi-line regexs. For some  log  formats
              this  will  not  required  to  be  changed.  Other  logs  may  require to increase this value if a
              particular log file is frequently written to.

       datepattern
              specifies a custom date pattern/regex as  an  alternative  to  the  default  date  detectors  e.g.
              %Y-%m-%d  %H:%M(?::%S)?.  For  a list of valid format directives, see Python library documentation
              for strptime behaviour.
              Also, special values of Epoch (UNIX Timestamp), TAI64N and ISO8601 can be used.
              NOTE: due to config file string substitution, that %'s must be escaped by an % in config files.

       journalmatch
              specifies the systemd journal match used to filter the  journal  entries.  See  journalctl(1)  and
              systemd.journal-fields(7)  for  matches  syntax  and  more details on special journal fields. This
              option is only valid for the systemd backend.

       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>,  Daniel  Black
       <daniel.subs@internode.on.net> and Steven Hiscocks <steven-fail2ban@hiscocks.me.uk> along with  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 © 2013 the Fail2Ban Team
       Copyright of modifications held by their respective authors.
       Licensed under the GNU General Public License v2 (GPL) or (at your option) any later version.

SEE ALSO

       fail2ban-server(1)