SFTP

Providers
Settings are specific to service providers. Use the provided connection profiles.
Note
All connection profiles are available through the Preferences → Profiles tab.
Connecting
If you have access to a server using a secure shell (SSH2), most probably sftp-server
is also installed and configured and you can connect using SFTP.
OpenSSH Configuration Interoperability
Public Key Fingerprints
Public key fingerprints are checked against and written to ~/ssh/known_hosts
when accepted. This does not apply to the Mac App Store version which does store key fingerprints in the preferences.
Configuration File
The following configuration options from ~/.ssh/config
are supported for SFTP connections:
IdentityFile for public key authentication.
IdentityAgent for public key authentication. Specifies the UNIX-domain socket used to communicate with the authentication agent.
HostName aliases.
User preference for login credentials.
ProxyJump to connect via SSH tunnel through bastion server.
PreferredAuthentications to limit authentication methods tried to login.
IdentitiesOnly. Only try explicitly set private keys to authenticate but not all identities found in SSH agent. Resolves Too many authentication failures errors with servers limiting the number of attempted authentication requests.
A bookmark will update its public key authentication setting from the IdentityFile configuration in
~/.ssh/config
. Also when opening a new connection using File → Open Connection…, IdentityFile and User parameters in the OpenSSH user config file are auto completed.
Example ~/.ssh/config
configuration:
Host myhostname
User myusername
IdentityFile ~/.ssh/mykey-rsa
To use the same key for all hosts add a wildcard entry such as
Host *
IdentityFile ~/.ssh/mykey-rsa
which is then used when configuring a new bookmark.
Important
If you have a configuration in your ~/.ssh/config
make sure to specify the Host
alias as hostname in your bookmark configuration. This is important for cases the Host
alias is different from the HostName
:
Host myhostalias
HostName myverylonghostname.exmaple.com
User myusername
IdentityFile ~/.ssh/mykey-rsa.pub
For the configuration above the hostname to specify in your bookmark is myhostalias
.
Default Public Key Authentication Keys
You can enable the use of a default set of keys ~/.ssh/id_rsa
and ~/.ssh/id_dsa
(in this order) by setting the hidden configuration option ssh.authentication.publickey.default.enable
to true
.
defaults write ch.sudo.cyberduck ssh.authentication.publickey.default.enable true
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 that should be kept in a secure place and protected with a password
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 can be configured in the Bookmark or Connection panel.
PuTTY Key Format Interoperability
PuTTY private keys (.ppk
) are supported for rsa
key types. ed25519
is not supported.
OpenSSH Key Format Interoperability
OpenSSH private keys of type rsa
, dsa
, ecdsa
and ed25519
(in OpenSSLPEM
format) are supported. The new OpenSSH format (openssh-key-v1
) is only supported for ecdsa
and ed25519
.
Configure Public Key Authentication
Run the command
ssh-keygen
from the Terminal.app (macOS) or console (Windows) 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 passphrase every time 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.ssh-keygen -m PEM -t rsa
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 < ~/.ssh/id_rsa.pub 'cat >> .ssh/authorized_keys'
In the Connection Dialog or the Bookmark editor in Cyberduck select Use Public Key Authentication and select the private key in your
.ssh
directory.
CA signed SSH Certificate Interoperability
Certification Authority (CA) sigend SSH certificates are supported for keys of type rsa
, dsa
, ecdsa
, and ed25519
.
Public Key Authentication Using SSH Agent
When connecting to a SSH server, Cyberduck will lookup matching private keys from the SSH agent when attempting to authenticate with the server if no password is available and no explicit private key to use is configured in the bookmark.
Warning
The feature is not supported when running Cyberduck from the Mac App Store because of sandboxing restrictions.
The agent ssh-agent
is running by default on macOS. You add private key identities to the authentication agent using the program ssh-add
. The SSH agent is located using the IdentityAgent
directive in ~/.ssh/config
or if missing from the environment variable SSH_AUTH_SOCK
.
The following agents are supported:
Pageant. Refer to How To Use Pageant to Streamline SSH Key Authentication with PuTTY.
OpenSSH for Windows using the pipe (
\\.\pipe\openssh-ssh-agent
) by default. UseIdentityAgent
to set a custom socket path for any other compatible agent if needed.
Tip
When authenticating using Public Key Authentication with an SSH agent containing multiple identities, it makes sense to add IdentitiesOnly yes
in ~/.ssh/config
to limit authentication attempts with this identity only. Otherwise the server may deny the connection because of too many login failures and you will recieve the error Too many authentication failures.
Since the private key is not always available on the filesystem, specifying a public key as IdentifyFile
is also supported. This can be used to authenticate using an SSH agent backed by a hardware token containing the private key for example.
Example ~/.ssh/config
configuration:
Host myhostname
User myusername
IdentityFile ~/.ssh/mykey-rsa.pub
IdentitiesOnly yes
One-Time Passcodes (2FA)
Using a challenge-response authentication with one-time password generators such as DUO, SecurID or Google Authenticator is supported. After the initial login prompt for the username and password, a second login prompt is displayed to enter the one-time passcode.
Google Authenticator
A setup with a two-step verification such as Google Authenticator is supported.
Use the following configuration steps:
Install
libpam-google-authenticator
on the server.Run
google-authenticator
to create a new account and scan the 2D barcode using the Authenticator application on your phone. Refer to Install Google Authenticator.Make it required for SSH logins by running
echo 'auth required pam_google_authenticator.so' >> /etc/pam.d/sshd
.Add
ChallengeResponseAuthentication yes
to/etc/ssh/sshd_config
withecho 'ChallengeResponseAuthentication yes' >> /etc/ssh/sshd_config
.
When logging in, enter the time-based token requested after providing username and password.
Verify Host Keys
Upon connecting to an 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.
Connect via SSH Tunnel Through Bastion Server
Important
Cyberduck version 7.7 or later required
Using the ProxyJump
configuration directive in ~/.ssh/config
you can connect through a tunnel. The bookmark configuration refers to the target host in the internal network. We should find a ProxyJump
directive in the OpenSSH configuration ~/.ssh/config
matching the hostname in the bookmark.
Sample configuration:
Host internal
HostName server.lan
ProxyJump user-external@jump.example.org:2222
User user-internal
You can also work with aliases like
Host bastion-host-nickname
HostName bastion-hostname
User username
Port 2222
Host remote-host-nickname
HostName remote-hostname
ProxyJump bastion-host-nickname
Open in Terminal
Open in Terminal allows you to open an SSH shell for the current working directory with a single click.
Warning
The feature is not supported when running Cyberduck from the Mac App Store because of sandboxing restrictions.
Terminal.app
Use View → Customize Toolbar… to add the Terminal.app toolbar icon to your browser.
Customize SSH Command:
You can change the SSH command using the 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 iTerm2
Version 7.4 and later:
No configuration change is required. Choose iTerm2 → Make iTerm2 Default Term and restart Cyberduck. To revert, set the default application for a file named .command
to Terminal.app in Finder → Info → Open With….
Previous versions:
You can change a hidden configuration option to use a thirdparty terminal application instead of Terminal.app.
Example for iTerm2 Version 2
defaults write ch.sudo.cyberduck terminal.bundle.identifier com.googlecode.iterm2 defaults write ch.sudo.cyberduck terminal.command \"set\ t\ to\ \(make\ new\ terminal\)\\ntell\ t\\nset\ s\ to\ \(launch\ session\ \\\"Default\ Session\\\"\)\\ntell\ s\\nwrite\ text\ \\\"{0}\\\"\\nend\ tell\\nend\ tell\"
Example for iTerm2 Version 3
defaults write ch.sudo.cyberduck terminal.bundle.identifier com.googlecode.iterm2 defaults write ch.sudo.cyberduck terminal.command \"set\ t\ to\ \(create\ window\ with\ default\ profile\)\\ntell\ t\\nset\ s\ to\ \(current\ session\)\\ntell\ s\\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
Disable WSL
There is a hidden configuration option for toggling additional SSH-terminal applications. Currently implemented are ssh.exe
(OpenSSH built-in to Windows 10 since version 1709), bash.exe
(using WSL and invoking ssh
there) as well as PuTTY.
Disabling OpenSSH:
terminal.openssh.enable=false
Disabling WSL:
terminal.windowssubsystemlinux.enable=false
PuTTY.exe
Use View → Customize Toolbar… to add the Open in Putty toolbar icon to your browser.
Location of the PuTTY installation:
By default, the executable putty.exe
must be located in your user home folder. You can change the install location by editing the hidden configuration option terminal.command.ssh
to point to the path of the executable.
Distribution (CDN)
You can enable custom origin Amazon CloudFront (Content Delivery Network) distribution using File → Info → Distribution (CDN).
Create and Expand ZIP or 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.
Note
Send custom commands and Create and expand ZIP/TAR Archives are limited to FTP and SFTP.
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.
Expand
Select one or more files to expand in the current working directory.
Remote Commands
You can send any remote command to a remote SSH server. This is for example useful if you want a HTTP server to reload its configuration or changing the ownership of files using chown on a UNIX
system.
Note
The current working directory is always your use home. Determine using pwd to get the absolute path.

