FAIL2BAN-CLIENT(1)

📦
version 1.1.1 · 5 versions
, in arch rolling, nixpkgs unstable

💅 FAIL2BAN-CLIENT(1) 🎀

hii bestie!! you've landed on the FAIL2BAN-CLIENT(1) page — it lives in the User Commands section of the manual, and honestly? iconic placement. this is the lil client that lets you talk to your fail2ban server: configure it, poke it, control it. no cap, it's giving main character energy already 🦋

✨ NAME ✨

fail2ban-client — configure and control the server.

that's it. that's the whole job description. she configures, she controls, she slays 💅

🎀 SYNOPSIS 🎀

fail2ban-client [OPTIONS] <COMMAND>

🌸 DESCRIPTION 🌸

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

okay so in human words: she reads the log file that's full of password failure reports 😭 and then bans the matching IP addresses using firewall rules, like a bouncer with a clipboard and zero chill. fr fr 🔥

👑 OPTIONS 👑

grab a snack, there's a whole list 🍓

  • -c, --conf <DIR> — configuration directory. basically "bestie, the configs live HERE" 🗂️
  • -s, --socket <FILE> — socket path. the lil doorway she talks through 🔌
  • -p, --pidfile <FILE> — pidfile path. where she leaves her pid receipt 🧾
  • --pname <NAME> — name of the process (main thread) to identify instance, default is fail2ban-server. so you can be like "that one, yeah her" 💅
  • --loglevel <LEVEL> — logging level. how chatty she's feeling ✨
  • --logtarget <TARGET> — logging target, use file-name or stdout, stderr, syslog or sysout. pick her outfit, I mean her output 💖
  • --syslogsocket — auto|<FILE>. yes that's the whole thing.
  • -d — dump configuration. for debugging 🐛
  • --dp, --dump-pretty — dump the configuration using more human readable representation. a pretty dump, we love a glow-up ✨
  • -t, --test — test configuration (can be also specified with start parameters). vibe check your config before she commits, love that for us 🫶
  • -i — interactive mode. she wants engagement 💬
  • -v — increase verbosity. more words, more tea ☕
  • -q — decrease verbosity. shhh era 🤫
  • -x — force execution of the server (remove socket file). she's not asking, she's telling 💀
  • -b — start server in background (default). lurking, respectfully 🌙
  • -f — start server in foreground. front and center, main character style 👑
  • --async — start server in async mode. for internal usage only, don't read configuration ⚠️ like for real, this one's not for you
  • --timeout — timeout to wait for the server. for internal usage only, don't read configuration ⚠️ same energy, hands off bestie
  • --str2sec <STRING> — convert time abbreviation format to seconds. math but make it cute 🧮
  • -h, --help — display this help message. the classic "help me help you" 🙈
  • -V, --version — print the version (-V returns machine-readable short format). short and machine-readable, she's efficient like that 🌈

okay that's the options handled — but this page is not done with us yet, keep scrolling bestie 💜

✨ COMMAND ✨

okay bestie, this is the good part — every single thing you can actually do with fail2ban-client. Buckle in, there's like a million of them and they're all iconic in their own way 💅

🌸 BASIC 🌸

  • start — starts the server and the jails. the whole engine, up and running 🚀
  • restart — restarts the server. classic off-and-on-again energy.
  • restart [--unban] [--if-exists] <JAIL> — restarts the jail <JAIL>. it's literally just an alias for reload --restart ... <JAIL>, no cap 🫶
  • reload [--restart] [--unban] [--all] — reloads the config but doesn't restart the server itself. add --restart and the affected jails fully restart too, which can unban IP addresses (only if you also pass --unban, iykyk).
  • reload [--restart] [--unban] [--if-exists] <JAIL> — reloads just <JAIL>, or restarts it if you threw in --restart.
  • stop — stops all the jails and terminates the server. it's giving "closing time at the mall" 😭
  • unban --all — unbans every single IP address, in all jails and the database. mass forgiveness era 💖
  • unban <IP> ... <IP> — unbans the <IP>(s) you name, across all jails and the database.
  • banned — returns the jails that have banned IPs, as a dictionary.
  • banned <IP> ... <IP>] — returns the list(s) of jails where the given IP(s) are banned.
  • status — gets the current status of the server. the vibe check of the whole operation.
  • status --all [FLAVOR] — gets the status of all the jails, with an optional output style [FLAVOR]. the flavors are: 'basic' (default), 'cymru', 'short', 'stats' ✨
  • stat[istic]s — gets the current statistics of all jails as a table. numbers girlies rise 🍓
  • ping — tests if the server is alive. are you there bestie?? 👀
  • echo — for internal usage; returns back and outputs a given string.
  • version — returns the server version. slay, what era are we in 💅

