OpenSSH Troubleshooting¶

Common failure modes and their fixes. For a systematic diagnostic walkthrough (verbose flags, connection-vs-auth-vs-forwarding triage table), see openssh-comprehensive-guide.md §14 — this doc holds the specific recurring issues encountered day-to-day.

"Too many authentication failures"¶

Covered in full in openssh-key-management.md §5 — an agent or default key search is offering more keys than the server allows before reaching the correct one. Fix with IdentitiesOnly yes + explicit IdentityFile.

"Could not open a connection to your authentication agent"¶

No ssh-agent is running, or SSH_AUTH_SOCK isn't set in the current shell.

eval $(ssh-agent -s)
ssh-add

To make this automatic per login shell:

# ~/.bash_profile
eval $(ssh-agent) &>/dev/null
ssh-add &>/dev/null
export SSH_AUTH_SOCK

Starting a fresh ssh-agent on every shell/terminal spawn leaves orphaned agent processes behind over time (each with its own socket). Consider keychain or your desktop session's built-in agent (gnome-keyring, systemd --user socket-activated ssh-agent) instead for a single long-lived agent shared across sessions.

Inspecting what keys an agent is offering¶

ssh-add -l    # fingerprints only
ssh-add -L    # full public keys

Useful combined with agent forwarding (ssh -A) to confirm what a remote host would see if it used your forwarded agent — see the forwarding risk note in openssh-client-config.md §2.

X11 forwarding issues¶

Warning: No xauth data; using fake authentication data for X11 forwarding

Check ~/.ssh/config — ForwardX11 must not be no for the host in question:

Host myhost
  ForwardX11 yes

.Xauthority does not exist after ssh -X hostname:

touch ~/.Xauthority

X11 connection rejected because of wrong authentication (commonly seen launching GUI tools like virt-manager over a forwarded/relayed X session):

export XAUTHORITY=$HOME/.Xauthority
sudo virt-manager

Note that sudo by default doesn't preserve your user's XAUTHORITY/DISPLAY environment — either export XAUTHORITY explicitly as above, or use sudo -E to preserve the calling user's environment (weigh that against the broader environment-leak risk of -E under sudo).

ssh 'DOMAIN\username@host'

See openssh-client-config.md §6.

Logging session output to a file¶

Not built into ssh itself — wrap it with tee:

# ~/.bashrc
myssh () { ssh "$1" 2>&1 | tee -a ~/logdir/"$1".log; }
alias ssh=myssh

For anything beyond ad-hoc local logging — audit trails, session recording, compliance — this shell-wrapper approach is too fragile (doesn't capture full terminal control sequences correctly, easy to bypass). Reach for script/asciinema for local session recording, or sshd's own auth logging (LogLevel VERBOSE, see openssh-comprehensive-guide.md §12) plus a bastion host with something like auditd or commercial session-recording (e.g. Teleport, Gravitational's original use case) if you need real command-level audit trails server-side.