DEV Community

dpm_bush
dpm_bush

Posted on Originally published at sshflow.com

SSH Usernames: Log In as the Right Remote Account

#productivity #tutorial #devops #beginners

An SSH connection can reach the right server and still fail because the client is trying to log in as the wrong user. The username identifies an account on the remote machine; it is not necessarily the same as the username on your laptop.

Specify the remote user

The usual syntax puts the username before the hostname, separated by @:

ssh deploy@server.example.com
Enter fullscreen mode Exit fullscreen mode

You can also use -l to pass the login name separately:

ssh -l deploy server.example.com
Enter fullscreen mode Exit fullscreen mode

Both commands ask SSH to connect to server.example.com as the remote account deploy. Use whichever form is clearer in your scripts or notes.

If you leave out the username, OpenSSH normally tries your current local username:

ssh server.example.com
Enter fullscreen mode Exit fullscreen mode

Check the local username with:

whoami
Enter fullscreen mode Exit fullscreen mode

That default is convenient when your local and remote account names match. If they differ, specify the remote username explicitly instead of assuming SSH will discover it.

Save the username for a host

For a server you connect to regularly, put the login name in that host's SSH config entry. For example, add this to ~/.ssh/config:

Host staging
  HostName server.example.com
  User deploy
Enter fullscreen mode Exit fullscreen mode

Now connect with the short alias:

ssh staging
Enter fullscreen mode Exit fullscreen mode

SSH uses deploy as the remote user for this host. A username written directly in the command takes precedence over the configured User value:

ssh admin@staging
Enter fullscreen mode Exit fullscreen mode

This requests admin rather than deploy. If you want to add host aliases, ports, and key paths to the same file, see this practical SSH config example.

Where do you find the right username?

There is no universal SSH username. The account must exist on the server, and the right name depends on how that machine was provisioned.

  • Cloud VM: Check the provider's documentation for the specific image you launched. Defaults vary by provider and image; a username that works for one distribution or image may not work for another.
  • Managed server or shared hosting: Ask the provider or administrator who created the account.
  • A machine you can already access: Run whoami or id -un in that session to print the account name.

An SSH client can't tell you which account to use before you authenticate. If you're unsure, check the image documentation or ask whoever set up the server rather than cycling through guessed usernames.

A username is not a password

Put only the account name in the connection command. SSH may ask for the account password after it connects, if password authentication is enabled:

ssh deploy@server.example.com
Enter fullscreen mode Exit fullscreen mode

Do not put a password in the command or a script. There is no standard OpenSSH syntax like ssh username:password@hostname; embedding secrets can expose them through shell history, process listings, or logs. If the server uses key authentication, SSH will attempt to authenticate with an available key instead.

It also helps to separate two kinds of failure:

  • Connection problem: The client cannot reach the SSH server.
  • Authentication problem: The server was reached, but the login account or offered credentials were not accepted.

If the username is correct but key authentication still fails, use a step-by-step public-key authentication troubleshooting guide to check the key and account setup.

Usernames that need quoting

Most account names are straightforward, but a username containing special characters can interact with either SSH's syntax or your shell's parsing.

If the username itself contains @, the user@host form can be ambiguous. Pass the full name as the argument to -l instead:

ssh -l 'unusual@user' server.example.com
Enter fullscreen mode Exit fullscreen mode

For a domain-style account containing a backslash, quote the username so the shell passes the backslash through:

ssh -l 'DOMAIN\username' server.example.com
Enter fullscreen mode Exit fullscreen mode

The exact quoting rules depend on the shell. If a special-character login isn't behaving as expected, check what your shell passes to the command before changing server settings.

Quick checks before connecting

When a login doesn't work, check these in order:

  1. Is the hostname or IP address correct?
  2. Are you specifying the remote account, rather than assuming your local username matches?
  3. Does that account exist on the server and allow SSH access?
  4. If authentication fails, are you using a credential the server accepts?

For most connections, the key idea is simple: ssh user@host selects the remote account, while authentication proves you are allowed to use it.

I originally published a more detailed version of this guide on the SSHFlow blog.

I'm also building SSHFlow — an SSH client where every server gets its own workspace for terminals, SFTP, code, and databases.

Top comments (0)