[[TOC()]]

= [wiki:help/en Cyberduck Help] / [wiki:help/en/howto Howto] / SFTP =

== SFTP connections ==

If you have access to a server using a secure shell ([http://en.wikipedia.org/wiki/Secure_Shell SSH2]), most probably `sftp-server` is also installed and configured and you can connect using [http://en.wikipedia.org/wiki/SSH_file_transfer_protocol SFTP].

== OpenSSH Configuration Interoperability ==

The following configuration options from `~/.ssh/config` are supported for SFTP connections:
 * ''IdentityFile'' for public key authentication.
 * ''HostName'' aliases.
 * ''User'' preference for login credentials.

Host keys are checked against and written to `~/ssh/known_hosts` when accepted.

A [wiki:help/en/howto/bookmarks bookmark] will update its public key authentication setting from the ''IdentityFile'' configuration in `~/.ssh/config`. Also when opening a new [wiki:help/en/howto/connection#Toolbarbutton connection] using ''File → Open Connection…'', ''IdentityFile'' and ''User'' parameters in the OpenSSH user config file are auto completed.

Example configuration:

{{{
Host myhostname
	User myusername
	IdentityFile ~/.ssh/mykey-rsa
}}}

Contrary to ''OpenSSH'', we do '''not''' use the keys named `~/.ssh/identity`, `~/.ssh/id_rsa` or `~/.ssh/id_dsa` by default.

== Public Key Authentication ==

Public-key authentication allows you to connect to a remote server without sending your password over the Internet. Public-key authentication uses two keys, a private key that only you have--it should be kept in a secure place and protected with a password. And the public key, which is placed on the server you wish to gain access to, usually by the system administrator when your account is set up. Private keys containing a `DSA` or `RSA` private key in ''PEM'' format are supported (look for `-----BEGIN DSA PRIVATE KEY-----` or `-----BEGIN RSA PRIVATE KEY-----` in the file) and can be configured in the [wiki:help/en/howto/bookmarks Bookmark] or [wiki:help/en/howto/connection Connection] panel.

=== How to configure public key authentication? ===

 1. Run the command {{{ssh-keygen}}} from the Terminal.app to generate a public/private pair of keys. They will be put in your directory {{{~/.ssh}}}, though you will probably be asked to approve or change this location. When you generate the keys you will be asked for a 'passphrase'. If you use a passphrase then you will have to enter it each time you use the keys for authentication. That is, you will have to type in the pass phrase everytime you log in, just as you would with a password. If you don't enter a passphrase (just press the return key) then you will be allowed to log-in without having to enter a passphrase. This can be more convenient, but it is less secure.

{{{
cd .ssh
ssh-keygen -t rsa
}}}

 2. Copy the public key to the remote host you wish to access and add it to the file {{{authorized_keys}}} in your {{{~/.ssh}}} directory. (If that file does not exist then you should create it.) Anybody listed in the authorized_keys file (via their public key) is allowed to log-in, provided that they can prove that they possess the corresponding private key. Thus if you have the private key in your .ssh directory on your home machine you'll be allowed in.


{{{
ssh hostname < id_rsa.pub 'cat >> .ssh/authorized_keys'
}}}

 3. In the Connection Dialog or the Bookmark editor in Cyberduck select ''Use Public Key Authentication'' and select the private key in your {{{.ssh}}} directory.


== One-time passcodes ==

Using a challenge-response authentication with one time password generators like ''SecurID'' is supported. After the initial login prompt for the username and password a second login prompt is displayed to enter the one-time passcode.

== Verifying host keys ==

Upon connecting to a SSH server for the first time, you will see a message to verify the host key uniquely identifying the server. You can ask your provider for the public fingerprint of the server to make sure you are connecting to the right host. Subsequent connections to the SSH server will make sure that the host key does not have changed to prevent spoofing attacks.

[[Image(Unknown host key.png)]]

== Using SCP for file transfers ==

You can choose to use SCP for file transfers instead of SFTP for possible higher throughput. Change the default setting in the [wiki:help/en/howto/preferences Preferences].

== Open in Terminal ==

Use ''View → Customize Toolbar...'' to add the ''Terminal.app'' toolbar icon to your browser. It allows you to open a SSH shell for the current working directoy with a single click.

[[Image(Terminal.png)]]

=== Customize SSH command ===
You can change the SSH command using the [wiki:help/en/howto/preferences#Hiddenconfigurationoptions hidden configuration option]

{{{
defaults write ch.sudo.cyberduck terminal.command.ssh \"ssh\ -t\ {0}\ {1}@{2}\ -p\ {3}\ \\\"cd\ {4}\ \&\&\ exec\ \\\\\$SHELL\\\"\"
}}}

where 
 * {0} is `-i <path to the private key>`
 * {1} is the username from the login credentials
 * {2} is the hostname
 * {3} is the port number of the remote host
 * {4} is the current working directory in the browser

Because of all the escaping of characters, it might be easier to edit the key using ''Property List Editor'' if you have the developer tools installed. You can then set the string for the key `terminal.command.ssh` to `ssh -t {0} {1}@{2} -p {3} "cd {4} && exec \$SHELL"`. Test the string in ''Terminal.app'' first if it is valid.

=== Using iTerm ===

You can change a  [wiki:help/en/howto/preferences#Hiddenconfigurationoptions hidden configuration option] to use a thirdparty terminal application instead of ''Terminal.app''.

Exampe for [http://iterm.sourceforge.net/ iTerm]:
 
{{{
defaults write ch.sudo.cyberduck terminal.bundle.identifier net.sourceforge.iTerm
defaults write ch.sudo.cyberduck terminal.command \"make\ new\ terminal\\ntell\ the\ first\ terminal\\nlaunch\ session\ \\\"Default\ Session\\\"\\ntell\ the\ last\ session\\nwrite\ text\ \\\"{0}\\\"\\nend\ tell\\nend\ tell\"
}}}

To reset to the default settings use:

{{{
defaults delete ch.sudo.cyberduck terminal.bundle.identifier
defaults delete ch.sudo.cyberduck terminal.command
}}}

== Distribution (CDN) == 

You can enable [wiki:help/en/howto/cloudfront  Amazon CloudFront (Content Delivery Network) distribution] using ''File → Info → Distribution (CDN)''.

== Create and expand ZIP/TAR Archives == 

The remote systems must have the archiving tools `tar` or `zip` installed respectively. Use ''View → Customize Toolbar...'' to add the ''Archive'' toolbar button to your browser window. It is not included in the default toolbar configuration.

=== Archive ===

Select one or more files to archive in the browser. For multiple files, a file with the name `Archive` with the given extension of the archive format will be created.

[[Image(Compress.png)]]

=== Expand ===

Select one or more files to expand in the current working directory.
== Remote Commands ==

See the Browser [wiki:help/en/howto/commands#SSHserver Custom Command] page to send custom commands over SSH.

== Default protocol handler ==

You can set Cyberduck or a third party application as the default application (protocol handler) for `SFTP` in ''Preferences → SFTP''. When you click URLs in another application like your web browser, this application is opened to open the URL instead. 

== Problems ==

=== Illegal sftp packet len ===
The error message `Illegal sftp packet len` may indicate you have either:
 * An `echo` statement in your shell init script like ''.bashrc''. Make sure it does not output any text.
 * Interoperability issue with Globalscape EFT Server. Issue #5308.

=== Kex Timeout ===

This error can occur if you are connecting the first time to a device with a slow processor. You can raise the tmeout value in ''Preferences → Connection → Timeout ''.

[[Image(Kex Timeout.png)]]