SSH, also known as Secure Shell, is the method of connecting from your computer to the web server where your site is hosted. With SSH access you can use a variety of command-line tools like: WP CLI, MySQL command line, and bash to manage your website.
WP Engine’s SSH Gateway is a feature available to customers. With SSH Gateway you can connect to a container that sits like a sidecar next to your website, and allows you to access your website’s filesystem and database.
SSH Gateway uses key-based authentication for even greater security than a simple username and password combination. In this article we’ll cover the steps and all you need to know to get started with SSH access on your website.
NOTE: SSH Gateway is not compatible with Legacy Staging environments. Please contact your Account Manager to check if your account qualifies for access.
Enable SSH Gateway
For most WP Engine environments, SSH Gateway is already enabled. There are a few cases where it may not be enabled, such as sites hosted on certain AWS servers. It’s best to confirm before proceeding if SSH Gateway is enabled for an environment.
To check if SSH Gateway is enabled
- Login to the User Portal
- Click on the environment name you wish to connect to
- Locate SSH Login
You will either see your SSH details used to connect, or a note detailing that SSH Gateway is not available.
If SSH Gateway needs to be enabled, this may require a migration. While this migration does not require any downtime, a content freeze is still advised and DNS will need to be updated.
Create SSH Key
- If you already have an SSH key locally labelled
wpengine_rsa.pub, then simply copy the contents when adding the key in the next step.
- If not, please follow SSH Key Management to generate a key first.
NOTE: We highly advise setting up an SSH config file as well before proceeding, as this will mitigate many potential issues down the road.
Add SSH Key
A direct link to this page can be found at: https://my.wpengine.com/ssh_keys
To access this page manually, use the following steps:
- Login to the User Portal
- At the top right, locate your name and click it
- Select My Profile
- Click SSH Keys
- Click New SSH Key
- Paste your Public Key * into the field
- Click Add SSH Key
NOTE: The key contents must begin with
ssh-rsa and the entire key text should follow on one single line.
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.
Connect to SSH Gateway
When connecting to SSH Gateway, you can use the following syntax from your terminal window. Be sure to replace the word
environment with your WP Engine environment name (EX: environment.wpengine.com)
If you do not use an SSH config file, then you must specify which key your machine should use to authenticate the connection:
ssh -i ~/.ssh/wpengine_rsa -o IdentitiesOnly=yes email@example.com
If you encounter any connection errors, please reference our Troubleshooting SSH Connection Issues guide.
Now that you have successfully set up your keys and connected, it’s time to get started using SSH Gateway. You can use WP-CLI, bash loops, edit files using your favorite editor, and many other CLI tools. Be sure take a backup prior to making any changes, and to reference our FAQ for answers to common questions about SSH Gateway.
Below are some examples of commands you can use. Be sure to replace
environment with your WP Engine environment name or update the file name and path to the appropriate location.
After connecting to SSH, you will need to enter the directory for your website to see and interact with your files. To do this, type:
cd sites/environment && ls
You will then be in your website’s root directory, and have a listing of the files and directories in your website.
NOTE: If you do not change directories initially and add files above the root directory for your website they will not persist past the end of your SSH session. Only files added to your website’s root directory or lower will persist.
Below are some examples of commands you can use:
Import a SQL file to your WordPress site’s database with WP-CLI:
wp db import mynewsqlfile.sql
Install and activate the WooCommerce plugin with WP-CLI:
wp plugin install woocommerce --activate
Run database queries with WP-CLI by encasing the query in quotes:
wp db query "SELECT * FROM wp_users WHERE user_email='[email protected]';"
See if WordPress core files have been modified:
wp core verify-checksums
Add “administrator” capabilities to a user named “wpengine” with WP-CLI:
wp user add-cap wpengine administrator
Search-replace for olddomain.com to newdomain.com using precise (PHP-based search) on all tables with WP-CLI:
wp search-replace “olddomain.com” “newdomain.com” --all-tables --precise
Sync all the files from folder1 to folder2 using rsync (non-destructive):
rsync -rvP folder1/ folder2/
Sync example.png on your local machine to folder4 on your website (non-destructive):
rsync example.png firstname.lastname@example.org:/sites/environment/folder4
Edit a file named myfile.txt using vim:
Enter MySQL command line and query your table storage engine for all tables:
SELECT table_name, Engine FROM information_schema.tables WHERE table_schema='wp_environment'
Update WordPress to version 4.9.9 for multiple sites using a bash loop*:
for environment in environment1 environment2 environment3; do ssh [email protected]$environment.ssh.wpengine.net && "cd /sites/$environment && wp core update --version=4.9.9"; done
*You must run loops which iterate through multiple environments from your local machine instead of from the remote server.