Generate and Add SSH Keys

Understand how to generate SSH keys to configure Git, SFTP, or Drupal Drush.

Tweet

To take full advantage of Pantheon, you should load your public SSH key into your account. SSH keys are a best practice for authentication, allowing you more security than a simple password. You will only need to do this once for each work environment (laptop, desktop, etc.), no matter how many sites you work on.

 Note

Pantheon does not provide access to a shell environment over SSH. These directions allow you to have passwordless access if you configure Git, SFTP, or Drush to use SSH keys.

Generate SSH Key

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

    ssh-keygen

    This command works on Linux, MacOS, and Windows 10.

  2. Unless you have reason to change it, leave the default location of ~/.ssh/id_rsa. If the command says the key already exists, you can either overwrite it or continue onto the next step with your existing key.

  3. A passphrase is recommended to provide greater security, but can conflict with tools that cannot handle them.

  4. Once the files are created, copy the contents of ~/.ssh/id_rsa.pub to your clipboard.

    Linux and Mac users can catthe file to the terminal and copy the output:

    cat ~/.ssh/id_rsa.pub

    Windows users can achieve the same result with type:

    type .ssh\id_rsa.pub

Add Your SSH Key to Pantheon

  1. Log in to Pantheon and go to the Account tab in your User Dashboard.

  2. Click SSH Keys.

  3. Paste the copied public key into the box, and click Add Key.

    Adding SSH Keys

    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.

  4. In your Terminal environment, copy the SSH clone URL from the Connection Info of any site's Dev environment to clone your site code to your workstation.

  5. If prompted, enter the passphrase you set above.

Delete a Key from Pantheon

To delete a key, go to the Account tab of your User Dashboard and click SSH Keys. Click the Remove button next to the key you want to delete:

Delete SSH Key

If you have active sites and no keys remaining, you can still access the sites. Make site changes via SFTP or Git using your account password to authenticate. If you sign in through Google and haven't defined a password, you can set one on the Reset Password page.

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.

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:

ssh_config
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:

ssh_config
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:

ssh_config
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. 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