Creating an SSH key#

An SSH key is a pair of files that lets you log in to a server without a password. You keep the private half secret and hand out the public half; the server uses the public key to recognise you. This guide covers generating a key, adding it to a server, and connecting.

Generate a key#

On macOS or Linux, run ssh-keygen. We recommend the ed25519 algorithm, which is fast, short, and secure:

ssh-keygen -t ed25519 -C "you@example.com"

You'll be asked where to save the key (the default, ~/.ssh/id_ed25519, is fine) and for an optional passphrase. Set a passphrase: it encrypts the private key on disk, so a copied file is useless on its own.

This writes two files:

Never share or upload the private key (the file without .pub). Anyone who has it can log in as you. You only ever copy the .pub file to a server or paste it into a control panel.

ed25519 or RSA?#

Use ed25519 unless you have to talk to an old system that doesn't support it. In that case, generate a 4096-bit RSA key instead:

ssh-keygen -t rsa -b 4096 -C "you@example.com"

Avoid older ssh-rsa defaults and DSA keys; they're weaker and increasingly rejected by modern servers.

View your public key#

Print the public key so you can copy it:

cat ~/.ssh/id_ed25519.pub

It's a single line that starts with ssh-ed25519 and ends with the comment you set. That whole line is what a server needs.

Add your key to a server#

You have a few options, from easiest to most manual.

At deploy time. When you create a Nikosa server, select your public key in the control panel (or pass it with the nikosa CLI) and it's installed for the root user automatically, with no copying needed.

With ssh-copy-id. For an existing server you can already log in to, this appends your public key to the right place:

ssh-copy-id -i ~/.ssh/id_ed25519.pub root@203.0.113.42

By hand. If ssh-copy-id isn't available, add the key yourself. On the server, append the public-key line to ~/.ssh/authorized_keys and fix the permissions:

mkdir -p ~/.ssh && chmod 700 ~/.ssh
echo "ssh-ed25519 AAAA... you@example.com" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

Connect#

If the key is in the default location, SSH finds it automatically:

ssh root@203.0.113.42

To point at a specific key, use -i:

ssh -i ~/.ssh/id_ed25519 root@203.0.113.42

For servers you use often, add an entry to ~/.ssh/config so you can type a short name:

Host my-server
  HostName 203.0.113.42
  User root
  IdentityFile ~/.ssh/id_ed25519

Then just ssh my-server. If you set a passphrase, add the key to your agent once per session so you aren't prompted every time:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Troubleshooting#

• Permission denied (publickey): the server didn't accept your key. Check you're using the right username, that the public key is in the server's ~/.ssh/authorized_keys, and that you're offering the matching private key.
• Wrong permissions: SSH ignores ~/.ssh and authorized_keys if they're too open. Use chmod 700 ~/.ssh and chmod 600 ~/.ssh/authorized_keys.
• See what's happening: run ssh -v root@<ip> for a verbose log of which keys are offered and why a login fails.