💜 LOGGING 💜

  • set loglevel <LEVEL> — sets the logging level to <LEVEL>. the levels are: CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG, TRACEDEBUG, HEAVYDEBUG, or the corresponding numeric value (50-5).
  • get loglevel — gets the logging level.
  • set logtarget <TARGET> — sets the logging target to <TARGET>. can be STDOUT, STDERR, SYSLOG, SYSTEMD-JOURNAL, or a file.
  • get logtarget — gets the logging target.
  • set syslogsocket auto|<SOCKET> — sets the syslog socket path to auto or <SOCKET>. heads up: this is only used if logtarget is SYSLOG 🫶
  • get syslogsocket — gets the syslog socket path.
  • flushlogs — flushes the logtarget if it's a file and reopens it. for log rotation, periodt.

🦋 DATABASE 🦋

  • set dbfile <FILE> — sets the location of the fail2ban persistent datastore. set it to "None" to disable it entirely.
  • get dbfile — gets the location of the fail2ban persistent datastore.
  • set dbmaxmatches <INT> — sets the max number of matches stored in the database per ticket.
  • get dbmaxmatches — gets the max number of matches stored in the database per ticket.
  • set dbpurgeage <SECONDS> — sets the max age, in <SECONDS>, that the history of bans will be kept.
  • get dbpurgeage — gets the max age in seconds that the history of bans will be kept.

👑 JAIL CONTROL 👑

  • add <JAIL> <BACKEND> — creates <JAIL> using <BACKEND>.
  • start <JAIL> — starts the jail <JAIL>.
  • stop <JAIL> — stops the jail <JAIL>. ngl, the jail is removed.
  • status <JAIL> [FLAVOR] — gets the current status of <JAIL>, with an optional output style [FLAVOR]. flavors: 'basic' (default), 'cymru', 'short', 'stats'.

🎀 JAIL CONFIGURATION 🎀

  • set <JAIL> idle on|off — sets the idle state of <JAIL>.
  • set <JAIL> ignoreself true|false — allows the ignoring of your own IP addresses.
  • set <JAIL> addignoreip <IP> — adds <IP> to the ignore list of <JAIL>.
  • set <JAIL> delignoreip <IP> — removes <IP> from the ignore list of <JAIL>.
  • set <JAIL> ignorecommand <VALUE> — sets ignorecommand of <JAIL>.
  • set <JAIL> ignorecache <VALUE> — sets ignorecache of <JAIL>.
  • set <JAIL> addlogpath <FILE> ['tail'] — adds <FILE> to the monitoring list of <JAIL>, optionally starting at the 'tail' of the file (default is 'head').
  • set <JAIL> dellogpath <FILE> — removes <FILE> from the monitoring list of <JAIL>.
  • set <JAIL> logencoding <ENCODING> — sets the <ENCODING> of the log files for <JAIL>.
  • set <JAIL> addjournalmatch <MATCH> — adds <MATCH> to the journal filter of <JAIL>.
  • set <JAIL> deljournalmatch <MATCH> — removes <MATCH> from the journal filter of <JAIL>.
  • set <JAIL> addfailregex <REGEX> — adds the regular expression <REGEX>, which must match failures for <JAIL>.
  • set <JAIL> delfailregex <INDEX> — removes the regular expression at <INDEX> for failregex.
  • set <JAIL> addignoreregex <REGEX> — adds the regular expression <REGEX>, which should match patterns to exclude for <JAIL>.
  • set <JAIL> delignoreregex <INDEX> — removes the regular expression at <INDEX> for ignoreregex.
  • set <JAIL> findtime <TIME> — sets the number of seconds <TIME> for which the filter will look back for <JAIL>.
  • set <JAIL> bantime <TIME> — sets the number of seconds <TIME> a host will be banned for <JAIL>.
  • set <JAIL> datepattern <PATTERN> — sets the <PATTERN> used to match date/times for <JAIL>.
  • set <JAIL> usedns <VALUE> — sets the usedns mode for <JAIL>.
  • set <JAIL> attempt <IP> [<failure1> ... <failureN>] — manually notify about <IP> failure.
  • set <JAIL> banip <IP> ... <IP> — manually Ban <IP> for <JAIL>. you're the bouncer now 💅
  • set <JAIL> unbanip [--report-absent] <IP> ... <IP> — manually Unban <IP> in <JAIL>.
  • set <JAIL> maxretry <RETRY> — sets the number of failures <RETRY> before banning the host for <JAIL>.
  • set <JAIL> maxmatches <INT> — sets the max number of matches stored in memory per ticket in <JAIL>.
  • set <JAIL> maxlines <LINES> — sets the number of <LINES> to buffer for regex search for <JAIL>.
  • set <JAIL> addaction <ACT>[ <PYTHONFILE> <JSONKWARGS>] — adds a new action named <ACT> for <JAIL>. optionally, for a Python-based action, you can specify a <PYTHONFILE> and <JSONKWARGS>; otherwise it'll be a Command Action.
  • set <JAIL> delaction <ACT> — removes the action <ACT> from <JAIL>.

