Library

All about SFTP in Transmit 5

In a nutshell, SFTP (SSH File Transfer Protocol) is a network protocol mostly used for transferring files over the web. It builds on the classic File Transfer Protocol (FTP) and includes Secure Shell (SSH) security components. In the following document we explain how Transmit handles connections to SFTP servers and what you can do to troubleshoot connections if Transmit behaves in a way you didn’t expect.

The Authentication Flow

How does SFTP Authentication work in Transmit 5?

When Transmit attempts to make an SFTP connection it looks in several places for usernames, passwords and/or keys. Here here are those places and the order in which they’re used. Transmit will always attempt the following in order, continuing on to the next option if previous items fail or cannot be found. Here’s a quick list, with more details below.

Username Preference Order
  1. Username defined in Transmit’s connection settings
  1. Username defined in your SSH config file
  1. Shortname of current user on your Mac
Password & Key Preference Order
  1. SSH Keys that have been added to the system SSH agent
  1. SSH Key defined in Transmit’s connection settings
  1. SSH Key defined in your SSH config file
  1. Passwords defined in Transmit’s connection settings
  1. Default id_* key files on disk in ~/.ssh
  1. If no other passwords/keys are found or entered, Transmit will prompt you for credentials when you attempt the connection

Username Preference Order

When authenticating over SFTP Transmit will attempt to find and use usernames in the following order:

A username entered in Transmit’s connection settings
A username manually entered and saved in one of Transmit’s server connections, or manually entered via Quick Connect
A username defined in your SSH config File (Located here: ~/.ssh/config. More Info)
If your username is defined in your config file, leave the username field empty in Transmit’s connection settings.
The local user on your Mac
If no username is defined in your config file or in Transmit’s connection settings, Transmit will send the Shortname of the current user on your Mac by default.

Password & Key Preference Order

Transmit 5 uses passwords and keys in a specific order depending on where they exist on your Mac.

SSH Keys that have been added to the system SSH agent
The first authentication method attempted by Transmit are SSH keys that have been added to the system ssh-agent.
SSH Key defined in Transmit’s connection settings
If you’re unfamiliar with how to add keys to the system agent, you can add keys directly to Transmit.

To associate an SSH key with a Server, import the key from a file on disk, or generate it right in Transmit.

All key management is handled in the Keys tab of Transmit’s Settings menu. If you import an encrypted key, you will be prompted for the passphrase and it will be securely stored alongside the key in your system keychain. SSH Keys in Transmit Settings. After your key is imported, edit your Server and select the key you’d like to use for authentication. If your key is encrypted and you chose not to store the passphrase, you will be prompted for it when you connect. SSH key associated with Transmit Server.

SSH Key defined in your SSH config file
If the Server does not have a key associated with it in Transmit’s connection settings, Transmit will attempt to use any keys explicitly specified for the server found in your ssh config file.
Passwords defined in Transmit’s connection settings
The next authentication method that Transmit will try is a password specified in the Server settings.
Default id_* key files located in ~/.ssh
Transmit will attempt to use any id_* keys (id_rsa, id_dsa, id_ed25519, and id_ecdsa) in your ~/.ssh directory. If you have existing keys on disk but do not want Transmit to attempt to use them when connecting, we recommend you specify a key or password with the Server. If these keys are encrypted and the passphrase is not stored in the keychain, Transmit will prompt you for the key’s passphrase when you connect to the server.
SSH Key passphrase alert prompt.

To skip authenticating with an encrypted key, leave the passphrase field blank and click Connect.

Prompt for credentials when connecting
If you do not want to use an SSH key to connect, and also do not want to store your password in Transmit, Transmit will prompt for the server’s password at the time of connection.

Troubleshooting

Transmit won’t connect to my server

There are any number of different things that could cause an SFTP connection to fail. If you’re having trouble connecting to your server, here’s what you should check.

1. Make sure your login details are correct

It may sound obvious, but double-check to make sure that you have the correct login details. At the bare minimum, you will need the following information in order to connect to your SFTP server:

  • Server Address (Typically a domain name such as server.com or an IPv4 address)
  • Port number (Typically 22 for SFTP)
  • Username
  • Password (and/or SSH Key)

Note: Panic is not your web host. We have zero control over your login details. If you need to reset your website password, you will need to contact the hosting company or the person that manages your web server.

If you’re using an SSH key, there are a lot of little details to keep in mind. See our documentation for working with SSH keys for more information.

2. Check the Transcript or error messages

Errors and other connection related information get logged in the Transcript. You can view the Transcript by selecting Transcript from the Window Menu in the menubar. Often times, error messages logged in the transcript will tell you what’s wrong or what setting you need to change. You can find many additional server settings in Settings > Advanced > Advanced Server Settings.

3. Disable firewalls or other network filtering software

Aggressive settings enabled in firewalls, apps like Little Snitch, or devices like network routers can sometimes cause issues with server connections. This is especially common with corporate or university networks. If you’re having trouble connecting, try disabling any of these apps or devices you may be running. Power cycling your network equipment may also help.

As a test, try connecting your Mac to a different network. If you’re at home, take your Mac to work/school or vice versa. If one network allows you to connect but another network does not, then you’ve found the issue.

4. Try connecting with a different SFTP client app

