SSH and secure remote access

Before you read. You generated a key, copied the public half to the server, and checked with your own eyes that it is sitting in authorized_keys. You connect, and it asks for a password anyway. Nothing in the output says why. The connection was accepted, so the network is fine and the server is running.

What is refusing a key that is demonstrably present?

Something on the far machine decided your key was not trustworthy and did not say so, because saying so would tell an attacker the same thing. The reason is usually not the key at all: it is the permissions on the directory the key file sits in, and the only machine that knows that is the one that refused you. That is the shape of almost every SSH problem. Two programs, on two machines, each with its own configuration file, each built to be unhelpful in public. The skill is knowing which of the two you are talking to, and how to make it show you what it thinks rather than what a file says.

Some words you will need

client

ssh, the program you run. It reads ~/.ssh/config and then /etc/ssh/ssh_config.

server

sshd, the daemon listening on the far machine. It reads /etc/ssh/sshd_config and the drop-in files beside it. The d is for daemon.

private key

~/.ssh/id_ed25519. Never leaves the machine it was made on. Anybody holding it is you.

public key

~/.ssh/id_ed25519.pub. Safe to publish, derivable from the private key, and useless on its own.

authorized_keys

A file in the target user's home directory on the server, listing the public keys permitted to log in as that user.

host key

The server's own key pair, in /etc/ssh. How the machine proves it is the same machine you reached last time.

passphrase

A password that encrypts a private key file. It is not the account password and it never crosses the network.

What breaks without this

You cannot reach the machine at all. Every other topic in this track quietly assumes you already have a shell on the far end. This is the topic that gets you one.

Your credentials cross the network as readable bytes. Telnet and FTP send the username and password with no encryption whatsoever, so anybody on the path reads them once and owns the account forever. That is why both are gone from current builds and why “we only use it internally” is not a defence.

The server accepts password guesses from the entire internet, thousands a day on any public address with password authentication on.

You reload the server with a broken configuration and lock yourself out. The session you are sitting in survives. The next one does not, and there is nobody in the building.

Two programs, and which one you are configuring

Client and server ship in separate packages and can be different versions, so start by proving what you have:

# Debian 13 (trixie), x86_64
$ ssh -V
OpenSSH_10.0p2 Debian-7+deb13u4, OpenSSL 3.5.6 7 Apr 2026

Two numbers, two concerns. OpenSSH 10.0 decides which algorithms exist and which have been removed; OpenSSL 3.5.6 is the library underneath, patched separately.

The two configuration files differ by one letter and that letter is everything.

Editing ssh_config to stop password logins does nothing at all, and people make that mistake more than once, because both filenames sit in the same directory listing and the wrong one sorts first.

The cryptography is negotiated, not fixed. Both ends advertise what they can do and pick the strongest thing they have in common:

# Debian 13 (trixie), x86_64
$ ssh -Q kex | head -6; echo '---'; ssh -Q key | head -6
diffie-hellman-group1-sha1
diffie-hellman-group14-sha1
diffie-hellman-group14-sha256
diffie-hellman-group16-sha512
diffie-hellman-group18-sha512
diffie-hellman-group-exchange-sha1
---
ssh-ed25519
ssh-ed25519-cert-v01@openssh.com
sk-ssh-ed25519@openssh.com
sk-ssh-ed25519-cert-v01@openssh.com
ecdsa-sha2-nistp256
ecdsa-sha2-nistp256-cert-v01@openssh.com

That list is easy to misread. ssh -Q prints what the binary was compiled to understand, not what it will offer: diffie-hellman-group1-sha1 is in there and has not been enabled by default for years. What this machine actually proposes is a different question, answered by sshd -T | grep -i ciphers and nothing else. Telnet and FTP have no equivalent of any of it, because there is nothing to negotiate.

What a key pair actually is

One command produces both halves:

# Debian 13 (trixie), x86_64
$ ssh-keygen -t ed25519 -f /root/.ssh/id_ed25519 -N '' -C 'sam@laptop'; echo '---'; cat /root/.ssh/id_ed25519.pub; ssh-keygen -lf /root/.ssh/id_ed25519.pub
Generating public/private ed25519 key pair.
Your identification has been saved in /root/.ssh/id_ed25519
Your public key has been saved in /root/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:XKXOoBVfKo/PqeLCRhsgJkaogjcbxdKkOHKvtAifNUQ sam@laptop
The key's randomart image is:
+--[ED25519 256]--+
|.  +E   .   o    |
|.o.o+    o =     |
|B oo.   + =      |
|B==o   + O       |
|*o.=+ . S +      |
|.+.=o.   o .     |
|. =o o    +      |
|    = .  .       |
|   . o...        |
+----[SHA256]-----+
---
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEUb1tzaDFMXTISKXP7Jj7y/udNEgGfgPgwqC1+Mf1ak sam@laptop
256 SHA256:XKXOoBVfKo/PqeLCRhsgJkaogjcbxdKkOHKvtAifNUQ sam@laptop (ED25519)

Two files, one with no extension and one ending .pub: the secret, and the one you give away. The fingerprint is a hash of the public key, not the private one, which is why ssh-keygen -lf works on the .pub file and why fingerprints are safe to read aloud on a phone call. The randomart is that fingerprint drawn as a picture, because people compare two grids of symbols more reliably than two lines of base64; it is not a second security property. The -C comment is free text, and the reason authorized_keys still says which human and which machine each line belongs to six months later. -N '' set an empty passphrase, right for a capture and wrong for a laptop: a passphrase encrypts the key file on disk, so somebody who copies it still cannot use it.

The parameters worth knowing:

Key length only compares within an algorithm. Generate an RSA key beside that one with ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa, and the 256-bit Ed25519 key is still the stronger of the two: the bit counts measure different things and cannot be ranked against each other.

# Debian 13 (trixie), x86_64
$ ls -l /root/.ssh/
total 16
-rw-------. 1 root root  399 Aug  8 17:50 id_ed25519
-rw-r--r--. 1 root root   92 Aug  8 17:50 id_ed25519.pub
-rw-------. 1 root root 3369 Aug  8 17:50 id_rsa
-rw-r--r--. 1 root root  736 Aug  8 17:50 id_rsa.pub

0600 on the private keys, 0644 on the public ones, set by the tool. The .pub files are publishable because a public key cannot be turned back into the private one. The reverse is trivial:

# Debian 13 (trixie), x86_64
$ ssh-keygen -y -f /root/.ssh/id_ed25519; echo '---'; cat /root/.ssh/id_ed25519.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKOesT1GEUt/RvS0XHbPxd+pax/Zyn/Wy9+vDDR6Fp3K sam@laptop
---
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKOesT1GEUt/RvS0XHbPxd+pax/Zyn/Wy9+vDDR6Fp3K sam@laptop

Identical. ssh-keygen -y regenerated the public key from the private one, byte for byte, so deleting the .pub file costs nothing and the private key is the only thing here worth protecting. That asymmetry is the whole argument for keys over passwords. A password is a shared secret: you type it across the connection and a compromised server learns it. A key is not shared. The server holds only the public half, the private half never crosses the wire, and a compromised server learns something it could have looked up. A key also carries far more entropy than anything a person types twice a day.

# a CA, once, kept offline
ssh-keygen -t ed25519 -f /secure/ssh_user_ca -C 'user CA'

# a user's key, valid for a day, for two named accounts
ssh-keygen -s /secure/ssh_user_ca -I sam@example.com -n sam,deploy -V +1d ~/.ssh/id_ed25519.pub

# a host's key
ssh-keygen -s /secure/ssh_host_ca -I web01 -h -n web01.example.com /etc/ssh/ssh_host_ed25519_key.pub

# /etc/ssh/sshd_config on every server, instead of a per-user file
TrustedUserCAKeys /etc/ssh/user_ca.pub
RevokedKeys /etc/ssh/revoked_keys

