Connecting to a remote server using an SSH key is quite simple. However, when you have a lot of keys or multiple GitHub accounts, problems may arise. In this article, I am going to show you how to generate and manage keys in a neat way.
Contents
- 1. What is SSH?
- 2. SSH key
- 3. Generating a new SSH key
- Step #1: Run "ssh-keygen" command
- Step #2: Enter the private key's location
- Step #3: Enter a passphrase
- Step #4: Done
- 4. Potential problems due to multiple SSH keys
- Problem #1: Too many authentication failures
- Problem #2: Multiple GitHub accounts
- 5. SSH config file
- 6. Benefits
- Benefit #1: Connecting to a server using its alias
- Benefit #2: Dealing with multiple GitHub accounts
- 7. Conclusion
1. What is SSH?
SSH (Secure Shell) is an authenticated and encrypted network protocol used for remote communication between machines.
SSH supports various authentication methods. Password authentication is the easiest method, but it suffers from security vulnerabilities, such as brute force attacks. Another method is public-key authentication, which is more secure, and for me, more convenient.
2. SSH key
An SSH key, or an SSH key pair, is a pair of keys: a public key and a private key.
The public key:
- Usually named
id_rsa.pub - Acting as a public lock
- Placed on the SSH server that you want to log into
- Used to encrypt data
The private key:
- Usually named
id_rsa - Acting as a secret key
- Securely stored on your machine only
- Used to decrypt data
By default, these keys are stored in the ~/.ssh directory. You can also have multiple key pairs on your machine.
3. Generating a new SSH key
To create a pair of keys, you can use the ssh-keygen tool with just a few steps. Let's do it!
Step #1: Run "ssh-keygen" command
$ ssh-keygen -t rsa -b 4096 -C "Your Name <your_email@example.com>"
The -C option is used as a note to specify who/when/where the key was generated. Although this option is optional, I highly recommend filling it.
Step #2: Enter the private key's location
Generating public/private rsa key pair.
Enter file in which to save the key (/home/<user>/.ssh/id_rsa): [Type]
Step #3: Enter a passphrase
A passphrase, an extra security layer, is used to encrypt your private key. You can leave it blank and press enter to skip creating a passphrase, but I strongly recommend setting up the one.
Enter passphrase (empty for no passphrase): [Type]
Enter same passphrase again: [Re-type]
Step #4: Done
You can check the newly generated keys:
$ ls -l ~/.ssh
$ cat ~/.ssh/id_rsa.pub
4. Potential problems due to multiple SSH keys
If you have only one SSH key, congratulations, you have nothing to worry about. But what if you have more keys, for example, to access more remote servers?
I will show you a few potential problems right away.
Problem #1: Too many authentication failures
$ ssh -i ~/.ssh/id_rsa_vps user@1.2.3.4
Received disconnect from 1.2.3.4 port 22:2: Too many authentication failures
Disconnected from 1.2.3.4 port 22
As you can see, I failed to connect to the server with the corresponding private key, and the error was "Too many authentication failures".
What?
That means the SSH client tried a lot of other keys, and the authentication process failed before the key I specified was used.
Let me explain.
The SSH agent tracks private keys and their passphrases. When connecting to a server, the SSH client uses all the keys in the agent and the specified key to compose a key list to try each by each. The specified key will be added to the top of the list if it has been already tracked by the agent. Otherwise, it will be added to the end of the list.
Not too complicated, right?
Okay. The fact that the key I specified, ~/.ssh/id_rsa_vps, has not been tracked. Thus, there are at least 3 solutions as follows:
Solution #1.1: Adding the private key to the SSH agent by using the "ssh-add" tool
$ ssh-add ~/.ssh/id_rsa_vps
Solution #1.2: Ignoring the key list in the SSH agent by providing the SSH option "IdentitiesOnly=yes"
$ ssh -o IdentitiesOnly=yes -i ~/.ssh/id_rsa_vps user@1.2.3.4
Solution #1.3: Using the SSH config file
Keep reading. I will describe it in section 5.
Problem #2: Multiple GitHub accounts
This is an example of GitHub, but it is similar to any Git servers, such as GitLab, BitBucket, etc.
Suppose you have multiple GitHub accounts (personal and team), and you have added the corresponding key to each account. When you try to clone a repository from one account, you may see the following error.
$ git clone git@github.com:personal/repo.git
Cloning into 'repo'...
ERROR: Repository not found.
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.
Note: if you do not see any errors, try the other account's repository.
Let me explain.
First, you cannot add the same key to multiple GitHub accounts. Second, when you clone a repository using SSH, the SSH client sends each key in the list (that I have just described in the "Problem #1" section) to the GitHub server.
Depending on the key list order, id_rsa_personal or id_rsa_team will be accepted by the server. You know, if the accepted one does not belong to the owner of the repository, the permission error will be returned.
Okay. The solution is right below.
5. SSH config file
Forget the SSH agent. Using the SSH config file is a better way to manage multiple SSH keys. Believe me, the above potential problems will never happen again.
You can find the config file at ~/.ssh/config, or just create one.
Here is an example:
$ cat ~/.ssh/config
Host vps
HostName 1.2.3.4
Port 22
User user
IdentityFile ~/.ssh/id_rsa_vps
IdentitiesOnly yes
Host github-personal
HostName github.com
User git
IdentityFile ~/.ssh/id_rsa_github_personal
IdentitiesOnly yes
Host github-team
HostName github.com
User git
IdentityFile ~/.ssh/id_rsa_github_team
IdentitiesOnly yes
Let me explain.
- Host: I used as an alias of the host
- HostName: the real hostname to log into
- Port: the port number
- User: the user used to log into
- IdentityFile: the private key file
- IdentitiesOnly: setting it to "yes" that tells the SSH client to only use the private keys configured in the SSH config files, so the "Problem #1" will be resolved!
6. Benefits
Let's discuss the benefits of using the SSH config file.
Benefit #1: Connecting to a server using its alias
You do not have to specify user, host, or port every time to connect to a server via SSH.
$ ssh vps
Awesome!
An example of using SCP to copy a file from the remote server to the local machine:
$ scp vps:/path/to/the/remote/file /home/<user>/Downloads
Benefit #2: Dealing with multiple GitHub accounts
You can clone the repository that belongs to the corresponding account. For example, to clone the repository of the personal account, I replaced github.com by the alias github-personal in the config file.
$ git clone git@github-personal:personal/repo.git
7. Conclusion
Managing multiple SSH keys by using the SSH config file is not complicated. You can explore even more SSH options if you like. I hope this article is helpful to you.
Top comments (1)
Very useful information, thank you 😀