Session URL

On command-line and in parameter of scripting command open, you can, in addition to using site name, specify an ad-hoc session using URL.

You can also paste session URL on Login dialog or main window (This feature is available only in the latest beta release.) or even Windows Explorer or web browser (if WinSCP is registered to handle file transfer protocol URL addresses).

Syntax

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

Elements

The only mandatory part is host. 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]).

Advertisements:

You should also always explicitly specify a protocol (sftp, ftp, scp, for FTP over TLS/SSL use ftps, for WebDAV use http, for WebDAV over TLS/SSL use https).1) For all protocols WinSCP-specific alternative is supported, with winscp- prefix. WebDAV protocol is available only in the latest beta release.

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, 990 for implicit ftps, 80 for http and 443 for https).

SSH Host Key Fingerprint

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

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 URL2) 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 2048 or 1024);
  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.

Special Characters

Special characters (like @ in username, see example below) have to be encoded using %XX syntax, where XX is hexadecimal UTF-8 code.3)

Common special characters are:

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

Note that when specifying session URL on command-line, you cannot use characters that have special meaning on Windows command-line, just as with any other command-line argument. Such characters include & (ampersand), | (pipe), < (less-than sign), > (greater-than sign), " (double-quote). To escape these characters, you can wrap whole session URL to double-quotes (") or encode the characters as shown above.

Examples

sftp://martin:mypassword@example.com/
sftp://root@example.com:2222/
ftp://127.0.0.1:2121/
ftp://[2001:db8:85a3:8d3:1319:8a2e:370:7348]:2121/
sftp://martin;fingerprint=ssh-dss-0b-77-8b-68-f4-45-b1-3c-87-ad-5c-be-3b-c5-72-78@example.com/
http://martin@example.com/dav/

Generating

You can have WinSCP generate session URL. This feature is available only in the latest beta release.

Advertisements:
1) Protocol is sftp by default, but the default can be changed.
2) Fingerprint format for URL is based by draft-ietf-secsh-scp-sftp-ssh-uri.
3) For multi-byte codes, use % before every byte, for instance to represent pound-sign £ use %C2%A3.
 
  session_url.txt · Last modified: by prikryl
 

Search Documentation

This page

Donate

About donations

$9   $19   $49   $99

About donations

Recommend

Associations

Site design by Black Gate