fail2ban-client(1)

1FAIL2BAN-CLIENT(1)               User Commands              FAIL2BAN-CLIENT(1)
2
3
4

NAME

6       fail2ban-client - configure and control the server
7

SYNOPSIS

9       fail2ban-client [OPTIONS] <COMMAND>
10

DESCRIPTION

12       Fail2Ban  v1.0.2  reads  log file that contains password failure report
13       and bans the corresponding IP addresses using firewall rules.
14

OPTIONS

16       -c, --conf <DIR>
17              configuration directory
18
19       -s, --socket <FILE>
20              socket path
21
22       -p, --pidfile <FILE>
23              pidfile path
24
25       --pname <NAME>
26              name of the process (main thread) to identify instance  (default
27              fail2ban-server)
28
29       --loglevel <LEVEL>
30              logging level
31
32       --logtarget <TARGET>
33              logging  target,  use  file-name  or  stdout,  stderr, syslog or
34              sysout.
35
36       --syslogsocket auto|<FILE>
37
38       -d     dump configuration. For debugging
39
40       --dp, --dump-pretty
41              dump the configuration using more human readable representation
42
43       -t, --test
44              test configuration (can be also specified with start parameters)
45
46       -i     interactive mode
47
48       -v     increase verbosity
49
50       -q     decrease verbosity
51
52       -x     force execution of the server (remove socket file)
53
54       -b     start server in background (default)
55
56       -f     start server in foreground
57
58       --async
59              start server in async mode (for internal usage only, don't  read
60              configuration)
61
62       --timeout
63              timeout  to  wait for the server (for internal usage only, don't
64              read configuration)
65
66       --str2sec <STRING>
67              convert time abbreviation format to seconds
68
69       -h, --help
70              display this help message
71
72       -V, --version
73              print the version (-V returns machine-readable short format)
74

COMMAND