Preferences
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.
Supported Algorithms
Ciphers
aes{128,192,256}-{cbc,ctr}
, blowfish-{cbc,ctr}
, 3des-{cbc,ctr}
, twofish{128,192,256}-{cbc,ctr}
, twofish-cbc
, serpent{128,192,256}-{cbc,ctr}
, idea-{cbc,ctr}
, cast128-{cbc,ctr}
, arcfour
, arcfour{128,256}
, aes{128,256}-gcm@openssh.com
, chacha20-poly1305@openssh.com
Key Exchange
diffie-hellman-group1-sha1
, diffie-hellman-group14-sha1
, diffie-hellman-group14-sha256
, diffie-hellman-group15-sha512
, diffie-hellman-group16-sha512
, diffie-hellman-group17-sha512
, diffie-hellman-group18-sha512 diffie-hellman-group-exchange-sha1
, diffie-hellman-group-exchange-sha256
, ecdh-sha2-nistp256
, ecdh-sha2-nistp384
, ecdh-sha2-nistp521
, curve25519-sha256@libssh.org
Signatures
ssh-rsa
, ssh-dss
, ecdsa-sha2-nistp256
, ecdsa-sha2-nistp384
, ecdsa-sha2-nistp521
, ssh-ed25519
Compression
Compression with zlib
and zlib@openssh.com
is supported.
Private Key Files
pkcs5
, pkcs8
, openssh-key-v1
, ssh-rsa-cert-v01@openssh.com
, ssh-dsa-cert-v01@openssh.com
Incompatibilities
Serv-U MFT
Serv-U MFT does not fully implement SFTPv3. Files cannot be created, renamed, uploaded as a required flag is not implemented and results in error messages.
Known Issues
Too many authentication failures
Running an SSH agent with many added identities can lead to the server error Too many authentication failures when trying to authenticate with all available identities.
Select the identity in the bookmark with SSH Private Key.
Increase the allowed authentication tries on the server by adjusting
MaxAuthTries
.
Possible remedies using configuration in OpenSSH configuration file:
IdentitiesOnly
in client configuration file~/.ssh/config
. Only try to authenticate with explicitly set private key instead of all identities retrieved from SSH agent.Set
PreferredAuthentications
in client configuration file~/.ssh/config
to disable public key authentication for example.
Illegal sftp packet length. Invalid packet: indicated length 1114795883 too large
The error message Invalid packet: indicated length 1114795883 too large
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).
Possibly the server is printing a message similar to Please login as the ubuntu user rather than root user. Please verify the username for your connection.
Enable SSH access on your server. Use the sftp command in a terminal to verify
sftp username@domain_name
. It’ll ask for your password. If you don’t have SSH access, you’ll get “Received message too long”, hence the error message.
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.
Connect Does not Work
Cyberduck refuses to connect if there are malformed entries in your known_hosts
file located under ~/.ssh
. Renaming this file and recreating it usually resolves this. An alternative requires manually editing the known_hosts
file removing all malformed entries. Please refer to sshd(8) for a valid format.
Symbolic Link isn’t Accessible
Symbolic links only work within Mountain Duck if the target of the symbolic link is available within the mounted path.
File Permissions Reset When Saving File (macOS)
Mountain Duck will forward all permission changes done by Finder or the editing application to the SFTP server. There is a hidden preference to disable the writing of permissions. Enter the following command in a Terminal.app window
defaults write io.mountainduck fs.setattr.chmod false
to disable. Make sure to quit Mountain Duck before making the change and then re-open the application.
File Owner Reset When Saving File (macOS)
Some editors save files using an Atomic Save feature that writes changes to a file to a temporary file later replacing the edited file by renaming the temporary file to the name of the edited file. This works well on local filesystems, where there is support to retain the owner of the file that is different from the editing user using a special function call. This does not work for volumes mounted with Mountain Duck and the file owner will be reset to the default owner for new files created on the server by the logged-in user. As a workaround, try to find a setting for the editor to disable the Atomic Save feature.
See also
Free Space Calculation is Incorrect
The available space for a volume mounted over SFTP is determined using quota features of the SSH protocol. Technically using the space-available extension of the SFTP protocol or the statvfs@openssh.com
extension from OpenSSH. If the connected device returns an invalid value (e.g. from the disk the server is running instead of the data disk) you will get an incorrect calculation for the free space.
You can work around the issue using one of the following options:
Set a default path you want to connect to within the bookmark Path option.
Disable the feature within Mountain Duck by setting the hidden property
fs.quota.enable=false
in %AppData%\Cyberduck\default.properties on Windows or in ~/Library/Group Containers/G69SCX94XU.duck/Library/Application Support/duck/deafult.properties on macOS. If the file doesn’t exist create it within the application support folder.