Troubleshooting - SSH key authorization and passphrases
Historical incident: 5 November 2026. The deployment client was WSL and the target was the documentation container. This case predates the current image-based delivery pipeline.
Symptom
An administrative SSH key did not provide the expected login. Another key prompted for a passphrase but could not be unlocked with the entered value. Similar-looking password prompts made these separate problems easy to confuse.
Evidence and diagnosis
| Finding | Meaning |
|---|---|
| The intended newer public key was absent from the target's authorized_keys | The target did not authorize that key |
| An older key was authorized, but its local unlock test rejected the entered passphrase | Local private-key unlocking was a separate failure |
| An initially added authorized_keys entry omitted its key-type prefix | The entry was incomplete and needed correction |
The investigation used verbose SSH output to inspect the offered identity, a local ssh-keygen passphrase test, and a trusted administrative path to inspect the target's authorized_keys. No private key material belongs in logs or documentation.
A passphrase protects a private key on the client. An account password is a server authentication credential. Neither is the public-key authorization entry stored on the target.
Correction
- Preserve a working administrative session and back up the target state.
- Add the intended complete public-key line outside the Proxmox-managed block.
- Retain restrictive authorized_keys permissions.
- Test key-based login from a separate WSL session before closing the working session.
- Configure a host-specific IdentityFile and IdentitiesOnly setting to select the intended key explicitly.
The historical record reports successful key-based access and a successful file transfer after the repair. It did not establish a complete content-level verification of every deployed page, so that is not claimed here.
A later diagnostic trap
A subsequent transfer attempt looked silent because diagnostic output was filtered. After loading the key into ssh-agent and running the transfer without that filter, the transfer succeeded. The exact cause of that attempt's failure was not conclusively established; an incorrectly entered passphrase was a hypothesis, not a proven root cause.
What I learned
- Separate identity selection, server authorization and local key unlocking.
- Read the prompt: account password and private-key passphrase are different.
- Do not filter interactive authentication diagnostics so aggressively that prompts and errors disappear.
- Check the execution environment before running a transfer: a WSL source path does not exist inside the target container.
- Do not change permissions blindly or weaken authentication to bypass diagnosis.