Troubleshooting SSH Gateway Issues

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 available for customers on dedicated servers. 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 like so:

[email protected]

You will find your full login string in the Overview page for your install:

Region Not Accepted

Using a region and email address in your SSH login string is no longer necessary. If you are using a login string that includes a region like this…

'[email protected]+myinstall'@ssh.gcp-us-central1-farm-01.wpengine.io

…Then you should use the updated method which automatically determines your region instead. That format looks like this:

[email protected]

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.

Memory Limitations

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.

Lockouts

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.

Broken Connection

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: