Anime-Sanctuary

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
  1. Why strangers try your passwords
  2. Install fail2ban
  3. Tune the monitoring in jail.local
  4. Read the monitoring status
  5. Unban an address
  6. If it fails
  7. Frequently asked questions
  8. What's next
  9. Sources

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.

On the server
sudo journalctl -u ssh | grep "Invalid user" | tail -4
Expected output
Nov 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 49668

Each 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.

On the server
sudo apt install -y fail2ban

The 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.

On the server
systemctl is-active fail2ban
Expected output
active

Now 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.

On the server
sudo fail2ban-client status
Expected output
Status
|- Number of jail:	1
`- Jail list:	sshd

Debian 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:

SettingRoleDebian, then us
maxretryfailures allowed5, then 3
findtimehow long failures are counted10 min
bantimehow long the block lasts10 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.

On the server
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
EOF

The 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.

On the server
sudo fail2ban-client -t
sudo systemctl restart fail2ban
sudo fail2ban-client get sshd maxretry
Expected output
OK: configuration test is successful
3

The 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.

On the server
sudo fail2ban-client status sshd
Expected output
Status 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.23

Five 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.

On the server
sudo fail2ban-client set sshd banip 198.51.100.99
Expected output
1
Find 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.

On the server
sudo grep -E " (Ban|Unban) " /var/log/fail2ban.log
Expected output
2026-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.23

So 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.

On the server
sudo fail2ban-client set sshd unbanip 198.51.100.99
Expected output
1

The 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 by Source contains parsing errors: '/etc/fail2ban/jail.local' and a line number. A typo hides in jail.local, often a forgotten bracket in [sshd]. Fix the line it points to, then run sudo fail2ban-client -t again until you read OK.
  • Failed to access socket path: /var/run/fail2ban/fail2ban.sock. Is fail2ban running?. The service is stopped. Type sudo 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.

Sources (accessed November 4, 2026)

  • fail2ban: jail.conf(5), fail2ban-client(1).
  • Default values (5, 10 minutes, 10 minutes): the package's /etc/fail2ban/jail.conf file.
  • Commands: tested on Debian 13.7 (fail2ban 1.1.0-8) with a real SSH server; example addresses.