🌈 COMMAND ACTION CONFIGURATION 🌈

  • set <JAIL> action <ACT> actionstart <CMD> — sets the start command <CMD> of the action <ACT> for <JAIL>.
  • set <JAIL> action <ACT> actionstop <CMD> — sets the stop command <CMD> of the action <ACT> for <JAIL>.
  • set <JAIL> action <ACT> actioncheck <CMD> — sets the check command <CMD> of the action <ACT> for <JAIL>.
  • set <JAIL> action <ACT> actionban <CMD> — sets the ban command <CMD> of the action <ACT> for <JAIL>.
  • set <JAIL> action <ACT> actionunban <CMD> — sets the unban command <CMD> of the action <ACT> for <JAIL>.
  • set <JAIL> action <ACT> timeout <TIMEOUT> — sets <TIMEOUT> as the command timeout in seconds for the action <ACT> for <JAIL>.

🧚 GENERAL ACTION CONFIGURATION 🧚

  • set <JAIL> action <ACT> <PROPERTY> <VALUE> — sets the <VALUE> of <PROPERTY> for the action <ACT> for <JAIL>.
  • set <JAIL> action <ACT> <METHOD>[ <JSONKWARGS>] — calls the <METHOD> with <JSONKWARGS> for the action <ACT> for <JAIL>.

🦋 JAIL INFORMATION 🦋

  • get <JAIL> banned — returns the banned IPs of <JAIL>.
  • get <JAIL> banned <IP> ... <IP>] — returns 1 if the IP is banned in <JAIL>, otherwise 0; or a list of 1/0 for multiple IPs.
  • get <JAIL> logpath — gets the list of the monitored files for <JAIL>.
  • get <JAIL> logencoding — gets the encoding of the log files for <JAIL>.
  • get <JAIL> journalmatch — gets the journal filter match for <JAIL>.
  • get <JAIL> ignoreself — gets the current value of the ignoring of your own IP addresses.
  • get <JAIL> ignoreip — gets the list of ignored IP addresses for <JAIL>.
  • get <JAIL> ignorecommand — gets ignorecommand of <JAIL>.
  • get <JAIL> failregex — gets the list of regular expressions which match the failures for <JAIL>.
  • get <JAIL> ignoreregex — gets the list of regular expressions which match patterns to ignore for <JAIL>.
  • get <JAIL> findtime — gets the time for which the filter will look back for failures for <JAIL>.
  • get <JAIL> bantime — gets the time a host is banned for <JAIL>.
  • get <JAIL> datepattern — gets the pattern used to match date/times for <JAIL>.
  • get <JAIL> usedns — gets the usedns setting for <JAIL>.
  • get <JAIL> banip [<SEP>|--with-time] — gets the list of banned IP addresses for <JAIL>. optionally you can pass the separator character ('<SEP>', default is space) or the option '--with-time' (which prints the times of ban). the IPs are ordered by end of ban ✨
  • get <JAIL> maxretry — gets the number of failures allowed for <JAIL>.
  • get <JAIL> maxmatches — gets the max number of matches stored in memory per ticket in <JAIL>.
  • get <JAIL> maxlines — gets the number of lines to buffer for <JAIL>.
  • get <JAIL> actions — gets a list of actions for <JAIL>.

💜 COMMAND ACTION INFORMATION 💜

  • get <JAIL> action <ACT> actionstart — gets the start command for the action <ACT> for <JAIL>.
  • get <JAIL> action <ACT> actionstop — gets the stop command for the action <ACT> for <JAIL>.
  • get <JAIL> action <ACT> actioncheck — gets the check command for the action <ACT> for <JAIL>.
  • get <JAIL> action <ACT> actionban — gets the ban command for the action <ACT> for <JAIL>.
  • get <JAIL> action <ACT> actionunban — gets the unban command for the action <ACT> for <JAIL>.
  • get <JAIL> action <ACT> timeout — gets the command timeout in seconds for the action <ACT> for <JAIL>.

🍓 GENERAL ACTION INFORMATION 🍓

  • get <JAIL> actionproperties <ACT> — gets a list of properties for the action <ACT> for <JAIL>.
  • get <JAIL> actionmethods <ACT> — gets a list of methods for the action <ACT> for <JAIL>.
  • get <JAIL> action <ACT> <PROPERTY> — gets the value of <PROPERTY> for the action <ACT> for <JAIL>.

📂 FILES 📂

  • /etc/fail2ban/*

that's the whole config neighborhood, bestie 🏡

🐛 REPORTING BUGS 🐛

found a bug? don't gatekeep it — report it to https://github.com/fail2ban/fail2ban/issues 🫶

🌸 SEE ALSO 🌸

okay that's the whole thing, you're officially a fail2ban-client expert now, no cap 👑 this gorgeous specimen of a manual page came from Fail2Ban v1.1.1, dated August 2026, and it's the FAIL2BAN-CLIENT(1) page — go forth and ban responsibly, mwah 💋💖✨

📦 where this page comes from