SFTP
At Files.com, we are one of the largest providers of cloud-based SFTP in the world. That said, SFTP lacks some of the more sophisticated capabilities for security and performance found in our direct integrations, such as our Desktop, Mobile, and Web apps, SDKs, API, and Command Line app. Additionally, corporate firewalls commonly interfere with SFTP traffic.
Please visit our Preferred Apps For File Transfer page to learn about and download the Files.com native apps as an alternative to SFTP.
We offer SFTP primarily as an integration tool to enable connectivity to some other application that supports SFTP but has no direct integration with Files.com.
If you represent a vendor seeking to connect to Files.com via SFTP, we would much prefer that you implement one of our SDKs or our forthcoming App Store functionality. We offer incentives for you to do so; please get in touch to learn more.
SFTP has no maximum file size limitation, nor any limitation about the number of files that can be transferred.
It is one of the slower encrypted transfer protocols but makes up for it by only requiring a single port, typically port 22, for data transmission. This makes it firewall friendly and great for file transfers where dependability is more important than speed.
SFTP can be found on various operating systems and in a wide variety of applications and devices, making it a ubiquitous tool for secure file transfer. There are graphical (GUI) SFTP clients as well as command line (CLI) clients, allowing SFTP to be used by both users and scripts.
The sftp command is useful on “headless” systems and servers that don’t provide a graphical desktop interface and only provide you with Shell access, a terminal, or a command line only.
To connect and authenticate:
- Connect to Files.com
sftp username@MYCOMPANY.files.com - When prompted, enter your password
To connect and authenticate using a SSH/SFTP Key:
- Save the SSH/SFTP Key to a file on your computer. For example, my_ssh_key.key
- Make sure that the key file has restricted access permissions, so that only your user ID can access the file. (Remove the access permissions for Groups and Everyone, leaving only read permission for yourself.)
- Connect to Files.com, specifying the Key file by using the -i (identity file) flag:
Mac/Linux:
sftp -i /path/to/my_ssh_key.key username@MYCOMPANY.files.com
Windows:
sftp -i C:\path\to\my_ssh_key.key username@MYCOMPANY.files.com
To upload files:
- Upload a single file using the put command
put file.ext - Upload multiple files using the mput (multiple put) command
mput file1.ext file2.ext file3.ext
or use a wildcard to match file names
mput file*.ext
To upload a folder:
- Create the destination folder using the mkdir (make directory) command (make sure the folder name matches the name of the folder you’re trying to upload)
mkdir TheFolderName - Upload the folder contents using the put -r (put recursively) command
put -r TheFolderName/
To download files:
- Download a single file using the get command
get file.ext - Download multiple files using the mget (multiple get) command
mget file1.ext file2.ext file3.ext
or use a wildcard to match file names
mget file*.ext
To download a folder:
- Create the local destination folder using the lmkdir (locally make directory) command (make sure the folder name matches the name of the folder you’re trying to download)
lmkdir TheFolderName - Set your local permissions using the lumask (locally set the mask for user permissions) command
lumask 002 - Download the folder contents using the get -r (get recursively) command
get -r TheFolderName/
Using the lumask command to set the UMASK to 002 will set the correct permissions for all the files to download successfully. If you miss this step then you might see permission errors, where subfolders will be created but the files contained within them will fail to download.
Files.com operates a proprietary SFTP server software that we build and maintain in-house using our full-time employees. Our server is compatible with SFTP standards and tested against many popular SFTP apps used by businesses.
Files.com's SFTP server also supports the SCP protocol, another file transfer protocol that is built on top of SSH. For purposes of most interactions with Files.com, SCP will work exactly the same as SFTP.
Functionality is restricted to only SFTP and SCP capabilities. This means that only the file transfer related capabilities of SSH are allowed, such as using SFTP or SCP to transfer files, and SSH Keys for authentication.
There are no other SSH services provided. SSH capabilities such as shell access or SSH tunneling are unavailable, preventing their use in any way.
Security scans will detect SSH availability as a "false positive" result. This is because SFTP and SCP are subsets of SSH functionality. No SSH capabilities, other than those required by SFTP and SCP, are available on the Files.com platform.
Files.com makes use of a 4096-bit RSA SSH host key. The host key itself (in OpenSSH format) as well as fingerprints in 3 different formats are provided below. Use whichever format is required by your SFTP app.
- OpenSSH host key: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQCD+pdvc7zeWkcDuyo4k7fca+BVqSSnbGteq2fcquo+jbN9rXySnlbHyAZsxwXIxn/TMWFQCgD619TbdMQ2F4x0tC/UfrNiF0tCQ0UZNlOuQz6G2a0QBzMRgeugGqbFOHHQTaOcgMJoW0ai8vbpHlGMybqcjQg+MWC8fNl4WcX9Ruze713WhcTIbrA4P7iqlyjFkiaQMX642mO0/RboME/4TdyNg7w0bxJaLifiIGtStZ5cRWSW8nxr/PEdQPeSg/2HshyUFJx6GD7ej3NeFsDuYCYFdBXGpZ/Tp6i2mIC/NoVO+3Hz7Pw6JA+H3tEy8U9zqSwPk9RIGlKoWTtZvo9xcBwCFIPyMymU83gfioZYZN4uK196oX/2sspMUIOTUlA4eeIdmbDbK0w1QYGr1bOk/5bKgxybDx4m7FsY3NDylZKDmS1SMVPg1C/GYVdpheOHZpzH5f8qT34ZRFGmktIhRqD+cSiNdcDMDebRBeFG/mCIVSNnoEiDKjKqH/+dpdiJHlTDSH1QCg/d+HSX4eEVG0AudIeSELjaJg2V0kVbk9gF28G0BzQ6NxGm9d7hZD61BfjcuxgRr1bqx6uEip0WrNTinNEIleB1L6M5BUapeICBe+F0Kte+qBYrVENWJoai9V9l/IuBvYWIWkMf0MsuGeiQi2IOvEMfwrD9jBlWqw==
- SHA256 fingerprint: JvS7SrgY9QfsC2otdG0TGo0aWcvvieGg1R2Vx8/5VSw
- SHA1 fingerprint: go2g72JG1emRzP54QtFmFrE0DTg
- SHA1 hex digest: 82:8d:a0:ef:62:46:d5:e9:91:cc:fe:78:42:d1:66:16:b1:34:0d:38
- MD5 fingerprint: 79:e1:fc:1c:8d:d7:95:25:84:c5:70:16:4d:07:e0:c5
Please refer to the documentation for your specific SFTP client for exact details about how to use a host key fingerprint as some clients provide this capability while others do not.
For example, WinSCP provides host key fingerprint capability via its -hostkey option. When using the WinSCP command line, you can specify:
-hostkey="ssh-rsa 4096 JvS7SrgY9QfsC2otdG0TGo0aWcvvieGg1R2Vx8/5VSw"
When using the WinSCP Script Command option, you can specify:
open sftp://user:XXXXX@[subdomain].files.com -timeout=30 -privatekey=C:\path\to\my-private.key -hostkey="ssh-rsa 4096 JvS7SrgY9QfsC2otdG0TGo0aWcvvieGg1R2Vx8/5VSw"
For maximum security, you should verify the host key fingerprint when connecting via SFTP. A host key mismatch means that, in the best case, you are experiencing a misconfiguration and, in the worst case, an active attack is taking place.
Although host keys should be unique and restricted to their specific corresponding host, there are times when a host key needs to be migrated to a new host. In these situations, it's often desirable for SFTP connections can continue functioning seamlessly, without the burden of SFTP clients having to reconfigure their known host key settings.
Files.com provides the ability to configure your SFTP host key, so that migrating your SFTP service to our platform is as frictionless as possible.
To configure your SFTP host key, type SFTP Host key in the search box at the top of every page and then click on the matching result. Scroll down to locate the setting labelled SFTP Host Key.
The available options are:
- Use Files.com host key (default) - This option uses the Files.com SFTP host key described above.
- Use ExaVault host key - This option uses the ExaVault SFTP host key and is provided for customers who have migrated from the ExaVault platform to the Files.com platform.
- Use a custom host key - This option allows you to import your own SFTP host key and is provided for customers who are migrating from other SFTP services, such as on premises solutions, to the Files.com platform.
To use a custom host key:
- Select the Use a custom host key option.
- Enter a name for this host key. (This should be something descriptive that informs you of the key's origin.)
- Enter the host key text.
- Click the Save button.
Once saved, the SFTP host key will take effect within five (5) minutes.
You can also view the fingerprint of an imported SFTP host key by returning to the Use a custom host key option. The SHA256 and MD5 fingerprints of the current imported SFTP host key will be shown, allowing you to verify its integrity. You can replace the imported SFTP host key by selecting the Replace host key link and entering the text of the replacement SFTP host key.
Custom SFTP host keys should be in PEM format.
Files.com supports the following SFTP host key types:
- RSA
- DSA
- ECDSA
- ed25519
RSA type host keys in PEM format will begin with -----BEGIN RSA PRIVATE KEY----- and end with -----END RSA PRIVATE KEY-----.
DSA type host keys in PEM format will begin with -----BEGIN DSA PRIVATE KEY----- and end with -----END DSA PRIVATE KEY-----.
ECDSA type host keys in PEM format will begin with -----BEGIN EC PRIVATE KEY----- and end with -----END EC PRIVATE KEY-----.
ed25519 type host keys in PEM format will begin with -----BEGIN OPENSSH PRIVATE KEY----- and end with -----END OPENSSH PRIVATE KEY-----.
Files.com supports setting a custom root folder on a per-user basis, and it will apply only to FTP connections (and optionally also SFTP connections), but not anywhere else such as the web, mobile, or desktop app.
This is meant for applications that are unable to change directories appropriately in order to look in the right place for files.
This setting is not a security setting and does not restrict the user from accessing other folders via mechanisms other than FTP. You should use Permissions to set access controls on a per folder basis.
To change this setting for a user, type Manage users in the search box at the top of each page and then click on the matching result. Edit the desired user and click o the Other Connections section to locate the FTP/SFTP client root folder setting.
If set, Files.com will act as if the selected folder is the root folder for any given FTP session.
This setting may also be applied to SFTP connections. To enable this, type SFTP client root folders in the search box at the top of every page and then click on the matching result. Update the SFTP client root folders toggle.
Our SFTP service includes the ability to configure a welcome message, also known as the Message Of The Day (MOTD), to users. The message will be shown to users when they first connect to Files.com using the SFTP protocol.
To configure the message, type Custom message of the day in the search box at the top of every page and then click on the matching result. Scroll to the setting Custom message of the day (MOTD), select Edit, enter the plain text of your message, check the Show message to users connecting via SFTP checkbox, and select Save.
Tip: Set the number of simultaneous connections to the maximum supported by your SFTP app.
To increase the number of simultaneous connections in FileZilla, go to Edit > Settings > Transfers and increase the Maximum simultaneous transfers setting to 10.
To increase the number of simultaneous connections in Cyberduck, first go to Edit > Preferences > Transfers and set Transfer Files to "Open multiple connections".
Then, go to to Window > Transfers and increase the counter in the lower right to the maximum.
Increasing the number of simultaneous connections will help when uploading multiple files at the same time but will not have any effect when uploading a single file.
Tip: Minimize network latency.
Network latency is measured as the round-trip delay between sending data across a network and receiving a reply that the data was received. Higher latency, also known as "lag", can be caused by:
- physical limitations, such as your physical network connection.
- how much data is currently saturating your network connection.
- the network distance between you and your destination.
- network tools and software that regulate or restrict bandwidth usage.
Network latency has a large impact on SFTP performance and these suggestions can help:
- Use the best physical network available to you. - For example, choose a physical ethernet connection over a Wi-Fi connection.
- Use the shortest network distance wherever possible. - Ideally, you should be in the same geographic region as the destination that you are connecting to. Using VPNs or network proxies that are located in other geographic regions will always add latency. For example, if you are located in the EU, the SFTP destination is also located in the EU, but your VPN is located in the US then all your data will be routed through the US which will cause much higher latency despite the SFTP destination being geographically close to you.
- Try increasing the size of the data chunks (buffer size) that is sent by your SFTP client. - Most SFTP clients send data in 32K (32000 bytes) size chunks. Check your client configuration settings and try increasing the buffer size to double or triple. For example, you can set the buffer size for the command line sftp command using the -B option: sftp -B 64000 username@MYCOMPANY.files.com
Under the hood, the SFTP protocol uses an SSH connection. One of the benefits of SFTP is the ability to use an SSH Key to authenticate instead of a password.
The use of an SSH Key to authenticate is not mandatory. SSH Keys can either be used as an optional alternative to a password, or as a mandatory replacement for a password, depending on how the system is configured.
SSH Keys will never grant access to a shell or system prompt at Files.com and are only for SFTP protocol usage.
An SSH Key is really a matched pair: a public key and a corresponding private key.
When generating an SSH key, the two halves (public and private) will always be created.
The private key must never be shared, and should remain under the control of the user, script, or system, that will be using SFTP to connect to an SFTP account. The private key is the equivalent of your password and should be protected similarly.
The public key can be shared with any system that needs to provide secure access to the user, script, or system, that owns the corresponding private key. The public key does not need to be kept secret and can be distributed freely. The public key has no power, authorization, or authority without the corresponding private key.
Important: Never share a private key.
Whenever exchanging SSH keys for use with SFTP or SSH access, only send or share the public key portion.
SSH Keys can be imported into Files.com and used to authenticate users.
Users can add their own SSH public keys themselves within the Files.com web interface. After logging in with their username and password, they can select their username at the top right of the page then select My account > SFTP keys > Add SFTP key, and paste in the public key portion of their SSH key.
Administrators can add an SSH key to any Files.com user account. Type SFTP/SSH Keys in the search box at the top of every page and then click the matching result. Click Add SFTP key, and paste in the public key that was provided by that use. Once imported, the user account can use their SSH private key to authenticate and gain access to Files.com using the SFTP protocol.
SFTP public keys can also be added programmatically via the REST API.
Public keys are not viewable once saved, but can be identified by their unique "key fingerprint". If you need to verify that you have the correct key, you can view the public key's fingerprint. Type SFTP/SSH Keys in the search box at the top of every page and then click the matching result. All of the keys for the selected user are listed, with the title given to the key, the fingerprint, and the option to delete the key from Files.com. If you believe that the key pair has been compromised or is no longer in use, remove the key by clicking the Delete button.
We support the ED25519 (including ED25519-sk), ECDSA (including ECDSA-sk), RSA, and DSA encryption types for keys.
We recommend using ED25519 keys because they are the most secure. RSA and DSA keys are considered less secure and slower than ED25519.
If using an RSA key, we recommend using a key length of at least 2048 bits.
User accounts with passwords
When a user account is configured with a password, the SSH Key will act as an additional method of authentication. That is, both the SSH Key or the password can be used to authenticate an SFTP connection by that user account. A user account is considered to have a password when the Authentication Method for that account was configured to use any of the following options:
- Password
- Imported hash
- Email sign-up
- Any of the available Single-Sign-On (SSO) methods
User accounts without passwords
When a user account is configured with no password, the SSH Key will act as the only method of authentication. That is, only the SSH Key can be used to authenticate an SFTP connection by that user account. A user account is considered to have no password when the Authentication Method for that account was configured to use the following option:
- None
We have put together separate tutorials for web interface, Windows, Mac, and Linux.
Both users and administrators can generate SSH Key pairs within the Files.com web interface.
Users can generate their own SSH keys by logging in with their username and password, selecting their username at the top right of the page, selecting My account > SFTP keys > Add SFTP key, selecting the Generate in browser option, then selecting Generate key pair.
Site administrators can generate an SSH key for a user account. Type SFTP/SSH Keys in the search box at the top of every page and then click the matching result. Click Add SFTP key, and and select the Generate in browser option, then selecting Generate key pair.
NOTE: You will only have one chance to copy or download the private key.
Do not dismiss the private key information until you have copied or saved it to a secure location.
This guide requires you to use the PUTTYgen (free) open-source application. PUTTYgen is a standalone application that does not require you to install it. You can download a copy of this utility from the downloads page at the maintainer's website.
Generating compatible keys with PUTTYgen
1) Open the PUTTYgen application by double clicking on it.
2) Choose ED25519 for the Type of key to generate
3) Click the Generate button
4) Move your mouse around until the progress bar is full.
5) You now will have a generated public and private key.
6) Save the private and public key files to a location that only you can access and that you will not lose.
7) Right click in the text field labeled Public key for pasting into OpenSSH authorized_keys file and choose Select All
8) Right click again and choose Copy
9) Finally you need to add the SFTP public key to your Files.com account. Navigate to Settings > Users and click the the username of the appropriate user. Click the SFTP Keys setting, and paste the contents of your clipboard into the Public Key text area. For the Title you can enter any piece of identifying information that you want (for example, my laptop).
MacOS already includes the necessary software to generate a key pair. Simply click the magnifying in the top right hand of your screen, type in Terminal and hit enter to open the application.
1) Create the new ED25519 Key
ssh-keygen -t ed255192) When prompted specify the path you want to save the key files in.
Enter file in which to save the key (/home/user/.ssh/id_ed25519):3) If you wish to enter a passphrase for the private key you can enter it when prompted. A passphrase is not required for the private key though. If you do enter a passphrase you will have to type it in each time you use the private key.
Enter passphrase (empty for no passphrase):4) Now that your key is generated you will want to copy it to your clipboard so that you can add it to your SFTP Keys.
pbcopy < ~/.ssh/id_ed25519.pub5) Finally you need to add the SFTP public key to your Files.com account. Navigate to Settings > Users and click the the username of the appropriate user. Click the SFTP Keys setting, and paste the contents of your clipboard into the Public Key text area. For the Title you can enter any piece of identifying information that you want (for example, my laptop).
Linux already includes the necessary software to generate a key pair. Simply open your bash shell and type the following commands.
1) Create the new ED25519 Key
ssh-keygen -t ed255192) When prompted specify the path you want to save the key files in.
Enter file in which to save the key (/home/user/.ssh/id_ed25519):3) If you wish to enter a passphrase for the private key you can enter it when prompted. A passphrase is not required for the private key though. If you do enter a passphrase you will have to type it in each time you use the private key.
Enter passphrase (empty for no passphrase):4) Now that your key is generated you will want to copy it to your clipboard so that you can add it to your SFTP Keys.
xclip -sel clip < ~/.ssh/id_ed25519.pub5) Finally you need to add the SFTP public key to your Files.com account. Navigate to Settings > Users and click the the username of the appropriate user. Click the SFTP Keys setting, and paste the contents of your clipboard into the Public Key text area. For the Title you can enter any piece of identifying information that you want (for example, my laptop).
Most of the time, SFTP connection issues are 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 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 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 blocks that didn't previously exist.
- Have you manually whitelisted any IP addresses anywhere? 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 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 the prior bullet.) - See if you need to ask for an IP whitelist. If you have not whitelisted IP addresses, maybe your firewall administrator requires this 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 bullet point.
- Try other ports. - 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 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 and we are unable to proceed with helping you troubleshoot if you are doing this.
- Port - 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.
- 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 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.
- Keepalives - 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.
- Ciphers - 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 Manage 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 Manage users in the search box at the top of every page and then click the matching result. Edit the user and select the Privileges tab, and scroll to Protocol access section and check for SFTP.
- 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 Manage 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 you are specifically receiving error messages in your SFTP client about an invalid username or password, please be aware of the following. The SFTP protocol uses integers internally to communicate authentication failure codes and does not provide for 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.
If you are receiving error messages in your SFTP client about an invalid username or password, check your account audit history. 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, brute force protection, IP restrictions, 2FA restrictions, geographic restrictions, or other authentication restrictions that you've configured on your site.
Get Instant Access to Files.com
The button below will take you to our Free Trial signup page. Click on the white "Start My Free Trial" button, then fill out the short form on the next page. Your account will be activated instantly. You can dive in and start yourself or let us help. The choice is yours.
Start My Free Trial