SSH config: fix an alias using the wrong account

Compare the effective configuration

Print the resolved alias with ssh -G. This evaluates the configuration without opening an SSH connection. Inspect hostname, user, port, identityfile, proxyjump, and any configured forwardings. Compare the values with the known working command.

This step is useful before increasing server log verbosity: a wrong username in the client’s own configuration is already enough to explain a rejected login. Keep the full output private if it exposes infrastructure details.

sh · EXAMPLE

ssh -G app-server
# A connection attempt can additionally show which files and rules apply.
ssh -v app-server

Recognize the early wildcard

The following example looks as though the later User setting should override the general default. In the controlled lab it did not: the wildcard filled User first, so the alias kept wrong-user and authentication failed.

Do not apply this explanation indiscriminately to every directive. OpenSSH documents exceptions, including multiple IdentityFile entries. Reordering a scalar User rule does not automatically remove accumulated identities.

sshconfig · EXAMPLE

# Problematic order for this scalar User setting:
Host *
  User wrong-user

Host app-server
  HostName server.example.com
  User developer

Place the specific rule before the default

Move the host-specific scalar settings before the broad defaults. Use the intended identity path and endpoint for your environment. A dedicated identity can be combined with IdentitiesOnly, while remembering that other matching IdentityFile directives may still accumulate.

Our corrected lab configuration selected developer and completed a harmless remote command. Neither authorized_keys nor server authentication settings changed; the repair was entirely in alias evaluation.

sshconfig · EXAMPLE

Host app-server
  HostName server.example.com
  User developer
  IdentityFile ~/.ssh/app_ed25519
  IdentitiesOnly yes

Host *
  User default-user
  ServerAliveInterval 30

Test a candidate file before replacing the original

Save the candidate in a separate file with appropriate local permissions, then use -F to inspect and test it. Substitute the actual path below. OpenSSH treats an explicitly supplied user configuration differently from the default search, so make required includes intentional.

A successful -G result proves parsing and selection, not reachability or authentication. Follow it with one benign remote identity check. Only after both checks should you apply the same narrowly scoped change to your usual configuration.

sh · EXAMPLE

ssh -G -F ./ssh-config.candidate app-server
ssh -F ./ssh-config.candidate app-server 'id -un'

Check includes and reused connections when results differ

If the normal file still behaves differently, follow verbose output through Include files and applicable Match blocks. A file in an include directory may set a value earlier than the rule you edited.

An already established multiplexed session can also confuse a comparison. Test a fresh connection with multiplexing disabled when diagnosing configuration changes, rather than terminating every shared session. Preserve unrelated aliases and forwardings while narrowing the one rule responsible.

Know the limits

Reproduced on OpenSSH 9.2p1 with a wildcard User rule placed before a host-specific User rule. IdentityFile is additive and must not be treated as a simple last-value or first-value scalar. Includes and Match rules can also affect the result.

Sources & further reading

A technical publication by CoreTrailKit.

Browse all articles