By connecting with a different SFTP client that’s not Transmit, it can tell you a lot of things. Here are some examples:

  • If you cannot connect to your server with Transmit or other SFTP clients, then you know that the connection issue is likely due to your server or your login. Should this be the case, there’s not really anything we can do on our end. You will need to check with your server’s administrator.
  • If you CAN connect in other SFTP clients but NOT in Transmit, then it’s either a matter of getting your settings correct, or there’s some quirk with your server that our apps aren’t respecting. Email us with a test login (see our note below) and we can generally determine why this is happening.

Note: For security purposes, do NOT send us the credentials that you yourself use to login! If you send us a login, make sure it’s a newly-created test account. Feel free to lock it down to a single folder if you like.

5. Make sure SFTP is actually enabled on your server

Believe it or not, SSH can be enabled on a given server while having SFTP disabled at the same time. This would allow you to connect via SSH on the command line, but not in an SFTP client app like Transmit. Your server administrator can help you confirm that SFTP is properly enabled.

6. If all else fails, contact us

I’ve you’ve gone through all of the steps above, feel free to reach out to us for technical support. Be sure to include a copy of the Transcript from step 2.

Why can’t I connect to my server after updating to Transmit 5.6.4 or 5.6.5?

If you’re suddenly unable to connect after updating Transmit, you may need to alter your SSH/SFTP configuration. The details of this are explained in the following section.

SSH Authentication Changes in Transmit 5.6.4

Starting in Transmit 5.6.4 we’ve made some changes to improve security, address a few bugs, and bring Transmit’s SFTP authentication behavior more in line with how SSH behaves on the command line. As a result, Transmit will now use key files associated with a server before passwords saved in Transmit favorites.

What is a key, you ask? It’s a file you can think of as a “super password” that is unique to your computer and the server. Odds are, you set this up on your computer and have completely forgotten about it, that’s why you’re reading this article. Since keys are more secure than passwords, Transmit now favors using them when logging in to your servers.

Due to these changes, it’s possible you may find yourself in a situation where you are prompted for an SSH key passphrase upon connecting to any SFTP server, like so:

SSH Key Passphrase Prompt

Another possibility is that you may get an Authentication Failed error with a miscellaneous error code showing up in the Transcript log.

If you find yourself in this situation, it is likely that you have a key defined for this connection in your SSH config file, whether you meant to or not.

Check your ~/.ssh folder for any errant key files

Open your ~/.ssh folder in Finder. Here’s how:

  1. In Finder’s menubar, select Go to folder from the Go menu.
  2. In the box that appears, enter the following and click Go: ~/.ssh

In this folder, look for any key files that start with id_ such as id_rsa or id_ecdsa. If these key files aren’t being used, delete them or rename them. Otherwise, Transmit will offer these default keys before attempting password authentication. If your server isn’t set up to accept these keys, you may run into connection issues.

Check Your SSH Config File For Accuracy

If you’ve checked for any unnecessary keys, the next thing to check would be your SSH config file.

First, open your config file in a text editor of your choosing. Here’s how:

  1. In Finder’s menubar, select Go to folder from the Go menu.
  2. In the box that appears, enter the following and click Go: ~/.ssh
  3. Right click config and open it in a text editor.

Wildcard (*) configurations in your SSH config are often not ideal as they will offer these keys for every connection. Unless you have the passphrase stored in your keychain, Transmit will prompt for a passphrase in order to use the key for authentication. One common situation would be for Github, as their documentation currently instructs you to configure things this way. Here’s an example of what this would look like in your config file:

Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_rsa

The entry above will cause Transmit to prompt you for your SSH Key passphrase with every SFTP connection, as this key is explicitly defined for all addresses due to the wildcard.

Since the config file is used by many different apps (Transmit, Terminal, Coda, Git clients, etc.), this is not an optimal way to define the key in your config file. For the most part, Transmit attempts to match the behavior of SSH on the command line. If you attempt to SSH into the same server on the command line (with a wildcard address in your config file like the example above), you’ll be prompted for the passphrase the same as you would in Transmit.

In an ideal scenario, rather than using a wildcard for the host entry, you would use only the address to which the key actually applies. Using the Github example above as the server in question, that entry in your config file would look like this:

Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_rsa

In this case, Transmit would only prompt you for your SSH key passphrase when connecting to github.com.

If you were previously using a wildcard entry deliberately to use your key for multiple addresses, you can add those all to the host entry separated by spaces, avoiding the wildcard scenario and still allowing multiple hosts for a single key entry. Here’s one possible example:

Host github.com mysite.com myserver.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_rsa

Other Solutions

If avoiding a wildcard isn’t an option, you’ll need to manually specify any non-key based connection as requiring password authentication above your wildcard in your config file, like so:

Host mysite.com
  PasswordAuthentication yes

Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_rsa

The configuration above allows you to keep the wildcard while requiring the server “mysite.com” to stick to password authentication.

TL;DR: Now that Transmit 5.6.4 (and later) uses explicitly-defined keys in your config file and default keys in your ~/.ssh directory (just like SSH on the command line) make sure that the Host entry for keys defined in your config file are only for the necessary addresses, not a wildcard.

For more information about how SSH keys work in Transmit or any other Panic app, please see our SSH key documentation.