Setup and Connect to SSH Gateway
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. With WP Engine’s 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.
About SSH Gateway
SSH stands for “Secure Shell” and is the authentication method two devices (computers, servers, or other internet devices) use to communicate with each other. On the WP Engine platform, SSH Gateway access means the ability for you to connect remotely from your local machine to a container where your site’s content is hosted. Developers who are testing, building, or managing multiple websites can and should use SSH Gateway. It should be used by people who are familiar with the use of command line, bash, and WP CLI.
SSH Gateway is ideal because it allows users an easy, secure interface to interact with their site’s files and content. This includes using WP-CLI to manage WordPress settings and administration, navigating files and directories, using rsync and SCP to move and transfer files, and using MySQL command line to manage databases. Users can even create scripts and bash loops to automate tasks that previously would take a lot of manual work. WP CLI allows developers and site administrators to manage their site outside of the confines of the WordPress back-end, which allows for faster work and chained commands to automate site workflows.
WP Engine uses a sandboxed SSH “sidecar” that sits alongside your server with a timeout of 10 minutes. Each site will have its own unique connection details and a separate sandbox to ensure there is no cross-contamination of sites or resources. This ensures the highest security level while allowing access to your site, without requiring additional steps such as IP allowing. When connected through SSH Gateway, you will be able to access the WordPress files and database as though you were connected directly to the server, but you won’t see all of the standard processes that are running on a server, such as Apache or MySQL.
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.
We highly advise setting up an SSH config file before proceeding, as this will mitigate many potential issues down the road.
Add SSH Key
Adding your SSH key to the User Portal allows the key to be used on all environments your email has access to in the User Portal. This makes it simple and easy to ensure you have SSH access ready to go when it’s needed for past and future environments.
After your key has been added to the User Portal, the command you must use to connect using SSH will require that you specify the environment name to ensure you enter the appropriate website.
A direct link to the page to add your SSH key to your account can be found at: https://my.wpengine.com/ssh_keys
Or, to access this page manually, use the following steps:
- Log in 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
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 the unique 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. In this example the key file is located at
ssh -i ~/.ssh/wpengine_rsa -o IdentitiesOnly=yes firstname.lastname@example.org
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.
After connecting to SSH, you will need to enter the root directory for your website to see and interact with your files. To do this, type:
Or, you can enter the root directory of your website and list the files/directories there in a single command:
cd sites/environment && ls
Be sure to replace
environment with your WP Engine environment name or update the file name and path to the appropriate location.
Below are some examples of commands you can use once within the root directory of your install:
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 email@example.com:/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 5.6 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=5.6"; done
*You must run loops which iterate through multiple environments from your local machine instead of from the remote server.
SSH Gateway Limitations
In general, you cannot use SSH to manage the aspects of your site that are in the User Portal (purge cache, create users, add a new environment).
You cannot use SSH Gateway access to perform any actions that require root or sudo access, and cannot use it to access server logs.
New or permanent files/directories can only be created in the
/sites/environmentname/ directory. Newly created files outside of this path will disappear when your SSH session ends. Any scripts you create should be stored in your site’s
_wpeprivate folder to ensure they’re secure, hidden and persistent.
You can only remove files with the user “wpe-user” or “www-data”. You cannot remove files which are owned by root or “nobody”. Reset file permissions or reach out to Support if you have issues with these file permissions being set properly.
SSH Gateway is not meant to be a means of deploying local file changes like Git. Build tools like Grunt, Composer, and Gulp are not able to be used with SSH Gateway. It’s not advised to use the same key for Git and SSH Gateway. You will want to set up two separate SSH keys and create an SSH config file to manage them. In the future there is the potential that we may merge the Git and SSH services. If this happens, it will be easier to make this transition for users who are currently using separate keys for each service.
The SSH Gateway connection limit is 5 per user. To serve customers at our scale we have several instances of our SSH Gateway service running and it is possible that occasionally customers will be able to initialize more than 5 connections.
The SSH session does not use the Memory dedicated to the server itself and as such will also not cause load to increase. SSH Gateway processes are not affected by the Apache timeout. The Apache kill script exists on the server itself, while the commands are running in the sidecar container.
SSH multiplexing is supported, which provides a way to reuse a connection for multiple SSH sessions to reduce the connection overhead for subsequent sessions. Since SSH Gateway spins up a new sidecar environment for each connection, multiplexed sessions reuse the same environment resulting in much faster connection times.
If desired, add the content below config to
~/.ssh/config to enable multiplexing for a given WP Engine environment.
Host * ControlPath ~/.ssh/socket-%C ControlMaster auto ControlPersist 10m