Troubleshooting SSH Gateway Issues
When using SSH Gateway on WP Engine there are some known limitations or access issues you may experience. In this article we’ll explain what limitations exist, why they happen, and how to best proceed without conflicts.
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.
Not Seeing File Changes Immediately
File changes may take 5+ seconds to appear between the WordPress Admin Dashboard and your SSH session, and vice versa.
In this case, simply wait a few seconds and then you should see the changes appear. In some cases you may need to use an incognito window or refresh your browser cache to see changes faster.
Username Not Accepted
If you are receiving authentication errors when connecting, you will want to double check the format of your username. Your username must be formatted as: ‘<email_address>+<install_name>. For example:
The email address must match the address used by your User in the WP Engine User Portal. You will find your full login string in the Overview page for your install:
Region Not Accepted
Using a region in your SSH login string is no longer necessary. If you are using a login string that includes a region like this…
…Then you should use the updated method which automatically determines your region instead. That format looks like this:
If you are unsure of your region or login string as a whole, you can find this information in your User Portal, on the Overview page for each install.
Just click the clipboard icon to copy the string for use in your terminal.
New Files Not Saved
Only files updated and saved within the /sites/[install]/ directory will remain after the SSH session ends. A new SSH sandbox is created with each SSH session. To avoid this issue please ensure any new files or directories are created within your /sites/[install]/ directory, as this is the root directory of your WordPress site. If you are creating scripts for use in SSH, please be sure these are placed in the _wpeprivate folder of your site, so these files will persist past the SSH session for future use.
If opening a new file or performing an action with WP-CLI requires too many server resources, it is possible the action or the session itself may be killed. Actions should be batched into smaller sets to ensure minimal resource consumption.
By default, your local machine will attempt to use all SSH keys present when connecting to your SSH Gateway. If 6 or more keys are presented unsuccessfully, the SSH Gateway will disconnect. To avoid this issue, you should use an SSH config file to designate which key file should be used with which hostname. In the config file, be sure to designate the “IdentitiesOnly=yes” option when using multiple keys. For more help setting up your keys and config, see SSH Gateway Key Management.
In some rare cases, it may be possible for software deploys to break existing connections. If this happens, simply reconnect after a few minutes to continue your work in SSH.
Connection Error Messages
In addition to common areas of confusion, there are some error messages you may encounter when connecting. A series of checks are performed when a user connects. The first check is to determine if your public key on file in the User Portal for your email address and the private key on your computer match up, and whether your user has SSH access enabled. If not, you will receive the following error:
Permission denied (publickey).
Otherwise, you may see a number of other error messages depending on the error condition:
|Cannot access install [install_name]||Either the install you are trying to connect to does not exist (potentially mistyped), or you do not have access to the install|
|Install [install_name] does not support ssh||The install you are trying to connect to exists and you have access to it, but the install is not on a server environment that supports SSH Gateway access|
|Install [install_name] is disabled||The install you are trying to connect to is disabled or inaccessible|
|Wrong gateway host. Use ssh.gcp-[region]-farm-01.wpengine.io instead||The install you are trying to connect to exists and your user has access to it, but you have entered the wrong hostname. Use the suggested hostname in the error message instead.|