[[TOC()]]

= [wiki:help/en Cyberduck Help] / [wiki:help/en/howto Howto] / FTP & FTP-TLS=

== FTP Connect Mode ==

Choose between an [http://en.wikipedia.org/wiki/File_Transfer_Protocol#Connection_methods Active (PORT) or Passive (PASV) connect mode] per [wiki:help/en/howto/bookmarks bookmark] or when opening a [wiki:help/en/howto/connection#Toolbarbutton new connection]. The default setting can be set in the ''System Preferences'' in ''Network'' → ''Advanced...'' → ''Proxies'' → ''Use Passive FTP Mode (PASV)''.

== Character Encoding ==

The character encoding used to parse directory listings can be set as a per bookmark setting. If special characters such as Umlaute aren't displayed correctly in the browser, try to change the character encoding used. To change the character encoding for the current browser, use ''View → Text Encoding''. The setting is also available per [wiki:help/en/howto/bookmarks bookmark]. Try {{{UTF-8}}} (the default), {{{ISO-8859-1}}} and {{{Windows-1252}}}.

== TLS Connections (FTPS) ==

[http://en.wikipedia.org/wiki/FTPS#Explicit Explicit] TLS is supported.

=== Switch to secure connection ===

If you attempt to connect to a server using FTP without TLS transport security but the server advertises support for TLS (as a response to `FEAT`), a prompt is displayed to secure the connection.

[[Image(Unsecured connection.png)]]

You can always switch back to FTP without TLS transport security by changing the protocol selection in the bookmark to ''FTP (File Transfer Protocol)''.

== Server compatibility ==

=== ProFTPd ===
 * You need to have the option set `TLSOptions NoSessionReuseRequired` for FTP-TLS connections. Issue #5087. If configuring the server is not an option, users should switch back to plain FTP connections. Choose ''FTP (File Transfer Protocol)'' in the bookmark protocol setting. Most users hit by this compatibility issue have been asked to secure the connection because support for TLS was detected upon negogiating the connection.

Example configuration:

{{{
TLSOptions

      The NoSessionReuseRequired option has been added.  As of
      ProFTPD 1.3.3rc1, mod_tls only accepts SSL/TLS data connections
      that reuse the SSL session of the control connection, as a security
      measure.  Unfortunately, there are some clients (e.g. curl) which
      do not reuse SSL sessions.

      To relax the requirement that the SSL session from the control
      connection be reused for data connections, use the following in the
      proftpd.conf:

        <IfModule mod_tls.c>
          ...
          TLSOptions NoSessionReuseRequired
          ...
        </IfModule>
}}}

 * The option `TLSOptions AllowClientRenegotiations` must be set for FTP-TLS connections. Issue #3012.
 * The option `TLSProtocol SSLv23` must be set for FTP-TLS connections. Issue #5061.

== Problems ==

=== Error opening data socket ===

For data transfers and possibly file listings (depending on the features supported by the server), a second data connection must be opened using `PASV` or `PORT` commands which is referred to as a passive or active data connection.

Depending on the firewall and router configuration in your network there may be errors reported:
 * Failure opening active data socket reports `I won't open a connection to xxx.xxx.xx.xx (only to xxx.xx.xxx.x)`

=== It is not possible to change permissions ===
The error message {{{FTP Error: SITE not understood}}} or similar is displayed. The server does not support this feature (which is an optional extension to the FTP protocol) and can not be used.

=== Leading whitespace in filenames ===
if you have issues with filenames parsed with a leading whitespace as described in #2895, disable whitespace awareness in the directory listing parser using the [wiki:help/en/howto/preferences#Hiddenconfigurationoptions hidden configuration option]

{{{
defaults write ch.sudo.cyberduck ftp.parser.whitespaceAware false
}}}

=== Listing directories fails or shows no content  ===
Directory listings are requested using {{{STAT}}}, {{{LIST -a}}} and {{{LIST}}} commands in that order. If a failure is detected (because the server may not support the command), the next option is tried. Because this can be fuzzy logic, it may still be that Cyberduck does not correctly fall back to a supported list command. You may then try to force the use of a given command. 

To disable {{{STAT}}} for directory listings, open a Terminal.app window and enter

{{{
defaults write ch.sudo.cyberduck ftp.sendStatListCommand false
}}}

To disable {{{LIST -a}}} for directory listings, open a Terminal.app window and enter

{{{
defaults write ch.sudo.cyberduck ftp.sendExtendedListCommand false
}}} 

To disable {{{MLSD}}} for directory listings, open a Terminal.app window and enter

{{{
defaults write ch.sudo.cyberduck ftp.sendMlsdListCommand false
}}} 

Restart Cyberduck.

== References ==

 * [http://en.wikipedia.org/wiki/FTPS FTPS Wikipedia Article]