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.
- 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
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.
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
- 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
- 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.
To create a pair of keys, you can use the
ssh-keygen tool with just a few steps. Let's do it!
$ ssh-keygen -t rsa -b 4096 -C "Your Name <email@example.com>"
-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.
Generating public/private rsa key pair. Enter file in which to save the key (/home/<user>/.ssh/id_rsa): [Type]
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]
You can check the newly generated keys:
$ ls -l ~/.ssh $ cat ~/.ssh/id_rsa.pub
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.
$ ssh -i ~/.ssh/id_rsa_vps firstname.lastname@example.org Received disconnect from 126.96.36.199 port 22:2: Too many authentication failures Disconnected from 188.8.131.52 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".
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:
$ 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 email@example.com
Keep reading. I will describe it in section 5.
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 (
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 firstname.lastname@example.org: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_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.
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 184.108.40.206 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!
Let's discuss the benefits of using the SSH config file.
You do not have to specify user, host, or port every time to connect to a server via SSH.
$ ssh vps
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
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
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.