Session URL

[ sftp|ftp|ftps|scp :// ][ <username> [ : <password> ] [ ; <fingerprint> ] @ ] <host> [ : <port> ] [ ; <options> ]

The only mandatory part is host. You should also always explicitly specify a protocol (sftp, ftp or scp, the ftps protocol is FTP over TLS/SSL).1 Most URL’s will include also username. The port needs to be specified only, when it differs from the default port for the protocol (22 for sftp/scp, 21 for ftp and 990 for implicit ftps).

The host can either be a host name (such as example.com), an IPv4 address (such as 127.0.0.1) or an IPv6 address surrounded by square brackets (such as [2001:db8:85a3:8d3:1319:8a2e:370:7348]).

The SFTP/SCP URL can optionally contain expected SSH host key fingerprint with syntax fingerprint=<fingerprint>.

This feature is available only in the latest beta release.

Providing the fingerprint in the session URL is mainly useful, if you need to provide all session settings using URL only, such as using a hyperlink on a web page.

For security reasons, fingerprint provided in session URL does not override any fingerprint already cached on the machine. This for instance differs from behavior, when fingerprint is provided using -hostkey switch of open command in scripting.

Format of the fingerprint for URL somewhat differs from format used in other WinSCP features (-hostkey switch of open command in scripting for instance). To convert WinSCP fingerprint format to URL format:

1. Drop bit count part (the number after ssh-rsa or ssh-dsa, typically 1024 or 2048);
2. Replace remaining space and all colons (:) with a dash sign (-).

For example WinSCP fingerprint ssh-rsa 2048 ee:f3:c1:59:4d:b4:e2:c5:da:22:3a:6e:97:a0:28:29 converts to ssh-rsa-ee-f3-c1-59-4d-b4-e2-c5-da-22-3a-6e-97-a0-28-29.

To make WinSCP save session settings provided by URL to a site instead of opening a session, add URL option save.

This feature is available only in the latest beta release.

Options are separated by a semicolon (;) from the actual URL.

The save option can be used, when using session URL on command-line only. But particularly it is useful, when providing session settings using a hyperlink (on a web page). For SFTP/SCP URL this should be combined with including SSH host key fingerprint in the URL.

Special characters (like @ in username, see example below) have to be encoded using %XX syntax, where XX is hexadecimal UTF-8 code.2 In versions prior to the latest beta release ASCII code is used.

Common special characters are:

• space: %20 or +
• %: %25 (percent sign)
• +: %2B (plus sign)
• /: %2F (slash)
• @: %40 (at sign)
• ;: %59 (semicolon)

sftp://martin:mypassword@example.com
martin%40example.com:4pRte!ai%253@example.com
sftp://root@example.com:2222
example.com
ftp://127.0.0.1:2121
ftp://[2001:db8:85a3:8d3:1319:8a2e:370:7348]:2121