fail2ban-client

Retrieve current status of the jail service

$ fail2ban-client status [jail]

$ fail2ban-client set [jail] unbanip [ip_address]

$ fail2ban-client ping

fail2ban-client [-V | -v [-v] | -q [-q] | -x | --log-level LEVEL | --log-encoding ENCODING | -h] ACTION [JAIL [PARAMETERS]]

ACTION examples: start, stop, reload, status, set OPTION=VALUE, get PROPERTY, ping

-V, --version
    Show version information and exit

-v, --verbose
    Increase verbosity (repeatable for more detail)

-q, --quiet
    Decrease verbosity (repeatable to suppress output)

-x, --running
    Test if Fail2ban server is running; exit with code

--log-level LEVEL
    Set logging level (CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG)

--log-encoding ENCODING
    Set log file encoding (e.g., UTF-8, latin-1)

-h, --help
    Display help message and exit

The fail2ban-client is the command-line interface to the Fail2ban daemon, a popular open-source intrusion prevention tool for Linux systems. Fail2ban scans log files (e.g., auth.log, apache logs) for patterns indicative of brute-force attacks, failed logins, or other malicious activity. When matches are found, it updates firewall rules to ban offending IP addresses for a configurable duration, typically using backends like iptables, nftables, firewalld, or shorewall.

The client communicates with the fail2ban-server via a Unix socket, enabling administrators to control the service dynamically without restarting. Key capabilities include starting/stopping the service, reloading configurations, querying jail statuses (jails are per-service monitors, e.g., sshd, apache-auth), setting runtime parameters like ban times or findtime, unjailing IPs, and monitoring active bans.

For example, it supports actions like checking global status, detailed jail info, or manual interventions such as unbanning a legitimate IP. Verbosity levels allow fine-tuned output, and it's essential for server hardening against automated attacks. While powerful, it requires proper configuration in /etc/fail2ban/jail.local to avoid false positives. Widely used on VPS and dedicated servers, it integrates seamlessly with common services.

Most actions require fail2ban-server running and root privileges.
Client uses Unix socket (/var/run/fail2ban/fail2ban.sock); ensure permissions.
Avoid false bans by tuning jail regex/findtime; test with dry-run.

fail2ban-client status: Global overview.
fail2ban-client status sshd: Jail details/banned IPs.
fail2ban-client set sshd banip 1.2.3.4: Manual ban.
fail2ban-client set sshd unbanip 1.2.3.4: Unban IP.

If connection fails: sudo systemctl status fail2ban or check /var/log/fail2ban.log.
Restart with fail2ban-client reload after config changes.

Fail2ban originated in 2003-2004 by Cyril Jaquier as a Python script to combat SSH brute-force attacks. The client was integral from early versions (0.6+). Major milestones: v0.8 (2010) added actions/backends; v0.9 (2014) improved client-server split; v1.0 (2020) enhanced Python3 support and nftables. Actively maintained on GitHub.

fail2ban-server(1), fail2ban-regex(1), fail2ban(1), iptables(8), firewalld(1)