SSH Gateway Issues

When using SSH Gateway on WP Engine there are several known limitations or potential access issues. In this article learn which limitations exist, why, and how to best proceed without conflicts.

---

Not Seeing File Changes Immediately

File changes may take 5+ seconds to appear between the WordPress Admin Dashboard and the SSH session, and vice versa.

In this case, simply wait a few seconds and then the changes should appear. Additionally, use an incognito window or clear the browser cache to see changes faster.

Review our guide for purging caches.

---

Username Not Accepted

If receiving authentication errors when connecting, double-check the format of the username. The username must be formatted like so, where environment is replaced by the unique WP Engine environment name.

environment@environment.ssh.wpengine.net

1. Log in to the User Portal
2. Click on the environment name to connect to
3. In the Overview section, locate SSH Login
4. Click the clipboard icon to copy the SSH loginfor easy pasting into the terminal

---

Region Not Accepted

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

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

…Instead, use the updated method. This method automatically determines the region and looks like the following:

environment@environment.ssh.wpengine.net

---

New Files Not Saved

Only files updated and saved within the /sites/environment/ 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 the /sites/environment/ directory, as this is the root directory of the WordPress site.

If creating scripts for use in SSH, please be sure these are placed in the _wpeprivate folder of the 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, the local machine will attempt to use all SSH keys present when connecting to the SSH Gateway. If 6 or more keys are presented unsuccessfully, the SSH Gateway will disconnect.

To avoid this issue, use an SSH config file to designate which key file should be used with which hostname.

---

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 work in SSH.

---

No Mutual Signature Algorithm

If the following error displays when attempting to connect to SSH Gateway debug1: send_pubkey_test: no mutual signature algorithm the key does not match the type the client is looking for – typically because SSH-RSA SHA-1 has been deprecated. This is most common when connecting with OpenSSH (8.8+). To resolve this issue, there are two options:

• (Recommended) Create the key using ED25519 instead
  • To generate a new key in the recommended format, use ssh-keygen -t ed25519 -f ~/.ssh/wpengine_ed25519
  • Use the new key files wpengine_ed25519 and wpengine_ed25519.pub
• (Not recommended) Enable support for RSA-SHA1

---

Permission denied (publickey)

When users are connecting to their SSH Gateway, there are two levels of authentication they pass through. The first determines whether the private and public keys match up and that the user has SSH access. If they do not, the user does not continue any further and receives the Permission denied (publickey) message.

1. Confirm the SSH key was added to the intended User Portal account
2. Confirm environment has SSH Gateway enabled
3. Confirm the SSH login is entered correctly, and that there are no typos or missing letters
4. Is there an SSH config file? Run cat ~/.ssh/config to check.
   • If yes, open it and ensure there is an entry in the SSH config file for *.wpengine.net mapped to the correct wpengine_ed25519 key file name and that everything is spelled correctly.
   • If there is no SSH config, set one up using this guide. This will ensure the machine uses the correct key when connecting.

---

Connection Error Messages

A number of other error messages may display, depending on the error condition:

Error Message	Meaning
Cannot access environment [environment_name]	Either the environment you are trying to connect to does not exist (potentially mistyped), or the User Portal user your SSH key is assigned to does not have access to this particular environment
Install [environment_name] does not support ssh	The environment you are trying to connect to exists and you have access to it, but the environment is not on a server environment that supports SSH Gateway access
Install [environment_name] is disabled	The environment you are trying to connect to is disabled or inaccessible
Wrong gateway host. Use ssh.gcp-[region]-farm-01.wpengine.io instead	The environment 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.

---

---

NEXT STEP: SSH key management for SSH Gateway