76              BASIC
77
78       start  starts the server and the jails
79
80       restart
81              restarts the server
82
83       restart [--unban] [--if-exists] <JAIL>
84              restarts the  jail  <JAIL>  (alias  for  'reload  --restart  ...
85              <JAIL>')
86
87       reload [--restart] [--unban] [--all]
88              reloads  the configuration without restarting of the server, the
89              option '--restart' activates completely restarting  of  affected
90              jails, thereby can unban IP addresses (if option '--unban' spec‐
91              ified)
92
93       reload [--restart] [--unban] [--if-exists] <JAIL>
94              reloads the jail <JAIL>, or restarts it (if  option  '--restart'
95              specified)
96
97       stop   stops all jails and terminate the server
98
99       unban --all
100              unbans all IP addresses (in all jails and database)
101
102       unban <IP> ... <IP>
103              unbans <IP> (in all jails and database)
104
105       banned return jails with banned IPs as dictionary
106
107       banned <IP> ... <IP>]
108              return list(s) of jails where given IP(s) are banned
109
110       status gets the current status of the server
111
112       ping   tests if the server is alive
113
114       echo   for internal usage, returns back and outputs a given string
115
116       help   return this output
117
118       version
119              return the server version
120
121              LOGGING
122
123       set loglevel <LEVEL>
124              sets  logging  level to <LEVEL>.  Levels: CRITICAL, ERROR, WARN‐
125              ING, NOTICE, INFO, DEBUG, TRACEDEBUG, HEAVYDEBUG or  correspond‐
126              ing numeric value (50-5)
127
128       get loglevel
129              gets the logging level
130
131       set logtarget <TARGET>
132              sets logging target to <TARGET>.  Can be STDOUT, STDERR, SYSLOG,
133              SYSTEMD-JOURNAL or a file
134
135       get logtarget
136              gets logging target
137
138       set syslogsocket auto|<SOCKET>
139              sets the syslog socket path to auto or <SOCKET>.  Only  used  if
140              logtarget is SYSLOG
141
142       get syslogsocket
143              gets syslog socket path
144
145       flushlogs
146              flushes  the  logtarget  if a file and reopens it. For log rota‐
147              tion.
148
149              DATABASE
150
151       set dbfile <FILE>
152              set the location of fail2ban persistent datastore. Set to "None"
153              to disable
154
155       get dbfile
156              get the location of fail2ban persistent datastore
157
158       set dbmaxmatches <INT>
159              sets the max number of matches stored in database per ticket
160
161       get dbmaxmatches
162              gets the max number of matches stored in database per ticket
163
164       set dbpurgeage <SECONDS>
165              sets the max age in <SECONDS> that history of bans will be kept
166
167       get dbpurgeage
168              gets the max age in seconds that history of bans will be kept
169
170              JAIL CONTROL
171
172       add <JAIL> <BACKEND>
173              creates <JAIL> using <BACKEND>
174
175       start <JAIL>
176              starts the jail <JAIL>
177
178       stop <JAIL>
179              stops the jail <JAIL>. The jail is removed
180
181       status <JAIL> [FLAVOR]
182              gets  the  current status of <JAIL>, with optional flavor or ex‐
183              tended info
184
185              JAIL CONFIGURATION
186
187       set <JAIL> idle on|off
188              sets the idle state of <JAIL>
189
190       set <JAIL> ignoreself true|false
191              allows the ignoring of own IP addresses
192
193       set <JAIL> addignoreip <IP>
194              adds <IP> to the ignore list of <JAIL>
195
196       set <JAIL> delignoreip <IP>
197              removes <IP> from the ignore list of <JAIL>
198
199       set <JAIL> ignorecommand <VALUE>
200              sets ignorecommand of <JAIL>
201
202       set <JAIL> ignorecache <VALUE>
203              sets ignorecache of <JAIL>
204
205       set <JAIL> addlogpath <FILE> ['tail']
206              adds <FILE> to the monitoring list of <JAIL>, optionally  start‐
207              ing at the 'tail' of the file (default 'head').
208
209       set <JAIL> dellogpath <FILE>
210              removes <FILE> from the monitoring list of <JAIL>
211
212       set <JAIL> logencoding <ENCODING>
213              sets the <ENCODING> of the log files for <JAIL>
214
215       set <JAIL> addjournalmatch <MATCH>
216              adds <MATCH> to the journal filter of <JAIL>
217
218       set <JAIL> deljournalmatch <MATCH>
219              removes <MATCH> from the journal filter of <JAIL>
220
221       set <JAIL> addfailregex <REGEX>
222              adds  the  regular  expression <REGEX> which must match failures
223              for <JAIL>
224
225       set <JAIL> delfailregex <INDEX>
226              removes the regular expression at <INDEX> for failregex
227
228       set <JAIL> addignoreregex <REGEX>
229              adds the regular expression <REGEX> which should  match  pattern
230              to exclude for <JAIL>
231
232       set <JAIL> delignoreregex <INDEX>
233              removes the regular expression at <INDEX> for ignoreregex
234
235       set <JAIL> findtime <TIME>
236              sets the number of seconds <TIME> for which the filter will look
237              back for <JAIL>
238
239       set <JAIL> bantime <TIME>
240              sets the number of seconds <TIME> a  host  will  be  banned  for
241              <JAIL>
242
243       set <JAIL> datepattern <PATTERN>
244              sets the <PATTERN> used to match date/times for <JAIL>
245
246       set <JAIL> usedns <VALUE>
247              sets the usedns mode for <JAIL>
248
249       set <JAIL> attempt <IP> [<failure1> ... <failureN>]
250              manually notify about <IP> failure
251
252       set <JAIL> banip <IP> ... <IP>
253              manually Ban <IP> for <JAIL>
254
255       set <JAIL> unbanip [--report-absent] <IP> ... <IP>
256              manually Unban <IP> in <JAIL>
257
258       set <JAIL> maxretry <RETRY>
259              sets  the number of failures <RETRY> before banning the host for
260              <JAIL>
261
262       set <JAIL> maxmatches <INT>
263              sets the max number of matches stored in memory  per  ticket  in
264              <JAIL>
265
266       set <JAIL> maxlines <LINES>
267              sets the number of <LINES> to buffer for regex search for <JAIL>
268
269       set <JAIL> addaction <ACT>[ <PYTHONFILE> <JSONKWARGS>]
270              adds  a  new  action  named  <ACT>  for <JAIL>. Optionally for a
271              Python based action, a  <PYTHONFILE>  and  <JSONKWARGS>  can  be
272              specified, else will be a Command Action
273
274       set <JAIL> delaction <ACT>
275              removes the action <ACT> from <JAIL>
276
277              COMMAND ACTION CONFIGURATION
278
279       set <JAIL> action <ACT> actionstart <CMD>
280              sets the start command <CMD> of the action <ACT> for <JAIL>
281
282       set <JAIL> action <ACT> actionstop <CMD> sets the stop command <CMD> of
283       the
284              action <ACT> for <JAIL>
285
286       set <JAIL> action <ACT> actioncheck <CMD>
287              sets the check command <CMD> of the action <ACT> for <JAIL>
288
289       set <JAIL> action <ACT> actionban <CMD>
290              sets the ban command <CMD> of the action <ACT> for <JAIL>
291
292       set <JAIL> action <ACT> actionunban <CMD>
293              sets the unban command <CMD> of the action <ACT> for <JAIL>
294
295       set <JAIL> action <ACT> timeout <TIMEOUT>
296              sets <TIMEOUT> as the command timeout in seconds for the  action
297              <ACT> for <JAIL>
298
299              GENERAL ACTION CONFIGURATION
300
301       set <JAIL> action <ACT> <PROPERTY> <VALUE>
302              sets the <VALUE> of <PROPERTY> for the action <ACT> for <JAIL>
303
304       set <JAIL> action <ACT> <METHOD>[ <JSONKWARGS>]
305              calls  the  <METHOD>  with <JSONKWARGS> for the action <ACT> for
306              <JAIL>
307
308              JAIL INFORMATION
309
310       get <JAIL> banned
311              return banned IPs of <JAIL>
312
313       get <JAIL> banned <IP> ... <IP>]
314              return 1 if IP is banned in <JAIL> otherwise 0, or a list of 1/0
315              for multiple IPs
316
317       get <JAIL> logpath
318              gets the list of the monitored files for <JAIL>
319
320       get <JAIL> logencoding
321              gets the encoding of the log files for <JAIL>
322
323       get <JAIL> journalmatch
324              gets the journal filter match for <JAIL>
325
326       get <JAIL> ignoreself
327              gets the current value of the ignoring the own IP addresses
328
329       get <JAIL> ignoreip
330              gets the list of ignored IP addresses for <JAIL>
331
332       get <JAIL> ignorecommand
333              gets ignorecommand of <JAIL>
334
335       get <JAIL> failregex
336              gets  the list of regular expressions which matches the failures
337              for <JAIL>
338
339       get <JAIL> ignoreregex
340              gets the list of regular expressions which matches  patterns  to
341              ignore for <JAIL>
342
343       get <JAIL> findtime
344              gets  the  time for which the filter will look back for failures
345              for <JAIL>
346
347       get <JAIL> bantime
348              gets the time a host is banned for <JAIL>
349
350       get <JAIL> datepattern
351              gets the pattern used to match date/times for <JAIL>
352
353       get <JAIL> usedns
354              gets the usedns setting for <JAIL>
355
356       get <JAIL> banip [<SEP>|--with-time]
357              gets the list of of banned IP addresses for  <JAIL>.  Optionally
358              the  separator  character ('<SEP>', default is space) or the op‐
359              tion '--with-time' (printing the times of ban) may be specified.
360              The IPs are ordered by end of ban.
361
362       get <JAIL> maxretry
363              gets the number of failures allowed for <JAIL>
364
365       get <JAIL> maxmatches
366              gets  the  max  number of matches stored in memory per ticket in
367              <JAIL>
368
369       get <JAIL> maxlines
370              gets the number of lines to buffer for <JAIL>
371
372       get <JAIL> actions
373              gets a list of actions for <JAIL>
374
375              COMMAND ACTION INFORMATION
376
377       get <JAIL> action <ACT> actionstart
378              gets the start command for the action <ACT> for <JAIL>
379
380       get <JAIL> action <ACT> actionstop
381              gets the stop command for the action <ACT> for <JAIL>
382
383       get <JAIL> action <ACT> actioncheck
384              gets the check command for the action <ACT> for <JAIL>
385
386       get <JAIL> action <ACT> actionban
387              gets the ban command for the action <ACT> for <JAIL>
388
389       get <JAIL> action <ACT> actionunban
390              gets the unban command for the action <ACT> for <JAIL>
391
392       get <JAIL> action <ACT> timeout
393              gets the command timeout in seconds for  the  action  <ACT>  for
394              <JAIL>
395
396              GENERAL ACTION INFORMATION
397
398       get <JAIL> actionproperties <ACT>
399              gets a list of properties for the action <ACT> for <JAIL>
400
401       get <JAIL> actionmethods <ACT>
402              gets a list of methods for the action <ACT> for <JAIL>
403
404       get <JAIL> action <ACT> <PROPERTY>
405              gets the value of <PROPERTY> for the action <ACT> for <JAIL>
406

FILES

408       /etc/fail2ban/*
409

REPORTING BUGS

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