In this article we give answers to common questions and misconceptions about SSH Gateway on WP Engine. If you have questions about how to get started using SSH Gateway access, start with our Getting Started guide.
What is 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.
Why should I use SSH Gateway?
SSH Gateway is ideal because it allows users an easy, secure interface to interact with their site’s files and content. With SSH access users can manage their site with WP CLI commands. 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.
What can I do with SSH Gateway?
SSH Gateway allows users to manage WordPress sites via a command line interface so you can save time and automate various tasks. 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.
Most bash, MySQL CLI and WP CLI commands will work in SSH Gateway.
Can you give me some command examples?
Install the Yoast (wordpress-seo) plugin and activate it
wp plugin install wordpress-seo --activate
Sync all the files in the “myplugin” folder over to wp-content/plugins/mynewplugin/
rsync -rvP myplugin/ ../wp-content/plugins/mynewplugin/
Import the mydbfile.sql file to your WordPress database
wp db import mydbfile.sql
Search and replace your old domain with your new domain with precise (SQL-based)
wp search-replace “myolddomain.com” “mynewdomain.com” --precise
Use the vi editor to view or edit the mysqlfile.sql file
Remove the “oldfolder” folder and all of its contents
rm -rfv oldfolder/
What can I NOT do with SSH Gateway?
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/[environment]/ 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.
How is SSH Gateway different than the Advanced tab in my User Portal?
If you have access to the Advanced section in User Portal, you have the ability to run WP-CLI commands there. The tool in the Advanced section has some limitations in the way it runs, such as timeouts.
Furthermore, SSH Gateway offers full access to command line tools beyond WP-CLI, so you have a wide variety of powerful bash commands at your fingertips to manage your website, content, and database.
How is SSH Gateway different than Git?
Git is a version control system used to deploy file changes from your local machine to your website. SSH is the method of connecting directly from your local machine to your sandboxed environment for your website’s server.
SSH Gateway is not meant to be a means of deploying local file changes like Git.
Furthermore, build tools like Grunt, Composer, and Gulp are not able to be used with SSH Gateway.
Can I use the same SSH key for Git and SSH Gateway?
It’s not advised to use the same key for these services. 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.
Is SSH access on WP Engine different than with other providers?
Yes. WP Engine uses a sandboxed SSH “sidecar” that sits alongside your server. This ensures the highest security level while allowing access to your site.
Each site will have its own unique connection details and a separate sandbox to ensure there is no cross-contamination of sites or resources.
When connected through SSH, 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.
While you have the ability to create new files, only files which are created within the
/sites/[environment]/ directory and below will remain after your SSH session ends. With that in mind, if you wish to store bash scripts for site, these should be placed within the
Does SSH Gateway work with Legacy 1-Click Staging?
No. SSH Gateway does not support Legacy Staging (environment.staging.wpengine.com) environments. There is no plan to roll out support for this in the future.
Do I need to have my IP whitelisted?
No. With SSH Gateway we use SSH key pairs which are added to the User Portal and can only access environments the corresponding User Portal user has access to.
For this reason we also recommend using a unique SSH key for each machine and each user.
What is the SSH Gateway timeout limit?
Currently the timeout is set to 10 minutes.
Does SSH Gateway cause load on the server?
No. The Memory dedicated to the SSH session is entirely on its own separate “sidecar” container. The SSH session does not use the Memory dedicated to the server itself.
Are SSH Gateway actions directly affected by the Apache kill script?
No, 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.
Does SSH Gateway support multiplexing?
Yes. SSH multiplexing provides a way to reuse a connection for multiple SSH sessions, thereby reducing 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.
Add the below config to
~/.ssh/config to enable multiplexing for a given WP Engine environment.
Host *.ssh.wpengine.net ControlMaster auto ControlPersist 10m ControlPath ~/.ssh/cm-%[email protected]%h:%p