Generate and Add SSH Keys
Understand how to generate SSH keys to configure Git, SFTP, or Drupal Drush.
Discuss in our Forum Discuss in SlackLoad your public SSH key into your account to take full advantage of Pantheon. SSH keys allow you to stay secure and compliant with security regulations, provided that you use best practice to generate, store, manage, and remove them. Using SSH keys are a best practice for authentication, offering 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
Use the following steps to generate your SSH Key:
Note
Currently, we do not support ed25519
keys.
Open your terminal and enter the following command to generate a key:
ssh-keygen
This command works on Linux, MacOS, and Windows 10.
Leave the default location of
~/.ssh/id_rsa
as is, unless you have 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.Linux and Mac users can
cat
the 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
Start the SSH agent.
For Linux and Mac users, run
eval
to start the agent. TheAgent pid
output confirms it's started:eval `ssh-agent` Agent pid 86810
For Windows users, run
start-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])
For Linux and Mac users, add the newly created key to the ssh-agent:
ssh-add ~/.ssh/id_rsa
Add Your SSH Key to Pantheon
Add SSH Key - New Dashboard
Log in to your Pantheon Dashboard, and go to the SSH Keys tab of your User Profile's Personal Settings page.
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
- Navigate to the SSH Keys tab of your User Profile's Personal Settings page to revoke a key.
- 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
You can still access the sites if you have active sites and no keys remaining. 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 no
# The settings on the next two lines are temporary until Pantheon updates the available key types.
# If 'PubkeyAcceptedAlgorithms' causes an error, remove it.
HostkeyAlgorithms +ssh-rsa
PubkeyAcceptedAlgorithms +ssh-rsa
Now, requests to any *.drush.in
server address should automatically accept the server's SSH key fingerprint without prompting you.
Connections Fail With: no matching host key type found. Their offer: ssh-rsa
OpenSSH 8.8 disables RSA signatures like the key type Pantheon uses.
While we are working to remedy this on the platform, OpenSSH 8.8 will return this error for CLI commands:
Unable to negotiate with 203.0.113.123 port 2222: no matching host key type found. Their offer: ssh-rsa
Solution: Until the key type is updated on the Pantheon platform, add ssh-rsa
to the accepted algorithms in ~/.ssh/config
:
Look for
$HOME/.ssh/config file
. If none present, create it usingtype
:cd %HOMEPATH%/.ssh type nul > config
Copy/paste the following into config:
~/.ssh/configHost *.drush.in # The settings on the next two lines are temporary until Pantheon updates the available key types. # If 'PubkeyAcceptedAlgorithms' causes an error, remove it. HostkeyAlgorithms +ssh-rsa PubkeyAcceptedAlgorithms +ssh-rsa
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 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
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
Note
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.