Troubleshooting FTP

---

Most of the time, FTP connection issues are caused by firewalls or incorrect settings in FTP software. The below steps will help you resolve these issues.

We are often met with resistance by customers who don't want to perform these steps because a given connection may have worked in the past but isn't working now. In our experience, the change that caused the problem is usually on the customer side, and that's why we'd really like you to go through and verify all of the following things before asking us for further help.

If we end up doing a Zoom call together to troubleshoot, these steps are exactly what we will do together.

On probably 9 out of 10 support calls for FTP, the root cause is a customer or customer counterparty's corporate or network firewall. FTP is very commonly blocked by firewalls, and often firewall changes can introduce new blocks that didn't previously exist. Furthermore, FTP has two separate modes, Passive and Active mode, which can interact with firewalls in unpredictable ways.

The approach should be to find a set of settings that will work for a particular network/firewall. This may vary across your user base depending on what corporate or network firewalls they find themselves behind.

Have you manually whitelisted any IP addresses anywhere? If so, verify that 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. You can find your dedicated IPs by going to Settings > Integrations and scroll to Firewall configuration. If you have a custom domain, you also need to ensure that you are connecting to it, and not to [your_subdomain].files.com.

If you do not have a custom domain, ensure that our main IPs on this list are whitelisted, not just some of them. There are quite a lot of IPs on that list (over 80 at last count) 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 if you need to ask for an IP whitelist. If you have not whitelisted IP addresses, maybe your firewall administrator requires this for FTP traffic. Please submit a request to your network or firewall administrator to allow FTP port 21 and 40000-50000 traffic to all of the IPs on this list. If your firewall team does not allow whitelisting port 21 traffic, ask for port 3021 instead and see the next bullet point.

Try other ports. By default, FTP is used on port 21. Files.com also supports 990, 3021, and 3990 as alternate ports. Many firewalls will allow traffic on port 3021 despite blocking it on port 21. 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.

Try toggling Active/Passive mode. Many FTP clients offer a choice of Active Mode vs Passive Mode. Files.com supports both, but your corporate or network firewall might block one or the other. We recommend testing both options in conjunction with testing the alternate ports in the above step.

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

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

Encryption - If supported in your client, encryption should be enabled. Some clients show this as a protocol setting, offering FTPS or FTPeS (with the "S" meaning "secure"). This means data will be encrypted in transit. If you are unable to use encryption, in your FTP client, insecure FTP without encryption must be enabled in your Files.com account.

Port - The port setting is a great way to work around corporate firewalls. The default FTP port of 21 is blocked or interfered with by many corporate firewalls. You can test port 3021 as an alternate port if you suspect possible firewall issues. Some FTP clients use "implicit security mode", which runs on port 990. In this case, we also support port 3990 as an alternative. In many cases, simply using the alternate port will get your corporate firewall to let the connection through.

Active/Passive - Many FTP clients offer a choice of Active Mode versus Passive Mode. Files.com supports both, but your corporate firewall might block one or the other. We recommend testing both options in conjunction with testing the alternate ports in the above step.

Timeout - If supported in your client, increase the connection timeout value to 60 seconds.

Retry Logic - If supported in your client, have your client attempt three 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 FTP client tries multiple IPs when available.

Keepalives - Files.com will time out FTP 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 FTP clients handle them without issue, but there are some clients that may not handle these timeouts gracefully. To prevent these idle timeouts, many clients offer a "keepalive" setting. Many FTP clients will complete transfers in progress and then will connect again upon the user issuing another command. If your client 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 FTP connection and avoid the timeout messages.

Almost all FTP connectivity issues are caused by firewalls. The FTP protocol uses multiple network ports in order to transfer data between a client and a server. If any of these ports are blocked then data transfer cannot occur. This issue can usually be detected when a client is able to connect to an FTP server, successfully navigate the folder structure, but is unable to upload or download files.

The FTP protocol uses multiple network ports. One network port is always used as a Command channel and one or more network ports are used as Data channels. The Command channel is used to establish the FTP connection and to issue commands to control the FTP session. This includes commands to list directories and folders on the server. The Data channels are used to transmit file contents, both for upload and download.

The Command channel usually uses a "well known port", such as 21 or 990, and firewall administrators will understand how to open these ports on a firewall. The Command channel is always established from the client to the server.

The Data channels are always random network ports and may be established either outbound (from client to server) or inbound (from server to client) depending on the FTP mode being used.

The majority of issues are caused by the firewall not being configured to allow the Data channels to pass through.

In order to troubleshoot FTP connectivity issues we need to first understand how the Active and Passive FTP modes work.

The original default mode of FTP is named Active mode. This mode was designed prior to the existence of firewalls and is considered an older deprecated mode. It should only be used on a Local Area Network (LAN) and never be used whenever a firewall exists between the client and the server.

