fail2ban
A few minutes after going online, your server already gets strangers trying passwords at its SSH door. Let's install fail2ban, a guard that spots them and throws them out for a while.
- Course
- Tutorial 13 of 35
- Time
- 20 min to read
- Tested with
- Commands: tested on Debian 13.7 (fail2ban 1.1.0)
What you will be able to do
- See in the logs who is trying to log in to your server.
- Install fail2ban and check that SSH monitoring is active.
- Set how many tries are allowed and how long a ban lasts.
- Read the monitoring status and unban an address.
Before you start: A firewall with ufw.
Contents
How do you install fail2ban on Debian to protect SSH? Your firewall decides which doors stay open, but it can't tell who is knocking at the SSH one. fail2ban adds that eye: it reads what the server writes down, spots the addresses that fail too often and blocks them for a while. Allow twenty minutes, and a little distrust of your own fingers, which we'll come back to.
Why strangers try your passwords
Automatic programs, called bots, constantly try passwords on every address on the Internet, and yours is no exception. An IP address is the number that identifies a machine on the network. The bot didn't pick your server: it knocks on every SSH door it finds open, with common account names like admin or ubuntu.
Your server keeps a record of every attempt in its log, the notebook where it writes down what happens to it. The journalctl command reads it; the article Read your logs with journalctl covers its options in detail. Here, one is enough: it shows the attempts on an account that doesn't exist. The addresses in the examples are made up; yours will be real.
sudo journalctl -u ssh | grep "Invalid user" | tail -4Nov 05 01:24:48 mon-serveur sshd-session[4069]: Invalid user admin from 198.51.100.23 port 50626
Nov 05 01:24:48 mon-serveur sshd-session[4071]: Invalid user ubuntu from 198.51.100.23 port 50630
Nov 05 01:27:21 mon-serveur sshd-session[4110]: Invalid user test from 198.51.100.23 port 49654
Nov 05 01:27:21 mon-serveur sshd-session[4112]: Invalid user oracle from 198.51.100.23 port 49668Each line says: at this time, the address 198.51.100.23 tried the account admin, which doesn't exist here. Four tries in a few minutes from the same address means a bot, not a forgotten password. If you turned passwords off with Secure SSH: turn off passwords, it still fails every time, but it fills your log for nothing. Time to show it the door, which is what fail2ban does.
1Install fail2ban
fail2ban installs like any Debian package, and it starts on its own. The -y option answers "yes" to the confirmation.
sudo apt install -y fail2banThe installation scrolls by for a minute. Then let's check that the service, a program that runs all the time in the background, is up.
systemctl is-active fail2banactiveNow let's ask fail2ban what it is watching. Each watch is called a jail: a rule that says which service to look at and when to crack down.
sudo fail2ban-client statusStatus
|- Number of jail: 1
`- Jail list: sshdDebian has already turned on the sshd jail, the one that watches SSH. So you're protected from this very minute, with the factory settings. They're correct but loose: let's look at them so we can tighten them.
2Tune the monitoring in jail.local
You change the settings in a file of your own, /etc/fail2ban/jail.local, and never in jail.conf. The latter belongs to the package: its header warns that an update may overwrite it. Your jail.local is read after jail.conf, and for fail2ban the last value read wins, so it overrides jail.conf and survives updates. That is the opposite of sshd in Secure SSH: turn off passwords, where the first value read wins. Each program has its own rule.
Three numbers decide everything, like a bouncer counting the bad entries:
| Setting | Role | Debian, then us |
|---|---|---|
maxretry | failures allowed | 5, then 3 |
findtime | how long failures are counted | 10 min |
bantime | how long the block lasts | 10 min, then 1 h |
With our values, an address that fails three times in ten minutes is blocked for an hour. A human who mistypes a password almost never gets there. A bot does, in its very first burst.
One risk is left: banning yourself after three typos. To ban is to refuse every connection from an address for a while. The ignoreip line is the whitelist, the addresses fail2ban never bans. Your server already knows the address you're connected from, in the SSH_CLIENT variable. We store it in MON_IP, then write the file with tee: everything after the command, up to the EOF line, becomes its content.
MON_IP=$(echo "$SSH_CLIENT" | cut -d' ' -f1)
sudo tee /etc/fail2ban/jail.local > /dev/null <<EOF
[DEFAULT]
ignoreip = 127.0.0.1/8 ::1 $MON_IP
maxretry = 3
findtime = 10m
bantime = 1h
[sshd]
enabled = true
EOFThe command prints nothing, which is a good sign. Before restarting the service, fail2ban can check a settings file without breaking anything. Otherwise, a typo in jail.local would stop the restart.
sudo fail2ban-client -t
sudo systemctl restart fail2ban
sudo fail2ban-client get sshd maxretryOK: configuration test is successful
3The 3 confirms the jail reads your file. Keep your SSH session open during the restart, then test a second connection before you close the first. A running watch proves nothing until you've seen what it sees, so let's read its report.
3Read the monitoring status
The fail2ban-client status sshd command gives a jail's report: how many failures it has seen, and who is banned right now. Here is what you'll see after a few unwanted visits. Your numbers and addresses will be different.
sudo fail2ban-client status sshdStatus for the jail: sshd
|- Filter
| |- Currently failed: 0
| |- Total failed: 3
| `- Journal matches: _SYSTEMD_UNIT=ssh.service + _COMM=sshd
`- Actions
|- Currently banned: 1
|- Total banned: 1
`- Banned IP list: 198.51.100.23Five lines matter to you:
Currently failed: the number of addresses that failed recently without reaching the ban threshold. It's a simple counter (here 0), not a list.Total failed: every failure seen since fail2ban started.Currently banned: the number of addresses blocked right now.Total banned: every ban since it started.Banned IP list: the list of those addresses.
The other lines ask nothing of you. Journal matches only says where fail2ban reads: _SYSTEMD_UNIT=ssh.service means "the log lines coming from the SSH service".
To see a ban without waiting for a bot, ban a made-up address by hand with banip. The command answers 1, and the address shows up in Banned IP list at the next status.
sudo fail2ban-client set sshd banip 198.51.100.991Find past bans
Past bans stay in fail2ban's file. Each Ban line says which address was blocked, and Unban says when it was released. This file writes dates as year-month-day, whereas journalctl writes the month, then the day.
sudo grep -E " (Ban|Unban) " /var/log/fail2ban.log2026-11-05 01:22:35,737 fail2ban.actions [3660]: NOTICE [sshd] Ban 198.51.100.23
2026-11-05 01:22:44,589 fail2ban.actions [3660]: NOTICE [sshd] Unban 198.51.100.23So you can read a ban. Now for the opposite move, handy the day someone gets blocked who shouldn't have been.
4Unban an address
To release an address, you name it in unbanip. The command answers 1 when an address has been released. Let's release our made-up address.
sudo fail2ban-client set sshd unbanip 198.51.100.991The address is gone from the list, and it can knock on the SSH door again. But you can only type this command if you can still reach the server. What if you're the one who got banned?
In that case SSH no longer answers, but the remote console, your hosting provider's emergency screen in its customer area, still works. Log in there as alice, then run the same command with your address, which you'll read in Banned IP list. Otherwise, wait: the ban ends by itself after an hour.
If it fails
Three messages come up, with their causes:
ssh: connect to host 203.0.113.10 port 22: Connection refused, while the server is running. You probably failed three times and fail2ban blocked you. Go through the remote console and unban yourself as in step 4.ERROR: test configuration failed, preceded bySource contains parsing errors: '/etc/fail2ban/jail.local'and a line number. A typo hides injail.local, often a forgotten bracket in[sshd]. Fix the line it points to, then runsudo fail2ban-client -tagain until you readOK.Failed to access socket path: /var/run/fail2ban/fail2ban.sock. Is fail2ban running?. The service is stopped. Typesudo systemctl start fail2ban.
Frequently asked questions
How do I install fail2ban on Debian to protect SSH?
Install the fail2ban package, which starts on its own: the sshd jail is already active with the factory settings. You can then tighten them in /etc/fail2ban/jail.local.
How do I unban an IP address with fail2ban?
Run sudo fail2ban-client set sshd unbanip followed by the address. The command answers 1 when the address has been released.
What do maxretry, findtime and bantime mean?
maxretry is the number of failures allowed, findtime is how long they are counted, and bantime is how long the block lasts. With 3, 10 minutes and 1 hour, an address that fails three times in ten minutes is blocked for an hour.
What's next
Your server now shuts the door on bots, and you've read your first log lines without knowing all their secrets. When something doesn't work, the log is almost always the first place to look. The next article, Read your logs with journalctl, teaches you to read it properly.