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.

---

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

1. Log in to the User Portal
2. Click on the environment name you wish to connect to
3. 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, but a content freeze is still advised and DNS will need to be updated.

Reach out to Support for further assistance.

---

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.wpestaging.qa/ssh_keys

Or, to access this page manually, use the following steps:

1. Log in to the User Portal
2. At the top right, locate your name and click it
3. Select My Profile

4. Click SSH Keys
5. Click New SSH Key

6. Paste your Public Key * into the field
7. 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.wpestaging.qa).

ssh environment@environment.ssh.wpengine.net

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/wpengine_rsa.

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

If you encounter any connection errors, please reference our Troubleshooting SSH Connection Issues guide.

---

Using SSH

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.

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.

Example commands

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 environment@environment.ssh.wpengine.net:/sites/environment/folder4

Edit a file named myfile.txt using vim:

vim myfile.txt

Enter MySQL command line and query your table storage engine for all tables:

First run: mysql

Then run: 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 $environment@$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.

SSH Gateway does not support Legacy Staging (environment.staging.wpestaging.qa) environments. There is no plan to roll out support for this in the future.

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.

---

Additional Information

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

---

NEXT STEP: Troubleshooting SSH Gateway connection issues