In Active mode, the client will first connect to the server using the Command channel. The port being used will depend on the type of FTP being used:

• FTPS (implicit FTP over TLS) uses port 990 (default) or 3990 (alternative Files.com port)
• FTPeS (explicit FTP over TLS) uses port 21 (default) or 3021 (alternative Files.com port)
• Plain, insecure FTP on port 21 (disabled by default, but can be enabled if your business needs require it) or 3021 (disabled by default, alternative Files.com port)

The Command channel is always established from the client to the Files.com FTP server using one of the above ports.

Once the connection is authenticated and authorized, the FTP server will connect back to the client using the Data channels. The client will send the server an IP address and a range of random port numbers and the server will attempt to use this IP address and those port numbers to establish Data channel connections.

The Active Data channels are always established from the Files.com FTP server to the client using a random port that was determined by the client.

When uploading or downloading, the command to initiate the transfer is sent via the Command channel but the actual file data is sent via the Data channels.

Passive (PASV) mode was designed for FTP clients that reside on a network that cannot receive inbound connections, such as behind a firewall or on a NAT subnet. Due to the wide proliferation of firewalls and NATs, Passive mode has become the de facto, and recommended, connection mode for FTP. In Passive mode, the Command channel is used in the same way as Active mode but the Data channels are established in the reverse direction compared to Active mode.

In Passive Mode, the client will first connect to the server using the Command channel. The port being used will depend on the type of FTP being used:

• FTPS (implicit FTP over TLS) uses port 990 (default) or 3990 (alternative Files.com port)
• FTPeS (explicit FTP over TLS) uses port 21 (default) or 3021 (alternative Files.com port)
• Plain, insecure FTP on port 21 (disabled by default, but can be enabled if your business needs require it) or 3021 (disabled by default, alternative Files.com port)

The Command channel is always established from the client to the Files.com FTP server using one of the above ports.

Once the connection is authenticated and authorized, the FTP server will inform the client of the port range of its passive data ports. The client will then connect to the FTP server, using random ports in the supplied range, to establish the Data channel connections. For Files.com, all versions of FTP use the following range for Passive Data channels:

• Passive (PASV) mode uses port range 40000 to 50000

The Passive Data channels are always established from the client to the Files.com FTP server using a random port in the range supplied above.

When uploading or downloading, the command to initiate the transfer is sent via the Command channel but the actual file data is sent via the Data channels.

Do not use Active mode unless there is no firewall between the FTP client and Files.com.

Always use Passive mode for FTP and FTPS connections to Files.com.

If you can connect and traverse directories and folders, but cannot upload or download files, then the FTP Data channel is being blocked. Make sure that connections to the Files.com Passive (PASV) port range is allowed though your firewall.

FTP uses the OPEN command via the Command channel to create a file prior to filling it with data received via the Data channel. If you see zero-byte files being created whenever you try to upload or download a file then this indicates that your firewall is blocking the Data channel. Make sure that connections to the Files.com Passive (PASV) port range is allowed though your firewall.

Files.com uses fully valid and chained SSL certificates for FTPS connections. You do not need to configure your FTP client to allow insecure or self-signed certificates in order to connect to Files.com. If your client is presented with invalid, self-signed, or expired SSL certificates when connecting to Files.com then verify your DNS settings to make sure that you are connecting to the correct IP addresses for Files.com.

If you have confirmed all of the above, here are some remaining things that have caused FTP 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.

The user might have FTP 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 Protocol access section and check that FTP is enabled for the user.

If the user has Two Factor Authentication (2FA) enabled, be aware that only certain 2FA methods work with FTP. The Two Factor Authentication documentation page has more information about this. When using 2FA with FTP, you need to disable any parallelism in your FTP client, 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 client for performance. 2FA is a case where this would not apply.)

If the user account has been configured to Require password change on next login then FTP 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 FTP.

If your site or user is subject to an IP whitelist then the user must access the site from 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 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.

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

The TLS/SSL certificate used for FTPS is the same certificate that is used for your Files.com site's web portal. This applies to both implicit (port 990) and explicit (port 21) versions of FTPS. The certificate is updated and renewed automatically every 3 months, making it impractical to provide a documented fingerprint as it changes so frequently.

Our TLS/SSL certificates are always valid and fully chained. Your FTPS client will automatically verify the validity of certificates for you and will prompt you if an invalid certificate is found when making a connection.

If you want to verify a certificate's validity yourself then you can check the certificate by using an online SSL Checker, and pointing it at your Files.com site.

If you are using the Custom Domain feature, and are providing your own TLS/SSL certificate for your site, then the certificate you provided will be used for FTPS instead.