File Transfer Protocol (FTP/SFTP)

Last updated on September 3rd, 2021

When hosting your WordPress site on WP Engine, you may need to connect directly to your website’s filesystem. On other platforms you may already be used to using FTP. At WP Engine we use SFTP which works the same, except it uses a layer of encryption for security and is restricted to a secured port.

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).

Table of Contents

7. Update SFTP Host Keys

7.1. Update Host Key

7.2. Delete All Host Keys

7.3. Update known_hosts File

8. Limitations

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 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.

NOTE: Before connecting, always ensure your client is updated, as this is a common cause of connection issues.

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.

Log in to the User Portal
Select the environment you wish to connect to
Click SFTP Users
Click Add SFTP User

Fill out the following required fields:
- Username — Your environment name will be appended to this automatically after saving:
  - EX: environmentname-username
- 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.
- Path (Optional) — A specific directory to connect to. Defaults to the root if left blank.
  - Must be a relative path, starting with a forward slash.
  - Do not include HTTP/HTTPS, or your domain.
  - Any subdirectory below the path defined can also be accessed. Any directory above the path defined cannot be accessed.
  - To restrict a theme developer to all theme directories: /wp-content/themes/
  - To restrict a vendor to media uploads from April 2019: /wp-content/uploads/2019/04/
- Environment —
  - Production, Staging, or Development: Refers to the active environment
  - Legacy Staging: Refers to Legacy 1-Click Staging
Click Add SFTP User

Edit SFTP User

To edit an existing SFTP user:

Log in to the User Portal
Select the environment you wish to connect to
Click SFTP Users
Click on an existing username
Fill in a new password with the following requirements OR hit the lock icon to generate a secure password automatically
- At least 8 characters
- Uppercase and lowercase letters
- Include numbers special characters
Click Update User

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. This rule excludes Legacy Staging which actually uses the exact same hostname as its live counterpart.

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

When using Quick Connect in FileZilla you will need to specify sftp protocol by also adding sftp:// before the hostname.
EX: sftp://environment.sftp.wpestaging.qa

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.

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.

NOTE: You may see a pop up referring to SSH host keys if you’ve never connected before. Accept any warnings to continue.

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.

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.wpestaging.qa
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?
Is the SFTP user configured for legacy staging? Legacy staging may not exist. Edit the user and set it to Production.

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

Still not seeing your changes?

If you modified a theme/plugin file, ensure you have the correct theme/plugin name activated
Add a comment to the top of your file and upload it again
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
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.wpestaging.qa. 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:

cd ~/.ssh
ssh-keygen -R environment.sftp.wpestaging.qa:2222

Delete All Host Keys

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

Mac/Linux

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

cd ~/.ssh
rm known_hosts

Windows

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

Open up regedit.exe by doing a search
Navigate to HKEY_CURRENT_USERSoftwareSimonTathamPuTTYSshHostKeys
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.

cd ~/.ssh
vi known_hosts +100

Once the file opens to this line:

Type the key d twice to remove the line
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.wpestaging.qa 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