# ~/.ssh/known_hosts on every client, one line for the whole estate
@cert-authority *.example.com ssh-ed25519 AAAA...

Getting the public half onto the server

The public key has to end up on one line of ~/.ssh/authorized_keys, in the home directory of the account you are logging in as, on the server. There is a tool for it, and by hand it is a cat and two chmods:

ssh-copy-id -i ~/.ssh/id_ed25519.pub sam@server

# what it does, without the tool
cat ~/.ssh/id_ed25519.pub | ssh sam@server \
  'mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys'

ssh-copy-id needs a way in already, a password, or another key. It opens an ordinary SSH session and appends to a file. On a cloud instance the first key arrives through the provider’s metadata service instead, which is why those images ship with PasswordAuthentication no and still let you in. Append, never overwrite: > in place of >> removes everybody else’s access, including the emergency key you were told to leave in place.

The permission rules are the part that bites, and they are checked on both sides:

The client is loud about its half:

# Debian 13 (trixie), x86_64
$ chmod 0644 /root/.ssh/id_ed25519; ssh -i /root/.ssh/id_ed25519 -o BatchMode=yes root@localhost id
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@         WARNING: UNPROTECTED PRIVATE KEY FILE!          @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Permissions 0644 for '/root/.ssh/id_ed25519' are too open.
It is required that your private key files are NOT accessible by others.
This private key will be ignored.
Load key "/root/.ssh/id_ed25519": bad permissions
root@localhost: Permission denied (publickey,password).

That is about as clear as a computer gets: the file, the mode, the rule, and what it did about it. One chmod and nothing else changes:

# Debian 13 (trixie), x86_64
$ chmod 0600 /root/.ssh/id_ed25519; ssh -i /root/.ssh/id_ed25519 -o BatchMode=yes root@localhost id
uid=0(root) gid=0(root) groups=0(root)

Same key, same server, and id ran on the far end. -o BatchMode=yes forbids every interactive prompt, so nothing here fell back to a password: the key did all of it.

The server is the exact opposite, and this is the important half. Change the mode on ~/.ssh on the server to something world-writable, leave everything else correct, and here is the entire client-side story:

# Debian 13 (trixie), x86_64
$ chmod 0777 /root/.ssh; ssh -i /root/.ssh/id_ed25519 -o BatchMode=yes root@localhost id; echo "exit status: $?"
root@localhost: Permission denied (publickey,password).
exit status: 255

One line, and it tells you nothing. No mention of permissions, no mention of a directory, no hint that the key was even considered. sshd will not explain a rejection to an unauthenticated stranger, because the explanation is reconnaissance.

The directive doing it is StrictModes, which defaults to yes and makes sshd refuse to read authorized_keys out of a directory somebody else could write to. The logic is sound, a group-writable home means any member of that group can install their own key into your account, and the diagnosis is impossible from the client. The explanation exists only in the server’s log:

# Debian 13 (trixie), x86_64
$ chmod 0777 /root/.ssh; ssh -i /root/.ssh/id_ed25519 -o BatchMode=yes root@localhost id >/dev/null 2>&1; grep -i 'Authentication refused' /var/log/sshd.log
Authentication refused: bad ownership or modes for directory /root/.ssh

The whole diagnosis, in one line, on the other machine. It names the check, the verdict, and the exact directory, and nothing resembling it reached the person being refused. On an ordinary systemd machine that line comes from sudo journalctl -u sshd -n 20; the capture reads a file directly because the container has no journal and sshd was started with -E /var/log/sshd.log. That single habit is most of what this topic is for: the client says Permission denied (publickey), then go and read the server’s log.

The client’s half comes from -v, and one -v is usually enough:

ssh -v -i ~/.ssh/id_ed25519 sam@server
# Offering public key: /root/.ssh/id_ed25519 ED25519 SHA256:XKXOoB...
# Authentications that can continue: publickey,password

