Setting Up SSH Keys on Linux: A Step-by-Step Guide

Introduction / Why This Is Needed

SSH keys provide a more secure and convenient method for authentication when connecting to remote servers via SSH compared to using a password. Instead of entering a password each time, you use a cryptographic key pair, which not only simplifies the process but also protects against brute-force attacks. This guide will help you generate SSH keys, add them to your server, and configure your client for passwordless login.

Requirements / Preparation

Before you begin, make sure that:

• You have access to a Linux machine (the client) with the openssh-client package installed. It is usually pre-installed on most distributions.
• You have a user account and password to access the target server via SSH.
• You are familiar with basic terminal commands and file editing (e.g., with nano or vim).

If openssh-client is not installed, install it:

For Ubuntu/Debian:

sudo apt update && sudo apt install openssh-client

For CentOS/Fedora:

sudo dnf install openssh-clients

Step 1: Generate SSH Keys

On the client machine, open a terminal and run:

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

Using the ed25519 algorithm is recommended as it is modern and secure. If your system does not support it, you can use rsa with a 4096-bit length:

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

The command will prompt you for a location to save the keys (default ~/.ssh/id_ed25519 or ~/.ssh/id_rsa) and a passphrase. For automation, you can leave it empty, but for security, a strong passphrase is recommended.

After execution, two files will appear in the ~/.ssh/ directory: a private key (without an extension or with .pem) and a public key (with .pub).

Step 2: Copy the Public Key to the Server

The simplest method is to use the ssh-copy-id utility:

ssh-copy-id user@server

Replace user with your username on the server and server with the IP address or domain. You will be prompted for your password to complete the copy.

If ssh-copy-id is not available, copy the key manually:

1. View the contents of the public key:

   cat ~/.ssh/id_ed25519.pub
   

2. Copy the output (it starts with ssh-ed25519 ...).
3. On the server, in an SSH session, open or create the file ~/.ssh/authorized_keys and paste the copied line.

   mkdir -p ~/.ssh
   echo "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..." >> ~/.ssh/authorized_keys
   

Ensure the authorized_keys file contains only your keys, one per line.

Step 3: Set Permissions on the Server

Correct permissions are critical for SSH key functionality. On the server, run:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

If the .ssh directory or authorized_keys file is owned by another user, change the owner:

chown -R $USER:$USER ~/.ssh

Note: These commands are run on the server, not on the client.

Step 4: Test the Connection

Try connecting to the server from the client:

ssh user@server

If you set a passphrase when generating the key, you will be prompted to enter it. Otherwise, the connection should be established without a password prompt.

To verify that the key is being used, add the -v flag for debugging:

ssh -v user@server

Look for lines about Offering public key and Authentication succeeded in the output.

Step 5: Use SSH Agent for Key Management (Optional)

If you have multiple keys or set a passphrase, using ssh-agent to cache them is convenient. Start the agent and add your key:

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

After this, the passphrase will not be requested again during the agent session. To start the agent automatically on login, add these commands to your ~/.bashrc or ~/.profile.

Verify the Result

A successful connection without a password prompt (or only with a passphrase prompt if you set one) indicates correct configuration. You can also check on the server in ~/.ssh/authorized_keys to confirm your public key is present.

Additionally, run on the client:

ssh-add -l

This will show the list of keys added to the agent.

Potential Issues

• "Permission denied (publickey)" error: Check permissions on the server: ~/.ssh should be 700, authorized_keys should be 600. Ensure the public key was copied completely and without modifications.
• Key not offered: Ensure the client is using the correct key. You can specify it explicitly: ssh -i ~/.ssh/id_ed25519 user@server. Also check that ~/.ssh/config does not have overrides.
• SELinux or AppArmor blocking access: On some systems with SELinux (CentOS, RHEL), you may need to adjust contexts. Use restorecon -Rv ~/.ssh on the server.
• Forgotten passphrase: If you forget the passphrase, generate a new key pair and replace the public key on the server.

Use ssh -v for detailed output to diagnose issues.