RSS Feed

SSH Access Setup Explained

Created: 18.10.2020

In order to perform actions with you public/private key pair (git, ssh access), you’ll need to configure it first. I found it quite hard to grasp at first with all the nuances, although it’s pretty straitforward if you just copy/paste the commands.

Let’s take GitHub and its manual in order to understand what we are doing and why. This will help in thoubleshooting later if we need it.

In order to use private/public keys, you will need to generate a pair first. All these keys on macOS and Linux machines are stored at ~/.ssh by default (hidden folder). Public keys have pub at the end, private have the same name but no pub extension. For example, a public key file would be named something like id_rsa.pub, unless you give it a different name and its corresponding private key would be called just id_rsa.

Let’s say that there is nothing in the ~/.ssh folder and we need to generate a new key pair. It’s as simple as running shell ssh-keygen -t ed25519 -C "your_email@example.com or shell ssh-keygen -t rsa -b 4096 -C "your_email@example.com". The difference is the algorithm (ed25519 or rsa). You need to know the technical requirements for the keys that are used for the system you are trying to set up access to. For example, GitHub prefers ed25519, however they do support rsa at the moment as well (📆 08/07/2022).


This is the point where you’d choose the name for your key, which can be anything you like (not sure about special characters though). By default, keys will be stored in ~/.ssh directory.

I’ve given this key 🗝 the following name: asgardmasterkey. Now the system what’s a password. I come up with something good enough for Asgard (123456) and press Enter.


❗️Copy the key fingerprint to add it later to the known_hosts file. It can be added automatically to the file once you’ve connected to the host for the first time.

Let’s now move into our ~/.ssh folder and see what’s there. So, there are asgardmasterkey.pub (public key) and asgardmasterkey(private). There are also several other files: config and known_hosts, both are very important!

We need to tell the ssh deamon that there is an update it needs to harvest. So, that’s why we first check if its running at all: shell eval "$(ssh-agent -s)". You get a PID in respone, you are good to move forward. Otherwise, start it with sudo -s -H or exec ssh-agent bash or exec ssh-agent zsh or whatever else works for your system.

For macOS users (like myself) there is an additional step to do - change the config file. Say, for example, that I need this key to connect to github.com (private Asgard repo!):

Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/asgardmasterkey

On GitHub they say you should put Host * instead, but this way, in case you ever add other ssh keys for other services, you’ll likely face errors. This line would mean that whatever you are connecting to, use this key. This name (github.com) can actually be something like privateasgardrepo or anything you like. Think of it as an alias, if you will. There are some additional things that can be used here but most of the time the below settings are enough. For more info see man ssh_config, Host and PATTERNS sections.

Usually, when connecting to a remote machine over ssh, you’d do something like the following:

ssh loki@

You’d be promted with a passoword then. Now let’s say that we have the following contents of the config file:

Host privateasgardrepo 
  User loki
  IdentityFile ~/.ssh/asgardmasterkey

In this case you’d only run ssh privateasgardrepo. This does sound like an overkill, however, it’s easier in case you have miltiple endpoint to connect to and you can’t remember all the IPs or domain names.

The next step is where you add your private key to the ssh daemon. shell ssh-add -K ~/.ssh/asgardmasterkey.

The next step is to share you public key (the one ending in pub) with the remote server. In case of GitHub you copy whatever is in the pub file (in our example, it’s asgardmasterkey.pub) go to your Account settings in the browser, open SSH keys and paste the contents of that file there.

If you’ve configured the config file correctly, you can now ssh privateasgardrepo (or whatever boring name there might be instead). Once you’ve connected to the host for the first time (in the example above, this would be some host at you’ll be promted with something like the following message:

The authenticity of host ' (' can't be established.
ED25519 key fingerprint is SHA256:Q[...]A34.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])?

It means that you’ve generated the keys, but you have not received the keys from the server yet. For this type connection both you and the server have a separate key pair which are different! You share your public key, server shares its. This is the point when you literally saying “Remember this server”. Now, it will be added to the known_hosts file and you won’t be prompted for this again in future unless the key changes or, for example, you have some 🐀 as the man-in-the-middle.