SSH keys: generate one, add it to the console and use it

Key authentication is both more convenient and much more secure than a password. There is nothing to guess or brute-force, and the private key never leaves your machine. This guide covers generating a key, storing it in the console, getting it onto a server, and the errors you are most likely to hit.

How a key pair works

A key pair is two files:

• The private key (for example ~/.ssh/id_ed25519) stays on your computer. Never share it, paste it into a website or email it.
• The public key (~/.ssh/id_ed25519.pub) is a single line you can hand out freely. A server that has it in ~/.ssh/authorized_keys will let in whoever holds the matching private key.

1. Generate a key on your own machine

On macOS, Linux, or Windows PowerShell:

ssh-keygen -t ed25519 -C "[email protected]"

Accept the default location and set a passphrase when asked. The passphrase encrypts the private key on disk, so a copied key file is useless without it.

Ed25519 keys are short, fast and strong. Use RSA only if a tool you depend on cannot handle ed25519, and then use 4096 bits:

ssh-keygen -t rsa -b 4096 -C "[email protected]"

2. Store the public key in the console

Print the public key:

cat ~/.ssh/id_ed25519.pub

It is one line beginning ssh-ed25519 (or ssh-rsa). In the console, open SSH Keys, add a new key, give it a recognizable name and paste that line.

Only ever paste the .pub file. Anything that starts with -----BEGIN OPENSSH PRIVATE KEY----- is the private half and must stay on your machine.

3. Install the key on a server

The simplest way to add a key to a running server is ssh-copy-id, which appends it to authorized_keys with the right permissions:

ssh-copy-id -i ~/.ssh/id_ed25519.pub [email protected]

On Windows, where ssh-copy-id is not available, do the same thing by hand:

type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh [email protected] "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

4. Connect

ssh [email protected]

You are asked for the key's passphrase, not the server password. To avoid typing the passphrase every time, load the key into your agent once per session:

ssh-add ~/.ssh/id_ed25519

If you manage several servers, a ~/.ssh/config entry saves typing:

Host web1    HostName 203.0.113.10    User root    IdentityFile ~/.ssh/id_ed25519

Now ssh web1 is all you need.

5. Turn off password login

Once key login works, keep that session open, then edit /etc/ssh/sshd_config on the server:

PasswordAuthentication noPermitRootLogin prohibit-password

systemctl reload ssh

Test from a second terminal before closing the first. If something is wrong you still have a working session to fix it from.

Check it worked

ssh [email protected] "whoami && hostname"

It should print root and the hostname without asking for a password.

Troubleshooting

• Permission denied (publickey). The server does not have the matching public key, or SSH is offering a different key. Run ssh -v [email protected] and look for which key files are tried.
• "Unprotected private key file". The private key is readable by other users. Fix it with chmod 600 ~/.ssh/id_ed25519.
• Still asked for a password. The key in authorized_keys is malformed, often split over several lines by a copy-paste. It must be one line.
• Connection refused or it hangs. That is a network or firewall problem, not a key problem. Test the port with nc -vz 203.0.113.10 22.
• Locked out completely. Use Open Console on the server page, or Reset root password. See Locked out of your server?.

Next steps

• On Windows and prefer a GUI? See Connecting from Windows with PuTTY.
• Deploy a Cloud Server and log in with your new key.
• Share servers safely by inviting teammates to a project with their own keys, rather than sharing one.