Side reading
When you have locked yourself out
What to try, in order, when SSH stops letting you in. Read it before you need it.
Everyone does this once. Make it cheap.
First, work out which stage is failing #
The error message tells you far more than it looks like it does, and each one points at a different half of the problem.
| What you see | What it means | Where to look |
|---|---|---|
Connection refused |
Something answered and said no. The host is up and reachable; nothing is listening on that port, or a firewall is actively rejecting. | Is sshd running? Is the port right? |
Connection timed out |
Nothing answered at all. Packets are being dropped, or you have the wrong address, or the machine is off. | Address, network, firewall policy of DROP |
Permission denied (publickey) |
You reached sshd and it works. It will only accept keys, and yours was not accepted. | Keys, permissions, AllowUsers |
Permission denied (publickey,password) |
Same, but passwords are also on the table and both failed. | Username, password, key |
Host key verification failed |
You got all the way to the host key check and it did not match known_hosts. |
See below. Do not blindly delete the line. |
Too many authentication failures |
Your client offered every key it has and sshd cut it off at MaxAuthTries. |
ssh -o IdentitiesOnly=yes -i <the right key> |
Ask sshd, not the file
Whenever you can still get in by any route, sudo sshd -T is the fastest way to find out what the server actually believes. A large fraction of lockouts are a drop-in file that was overruled or a typo in AllowUsers.
The recovery ladder #
Work down it. Stop as soon as one works.
1. Another session you left open. This is why the chapter tells you to keep one. It is already authenticated, and sshd reloading does not evict it. Fix the config there, run sudo sshd -t, reload, and test with a new connection.
2. Verbose output from the client. Not a fix, but it usually names the cause in one line.
$ ssh -vvv admin@192.168.1.20 2>&1 | tail -40
Look for Offering public key, Authentications that can continue, and any Permission denied. Together they tell you whether your key was ever offered and whether the method was even allowed.
3. A different key or user. If you added AllowUsers and got it wrong, another account may still be permitted. If you have several keys, force the one you mean:
$ ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 admin@192.168.1.20
4. A physical console. Plug in a monitor and keyboard. The most reliable option on this list, and the reason the machine being in your house is an advantage. You get a normal login prompt, unaffected by anything in sshd_config.
5. A root shell from the bootloader. If you cannot log in at the console either, hold shift or press escape during boot to reach GRUB and edit the kernel line.
Add init=/bin/bash. Do not use single: on Ubuntu the root account is locked, so single-user mode drops to sulogin and refuses you with "Cannot open access to console, the root account is locked". Ubuntu's own "Advanced options → recovery mode → root" entry works too.
This route depends on the machine's boot policy and on unlocking any encrypted disk first. With init=/bin/bash the root filesystem normally starts read-only, so remount it and preserve the suspect file rather than deleting evidence:
$ mount -o remount,rw /
$ mv /etc/ssh/sshd_config.d/10-hardening.conf \
/etc/ssh/sshd_config.d/10-hardening.conf.disabled
$ sync && reboot -f
This is also a security lesson
Anyone with physical access and no disk encryption can do exactly what step 5 describes. Your recovery path is also somebody else's attack path. Full disk encryption closes it, at the cost of a machine that cannot reboot unattended after a power cut. That is a genuine trade with no free answer, and it is worth making on purpose rather than by default.
6. Use a live system or another machine. Boot a live USB or attach the disk elsewhere, unlock it if necessary, mount the filesystem and rename the offending file. This still depends on having the disk-encryption recovery material and compatible storage hardware.
Host key verification failed #
This one deserves its own note, because the standard advice is to delete the line from known_hosts and move on, and that advice is sometimes wrong.
The message means the server presented a different host key than the one your laptop recorded. There are exactly three common reasons:
- You reinstalled the server, or rebuilt it, so it generated new host keys. Expected. Remove the old entry.
- The address now belongs to a different machine, because DHCP moved things around. Also expected, and an argument for reserving addresses.
- Something is intercepting your connection. Rare on a home network, and the reason the warning exists at all.
If you are on your own wifi and you know you just reinstalled, it is the first one:
$ ssh-keygen -R 192.168.1.20
If you cannot explain the change, do not clear it. Get the real fingerprint from the console with sudo ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub and compare it against what your client is complaining about.
Make the next one cheaper #
Three small habits, none of which cost anything until the day they save you an evening:
- Add a second key, from a second device. A phone with an SSH client counts. Two lines in
authorized_keys, two ways in. - Keep the console usable. Know where the monitor cable is. Make sure the machine does not need a password you have never typed.
- Change one thing, reload, test with a new connection. The reason lockouts get bad is that people make four changes and then discover they cannot get in, with four suspects and no way to test any of them.
I am locked out of my server
Work through the recovery ladder for my specific error
Paste this into a new agent session. It carries everything the agent needs to know about where you are, and asks it to walk you through the problem rather than fix it for you.