Generate and Add SSH Keys
Understand how to generate SSH keys to configure Git, SFTP, or Drupal Drush.
Discuss in our Forum Discuss in SlackTo 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.
Watch: Generate a SSH Key and Add it to Your Dashboard
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
Open your terminal and enter the following command to generate a key:
ssh-keygenThis command works on Linux, MacOS, and Windows 10.
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.A passphrase is recommended to provide greater security, but can conflict with tools that cannot handle them.
Once the files are created, copy the contents of
~/.ssh/id_rsa.pubto your clipboard.Linux and Mac users can
catthe file to the terminal and copy the output:cat ~/.ssh/id_rsa.pubWindows users can achieve the same result with
type:type .ssh\id_rsa.pub
Add Your SSH Key to Pantheon
Log in to Pantheon and go to the Account tab in your User Dashboard.
Click SSH Keys.
Paste the copied public key into the box, and click Add Key.
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.
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.
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:
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.
Pro Tip: Trust All Pantheon Hosts
The key fingerprint is a representation of the public key, used by the remote server to identify itself. These public keys, along with private keys, form a keypair used by the Diffie-Hellman key exchange to encrypt communication between you and the server.
On a standard server system, the server administrator would publish their host keys and fingerprints publicly, so clients could match them to the keys presented at these prompts. On Pantheon however, application containers are created and destroyed too rapidly to maintain a public key list.
You can, however, easily tell your machine to automatically trust all Pantheon *.drush.in servers by disabling the StrictHostKeyChecking option in your SSH configuration file.
Warning
Be aware that this disables a security feature and trusts your DNS system to always point you to the right IP addresses.
Open ~/.ssh/config (or create a new file if one does not exist) and add the following lines:
Host *.drush.in
StrictHostKeyChecking noNow, requests to any *.drush.in server address should automatically accept the server's SSH key fingerprint without prompting you.
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:%pThere are two ways to fix this. First, try adjusting the Controlpath line as shown below:
Host *
ControlMaster auto
ControlPath ~/.ssh/control-%rIf 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-%rServer 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 User Dashboard.
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