Troubleshooting SFTP

---

SFTP connection issues are typically caused by firewalls or incorrect settings in SFTP software. The below steps will help you resolve these issues.

We are often met with resistance by customers who don't want to invest in troubleshooting their client or firewall because a given connection may have worked in the past.

In our experience, the change that caused the problem is usually on the customer side, and we'd really like you to go through and verify all of the following things before asking us for further help.

If we do a Zoom call with you, these steps are what we will do together.

On most support calls related to SFTP, the root cause is a customer or customer counterparty's corporate or network firewall.

SFTP is very commonly blocked by firewalls, and often firewall changes can introduce new issues that didn't previously exist.

If so, you need to all of the appropriate IPs are whitelisted, not just some of them.

If your site uses a custom domain, you have two dedicated IPs that need to be whitelisted in your firewall. To find your dedicated IPs, type "Firewall" in the search box at the top of every page, and then click on the matching result. Scroll to Firewall configuration.

If you do not have a custom domain, ensure that our all of IPs on this list are whitelisted, not just some of them. There are quite a lot of IPs on that list and you need to whitelist all IPs or else you will experience failures. If whitelisting that many IP addresses is a problem for you, the solution is to move to a custom domain. This will get you a pair of IP addresses you can whitelist (see the prior paragraph.)

If you have not whitelisted IP addresses, maybe your firewall administrator requires an explicit whitelist for SFTP traffic. Please submit a request to your network or firewall administrator to allow SFTP port 22 traffic to all of the IPs on this list. If your firewall team does not allow whitelisting port 22 traffic, ask for port 3022 instead and see the next paragraph.

By default, SFTP is used on port 22. Files.com also supports 3022 as an alternate port. Many firewalls will allow traffic on port 3022 despite blocking it on port 22. We recommend testing this next if you have exhausted other firewall issues. In many cases, simply using the alternate port will get your corporate firewall to let the connection through.

The following connection settings are the next most common issues related to SFTP. Please double check all of the following.

The hostname should be set to [your_subdomain].files.com or the custom domain for your site, if applicable. Connecting by specifying an IP address may sometimes work, and we do have customers doing this for specific reasons, but it is not officially supported and we are unable to proceed with helping you troubleshoot if you are doing this.

By default, you should be using port 22. However, the port setting is a great way to work around corporate firewalls. The default SSH/SFTP port of 22 is blocked or interfered with by many corporate firewalls. You can test port 3022 as an alternate port if you suspect possible firewall issues. In many cases, simply using the alternate port will get your corporate firewall to let the connection through.

If supported in your app, please increase the connection timeout value to 60 seconds.

If supported in your app, have your app attempt 3 connection retries at 10 second intervals. This allows failed connections contacting one server to retry the connection via a different server. Our hostnames always resolve to multiple physical server hosts in different datacenter locations. Ensure that your SFTP app tries multiple IPs when available.

Files.com will time out SFTP sessions that have been idle for 60 seconds. This is to prevent unused sessions from being left open and using server resources. Such idle timeouts are normal, and most SFTP apps handle them without issue, but there are some apps that may not handle these timeouts gracefully. To prevent these idle timeouts, many apps offer a "keepalive" setting. Many SFTP apps will complete transfers in progress and then will connect again upon the user issuing another command. If your app aborts a transfer or errors out due to the idle timeout message, you can implement keepalives (either null packets or dummy commands) every 30 seconds to maintain the SFTP connection and avoid the timeout messages.

Your SFTP app and Files.com will only connect if both sides agree to use a secure cipher. Insecure ciphers can be rejected by either side. Make sure that your SFTP app uses a supported secure cipher. Please check the documentation for your SFTP app to find out how to configure ciphers for your connection.

If you have confirmed all of the above, here are some remaining things that have caused SFTP issues for some of our customers.

Verify that the username is enabled, and that the username and password are correct. Type "Users" in the search box at the top of every page and then click the matching result. Edit the user and verify that the Account enabled setting is turned on. Click on the Authentication tab in that user's settings, verify that the Authentication method is not set to "none". (When set to "none", a user account can only authenticate by using a SSH/SFTP Key.)

The user might have SFTP disabled in their settings. Type "Users" in the search box at the top of every page and then click the matching result. Edit the user, select the Privileges tab, scroll to the Protocol access section and check that SFTP is enabled.

If the user has Two Factor Authentication (2FA) Enabled, only certain 2FA methods work with FTP. The Two Factor Authentication documentation page has more information on this**.** Additionally, when using 2FA with SFTP, you need to disable any parallelism in your SFTP app, because 2FA is only valid for one connection at a time. (In a later step we will suggest maxing out the available parallelism in your app for performance. 2FA is a case where this would not be available.)

If your site or user is subject to an IP whitelist, the user must access the site using one of the whitelisted IPs from either list. To manage IP whitelists for all users, type "IP Whitelist/Blacklist" in the search box at the top of every page and then click on the matching result. To add additional IPs for an individual user, type "Users" in the search box at the top of every page and then click the matching result. Edit the user, select the Authentication tab, and scroll to the IP whitelists section.

The SFTP protocol has a "gotcha" that often confuses SFTP users when trying to troubleshoot authentication issues. The protocol uses integers internally to communicate authentication failure codes and does not even allow services (such as Files.com) to send detailed error messages that relate to authentication.

This is in contrast to nearly every other protocol, such as our API, FTP, web, etc., which all provide detailed messages that explain login failures.

Many SFTP client software will simply plug in a "default" message about authentication failure or invalid username/password when they experience any sort of authentication failure. We recommend using your Files.com site's history logs to determine the real reason for the failure.

Type "History" in the search box at the top of every page and then click on the matching result. Filter the history logs by Action: Login Failure. You can optionally filter the log further by username or IP. This will generate a log of the detailed reasons for the login failure.

Common causes of failure include expired passwords, required password change, brute force protection, IP restrictions, 2FA restrictions, geographic restrictions, or other authentication restrictions that you've configured on your site.

If the user account has been configured to Require password change on next login then SFTP login will not succeed until the password has been changed. Ask the user to access Files.com using our web interface and have them complete the password change prior to attempting a login via SFTP.

If a user is having problems logging in using SFTP then have them attempt to log in using the Files.com web interface. If the issue persists there then this eliminates SFTP as the cause.

The Files.com platform performs some operations asynchronously and these operations will run in the background in parallel.

SFTP clients are unaware of asynchronous background operations.

For example, using the SFTP rename command to move a file from one Files.com storage region to another, or from one Remote Server Mount to another, will asynchronously create a background process to move the file. Control is immediately returned to the SFTP client even though the move is still occurring in the background.

If you are programmatically interacting with SFTP, such as from a script or iPaaS process, then the next commands will execute while the move operation is still in progress. If your script, or process, immediately tries to access the moved file then it will fail because the move operation hasn't completed yet.

Considerations for a reliable integration with Files.com should take into account the asynchronous background operations and should implement verification steps in scripts and processes to detect that a moved, renamed, or copied file is available at the destination prior to attempting any further actions on it.