SFTP Usage and Access

When hosting your WordPress® site on WP Engine, you may need to connect directly to your website’s filesystem to directly edit documents, upload/download content, delete files, or manage directories/folders.¹ On other platforms you may be used to using FTP or cPanel to access files. At WP Engine we use SFTP which works the same for managing the file system, except it uses a layer of encryption for security and is restricted to a secured port.

Additionally, SFTP is not impacted by WordPress upload limits, so large media or content in bulk can be easily uploaded.

Most commonly you’ll need SFTP access when migrating your site, performing a partial restore, or while editing/accessing a specific file (such as the wp-config.php file).

---

SFTP Clients

Before you can connect to your site’s file system, you’ll need access to a compatible client. While we don’t restrict the programs you can use, but a program may not be compatible. We recommend one of the following clients:

• FileZilla – Works on all operating systems
• Visual Studio Code – Free visual code editor, compatible with Mac and PC. Make sure you install the SFTP extension.
• Notepad ++ – Works on PC only but has also has a great live edit mode

While you are free to use the SFTP client of your choice, your SFTP client will need to use one of the following supported ciphers:

• aes192-ctr
• aes256-ctr

We do not support the SFTP ciphers: SHA1, aes128-ctr, CBC, RC4, 3DES, MD5, and RIPEMD for security reasons. If your SFTP client uses one of these ciphers, it will not work properly with our platform and instead we recommend using one of the clients listed above.

---

Locate SFTP Credentials

SFTP users can be managed from the Users and SFTP page of an environment.

1. From the Sites page, select the environment name
2. Open Users and SFTP
3. Select the SFTP tab

Here you will find any existing SFTP users, as well as the SFTP address (hostname) and port number for connecting to SFTP. Additionally you can view and manage existing SFTP user credentials.

---

Add SFTP User

Along with an SFTP client you will need SFTP credentials. These are not your wp-admin or User Portal credentials. Each set of SFTP credentials will only work for one environment.

1. From the Sites page, select the environment name
2. Open Users and SFTP (You may have to expand the Manage dropdown section)
3. Select the SFTP users tab
4. Click Create SFTP user

5. Fill out the following required fields:
   • Username — Your environment name will be appended automatically:
     • EX: environmentname-username
6. Click Add SFTP User
7. Password — You can securely generate a random password by clicking the lock icon, or set a password with the following requirements:
   • At least 8 characters
   • Uppercase and lowercase letters
   • Include numbers and special characters
   • Once the password has been set it cannot be viewed again. If you lose the password, you will have to set a new one. Be sure to copy or write the password down before saving.
8. Path (Optional) — Specify a directory when connecting with SFTP (defaults to root).
   • Must be a relative path, starting with a forward slash.
   • Do not include HTTP/HTTPS, or your domain.
   • Any subdirectory within path defined can also be accessed.
     • Example 1: To restrict a theme developer to all theme directories, enter /wp-content/themes/
     • Example 2: To restrict a vendor to media uploads from April 2019, enter /wp-content/uploads/2019/04/

SFTP usernames cannot be modified after creation, however the user can be deleted and a new user created with the desired name.

---

Delete SFTP User

To delete an SFTP user:

1. From the Sites page, select the environment name
2. Click Users and SFTP
3. Select the SFTP users tab
4. Locate the user, then click Delete to the right

---

Connect to SFTP

After adding an SFTP user, take note of the SFTP Address and Port Number in your User Portal. The SFTP address is different for every environment.

In this example we’ll be using FileZilla, but the fields should be similar in any client. Fill out the following fields then hit Connect.

Host  — SFTP Address

• Your environment name plus sftp.wpengine.com
• EX: mysite.sftp.wpengine.com

Username  — Username set in the User Portal. Your unique environment name is appended and hyphenated automatically.

• Ex: environment-someuser

Password — Password exactly as set previously in the User Portal.

• Pay attention to capital letters, spaces, symbols, etc.
• If you forgot the password it cannot be viewed again after saving. You must edit the SFTP user to set a new password.

Port — Always set to 2222

• No other port numbers will work here.

---

SFTP Tips

• Make a backup before editing any site content.
• Once you are connected to your site, you will see a directory listing of your computer’s contents on the left. Your remote website directory is on the right.
• Double-click a directory name to expand and view the contents.
• Drag and drop files between locations or directories.
• If you are replacing a file be sure to accept any prompts to overwrite the existing file or you will not see your changes.
• Reset file permissions and purge server caches from the WP Engine plugin after making changes.
• Location quick reference:
  • Theme files: wp-content/themes/
  • Plugin files: wp-content/plugins/
  • Uploads: wp-content/uploads/
    • Often divided further by year, then month: wp-content/uploads/2019/04
• Your SFTP host name and user name will both include the environment name at the beginning. This should make verifying that you’re connecting correctly a little easier.

---

SFTP Troubleshooting

SFTP errors can vary depending on the software you are using. If you’re not getting a specific error message, we’ve provided some general troubleshooting steps below to help determine the cause of SFTP related issues.

1. Files aren’t uploading.
   • Do any files upload? Try uploading a different file, with a different file type. For example, a .txt file instead of a .png.
     • If a new file works, then the file you are uploading may be corrupted in some way. If possible, download the file again from the original source or export it as a different file type.
     • If the original file you are uploading is large, it’s possible the SFTP client is timing out and closing the connection prematurely. WP Engine does not impose a file size upload limit when using SFTP. Review the documentation for the SFTP client you are using to adjust the connection timeout length.
   • Do any other directories work? Try uploading to a different directory. For example, the root directory instead of the wp-content directory.
     • This may indicated a permissions issues. Try resetting file permissions. You may need to disconnect and reconnect to SFTP once this is complete.
   • If no files are uploading, then you are likely not connected successfully. Review the SFTP connection steps. We also recommend trying a different SFTP client.