If Offering public key never appears, the client never sent it, and the fault is on your side: wrong path, wrong mode, or an agent in the way. If it appears and is refused, the fault is on the server’s side and the log there has the reason.

The setting you cannot find is in a drop-in

sshd -T is the most valuable command in this topic. It prints the effective configuration: every keyword the server understands, with the value it will actually use, including the several hundred you never wrote down anywhere.

# Fedora CoreOS 44.20260707.3.1 on a virtual machine, aarch64
$ sudo sshd -T 2>&1 | grep -E "^(port|permitrootlogin|passwordauthentication|pubkeyauthentication|permitemptypasswords|x11forwarding|maxauthtries|logingracetime|usepam|kbdinteractiveauthentication) "
port 22
usepam yes
logingracetime 120
maxauthtries 6
permitrootlogin prohibit-password
pubkeyauthentication yes
passwordauthentication no
kbdinteractiveauthentication no
x11forwarding yes
permitemptypasswords no

passwordauthentication no on that machine. Now go and find it. It is not in /etc/ssh/sshd_config, and grepping for it there returns nothing useful:

# Fedora CoreOS 44.20260707.3.1 on a virtual machine, aarch64
$ ls /etc/ssh/sshd_config.d/; echo "--- and what the main file includes ---"; grep -vE "^#|^$" /etc/ssh/sshd_config | head -12
40-disable-passwords.conf
40-redhat-crypto-policies.conf
50-redhat.conf
90-afterburn-authorized-keys-file.conf
91-ignition-authorized-keys-file.conf
99-podman-sshd.conf
--- and what the main file includes ---
grep: /etc/ssh/sshd_config: Permission denied

Two facts in one capture. Six drop-in files, none of which appear in any tutorial, and the main file is not world-readable on this image, so an ordinary user cannot grep it at all, which is why sudo sshd -T rather than sshd -T.

# Fedora CoreOS 44.20260707.3.1 on a virtual machine, aarch64
$ cat /etc/ssh/sshd_config.d/40-disable-passwords.conf; echo "--- and the crypto policy include ---"; cat /etc/ssh/sshd_config.d/40-redhat-crypto-policies.conf
# Disable password logins by default.
# https://github.com/coreos/fedora-coreos-tracker/issues/138
# This file must sort before 50-redhat.conf, which enables
# PasswordAuthentication.
PasswordAuthentication no
--- and the crypto policy include ---
cat: /etc/ssh/sshd_config.d/40-redhat-crypto-policies.conf: Permission denied

The packagers wrote the rule into a comment because it catches everybody: “This file must sort before 50-redhat.conf, which enables PasswordAuthentication.” The number in the filename is not decoration, it is the mechanism.

The second half of the rule is where that Include line sits. Here is the whole of Debian’s shipped sshd_config with comments and blank lines removed:

# Debian 13 (trixie), x86_64
$ grep -vE '^#|^$' /etc/ssh/sshd_config
Include /etc/ssh/sshd_config.d/*.conf
KbdInteractiveAuthentication no
UsePAM yes
X11Forwarding yes
PrintMotd no
AcceptEnv LANG LC_* COLORTERM NO_COLOR
Subsystem	sftp	/usr/lib/openssh/sftp-server

Seven lines. Everything else in that file, hundreds of lines of it, is commented-out documentation showing you the default rather than setting it, which is why grepping for a keyword returns a comment and convinces people the setting is unset. Include is line one; note also KbdInteractiveAuthentication no and Subsystem sftp, both of which come back later.

First value wins, and the Include line is at the top of the shipped file. Put those two together and you get the consequence that ruins afternoons: a directive added at the bottom of /etc/ssh/sshd_config loses to any drop-in that mentions it, because the include was processed first. You edit the file you were told to edit, restart the service, and observe no change whatsoever. A different machine then gives a different answer, which is the point:

# Debian 13 (trixie), x86_64
$ sshd -T | grep -E '^(port|permitrootlogin|passwordauthentication|pubkeyauthentication|permitemptypasswords|x11forwarding|allowtcpforwarding|maxauthtries|logingracetime)'
port 22
logingracetime 120
maxauthtries 6
permitrootlogin without-password
pubkeyauthentication yes
passwordauthentication yes
x11forwarding yes
permitemptypasswords no
allowtcpforwarding yes

passwordauthentication yes here, against no on the CoreOS machine. A stock Debian server accepts passwords, and if that is not what you wanted, that one line is the finding. without-password is the deprecated spelling sshd -T still prints for prohibit-password: root may log in with a key, never with a password. A third machine, a third answer:

# AlmaLinux 10.2, x86_64
$ sshd -T | grep -E 'permitrootlogin|passwordauthentication'
permitrootlogin without-password
passwordauthentication yes

Three machines, three sets of defaults, one command. This is why “the default is” is not a sentence worth finishing about SSH: it depends on the distribution, the image, and whatever the vendor put in a drop-in, all of which are invisible in the file you were told to read. So when somebody says password authentication is off because the file says so, do not open the file, run sudo sshd -T | grep -i passwordauthentication, which accounts for every drop-in and every value the build was compiled with.

Check the file before you reload it

sshd -t parses the configuration and exits without starting anything. On a healthy machine it says nothing at all:

# Debian 13 (trixie), x86_64
$ sshd -t; echo "exit status: $?"
exit status: 0

Silence and zero. Now introduce one typo, a single extra letter in a value:

# Debian 13 (trixie), x86_64
$ echo 'PermitRootLogin yess' >> /etc/ssh/sshd_config; sshd -t; echo "exit status: $?"
/etc/ssh/sshd_config line 125: unsupported option "yess".
exit status: 255

The file, the line number, and the offending token, with exit status 255 for a script to test. Without that check, systemctl reload sshd on a configuration sshd cannot parse leaves the running daemon alive with the old configuration, which is survivable; systemctl restart sshd stops it, fails to start it, and there is now no SSH server on a machine you reach only over SSH.

The sequence that never goes wrong:

Prefer reload to restart. A reload has no window in which nothing is listening; whether your own session survives a restart depends on how that distribution wrote the unit. And step 6 is the one people skip: steps 3 and 4 prove the configuration is valid and says what you meant, and AllowUsers with your username misspelled passes both perfectly.

The directives worth changing

Everything below is sshd_config, on the server, and every one of them should be verified afterwards with sshd -T rather than by reading the file back.

The argument for PermitRootLogin no is auditing, not strength. A root key is exactly as hard to break as the same key on a user account; the difference is that sshd[1234]: Accepted publickey for root names nobody, while a login as sam followed by sudo names a person and a command in two logs.

PasswordAuthentication no alone is not enough, and this is the trap. PAM offers a second route in, keyboard-interactive, which on many builds also asks for a password and is controlled by a different directive. Both have to be off, which is why the Fedora CoreOS capture above shows the two as separate lines.

AllowUsers is the most powerful and the most dangerous, because setting it makes login default-deny for everyone not named:

AllowUsers sam deploy
AllowGroups ops

sshd applies DenyUsers, then AllowUsers, then DenyGroups, then AllowGroups, in that order. If AllowUsers is set and you are not in it, you are refused before authentication is attempted, no message about keys, nothing in the log about your key, and sshd -T | grep allowusers is the only thing that will tell you why. Both match on names rather than numeric IDs, and AllowGroups counts your primary group as well as your supplementary ones.

ssh -L 5432:db.internal:5432 sam@bastion   # local:  bring a remote service here
ssh -R 8080:localhost:3000   sam@server    # remote: expose a local service there
ssh -D 1080                  sam@bastion   # dynamic: a SOCKS5 proxy

Typing the passphrase once

A passphrase on a private key is only useful if you use one, and you will not if it means typing it every time. ssh-agent holds decrypted keys in memory and performs signatures on request:

eval $(ssh-agent -s)     # start it and export its variables
ssh-add ~/.ssh/id_ed25519
ssh-add -l               # what is loaded
ssh-add -D               # forget everything

eval is not a flourish. ssh-agent -s prints shell variable assignments to standard output, and a child process cannot set its parent’s environment, so without eval the agent starts and your shell never learns SSH_AUTH_SOCK, the socket path everything else uses to find it. A desktop session manager has already done this for you, which is why the command looks unfamiliar the first time you need it on a server.

The agent never gives out the key: it receives a challenge, signs it, returns the signature. So a process that can reach the socket can use your key without being able to copy it, a distinction less comforting than it sounds and the subject of the next panel. ssh-add -t 3600 loads a key with a one-hour lifetime, which on a shared or long-lived machine is worth the inconvenience.

One trap produces a baffling error. If your agent holds six keys the client offers them in order, each offer counts against the server’s MaxAuthTries of 6, and you can exhaust the limit before the right key is tried. The message is Too many authentication failures, which sounds like a password problem and is not. ssh -o IdentitiesOnly=yes -i ~/.ssh/the_right_key fixes it once; IdentitiesOnly yes with an IdentityFile in a ~/.ssh/config host block fixes it permanently.

ssh -J sam@bastion sam@web01

# or permanently
Host web01
    HostName web01.internal
    ProxyJump sam@bastion

Moving files, and accounts that can do nothing else

SFTP is a subsystem of the same daemon on the same port, not a separate service and nothing to do with FTP. No second port to open, no second thing to harden:

sftp sam@server
scp ~/report.pdf sam@server:/tmp/
rsync -avz ~/site/ sam@server:/var/www/site/

scp and sftp are the same protocol now. OpenSSH 9.0 changed scp to use SFTP underneath by default, because the original scp protocol expanded filenames on the remote shell and had the vulnerability class you would expect from that sentence. rsync is still worth reaching for on anything large or repeated, because it transfers differences.

The reason SFTP gets its own section is chrooted accounts, for a file transfer user who should never have a shell:

Match Group sftponly
    ChrootDirectory /srv/sftp/%u
    ForceCommand internal-sftp
    AllowTcpForwarding no
    X11Forwarding no

internal-sftp matters: it is implemented inside sshd, so the chroot needs no binary, no library, and no /dev inside it. The older sftp-server is a separate executable that would have to exist within the chroot along with everything it links against.

The chroot ownership rule is where this goes wrong, and it is not obvious: the ChrootDirectory and every directory above it must be owned by root and not writable by anybody else, so the user cannot own the directory they land in and cannot write to it. The arrangement that works:

/srv/sftp            root:root  0755
/srv/sftp/sam        root:root  0755   <- ChrootDirectory, user lands here, read-only to them
/srv/sftp/sam/upload sam:sam    0755   <- and this is where they can actually write

If sshd refuses the session with fatal: bad ownership or modes for chroot directory, that rule is the reason, every time.

# everybody, and this section must come first
PasswordAuthentication no
AllowTcpForwarding no

Match Address 10.0.0.0/8
    PasswordAuthentication yes

Match User ansible
    PermitTTY no
    AuthenticationMethods publickey

sudo sshd -T -C user=fileuser,host=localhost,addr=10.0.0.9
sudo sshd -T -C user=sam,host=localhost,addr=203.0.113.7

Slowing the brute force down

fail2ban reads a log, counts failures per source address, and asks the firewall to drop that address for a while. The vocabulary is three numbers:

Enable the shipped sshd jail from /etc/fail2ban/jail.local, never jail.conf, which the package replaces on upgrade:

# /etc/fail2ban/jail.local
[sshd]
enabled  = true
maxretry = 3
findtime = 10m
bantime  = 1h

# then
sudo systemctl enable --now fail2ban
sudo fail2ban-client status sshd
sudo fail2ban-client set sshd unbanip 203.0.113.9

Know what it is worth. With PasswordAuthentication no a brute force cannot succeed however many attempts it makes, and fail2ban’s contribution drops to keeping the log readable and shedding load. Three limitations: a distributed attempt from a thousand addresses never reaches maxretry on any single one; an IPv6 ban covers one address out of a /64 the attacker was given for free; and it bans you eventually, from the office address everybody shares, so ignoreip for your management network is part of deploying it rather than an afterthought.

Modern OpenSSH has some of this built in: MaxStartups limits unauthenticated connections in flight, and 9.8 added PerSourcePenalties, which slows repeat offenders without a second daemon. sshd -T | grep -i persource says whether your build has them and what they are set to.

Across distributions

The unit name is the row that wastes time. systemctl reload sshd on Debian works through the alias; systemctl status ssh on RHEL does not exist.

The crypto policy row is the RHEL-specific surprise. There update-crypto-policies maintains a drop-in that pulls in system-wide Ciphers, MACs, and KexAlgorithms, and because it sorts early it wins over anything you write in the main file. Setting Ciphers by hand and finding it ignored is the same first-value-wins rule arriving from a direction nobody expects. Change the policy instead, update-crypto-policies --set FUTURE, or add a drop-in that sorts earlier.

Prove it

# the effective configuration, which is not the file
sudo sshd -T | grep -iE 'passwordauth|kbdinteractive|permitrootlogin|allowusers|maxauthtries'

# who has an opinion about the setting you cannot find
ls -l /etc/ssh/sshd_config.d/
grep -rn -i permitrootlogin /etc/ssh/sshd_config /etc/ssh/sshd_config.d/

# what a specific user would get, Match blocks included
sudo sshd -T -C user=sam,host=localhost,addr=10.0.0.9

# never reload without this
sudo sshd -t && sudo systemctl reload sshd

# the two halves of a refusal: client, then server
ssh -v -i ~/.ssh/id_ed25519 sam@server
sudo journalctl -u sshd -n 50

The pairing worth memorising is sshd -T and journalctl -u sshd. The first says what the server has decided to be; the second says what it decided about you.

What trips people up

1. The private key is readable by somebody else

WARNING: UNPROTECTED PRIVATE KEY FILE!, and the key is ignored. The cause is almost always a copy through something with no Unix permissions (a FAT stick, a Windows share, a zip file) or a restore that did not preserve modes. chmod 600 on the file.

2. The home directory is group-writable

Permission denied (publickey) on the client and nothing else, because StrictModes will not read authorized_keys out of a directory somebody else could write to. Fix ~, ~/.ssh, and authorized_keys, and remember the evidence only ever appears in the server’s log.

3. Editing ssh_config when you meant sshd_config

ssh_config governs connections out of this machine; sshd_config governs connections in. Turning off password authentication in the first changes nothing about who can log in to you.

4. Editing the right file and being overridden anyway

First value wins, and the include sits at the top, so a directive appended to the bottom of sshd_config loses to any drop-in that mentions it. The same trap in reverse applies to Match: a block runs to the end of the file, so a “global” directive appended after one is not global at all.

5. PasswordAuthentication no and still a password prompt

KbdInteractiveAuthentication is a second door with its own directive. Turn both off, and check for a Match block re-enabling one for a network range somebody added years ago.

6. Changing the port and calling it hardening

Moving SSH to 2222 removes noise from your logs and no risk at all; a port scan finds it in seconds. There is a real cost, too: ports above 1023 can be bound by any unprivileged process, so if sshd is ever stopped on a multi-user machine an ordinary user can bind 2222 and collect credentials. Do it for log hygiene, not for a hardening report.

Work it through

A new colleague cannot log in to a server you are logged in to right now, using a key you installed for them yourself an hour ago. Same key type as yours, same server.

Reason it out before reading on.

Establish which machine holds the explanation, from the client:

ssh -v -i ~/.ssh/id_ed25519 newperson@server 2>&1 | grep -i 'offering\|denied\|authentications'

If Offering public key never appears, the client never sent it: wrong path, a mode that made ssh ignore the key, or an agent supplying something else. Nothing on the server is at fault. If it appears and is then denied, the server considered the key and refused it, and will not say why, so stop looking at the client.

Read the server’s version of events, which you can do because you are already logged in:

sudo journalctl -u sshd -n 50

Suppose it says Authentication refused: bad ownership or modes for directory /home/newperson/.ssh. That is StrictModes, and the cause is that you created the directory as root and never handed it over:

sudo chmod 700 /home/newperson/.ssh
sudo chmod 600 /home/newperson/.ssh/authorized_keys
sudo chown -R newperson:newperson /home/newperson/.ssh

Now change one detail. Suppose the log has nothing at all for that user. Then they were rejected before authentication began, and that is AllowUsers or AllowGroups:

sudo sshd -T | grep -iE 'allowusers|allowgroups|denyusers'

And one more. Suppose the key works from your laptop and not from theirs, with the same file and correct modes, and the server log shows a refusal after several offered keys. That is the agent: theirs holds eight keys and MaxAuthTries 6 ends the connection before the right one comes up. ssh -o IdentitiesOnly=yes -i <the key> proves it in one attempt.

The point worth extracting: the client and the server each know half of why a login failed, and SSH is built so neither shares its half with a stranger. Every question in this topic is answered by deciding which half you need (ssh -v on one side, journalctl -u sshd on the other) and going to the machine that has it.

Try it

Optional, on two machines you can break, or on one machine connecting to itself.

1. ssh-keygen -t ed25519 -C "$(whoami)@$(hostname)", then ls -l ~/.ssh and read the modes the tool chose.
2. ssh-keygen -y -f ~/.ssh/id_ed25519 and compare it to the .pub file. Delete the .pub file and regenerate it, to prove nothing was lost.
3. ssh-copy-id sam@server, then read ~/.ssh/authorized_keys on the server and find your comment field at the end of the line.
4. chmod 644 ~/.ssh/id_ed25519, connect, read the warning in full, chmod 600, connect again.
5. chmod 777 ~/.ssh on the server, connect, and note how little the client tells you. Then read journalctl -u sshd there and note how much it knew.
6. sudo sshd -T | wc -l, then pick three keywords out of the output that appear in no file on the machine.
7. Add PermitRootLogin yess to the bottom of sshd_config, run sshd -t, read the line number, and remove it.
8. Open a second session. Then set MaxAuthTries 3, sshd -t, systemctl reload sshd, and connect from a third terminal before closing anything.

Verification step. You have it when, handed Permission denied (publickey), you can say in one sentence which of the two machines holds the explanation and which command prints it, before touching anything else.

Check yourself

sudo journalctl -u sshd -n 50
# Authentication refused: bad ownership or modes for directory /home/sam/.ssh

sudo sshd -T | grep -iE 'passwordauthentication|kbdinteractiveauthentication'

References

• ssh(1) - Linux man-pages project. Accessed 2026-08-08.
• sshd(8) - Linux man-pages project. Accessed 2026-08-08.
• sshd_config(5) - Linux man-pages project. Accessed 2026-08-08.
• ssh_config(5) - Linux man-pages project. Accessed 2026-08-08.
• ssh-keygen(1) - Linux man-pages project. Accessed 2026-08-08.
• ssh-agent(1) - Linux man-pages project. Accessed 2026-08-08.
• ssh-copy-id(1) - Linux man-pages project. Accessed 2026-08-08.
• sftp(1) - Linux man-pages project. Accessed 2026-08-08.
• jail.conf(5) - Debian manpages. Accessed 2026-08-08.

Captured output came from two machines: a Debian 13 container for the client and server tooling, and a Fedora CoreOS virtual machine for the drop-in configuration. The refused-key transcripts are real, produced by loosening permissions on a live key and connecting to localhost inside the container. Blocks without a distribution and architecture header are illustrative: ssh-copy-id, sftp, fail2ban, Match blocks, and certificate signing all need a second machine or a running service manager, so those are shown as commands without invented output.