SSH host-key rotation: change server identity without teaching clients to ignore warnings

Last updated: 5 Oct 20267 min read

tutorial

An SSH client records or otherwise trusts a server host key, then rejects an unexpected identity on a later connection. A planned rotation therefore needs an independently verified replacement fingerprint and a client migration path. OpenSSH can present multiple host keys during an overlap. Where the client and trust configuration support it, UpdateHostKeys can learn additional keys after a connection authenticated with an already trusted plain host key. That mechanism has conditions and is not a universal distribution channel. Inventory automated clients, pinned known-host files, host certificates, and image rebuilds before removing the old key.

Operational decision

A build-runner fleet reaches a source mirror over SSH. Operators generate a new Ed25519 host key on the mirror, record the fingerprint through a trusted inventory channel, and configure both old and new host keys during a bounded overlap. They connect from a canary runner with strict host checking, verify the server presents the expected identity, and inspect whether its client configuration learned the additional key. Runners using centrally managed known-host files receive an explicit updated trust bundle instead. Only after every runner cohort can connect under strict checking do operators remove the old host key. A surprise key change pauses deployment until the mirror identity is investigated; deleting known_hosts entries is not a verification step.

ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
sshd -t

Cost and verification

Overlap preserves continuity but temporarily keeps the old private key usable, so the deadline must be short if it may be exposed. Distributing a new trust bundle consumes coordination across CI runners, human clients, and recovery consoles. Count clients that still trust only the retiring key and test an actual strict-check connection from each client class. A host certificate design can reduce per-host pinning work, but moves trust to a certificate authority and its signing controls. Record whether the rotation is planned or a suspected compromise; the latter changes the containment sequence.

Common Mistakes

Do not set StrictHostKeyChecking to no to make a rotation pass.
Do not confuse the server host key with a user's authorized key.
Do not assume UpdateHostKeys works with every custom known-hosts configuration.

Connected lessons

Practice and check

devops

linux

host-security