What this module does #
fail2ban is the guardian that watches your server's logs and, when it detects malicious access attempts (for example, many SSH password failures), automatically bans the offending IP for a while. Each watched service is organized into a jail (for example sshd).
The fail2ban module gives you control of those bans at runtime, without having to remember the syntax of fail2ban-client: check the status of the jails, list who is banned, check whether a specific IP is blocked, ban or unban by hand, unblock everything at once in an emergency and reload the configuration after a change.
This module acts on a fail2ban that is already installed and running. Every subcommand queries or modifies the state of the service, so they need root privileges (use sudo). If you've locked yourself out with your own IP, go straight to the emergency unblock.
Common tasks #
Pick what you want to do. Each recipe comes with the command ready to go — just swap the IP or the jail for yours, and hit Copy.
1
View the status and the jails
Check at a glance whether fail2ban is active and how many are banned.
Connect to your server over SSH as the ubuntu user and ask for the overall status:
$ sudo imaxe fail2ban statusWant it in machine-readable format, for a script or a dashboard? Add --json:
$ sudo imaxe fail2ban status --jsonsshd) and the number of banned IPs in each one.2
See which IPs are banned
List the active bans, across all jails or just one.
All banned IPs, across every jail at once:
$ sudo imaxe fail2ban bannedInterested in only one jail? Give it as an argument:
$ sudo imaxe fail2ban banned sshd3
Check whether an IP is banned
Find out in which jails a specific address is blocked.
Ask directly about the IP; it will tell you in which jails it appears banned:
$ sudo imaxe fail2ban check 203.0.113.74
Ban or unban an IP
Block an abusive address by hand or free a legitimate user.
Ban an IP in a specific jail (if there's only one jail, it is inferred automatically):
$ sudo imaxe fail2ban ban 203.0.113.7 --jail sshdBanned someone legitimate? Unban them from all jails at once:
$ sudo imaxe fail2ban unban 203.0.113.7imaxe fail2ban check on that same IP.5
Unblock everything (emergency)
You're locked out: free all IPs from all jails.
If your own IP got caught and you need to regain access now, unban them all. Add --yes to skip the confirmation:
$ sudo imaxe fail2ban unban-all --yesAfter a change to the jail configuration, reload it so it takes effect:
$ sudo imaxe fail2ban reloadunban-allIt's a destructive ban operation: it leaves all IPs unblocked, malicious ones included. Use it only to regain access in an emergency and check the status afterwards with imaxe fail2ban status.
Synopsis #
imaxe fail2ban <subcomando> [<ip>|<jail>] [--jail JAIL] [flags]Every subcommand requires root privileges (use sudo) because they query or modify the state of fail2ban through fail2ban-client. Add --json to status, banned or check for machine-readable output, suitable for scripting.
Subcommands #
| Subcommand | What it does | Relevant flags |
|---|---|---|
| status | fail2ban status: active, jails and number of banned IPs per jail. | --json |
| banned | Lists the banned IPs (all jails or a specific one). | --json |
| check | Indicates in which jails an IP is banned. | --json |
| ban | Manually bans an IP in a jail. | --jail |
| unban | Unbans an IP from all jails. | — |
| unban-all | EMERGENCY: unbans ALL IPs from all jails. | --yes |
| reload | Reloads the fail2ban configuration (validates jail.local). | — |
Arguments and flags #
| Argument / Flag | Type | Default | Description |
|---|---|---|---|
| <ip> req. | string | — | The IP to operate on. Required in check, ban and unban. |
| <jail> | string | todas | In banned, a specific jail to list. Without an argument, all jails are listed. |
| --jail | string | auto | In ban, the target jail for the ban. If there's only one jail, it is inferred automatically. |
| --yes | bool | false | In unban-all, confirms without asking (destructive ban operation). |
| --json | bool | false | In status/banned/check, emits the result as JSON on stdout. |
Files and paths #
| Path | Contents |
|---|---|
| /etc/fail2ban/jail.local | Local fail2ban configuration: active jails, ban times and thresholds. What reload validates. |
| /var/run/fail2ban/fail2ban.sock | Control socket that fail2ban-client uses to talk to the service. |
| /var/log/fail2ban.log | fail2ban's own log: bans, unbans and reloads. |
Exit codes and logs #
Each run returns a code you can check with echo $? — handy for chaining in scripts:
Follow the log live while you troubleshoot:
$ sudo journalctl -u fail2ban -f
$ sudo tail -f /var/log/fail2ban.logTroubleshooting #
| Symptom | Likely cause | Fix |
|---|---|---|
| You get SERVICE (code 3) | fail2ban is stopped or the socket isn't responding. | Start the service with systemctl start fail2ban and retry. |
| You get JAIL (code 4) | The --jail jail doesn't exist, or there are several and it can't be inferred. | Look at the jails with imaxe fail2ban status and give the correct one in --jail. |
| You get RELOAD (code 5) | There's a syntax error in jail.local. | Fix /etc/fail2ban/jail.local and run reload again. |
| I got locked out over SSH | Your own IP accumulated failures and got banned in sshd. | From another route, unban it with unban or free them all with unban-all --yes. |
Stuck with the Fail2ban module?
Write to us with the output of «imaxe <module> status --json» and we'll get back to you fast.