OpenSSH Key Management¶

Generating, deploying, and maintaining SSH keys. For key types and why ed25519 is preferred over RSA, see openssh-comprehensive-guide.md §4; this doc is the day-to-day command reference.

1. Generate a key¶

# Preferred — ed25519
ssh-keygen -t ed25519 -C "amercer@server1" -f ~/.ssh/id_ed25519_server1

# Legacy targets that don't support ed25519 (old network gear, ancient OpenSSH)
ssh-keygen -t rsa -b 4096 -C "amercer@legacy-host" -f ~/.ssh/id_rsa_legacy

Accept the default location unless you're managing multiple identities, in which case always give the file an explicit, descriptive name (-f) — this also makes IdentitiesOnly yes + IdentityFile in ~/.ssh/config unambiguous. Always set a passphrase when prompted; pair with ssh-agent so you're not typing it on every connection.

The old default of plain ssh-keygen -t rsa (no -b) generates a 1024-bit key on very old OpenSSH versions and is well below current recommendations regardless. If you have any keys like this still in use, rotate them.

2. Inspect a key¶

ssh-keygen -l -f ~/.ssh/id_ed25519.pub    # fingerprint, bit size, type
ssh-keygen -p -f ~/.ssh/id_ed25519        # change/add a passphrase on an existing key

3. Deploy a public key to a remote host¶

ssh-copy-id -i ~/.ssh/id_ed25519.pub amercer@host

Manual equivalent (useful when ssh-copy-id isn't available, e.g. minimal containers):

cat ~/.ssh/id_ed25519.pub | ssh amercer@host 'mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys'

Ensure the remote authorized_keys file and .ssh directory have correct permissions — sshd silently refuses to use authorized_keys if the directory is group/world-writable:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

4. Removing a stale `known_hosts` entry¶

Happens after a host is rebuilt/reimaged and its host key changes (or after cloning a server — see §6):

ssh-keygen -f ~/.ssh/known_hosts -R server_name

(Manually editing the file with vi/dd also works but the -R flag is safer — it targets the exact host and re-hashes correctly if HashKnownHosts is enabled.)

5. Cleaning up "too many authentication failures"¶

If ssh fails with Received disconnect ... Too many authentication failures, an agent or default key search is offering more keys than the server's MaxAuthTries allows before it even gets to the right one. Diagnose with:

ssh -vvv amercer@host

Look for a block like:

debug2: key: /home/andrew/.ssh/aws-elastic-compute.pem (0x...), agent
debug2: key: jenkins@domain.tld (0x...), agent
debug2: key: /home/andrew/.ssh/id_rsa ((nil))
debug2: key: /home/andrew/.ssh/id_ed25519 ((nil))

Fix by either unloading unneeded keys (ssh-add -d ~/.ssh/unneeded_key) or, better, setting IdentitiesOnly yes with an explicit IdentityFile for that host in ~/.ssh/config — see openssh-client-config.md.

6. Regenerating host keys after cloning a server¶

If you clone a VM/container image, every clone inherits the same host keys — a security problem (clients can't distinguish the clones) and a source of known_hosts mismatch warnings. Regenerate on each clone:

mkdir /tmp/ssh_keys
sudo mv /etc/ssh/ssh_host_* /tmp/ssh_keys/
sudo ssh-keygen -A
sudo systemctl restart sshd

Bake this into cloud-init / your image-build pipeline rather than doing it manually per instance where possible.

7. Migrating a PuTTY (`.ppk`) key to OpenSSH format¶

Relevant when moving from a Windows+PuTTY workflow to a native OpenSSH client (Linux, macOS, or modern Windows with Git Bash/OpenSSH built in).

On the Windows side, using PuTTYgen:

Load → select the existing private key → enter its passphrase.
Conversions → Export OpenSSH key → save (e.g. openssh_key).

On the destination machine:

mv ~/openssh_key ~/.ssh/id_ed25519_migrated   # or id_rsa_migrated, matching the original type
chmod 600 ~/.ssh/id_ed25519_migrated
ssh-add ~/.ssh/id_ed25519_migrated

Reference it explicitly via IdentityFile in ~/.ssh/config rather than relying on default filename lookup (id_rsa) — the default-name convention is fragile once you have more than one identity, which is virtually always the case now.

8. Removing all keys from the agent¶

ssh-add -D