SSH key setup

# SSH key authentication on fortrabbit

SSH key authentication is used to securely identify you for code access. Remember, on fortrabbit an account represents a person. Your fortrabbit account may store the public parts of several SSH keys.

# Reuse your GitHub SSH keys

Already using GitHub and our deployment flows? The fortrabbit dashboard can directly import public keys associated with your GitHub account so you don't need to setup additional keys for this.

# Do you already have a SSH key?

To see any existing keys, open a terminal to list the ~/.ssh folder:

$ find ~/.ssh
#/…/.ssh/config
#/…/.ssh/id_ed25519      ← private key part
#/…/.ssh/id_ed25519.pub  ← public key part
#/…/.ssh/known_hosts
shell

Proceed to the next section if you don't have any key pairs or get an error about a missing folder. If you do see key pairs like above, then you can upload the public SSH key.

# Generate a SSH key pair

# NOTE: me@fortrabbit is just an identifier, use what suits you
$ ssh-keygen -t ed25519 -C me@fortrabbit
# Generating public/private ed25519 key pair.
# Enter file in which to save the key (/home/user/.ssh/id_ed25519):
# Enter passphrase (empty for no passphrase):
# Enter same passphrase again:
shell

We suggest to use me@fortrabbit so that you can identify the key as being associated with your fortrabbit account later on. Use anything you like. It's just a comment.

# Importing SSH keys to fortrabbit

The public part of the key must be imported in the fortrabbit dashboard.

Make sure you paste the public part of the key and not the private part. It's also possible to import SSH keys from GitHub account into your fortrabbit account.

# Copy your public SSH key value

The value to paste into the text field can be read into the clipboard.

# macOS
$ pbcopy < ~/.ssh/id_ed25519.pub

# Linux
$ xclip -i < ~/.ssh/id_ed25519.pub

# Windows
# Open the `id_ed25519.pub` file, select all, then copy.
shell

# Deploy keys

In certain scenarios, you may want to grant a non-human service access to an environment. Use deploy keys for that. The deploy keys are managed via the dashboard with the environments. Adding and removing such keys follows the same concepts as described above. Use deploy keys to integrate with services, not to give other humans access.

# Specify a different key than the default

If you use an unprotected key (no passphrase) and still get asked about a password, it may be the case that the key in the default location is not imported into fortrabbit. To use a specific key run SSH like this:

$ ssh -i ~/.ssh/CUSTOM_KEY {{app-env-id}}@ssh.{{region}}.frbit.app
# Replace CUSTOM_KEY with a key on your machine
shell

# SSH keys generation on Windows

The procedure to create SSH keys is slightly different on macOS and Linux compared to Windows. There are different ways to set up and use Git with Windows and also different ways set up and store the keys. We recommend using the official installer from the Git website, together with Git Bash.

# SSH keys under Windows with PuTTY

If you generated an SSH key with PuTTY, you will need to make sure that the private key is saved in the location where git.exe or ssh.exe are looking for it or take steps to specify where the key is. Additionally, PuTTY uses a special format to store the private key, which also requires additional steps to use with other tools. Because of these reasons and previous experience with clients, we advise against using PuTTY.

# About SSH public key authentication

SSH key authentication is a more secure and convenient way to log in than using passwords. Instead of a short password, you use a virtually impossible to guess key file. The public part of the key is safe to share, while the private part should be kept secure. Once you import a public key into your account, it can be used to authenticate you. When you connect, the server will encrypt some secret using the public key. If you can decrypt the secret with the private key and send it back to the server, then the server knows that you can be trusted.