Generate and Add SSH Keys
Understand how to generate SSH keys to configure Git, SFTP, or Drupal Drush.
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.
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 an SSH Key
Use the steps in this section to generate your SSH key.
Pantheon supports ECDSA and RSA SSH keys. Currently, we do not support ed25519
keys.
Watch: Generate a SSH Key and Add it to Your Dashboard
MacOS/Linux
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.Set a passphrase for better security.
We recommend using a passphrase, but it can conflict with some tools.
Copy the contents of
~/.ssh/id_rsa.pub
to your clipboard after the files are created.MacOS users can
cat
the file to the terminal and copy the output:cat ~/.ssh/id_rsa.pub
Run
eval
to start the SSH agent. TheAgent pid
output confirms that the agent started:eval `ssh-agent` Agent pid 86810
Add the newly created key to the ssh-agent:
ssh-add ~/.ssh/id_rsa
Windows
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.Set a passphrase for better security.
We recommend using a passphrase, but it can conflict with some tools.
Copy the contents of
~/.ssh/id_rsa.pub
to your clipboard after the files are created.type .ssh\id_rsa.pub
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
Log in to your Pantheon Dashboard.
Go to your Personal Settings, then go to the SSH Keys tab.
Click Add New Key.
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
Log in to your Pantheon site.
Click your username in the top right, then select My Dashboard.
Open the Account tab in your User Dashboard.
Click SSH Keys.
Paste the copied public key into the Add Key box.
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:
Use Terminal to copy the SSH clone URL from the site's Connection Info.
Enter the passphrase you set above, if prompted.
Remove SSH Key from Pantheon
Revoke SSH Key from Pantheon - New Dashboard
Log in to your Pantheon Dashboard.
Go to your Personal Settings, then go to the SSH Keys tab.
Click the Revoke button next to the key you want to remove:
Remove SSH Key from Pantheon - Classic Dashboard
Navigate to the Account tab of your User Dashboard and click SSH Keys.
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.
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.
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 no
Now, 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:%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
Pantheon does not have access to keys that only exist on the host machine. You must ensure that your keys and, if applicable, your key agent are made available to the application running in the container, if you're using Lando, Docksal, or DDEV.