1JAIL.CONF(5)                Fail2Ban Configuration                JAIL.CONF(5)
2
3
4

NAME

6       jail.conf - configuration for the fail2ban server
7

SYNOPSIS

9       fail2ban.conf fail2ban.d/*.conf fail2ban.local fail2ban.d/*.local
10
11       jail.conf jail.d/*.conf jail.local jail.d/*.local
12
13       action.d/*.conf action.d/*.local action.d/*.py
14
15       filter.d/*.conf filter.d/*.local
16
17

DESCRIPTION

19       Fail2ban has four configuration file types:
20
21
22       fail2ban.conf
23              Fail2Ban global configuration (such as logging)
24
25       filter.d/*.conf
26              Filters specifying how to detect authentication failures
27
28       action.d/*.conf
29              Actions  defining  the  commands for banning and unbanning of IP
30              address
31
32       jail.conf
33              Jails defining combinations of Filters with Actions.
34
35
36

CONFIGURATION FILES FORMAT

38       *.conf files are distributed  by  Fail2Ban.   It  is  recommended  that
39       *.conf files should remain unchanged to ease upgrades.  If needed, cus‐
40       tomizations should be provided in *.local files.  For example,  if  you
41       would  like  to  enable  the  [ssh-iptables-ipset]  jail  specified  in
42       jail.conf, create jail.local containing
43
44
45       jail.local
46              [ssh-iptables-ipset]
47
48              enabled = true
49
50
51       In .local files specify only the settings you would like to change  and
52       the  rest  of  the  configuration will then come from the corresponding
53       .conf file which is parsed first.
54
55
56       jail.d/ and fail2ban.d/
57
58              In addition to .local, for jail.conf or fail2ban.conf file there
59              can be a corresponding .d/ directory containing additional .conf
60              files. The order e.g. for jail configuration would be:
61
62              jail.conf
63              jail.d/*.conf (in alphabetical order)
64              jail.local
65              jail.d/*.local (in alphabetical order).
66
67              i.e. all .local files are parsed after .conf files in the origi‐
68              nal  configuration  file and files under .d directory.  Settings
69              in the file parsed later take precedence over identical  entries
70              in  previously  parsed files.  Files are ordered alphabetically,
71              e.g.
72
73              fail2ban.d/01_custom_log.conf - to use a different log path
74              jail.d/01_enable.conf - to enable a specific jail
75              jail.d/02_custom_port.conf - to change the port(s) of a jail.
76
77       Configuration files have sections, those specified with [section name],
78       and  name  = value pairs. For those name items that can accept multiple
79       values, specify the values separated by spaces, or  in  separate  lines
80       space indented at the beginning of the line before the second value.
81
82
83       Configuration  files can include other (defining common variables) con‐
84       figuration files, which is often used  in  Filters  and  Actions.  Such
85       inclusions are defined in a section called [INCLUDES]:
86
87
88       before indicates  that  the  specified  file is to be parsed before the
89              current file.
90
91       after  indicates that the specified file is to be parsed after the cur‐
92              rent file.
93
94       Using  Python  "string interpolation" mechanisms, other definitions are
95       allowed and can later be used within other definitions as %(name)s.
96
97       Fail2ban has more advanced syntax (similar python  extended  interpola‐
98       tion).  This  extended  interpolation is using %(section/parameter)s to
99       denote a value from a foreign section.
100       Besides cross section interpolation the value of parameter in [DEFAULT]
101       section can be retrieved with %(default/parameter)s.
102       Fail2ban supports also another feature named %(known/parameter)s (means
103       last known option with name parameter). This interpolation makes possi‐
104       ble to extend a stock filter or jail regexp in .local file (opposite to
105       simply set failregex/ignoreregex that overwrites it), e.g.
106
107              baduseragents = IE|wget|%(my-settings/baduseragents)s
108              failregex = %(known/failregex)s
109                          useragent=%(baduseragents)s
110
111       Additionally to interpolation %(known/parameter)s, that does not  works
112       for  filter/action init parameters, an interpolation tag <known/parame‐
113       ter> can be used (means  last  known  init  definition  of  filters  or
114       actions  with  name  parameter).  This  interpolation makes possible to
115       extend a parameters of stock filter or action directly in  jail  inside
116       jail.conf/jail.local   file   without   creating   a   separately  fil‐
117       ter.d/*.local file, e.g.
118
119              # filter.d/test.conf:
120              [Init]
121              test.method = GET
122              baduseragents = IE|wget
123              [Definition]
124              failregex = ^%(__prefix_line)\s+"<test.method>"\s+test\s+regexp\s+-\s+useragent=(?:<baduseragents>)
125
126              # jail.local:
127              [test]
128              # use filter "test", overwrite method to "POST" and extend known bad agents with "badagent":
129              filter = test[test.method=POST, baduseragents="badagent|<known/baduseragents>"]
130
131       Comments: use '#' for comment lines and '; ' (space is  important)  for
132       inline  comments.  When  using  Python2.X, '; ' can only be used on the
133       first line due to an Python library bug.
134
135

FAIL2BAN CONFIGURATION FILE(S) (fail2ban.conf)

137       These files have one section, [Definition].
138
139       The items that can be set are:
140
141       loglevel
142              verbosity level of log output: CRITICAL, ERROR, WARNING, NOTICE,
143              INFO,  DEBUG,  TRACEDEBUG,  HEAVYDEBUG  or corresponding numeric
144              value (50-5). Default: ERROR (equal 40)
145
146       logtarget
147              log target: filename, SYSLOG, STDERR or STDOUT. Default:  STDOUT
148              if not set in fail2ban.conf/fail2ban.local
149              Note. If fail2ban running as systemd-service, for logging to the
150              systemd-journal, the logtarget could be set to STDOUT
151              Only a single log target can be specified.  If you  change  log‐
152              target  from  the  default  value and you are using logrotate --
153              also adjust or disable rotation in the corresponding  configura‐
154              tion file (e.g. /etc/logrotate.d/fail2ban on Debian systems).
155
156       socket socket filename.  Default: /var/run/fail2ban/fail2ban.sock
157              This  is used for communication with the fail2ban server daemon.
158              Do not remove this file when Fail2ban is running. It will not be
159              possible to communicate with the server afterwards.
160
161       pidfile
162              PID filename.  Default: /var/run/fail2ban/fail2ban.pid
163              This is used to store the process ID of the fail2ban server.
164
165       dbfile Database filename. Default: /var/lib/fail2ban/fail2ban.sqlite3
166              This  defines  where the persistent data for fail2ban is stored.
167              This persistent data allows bans to be reinstated  and  continue
168              reading  log  files from the last read position when fail2ban is
169              restarted. A value of None disables this feature.
170
171       dbpurgeage
172              Database purge age in seconds. Default: 86400 (24hours)
173              This sets the age at which bans should be purged from the  data‐
174              base.
175
176

JAIL CONFIGURATION FILE(S) (jail.conf)

178       The following options are applicable to any jail. They appear in a sec‐
179       tion specifying the jail name or in the [DEFAULT] section which defines
180       default values to be used if not specified in the individual section.
181
182       filter name   of   the   filter   --   filename   of   the   filter  in
183              /etc/fail2ban/filter.d/ without the .conf/.local extension.
184              Only one filter can be specified.
185
186       logpath
187              filename(s) of the log files to be monitored, separated  by  new
188              lines.
189              Globs  --  paths containing * and ? or [0-9] -- can be used how‐
190              ever only the files that exist at start up  matching  this  glob
191              pattern will be considered.
192
193              Optional  space  separated option 'tail' can be added to the end
194              of the path to cause the log file to be read from the end,  else
195              default 'head' option reads file from the beginning
196
197              Ensure  syslog  or the program that generates the log file isn't
198              configured to compress repeated log messages to  "*last  message
199              repeated  5  time*s"  otherwise  it will fail to detect. This is
200              called RepeatedMsgReduction in rsyslog and should be Off.
201
202       logencoding
203              encoding of log files used for decoding. Default value of "auto"
204              uses current system locale.
205
206       logtimezone
207              Force the time zone for log lines that don't have one.
208
209              If  this  option  is  not  specified,  log  lines  from which no
210              explicit time zone has been found are interpreted by fail2ban in
211              its own system time zone, and that may turn to be inappropriate.
212              While the best practice is to configure the  monitored  applica‐
213              tions  to include explicit offsets, this option is meant to han‐
214              dle cases where that is not possible.
215
216              The supported time zones in this option  are  those  with  fixed
217              offset:  Z,  UTC[+-]hhmm  (you  can  also use GMT as an alias to
218              UTC).
219
220              This option has no effect on log lines on which an explicit time
221              zone has been found.  Examples:
222
223                      logtimezone = UTC
224                      logtimezone = UTC+0200
225                      logtimezone = GMT-0100
226
227
228       banaction
229              banning  action (default iptables-multiport) typically specified
230              in the [DEFAULT] section for all jails.
231              This parameter will be used  by  the  standard  substitution  of
232              action  and  can  be  redefined central in the [DEFAULT] section
233              inside jail.local (to apply it to all jails at  once)  or  sepa‐
234              rately in each jail, where this substitution will be used.
235
236       banaction_allports
237              the  same  as banaction but for some "allports" jails like "pam-
238              generic" or "recidive" (default iptables-allports).
239
240       action action(s) from /etc/fail2ban/action.d/ without the  .conf/.local
241              extension.
242              Arguments  can be passed to actions to override the default val‐
243              ues from the [Init] section in the action  file.  Arguments  are
244              specified by:
245
246                     [name=value,name2=value,name3="values,values"]
247
248              Values  can also be quoted (required when value includes a ",").
249              More that one action can be specified (in separate lines).
250
251       ignoreself
252              boolean value (default true) indicates the  banning  of  own  IP
253              addresses should be prevented
254
255       ignoreip
256              list  of  IPs not to ban. They can include a DNS resp. CIDR mask
257              too. The option affects additionally to ignoreself (if true) and
258              don't need to contain own DNS resp. IPs of the running host.
259
260       ignorecommand
261              command  that  is executed to determine if the current candidate
262              IP for banning (or failure-ID for raw IDs) should not be banned.
263              The  option  affects additionally to ignoreself and ignoreip and
264              will be first executed if both don't hit.
265              IP will not be banned if command returns successfully (exit code
266              0).   Like  ACTION  FILES, tags like <ip> are can be included in
267              the ignorecommand value and will be  substituted  before  execu‐
268              tion.
269
270       ignorecache
271              provide  cache  parameters (default disabled) for ignore failure
272              check (caching of the result from `ignoreip`,  `ignoreself`  and
273              `ignorecommand`), syntax:
274
275                      ignorecache = key="<F-USER>@<ip-host>", max-count=100, max-time=5m
276                      ignorecommand = if [ "<F-USER>" = "technical" ] && [ "<ip-host>" = "my-host.example.com" ]; then exit 0; fi;
277                                      exit 1
278              This  will  cache  the result of ignorecommand (does not call it
279              repeatedly) for 5 minutes (cache time) for maximal  100  entries
280              (cache  size),  using  values  substituted  like  "user@host" as
281              cache-keys.  Set option ignorecache to empty value disables  the
282              cache.
283
284       bantime
285              effective ban duration (in seconds or time abbreviation format).
286
287       findtime
288              time  interval  (in  seconds or time abbreviation format) before
289              the current time where failures will count towards a ban.
290
291       maxretry
292              number of failures that have to occur in the last findtime  sec‐
293              onds to ban then IP.
294
295       backend
296              backend to be used to detect changes in the logpath.
297              It defaults to "auto" which will try "pyinotify", "gamin", "sys‐
298              temd" before "polling". Any of these can be  specified.  "pyino‐
299              tify" is only valid on Linux systems with the "pyinotify" Python
300              libraries. "gamin" requires the "gamin" libraries.
301
302       usedns use DNS to resolve HOST  names  that  appear  in  the  logs.  By
303              default it is "warn" which will resolve hostnames to IPs however
304              it will also log a warning. If you are using DNS here you  could
305              be  blocking  the  wrong  IPs  due  to  the asymmetric nature of
306              reverse DNS (that the application used to write the domain  name
307              to  log)  compared  to forward DNS that fail2ban uses to resolve
308              this back to an IP (but not necessarily the same  one).  Ideally
309              you  should  configure  your applications to log a real IP. This
310              can be set to "yes" to prevent warnings in the log  or  "no"  to
311              disable  DNS  resolution altogether (thus ignoring entries where
312              hostname, not an IP is logged)..
313
314       failregex
315              regex (Python regular expression) to be added  to  the  filter's
316              failregexes. If this is useful for others using your application
317              please share you regular expression with the fail2ban developers
318              by reporting an issue (see REPORTING BUGS below).
319
320       ignoreregex
321              regex  which,  if the log line matches, would cause Fail2Ban not
322              consider that line.  This  line  will  be  ignored  even  if  it
323              matches a failregex of the jail or any of its filters.
324
325
326   Backends
327       Available options are listed below.
328
329       pyinotify
330              requires  pyinotify (a file alteration monitor) to be installed.
331              If pyinotify is not installed, Fail2ban will use auto.
332
333       gamin  requires Gamin (a file alteration monitor) to be  installed.  If
334              Gamin is not installed, Fail2ban will use auto.
335
336       polling
337              uses  a  polling  algorithm  which  does  not  require  external
338              libraries.
339
340       systemd
341              uses systemd python library to access the systemd journal. Spec‐
342              ifying  logpath  is  not  valid  for  this  backend  and instead
343              utilises journalmatch from the jails associated filter config.
344
345
346   Actions
347       Each jail can be configured with only a single  filter,  but  may  have
348       multiple  actions. By default, the name of a action is the action file‐
349       name, and in the case of Python actions, the ".py"  file  extension  is
350       stripped. Where multiple of the same action are to be used, the actname
351       option can be assigned to the action to avoid duplication e.g.:
352
353       [ssh-iptables-ipset]
354       enabled = true
355       action = smtp.py[dest=chris@example.com, actname=smtp-chris]
356                smtp.py[dest=sally@example.com, actname=smtp-sally]
357
358

TIME ABBREVIATION FORMAT

360       The time entries in fail2ban configuration (like findtime  or  bantime)
361       can be provided as integer in seconds or as string using special abbre‐
362       viation format (e. g. 600 is the same as 10m).
363
364
365       Abbreviation tokens:
366
367              years?, yea?, yy?
368              months?, mon?
369              weeks?, wee?, ww?
370              days?, da, dd?
371              hours?, hou?, hh?
372              minutes?, min?, mm?
373              seconds?, sec?, ss?
374
375              The question mark (?) means the optional character, so day as well as days can be used.
376
377       You can combine multiple tokens in format (separated with  space  resp.
378       without separator), e. g.: 1y 6mo or 1d12h30m.
379       Note that tokens m as well as mm means minutes, for month use abbrevia‐
380       tion mo or mon.
381
382       The time format can be tested using fail2ban-client:
383
384              fail2ban-client --str2sec 1d12h
385
386

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

388       Action files specify which commands are executed to ban and unban an IP
389       address.
390
391       Like  with  jail.conf  files,  if  you  desire  local changes create an
392       [actionname].local file in  the  /etc/fail2ban/action.d  directory  and
393       override the required settings.
394
395       Action files have two sections, Definition and Init .
396
397       The    [Init]    section    enables    action-specific   settings.   In
398       jail.conf/jail.local these can be overridden for a particular  jail  as
399       options of the action's specification in that jail.
400
401       The following commands can be present in the [Definition] section.
402
403       actionstart
404              command(s) executed when the jail starts.
405
406       actionstop
407              command(s) executed when the jail stops.
408
409       actioncheck
410              command(s) ran before any other action. It aims to verify if the
411              environment is still ok.
412
413       actionban
414              command(s) that bans the IP address  after  maxretry  log  lines
415              matches within last findtime seconds.
416
417       actionunban
418              command(s) that unbans the IP address after bantime.
419
420       The   [Init]   section   allows   for   action-specific   settings.  In
421       jail.conf/jail.local these can be overwritten for a particular jail  as
422       options to the jail. The following are special tags which can be set in
423       the [Init] section:
424
425       timeout
426              The maximum period of time in seconds that a  command  can  exe‐
427              cuted, before being killed.
428
429       Commands  specified  in the [Definition] section are executed through a
430       system shell so shell redirection and process control is  allowed.  The
431       commands should return 0, otherwise error would be logged.  Moreover if
432       actioncheck exits with non-0 status, it is  taken  as  indication  that
433       firewall  status  has changed and fail2ban needs to reinitialize itself
434       (i.e. issue actionstop and actionstart commands).  Tags are enclosed in
435       <>.   All  the  elements  of  [Init]  are tags that are replaced in all
436       action commands.  Tags can be added by the  fail2ban-client  using  the
437       "set  <JAIL>  action <ACT>" command. <br> is a tag that is always a new
438       line (\n).
439
440       More than a single command is allowed to  be  specified.  Each  command
441       needs  to be on a separate line and indented with whitespace(s) without
442       blank lines. The following example defines two commands to be executed.
443
444        actionban = iptables -I fail2ban-<name> --source <ip> -j DROP
445                    echo    ip=<ip>,     match=<match>,     time=<time>     >>
446       /var/log/fail2ban.log
447
448
449   Action Tags
450       The  following  tags  are substituted in the actionban, actionunban and
451       actioncheck (when called before actionban/actionunban) commands.
452
453       ip     IPv4 IP address to be banned. e.g. 192.168.0.2
454
455       failures
456              number of times the failure occurred in the log file. e.g. 3
457
458       ipfailures
459              As per failures, but total of all failures for that  ip  address
460              across  all  jails from the fail2ban persistent database. There‐
461              fore the database must be set for this tag to function.
462
463       ipjailfailures
464              As per ipfailures, but total based on the IPs failures  for  the
465              current jail.
466
467       time   UNIX (epoch) time of the ban. e.g. 1357508484
468
469       matches
470              concatenated  string  of  the log file lines of the matches that
471              generated the ban. Many  characters  interpreted  by  shell  get
472              escaped to prevent injection, nevertheless use with caution.
473
474       ipmatches
475              As per matches, but includes all lines for the IP which are con‐
476              tained with the  fail2ban  persistent  database.  Therefore  the
477              database must be set for this tag to function.
478
479       ipjailmatches
480              As per ipmatches, but matches are limited for the IP and for the
481              current jail.
482
483

PYTHON ACTION FILES

485       Python based actions can also be used, where  the  file  name  must  be
486       [actionname].py.  The  Python file must contain a variable Action which
487       points to Python class. This class must implement a  minimum  interface
488       as  described by fail2ban.server.action.ActionBase, which can be inher‐
489       ited from to ease implementation.
490
491

FILTER FILES (filter.d/*.conf)

493       Filter definitions are those in /etc/fail2ban/filter.d/*.conf and  fil‐
494       ter.d/*.local.
495
496       These  are used to identify failed authentication attempts in log files
497       and to extract the host IP address (or hostname if usedns is true).
498
499       Like action files, filter files are ini files. The main section is  the
500       [Definition] section.
501
502       There are two filter definitions used in the [Definition] section:
503
504       failregex
505              is  the  regex  (regular  expression)  that  will  match  failed
506              attempts. The tag <HOST> is used as part of  the  regex  and  is
507              itself  a  regex  for  IPv4 addresses (and hostnames if usedns).
508              Fail2Ban will work out which one of these it actually  is.   For
509              multiline  regexs the tag <SKIPLINES> should be used to separate
510              lines. This allows lines between the matched lines  to  continue
511              to  be searched for other failures. The tag can be used multiple
512              times.
513
514
515       ignoreregex
516              is the regex to identify log entries that should be  ignored  by
517              Fail2Ban, even if they match failregex.
518
519
520
521       Similar  to  actions, filters have an [Init] section which can be over‐
522       ridden in jail.conf/jail.local. Besides the  filter-specific  settings,
523       the  filter  [Init]  section  can  be  used  to  set following standard
524       options:
525
526       maxlines
527              specifies the maximum number of lines to buffer to match  multi-
528              line  regexs.  For some log formats this will not required to be
529              changed. Other logs may require to increase this value if a par‐
530              ticular log file is frequently written to.
531
532       datepattern
533              specifies  a  custom date pattern/regex as an alternative to the
534              default date detectors e.g. %Y-%m-%d %H:%M(?::%S)?. For  a  list
535              of valid format directives, see Python library documentation for
536              strptime behaviour.
537              Also, special values  of  Epoch  (UNIX  Timestamp),  TAI64N  and
538              ISO8601 can be used.
539              NOTE:  due  to config file string substitution, that %'s must be
540              escaped by an % in config files.
541
542       journalmatch
543              specifies the systemd journal match used to filter  the  journal
544              entries.  See  journalctl(1)  and  systemd.journal-fields(7) for
545              matches syntax and more details on special journal fields.  This
546              option is only valid for the systemd backend.
547
548       Similar to actions [Init] section enables filter-specific settings. All
549       parameters specified in [Init] section can be redefined or extended  in
550       jail.conf/jail.local.
551
552       Filters can also have a section called [INCLUDES]. This is used to read
553       other configuration files.
554
555
556       before indicates that this file is read before  the  [Definition]  sec‐
557              tion.
558
559
560       after  indicates that this file is read after the [Definition] section.
561
562

AUTHOR

564       Fail2ban     was     originally     written     by     Cyril    Jaquier
565       <cyril.jaquier@fail2ban.org>.  At the moment it is maintained and  fur‐
566       ther developed by Yaroslav O. Halchenko <debian@onerussian.com>, Daniel
567       Black  <daniel.subs@internode.on.net>  and  Steven  Hiscocks   <steven-
568       fail2ban@hiscocks.me.uk>  along  with  a  number  of contributors.  See
569       THANKS file shipped with Fail2Ban for a full list.  Manual page written
570       by Daniel Black and Yaroslav Halchenko.
571

REPORTING BUGS

573       Report bugs to https://github.com/fail2ban/fail2ban/issues
574
576       Copyright © 2013 the Fail2Ban Team
577       Copyright of modifications held by their respective authors.
578       Licensed  under  the  GNU  General  Public License v2 (GPL) or (at your
579       option) any later version.
580

SEE ALSO

582       fail2ban-server(1)
583
584
585
586Fail2Ban                         November 2015                    JAIL.CONF(5)
Impressum