Generate and Add SSH Keys

SSH keys are a best practice for authentication and offer more security than a simple password. SSH keys allow you to stay secure and compliant with security regulations, provided that you follow recommended guidelines to generate, store, manage, and remove your SSH keys.

You can take full advantage of Pantheon by loading your public SSH key into your account. You must add your SSH key once for each work environment (laptop, desktop, etc.), no matter how many sites you work on.

Generate an SSH Key

Use the steps in this section to generate your SSH key.

MacOS/Linux

1. Open your terminal and enter the following command to generate a key:

   ssh-keygen -t rsa -m PEM

   Do not edit the default location of ~/.ssh/id_rsa unless you have a reason to change it. If the command says the key already exists, you can either overwrite it, or continue to the next step with your existing key.

2. Set a passphrase for better security.

   We recommend using a passphrase, but it can conflict with some tools.

3. Copy the contents of ~/.ssh/id_rsa.pub to your clipboard after the files are created.

   MacOS users can catthe file to the terminal and copy the output:

   cat ~/.ssh/id_rsa.pub

4. Run eval to start the SSH agent. The Agent pid output confirms that the agent started:

   eval `ssh-agent`
   Agent pid 86810

5. Add the newly created key to the ssh-agent:

   ssh-add ~/.ssh/id_rsa

Windows

1. Open your terminal and enter the following command to generate a key. This command works for Windows 10:

   ssh-keygen -t rsa -m PEM

   Do not edit the default location of ~/.ssh/id_rsa unless you have a reason to change it. If the command says the key already exists, you can either overwrite it, or continue to the next step with your existing key.

2. Set a passphrase for better security.

   We recommend using a passphrase, but it can conflict with some tools.

3. Copy the contents of ~/.ssh/id_rsa.pub to your clipboard after the files are created.

   type .ssh\id_rsa.pub

4. Run start-ssh-agent to start the SSH agent. The output confirms the agent has started. Enter the passphrase, if it was previously set.

   start-ssh-agent
   Removing old ssh-agent sockets
   Starting ssh-agent:  done
   Enter passphrase for /c/Users/[user]/.ssh/id_rsa:
   Identity added: /c/Users/[user]/.ssh/id_rsa ([user@machine_name])

Add Your SSH Key to Pantheon

Add SSH Key - New Dashboard

1. Log in to your Pantheon Dashboard.

2. Click your user icon in the top right then click Personal Settings, and go to the SSH Keys tab.

3. If this is your first key, click Get Started, otherwise click Add New Key.

4. Paste the copied public key into the box, and click Save.

   

   Your computer is now set up to securely connect to the Pantheon Git server. You can view a list of available keys on the same page.

Add SSH Key - Classic Dashboard

1. Log in to your Pantheon Dashboard.

2. Click your username in the top right, then select My Dashboard.

3. Open the Account tab in your User Dashboard.

4. Click SSH Keys.

5. Paste the copied public key into the Add Key box.

6. Click the Add Key button.

   Your computer is now set up to securely connect to the Pantheon Git server. You can view a list of available keys on the same page.

Clone Your Site Code

You can use your Dev environment to clone your site code to your workstation:

1. Use Terminal to copy the SSH clone URL from the site's Connection Info.

2. Enter the passphrase you set above, if prompted.

Remove SSH Key from Pantheon

Revoke SSH Key from Pantheon - New Dashboard

1. Log in to your Pantheon Dashboard.

2. Click your user icon in the top right then click Personal Settings, and go to the SSH Keys tab.

3. Click the Revoke button next to the key you want to remove:

   

4. Check the box in the confirmation prompt and click continue.

Remove SSH Key from Pantheon - Classic Dashboard

1. Navigate to the Account tab of your User Dashboard and click SSH Keys.

2. Click the Remove button next to the key you want to delete:

Site Access After Removing Keys

After removing SSH Keys from your user account, you will not be able to interact with the application and codeservers directly through command line interfaces like Git, SFTP, WP-CLI, and Drush. However removing SSH keys is separate from revoking the machine tokens used by Terminus to perform actions (e.g., creating Multidev environments) that can otherwise be done in the Pantheon Site Dashboard.

Troubleshooting

Authenticity & Fingerprint Prompts

Your first connection to any remote server over an SSH connection (like Git or SFTP) will prompt you to confirm the host identity:

The authenticity of host '[codeserver.dev.UUID.drush.in]:2222 ([IP.ADDRESS]:2222)' can't be established.
RSA key fingerprint is SHA256:yPEkh1Amd9WFBSP5syXD5rhUByTjaKBxQnlb5CahZZE.
Are you sure you want to continue connecting (yes/no)?

You can safely type yes and press enter to add the server's SSH key fingerprint to your computer's known_hosts file. Additional connections to this specific Pantheon container will complete successfully without prompts. However, you will be prompted to confirm connections following a container migration, which is part of regular maintenance on the platform. See the following Pro Tip to automatically accept all Pantheon connections.

Host *.drush.in
    StrictHostKeyChecking no

Control Path Error

You may receive the following error:

ControlPath too long fatal: Could not read from remote repository.

Check your SSH config files (by default, $HOME/.ssh/config and /etc/ssh/ssh_config) for a declaration like this:

Host *
ControlMaster auto
ControlPath ~/.ssh/control-%l.%r@%h:%p

There are two ways to fix this. First, try adjusting the Controlpath line as shown below:

Host *
ControlMaster auto
ControlPath ~/.ssh/control-%r

If this doesn't fix the issue, try creating an entry in your SSH configuration for your site specifically by its hostname. Don't use the ControlMaster option, instead use the ControlPath line as shown below, replacing SITE_UUID with your site's UUID:

Host *.SITE_UUID.drush.in
ControlPath ~/.ssh/control-%r

Server Refused to Allocate pty

This error occurs when a user is attempting to make a direct connection to Pantheon via SSH. Pantheon does not support direct SSH connections.

Authentication Prompts

Password requests may still occur after adding an SSH key to your Pantheon account if the corresponding key is not found by your local ssh-agent. Verify by listing the SSH fingerprints already loaded in your device's ssh-agent:

ssh-add -L | ssh-keygen -l -E md5 -f - | awk '{print substr($2,5)}'

The resulting string should match one of the keys listed in your Personal Settings.

To resolve, add your SSH key to the ssh-agent using the following command, replacing id_rsa with the name of your private key, if different:

ssh-add ~/.ssh/id_rsa

If you are using a Linux distribution such as Fedora 33 or later, make sure RSA keys are enabled in ~/.ssh/config:

Host *.drush.in
  PubkeyAcceptedKeyTypes=ssh-rsa