2. I uploaded a file but I don’t see it reflected on my website.
   • Are you connected to the right site? Verify that the site name in the SFTP hostname field matches the name of the site you are viewing.
   • The file may be cached, especially if the original was overwritten. Try clearing cache.
   • The file may have uploaded with non-default file permissions. Try resetting file permissions, then clear cache.
3. Additional steps to consider:
   • Try another SFTP client. The client you are using may be out of date or in some way incompatible.
   • Try another computer. This can be helpful if the computer may have settings applied that you are unfamiliar with.
   • Try another internet network. This can be beneficial to determine if there’s network security settings or a firewall causing an issue. If so, contact your network administrator for further assistance.

---

Common Issues

Error: Cannot establish FTP connection to an SFTP server. Please select proper protocol.

• Ensure you have set your client to connect using SFTP protocol.
• This may be a dropdown to select SFTP, or you may have to preface your hostname field with sftp://
  • EX: sftp://mysite.wpengine.com
• Ensure you are using the correct port. Only port 2222 is supported.

Error: Authentication failed.

• The user name or password is wrong.
• Change your password or try adding a completely new user.

I’m being prompted to update my SSH host keys. I hit “accept”, but still can’t connect.

• During security updates our server host keys can change. You may need to delete your existing SSH host keys first before new ones can be properly accepted by your SFTP client.

Still unable to connect with SFTP?

• Restart your FTP client completely
• Try connecting with a different client
• Ensure your client is up to date
• Verify the path you’re connecting to exists as a directory on your website, or reset the path to default completely
• Create a different SFTP user
• Try to connect to any other environments on your account with SFTP
• Contact our Support team

I connected without an error, but my remote directory and file listing is blank.

• Check the path your user is configured for. Does it exist? Is it spelled right?
• We recommend resetting this to default (blank) and trying again.

I’m not seeing changes on my site after uploading a file.

1. Reset file permissions
2. Purge server caches
3. Purge local caches

Still not seeing your changes?

1. If you modified a theme/plugin file, ensure you have the correct theme/plugin name activated
2. Add a comment to the top of your file and upload it again
3. Try opening your file in the browser directly- Do you see your comment or code changes?
   1. EX: http://mydomain.com/wp-content/uploads/test.txt
4. Try uploading a test TXT file to the same directory, then see if you can load that file in your browser directly. Can you view this test file?

If you can see changes in the files when viewed directly but not on the website, it is most likely a caching issue.

• Try purging local and server caches again
• You may even need to restart your computer
• Test again on a mobile device, disconnected from WiFi

If you can’t see any changes when directly viewing files you’ve added, it’s most likely an SFTP connection issue.

• Check the host name, username, password and port.
• Verify you’re uploading to the correct directory
• Confirm the file name spelling and capitalization

---

Update SFTP Host Keys

If when using your SFTP client on WP Engine, you receive a warning that your “host keys do not match” or “host key changed”, you will need to update host keys stored on your local machine. There are three options to update your host keys.

---

Update Host Key

Option one in this scenario is to manually update your host key. This method generates the new host key and connects you to your host: environment.sftp.wpengine.com. This is the easiest, recommended method. Please keep in mind these steps need to be taken on the local computer where you are experiencing this issue.

Run the following command in a local Mac/Linux Terminal window, where environment is the name of your WP Engine environment:

1. cd ~/.ssh
2. ssh-keygen -R environment.sftp.wpengine.com:2222

Delete All Host Keys

Option two in this scenario is to delete the host key entry for your host: environment.sftp.wpengine.com

Mac/Linux

To delete your local host key, you just need to remove your known_hosts file. Open terminal and run the following commands:

1. cd ~/.ssh
2. rm known_hosts

Windows

To update your local host key on a Windows machine, open up PuTTY and perform the following steps:

1. Open up regedit.exe by doing a search
2. Navigate to HKEY_CURRENT_USERSoftwareSimonTathamPuTTYSshHostKeys
3. Delete all keys listed

Update known_hosts File

Similar to removing removing all known hosts in Option two, this option removes just one known host.

The warning message your SFTP client shows will usually list the line in known_hosts that is triggering this message, so be sure to make a note of this.

Mac/Linux

On Mac/Linux you can simply edit the file using vi, which is a text editor. Run the following commands. Be sure to update 100 to the line number your error message displays.

1. cd ~/.ssh
2. vi known_hosts +100

Once the file opens to this line:

1. Type the key d twice to remove the line
2. Type :x to save.

Windows

On a Windows machine using PuTTY, go to the Registry folder just like in step two. In that directory, a list of hostnames appears. Right click on the environment.sftp.wpengine.com one, and then select Delete.

---

Limitations

We do not support the SFTP ciphers SHA1, aes128-ctr, CBC, RC4, 3DES, MD5, and RIPEMD for security reasons. If your SFTP client uses one of these ciphers, it may not work properly with our platform. We suggest reaching out to your SFTP software maker to get instructions on how to disable these.

WP Engine does not support FXP (File eXchange Protocol) due to its dependency upon FTP (File Transfer Protocol), which is an insecure method of transferring files. WP Engine only supports SFTP (Secure File Transfer Protocol) due to its improved security features.

---

NEXT STEP: Troubleshooting with the WP Engine error logs