# SSH Troubleshooting

**SSH connection issues** usually come from permissions, wrong keys, host key mismatches, or firewalls. Debug with verbose output and check logs.

Enable verbose output:

```bash
$ ssh -vvv user@host
```

Shows protocol details, key matching, and error messages. Three `-v` flags are maximum verbosity.

Common issues and fixes:

**Permission denied (publickey)**

```bash
$ ssh user@host
Permission denied (publickey).
```

Causes: wrong key, key not in `authorized_keys`, or file permissions.

Fix: Check client-side permissions:

```bash
$ chmod 600 ~/.ssh/id_*
$ chmod 700 ~/.ssh
```

Check server-side (on remote host):

```bash
$ chmod 644 ~/.ssh/authorized_keys
$ chmod 700 ~/.ssh
```

Verify key is present: `cat ~/.ssh/authorized_keys`

**Connection refused**

SSH server not running, or wrong port.

```bash
$ telnet host 22                 # check if port is open
$ ssh -p 2222 user@host          # specify port
```

On server: `sudo systemctl status ssh`

**Host key changed**

Unexpected key means possible man-in-the-middle attack.

```bash
$ ssh user@host
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
```

If you trust the host (e.g., server was rebuilt), remove old key:

```bash
$ ssh-keygen -R host
```

Or manually:

```bash
$ ssh-keygen -R 192.168.1.100
```

**Too many authentication failures**

SSH tried too many keys.

```bash
$ ssh -o PubkeyOnly=yes -i ~/.ssh/correct_key user@host
```

Or remove unwanted keys from agent: `ssh-add -d ~/.ssh/wrong_key`

**SSH key prompts for passphrase repeatedly**

Key not in agent, or agent not running.

```bash
$ ssh-add ~/.ssh/id_ed25519     # add to agent
$ echo $SSH_AUTH_SOCK            # check if agent is running
```

**Slow connection**

Enable compression or debug DNS:

```bash
$ ssh -o Compression=yes user@host
$ ssh -o UseDNS=no user@host    # skip reverse DNS lookup
```

Verify connectivity:

```bash
$ ssh-keyscan -p 22 host         # fetch host key (no auth needed)
```

Server logs:

```bash
$ sudo tail -f /var/log/auth.log       # Linux
$ sudo log stream --predicate 'process == "sshd"'  # macOS
```

Debug by disabling some options: `ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null user@host` (only for testing).