SSH Key Management for SSH Gateway

WP Engine’s SSH Gateway service provides shell access to a Linux environment so that you can manage your site’s files, database, and run commands such as those available through WP-CLI.

---

About SSH Keys

An SSH key casts aside the username and password, while providing greater security and saving you valuable typing time during authentication. WP Engine’s SSH Gateway system only allows you to authenticate via SSH key.

A private and public key pair must exist. Your private key should be kept private, and it should be stored on the machines from which you want to authenticate (usually in the ~/.ssh directory for UNIX-like operating systems, such as MacOS or Linux).

The public key is then added to the WP Engine User portal for authentication via our servers.

There are three primary steps for connecting your SSH key to WP Engine for use with the SSH Gateway:

1. A public/private SSH key pair
2. Add the public key to your User Portal profile
3. Create an SSH Config file (Optional, but highly recommended)

---

View and Validate Existing SSH Keys

Before you generate and add a new SSH key, you may first want to take a look at the SSH keys configured for your user profile. An existing key can be used easily, as long as it’s valid.

Check Local Machine for Existing SSH Key

1. Open a Terminal or Command Prompt window from your computer
2. Change directory into the “.ssh” folder and list out the files. On most machines you can simply run:
   • cd ~/.ssh && ls
3. If the following two files exist, then you already have an SSH key configured for WP Engine on this machine:
   • wpengine_ed25519 and wpengine_ed25519.pub

If you do not have a key listed here, learn how to generate a key below.

Validate Fingerprint on Existing SSH Key

If  the two files above exist, validate that the key on your computer matches the key with WP Engine by comparing fingerprints.

1. From your computer, print the fingerprint for this key using the following command:
   • ssh-keygen -E md5 -lf ~/.ssh/wpengine_ed25519.pub
2. Now, visit the following page in your User Portal:
   • https://my.wpengine.com/ssh_keys
3. Compare and confirm the fingerprints match.

If the fingerprints do not match, proceed to generating a new SSH key.

---

Generate New SSH Key

If you already have a key that you want to use for shell access, then you can certainly simply use that key when connecting. Otherwise you’ll need a new key pair which you can generate with these simple instructions:

1. Open a Terminal or Command Prompt window from your computer
2. Use ssh-keygen to generate a new key as shown below:
   • ssh-keygen -t ed25519 -f ~/.ssh/wpengine_ed25519
3. Hit enter or return to leave it the passphrase blank.
   • If you wish to set a password, you may. However the security benefit is debatable and it cannot be recovered if lost.
4. Once the process has completed, run the following to print the contents of the new key file:
   • cat ~/.ssh/wpengine_ed25519.pub

The entire contents of this SSH key file must be copied and added to your WP Engine user profile.

PuTTY

If you choose to use the PuTTY program on Windows, you must also install the PuTTYgen utility.

1. When you install the PuTTY program, also install the PuTTYgen utility
2. Open the PuTTYgen utility to generate your SSH key
3. When asked which type of key to generate, select ED25519
4. Click the Generate button to create your public and private key pair
5. Save both the public key and the private key locally and take note of where the files will reside on your computer

When asked to enter the public key into the WP Engine User Portal we recommend simply copying the key from the top of the window in PuTTY.

---

SSH Config File

After generating an SSH key pair, it is best practice to setup an SSH configuration file.

The SSH config file tells your computer which public/private key pair should be used for which hostname. It can prevent many issues and we highly recommend setting one up now to prevent issues down the road.

The configuration file will simply be named config and will live in your ~/.ssh/ directory.

If you are also using Git, you will also want to add a second section to this file for your Git SSH key.

Create SSH Config

This process will create an SSH config that tells your computer to use the newly generated ~/.ssh/wpengine_ed25519 key for any host matching *.ssh.wpengine.net

1. On your local machine, first navigate to your .ssh directory.
   • MacOS – Open Terminal and type:
     • cd ~/.ssh/
   • Windows – Use Git Bash and navigate to:
     • /c/Users/[youruser]/.ssh/
2. To create the file run:
   • touch config
3. To edit the file run:
   • vi config
4. Inside the file, tap i to insert text
5. Paste the following contents:
   • Host *.ssh.wpengine.net
IdentityFile ~/.ssh/wpengine_ed25519
IdentitiesOnly yes
6. To save and exit the vim editor:
   • esc button then :wq

If you are using SSH Gateway and Git, additional SSH Config contents should be added for Git.

Use SSH Config to Connect with an Alias

If you are a developer with several SSH keys and prefer to specify a key for each environment, the following SSH Config can be used instead:

Host MYCOOLALIAS
User ENVIRONMENTNAME
Hostname ENVIRONMENTNAME.ssh.wpengine.net
PreferredAuthentications publickey
IdentityFile ~/.ssh/YOURKEYFILENAME_ed25519
IdentitiesOnly yes

Be sure to update the following accordingly:

Update MYCOOLALIAS to the alias name you wish to use.
Update ENVIRONMENTNAME to the unique WP Engine name of the environment. This is also the name of the User.
Update ~/.ssh/YOURKEYFILENAME_ed25519 to your private key file path. This should typically be in the ~/.ssh/ directory and end in _ed25519.

To connect, you would then simply type the alias nickname you’ve assigned. For example: ssh MYCOOLALIAS

---

Test SSH Key

After adding your SSH key to your profile, you can test your shell access by typing this command on a terminal. Replace environment with your unique WP Engine environment name.

ssh environment@environment.ssh.wpengine.net

For example, if I was trying to connect to the “tiramisu” install:

ssh [email protected]

Connect with a Specific Key

Specifically, use this if you chose not to create the SSH configuration file previously.

ssh -i ~/.ssh/wpengine_ed25519 -o IdentitiesOnly=yes environment@environment.ssh.wpengine.net

---

Delete SSH Gateway Keys

Users can remove their SSH key from WP Engine with the following steps.

1. Login to the User Portal
2. Click your name, at the top right
3. Select My Profile
4. Click SSH Keys
5. Select Remove next to the desired key

Remove SSH Key for a User

Users cannot directly delete SSH Keys of other users, as they’re attached to a WP Engine user profile. However the profile itself can have access granted or removed to the environments or account, which will in turn remove their SSH access to those environments.

Remove Access to Specific Environment(s)

Edit their user role on the account to “Partial”.

Ensure the desired environment(s) are not selected.

Remove Access to all Environments on a WP Engine plan

Remove the user from the WP Engine plan entirely.

---

SSH Key Specifications

• The SSH key must begin with ssh-ed25519 with the entire key contents following on one single line when entered into the User Portal profile page.
• Each user can add multiple SSH keys to their User Portal profile.
• Each SSH key added to WP Engine is attached to a User Portal email address. If there are multiple computers from which a user will connect to SSH, it’s advised to use a separate key for each computer.
• Once your SSH key is added it can be used for all environments to which your WP Engine User Portal user also has access. If you cannot see the environment in the User Portal, you cannot access it using SSH.
• Each SSH Gateway user should add their own SSH key as a best practice. Do not share SSH keys between users or machines for security reasons.

---

Troubleshooting SSH

For more information to troubleshoot SSH connection issues, see our SSH Gateway Issues guide here.

---

NEXT STEP: Learn how to connect to SSH Gateway