Troubleshooting FTP
FTP connection issues are typically caused by firewalls or incorrect settings in FTP software. The steps below will help you resolve these issues.
We often encounter resistance from customers who are unwilling to invest in troubleshooting their client or firewall because a previous connection may have worked.
In our experience, the change that caused the problem is usually on the customer's side, and we would appreciate it if you could go through and verify all of the following things before asking us for further assistance.
Check for Firewall Issues
During the majority of support calls pertaining to FTP, the primary underlying factor is typically associated with the corporate or network firewall of the customer or customer counterparty.
FTP is a frequently restricted protocol by firewalls. In many cases, modifications to firewalls can inadvertently introduce new complications that were previously non-existent. Furthermore, FTP has two separate modes, Passive and Active mode, which can interact with firewalls in unpredictable ways.
Have you manually whitelisted any IP addresses anywhere?
If so, you need to all of the appropriate IPs are whitelisted.
See if you need to ask for an IP whitelist.
If you have not whitelisted IP addresses, maybe your firewall administrator requires an explicit whitelist for FTP traffic. Please submit a request to your network or firewall administrator to allow FTP ports 21 and 990 as well as data ports 21000-21050 to all of the IP addresses in this range: 209.43.40.0/24.
Try Toggling Active/Passive Mode
Many FTP clients offer a choice of Active Mode vs Passive Mode. SmartFile 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.
Connection Settings in Your FTP App
The following connection settings are the most common issues related to FTP. Please double-check all of the following.
Hostname
The hostname should be set to [your_subdomain].smartfile.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.
Port
The default FTP port of 21 is blocked or interfered with by many corporate firewalls. Some FTP clients use "implicit security mode", which runs on port 990.
Active/Passive
Many FTP clients offer a choice of Active Mode versus Passive Mode. SmartFile 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 app, please increase the connection timeout value to 60 seconds.
Retry Logic
If supported in your app, have your app attempt three connection retries at 10-second intervals. This will allow failed connections contacting one server to retry the connection via a different server.
Keepalives
SmartFile will time out FTP sessions that have been idle for 120 seconds. This is to prevent unused sessions from being left open and using server resources. Such idle timeouts are normal, and most FTP 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 FTP 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 100 seconds to maintain the FTP connection and avoid the timeout messages.
Troubleshooting FTP Connectivity Issues
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.
Understanding Active Mode FTP
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
990FTPeS (explicit FTP over TLS) uses port
21Plain, insecure FTP on port
21
The Command channel is always established from the client to the SmartFile 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 SmartFile 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.
Understanding Passive Mode FTP
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
990FTPeS (explicit FTP over TLS) uses port
21Plain, insecure FTP on port
21
The Command channel is always established from the client to the SmartFile 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 SmartFile, all versions of FTP use the following range for Passive Data channels:
Passive (PASV) mode uses port range
21000to21050
The Passive Data channels are always established from the client to the SmartFile 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.
Common Troubleshooting Tips
Do not use Active mode unless there is no firewall between the FTP client and SmartFile.
Always use Passive mode for FTP and FTPS connections to SmartFile.
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 SmartFile 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 SmartFile Passive (PASV) port range is allowed though your firewall.
SmartFile 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 SmartFile. If your client is presented with invalid, self-signed, or expired SSL certificates when connecting to SmartFile then verify your DNS settings to make sure that you are connecting to the correct IP addresses for SmartFile.
Configuration on SmartFile That May be Relevant
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. Click the Users icon in the left menu, users will have a green check if enabled and a red X if disabled. To enable a user, select the user that is disabled and click Enable/Disable.
Last updated