SSH Key Management
If you prefer maintaining WordPress sites using the command line environment, you’re in luck! 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.
Please note: SSH Gateway is currently in Limited Availability and is only an option for specific plan types. Please contact your Account Manager to check if your account qualifies for access.
In this article you’ll learn how to setup and manage SSH keys for shell access, so let’s get started.
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.
To configure key-based authentication for shell access, you’ll need a public/private key pair configured for your profile, which means you may need to generate a key pair for the SSH protocol (SSH key), and then you’ll need to add the public key of the key pair to your profile using the User Portal. Please note: While in Limited Availability, only users with SSH Gateway access enabled will see this page in their User Portal.
As the name implies, 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).
View Existing SSH Keys
Before you add an SSH key, take a look at the SSH keys configured for your profile. Please note: While in Limited Availability, only users with SSH Gateway access enabled will see this page in their User Portal.
If you have a public key configured for your profile, then you’ll just need to be sure the corresponding private key is stored on the machine from which you want to sign in. Look in your .ssh folder. If ~/.ssh/wpengine_rsa and ~/.ssh/wpengine_rsa.pub exist, you already have a key configured for SSH access on this machine. Ensure the .pub file matches at least one of the keys configured in your User Portal.
If you don’t have a key listed here or you want to create a different key pair for another machine, learn how to generate a key below.
Pro tip: Be sure to audit the SSH keys on your profile routinely to remove keys that you no longer use.
Generate New SSH Key
If you already have a key pair that you want to use for shell access, then you can use that key. Otherwise you’ll need a new key pair which you can generate with these simple instructions:
- Open a Terminal window (on Mac you can use the Spotlight utility and type “Terminal”), or Git Bash for Windows.
- Use ssh-keygen to generate a new key as shown below
ssh-keygen -t rsa -b 4096 -f ~/.ssh/wpengine_rsa
- Type a secure passphrase when prompted
Doing this will generate a private and public key pair. The wpengine_rsa file located in ~/.ssh/ is your private key, and the wpengine_rsa.pub file is your public key. You will need to add the contents of your wpengine_rsa.pub file to your SSH Keys page in User Portal.
Manage Your Keys with an SSH Configuration File
After setting up your public/private key pair and adding it in the User Portal, it is best practice to setup an SSH configuration file. The configuration file designates which public/private key pair should be used based on the hostname of the server you are connecting to.
The configuration file will simply be named “config” and will live in your ~/.ssh/ directory. If this file does not exist already, simply create one like so:
Now you can edit the file using your favorite command-line editor (such as nano or vim). Below is an example of what you can place in your ~/.ssh/config file:
This will ensure that the new key you created is used every time you attempt to connect to any host that matches “ssh.*.wpengine.io”.
Add SSH Key to Your Profile
To use shell access for your site, you’ll need to configure your profile’s SSH keys.
- Copy your public SSH key to your clipboard. Type the command below, then highlight the contents and copy them.
- Navigate to the SSH keys page in your profile, or use the direct link (https://my.wpengine.com/ssh_keys).
- Click “New SSH key” on the SSH keys page in your profile.
- In the Public key field, paste your public key.
- Click “Add SSH key.”
Test Your SSH Key
This login information can be found in your User Portal, Installs > Overview for each qualifying install. Click the clipboard icon to copy the string, and paste it in your terminal window.
For example, if my email were “[email protected]” with the “myinstall” install:
Or you can specify the key if you chose to not create the SSH configuration file: