session_url » Revisions »

Differences

This shows you the differences between the selected revisions of the page.

session_url 2014-05-04 session_url 2024-10-31 (current)
Line 1: Line 1:
====== Session URL ====== ====== Session URL ======
-On [[commandline|command-line]] and in parameter of scripting command ''[[scriptcommand_open|open]]'', you can, in addition to using [[session_configuration#site|site]] name, specify an ad-hoc session using URL.+On [[commandline|command-line]] and in parameter of scripting command ''[[scriptcommand_open|open]]'', you can specify basic session settings using session URL.
-===== Syntax =====+In [[library|WinSCP .NET assembly]], you can use session %%URL%% too as an alternative way to provide session options. Use method ''[[library_sessionoptions_parseurl|SessionOptions.ParseUrl]]''.
-  sftp|ftp|ftps|scp :// [ &lt;username&gt; [ : <password> ] [ ; &lt;fingerprint>; ] @ ] &lt;host> [ : <port> ] /+To ease assembling the %%URL%%, you can have WinSCP [[ui_generateurl|generate it for you]].
-===== Elements =====+===== [[syntax]] Syntax =====
-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]'').+&lt;code&gt; 
 +&lt;protocol&gt; :// [ &lt;username&gt; [ : &lt;password&gt; ] [ ; <advanced> ] @ ] &lt;host&gt; [ : &lt;port&gt; ] / 
 +&lt;/code&gt;
-You should also always explicitly specify a protocol (''[[sftp]]'', ''[[ftp]]'' or ''[[scp]]'', the ''[[ftps]]'' protocol is FTP over TLS/SSL). ((Protocol is ''sftp'' by default, but the default can be changed.)) For all protocols [[integration_url#winscp|WinSCP-specific alternative]] is supported, with ''winscp-'' prefix.+===== [[elements]] Elements =====
-Most URL's will include also ''username''.+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]'').
-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'').+You should also always explicitly specify a protocol (''[[sftp]]'', ''[[ftp]]'', ''[[scp]]'', ''[[s3]]'', for [[ftps|FTP over implicit TLS/SSL]] use ''ftps'', for [[ftps|FTP over explicit TLS/SSL]] use ''ftpes'', for [[WebDAV]] use ''http'', for WebDAV over TLS/SSL use ''https''). ((Protocol is ''sftp'' by default, but the default can be changed.)) For all protocols [[integration_url#winscp|WinSCP-specific alternative]] is supported, with ''winscp-'' prefix. URLs with ''%%http[s]%%'' protocol, but with known S3 API hostnames,((''s3.amazonaws.com'', ''digitaloceanspaces.com'', ''storage.googleapis.com'', ''r2.cloudflarestorage.com'')) are recognized as S3, not as WebDAV.
-===== [[hostkey]] SSH Host Key Fingerprint =====+Most %%URL%%'s will include also ''username''.
-The SFTP/SCP URL can optionally contain expected [[ssh#verifying_the_host_key|SSH host key fingerprint]] with syntax ''fingerprint=&lt;fingerprint&gt;''.+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 ''ftpes'', 990 for implicit ''ftps'', 80 for ''http'' and 443 for ''https'' and ''s3'').
-Providing the fingerprint in the session URL is mainly useful, if you need to provide all session settings using URL only, such as using [[integration_url|a hyperlink on a web page]].+===== [[advanced]] Advanced Settings =====
-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 ''[[scriptcommand_open|open]]'' command in scripting.+A session %%URL%% can optionally set any advanced session settings using a syntax based on [[rawsettings|raw site settings]].
-Format of the fingerprint for URL((Fingerprint format for URL is based by [[http://tools.ietf.org/html/draft-ietf-secsh-scp-sftp-ssh-uri|draft-ietf-secsh-scp-sftp-ssh-uri]].)) somewhat differs from format used in other WinSCP features (''-hostkey'' switch of ''[[scriptcommand_open|open]]'' command in scripting for instance). To convert WinSCP fingerprint format to URL format:+Providing advanced settings in the session %%URL%% is mainly useful, if you need to provide all session settings using %%URL%% only, such as using [[integration_url|a hyperlink on a web page]]; or when you want to serialize all session settings into a single &quot;connection string&quot;, such as when passing the current setting settings to a WinSCP [[extension]].
-  - Drop bit count part (the number after ''ssh-rsa'' or ''ssh-dsa'', typically ''2048'' or ''1024''); +A syntax to serialize raw site settings is '';x-name1=value1;x-name2=value2'' (inserted after username and password).
-  - 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''.+For example to use an HTTP proxy server ''proxy'', use the following %%URL%%: \\ ''%%sftp://username:password;x-proxymethod=3;x-proxyhost=proxy@example.com/%%''
-===== Special Characters =====+To have WinSCP generate a session %%URL%% with the advanced settings, check //Advanced settings// on [[ui_generateurl|Generate session URL/code]] dialog. To serialize all session settings for a WinSCP extension, use ''!E'' [[custom_command#patterns|pattern]]. 
 + 
 +When [[integration_url|using the URL in webbrowser]], note that this syntax is not compatible with Chrome M130 and newer (and Edge based on it), as Chrome re-encodes the ==semicolons==. Workaround is to drop the ''%%//%%'' separator after the protocol from the URL. Such format is acceptable for WinSCP and prevents Chrome from reinterpreting the URL. 
 + 
 +===== [[hostkey]] SSH Host Key Fingerprint ===== 
 + 
 +There's a special syntax to include an expected [[ssh_verifying_the_host_key|SSH host key fingerprint]] in SFTP/SCP %%URL%% among advanced site settings: ''fingerprint=<fingerprint>''. 
 + 
 +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 ''[[scriptcommand_open#hostkey|-hostkey]]'' switch of ''[[scriptcommand_open|open]]'' command in scripting. 
 + 
 +Format of the fingerprint for %%URL%%((Fingerprint format for %%URL%% is based on [[https://datatracker.ietf.org/doc/html/draft-ietf-secsh-scp-sftp-ssh-uri-04|draft-ietf-secsh-scp-sftp-ssh-uri]].)) somewhat differs from format used in other WinSCP features (''[[scriptcommand_open#hostkey|-hostkey]]'' switch of ''[[scriptcommand_open|open]]'' command in scripting for instance). To convert WinSCP fingerprint format to %%URL%% format: 
 + 
 +  - Drop bit count part (the number after ''ssh-rsa'', ''ssh-dss'', etc., typically ''2048'' or ''1024''); 
 +  - Replace the remaining space with a dash sign (''-''). 
 +  - Pluses (''+'') and slashes (''/'') in SHA-256 hash need to be [[#special|encoded]] or replaced with dashes (''-'') and underscores (''_'') respectively.((In case you are still using MD5 fingerprints, replace all colons ('':'') with a dash sign (''-'') too. Though you should switch to SHA-256 fingerprints.)) 
 + 
 +For example WinSCP fingerprint ''ssh-rsa 2048 2EP3avJqmpRtSRaUIqwrzavm15vssrhHxJWh9mBaz8M'' converts to ''ssh-rsa-2EP3avJqmpRtSRaUIqwrzavm15vssrhHxJWh9mBaz8M''. 
 + 
 +===== [[special]] Special Characters =====
Special characters (like ''@'' in username, see example below) have to be encoded using ''%XX'' syntax, where ''XX'' is hexadecimal UTF-8 code.((For multi-byte codes, use ''%'' before every byte, for instance to represent pound-sign ''£'' use ''%C2%A3''.)) Special characters (like ''@'' in username, see example below) have to be encoded using ''%XX'' syntax, where ''XX'' is hexadecimal UTF-8 code.((For multi-byte codes, use ''%'' before every byte, for instance to represent pound-sign ''£'' use ''%C2%A3''.))
Line 38: Line 57:
  * space: ''%20'' or ''+''   * space: ''%20'' or ''+''
 +  * ''#'': ''%23'' (number sign/hash)
  * ''%'': ''%25'' (percent sign)   * ''%'': ''%25'' (percent sign)
  * ''+'': ''%2B'' (plus sign)   * ''+'': ''%2B'' (plus sign)
  * ''/'': ''%2F'' (slash)   * ''/'': ''%2F'' (slash)
  * ''@'': ''%40'' (at sign)   * ''@'': ''%40'' (at sign)
-  * '':'': ''%58'' (colon) +  * '':'': ''%3A'' (colon) 
-  * '';'': ''%59'' (semicolon)+  * '';'': ''%3B'' (semicolon)
 +Note that when specifying session %%URL%% on [[commandline|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.
 +
 +Further, in Windows batch files, ''%'' (percent sign) needs to be doubled to be used correctly, even when the sign is itself used to encode other special characters. For example, to use ''@'' in a username, specify ''<nowiki>%%40</nowiki>''. Other programming and scripting languages have other special characters that need to be escaped using a construct of the respective language (for example ''$'' in PowerShell has to be escaped as ''`$'').
 +
 +You can have WinSCP [[ui_generateurl|generate correct URL]] for all kinds of uses (command-line, script or batch file).
 +
 +To avoid having to URL-encode the credentials, particularly when sourcing them from a variable, you can use ''-username'' and ''-password'' switches of the [[scriptcommand_open#username|''open'' command]] or [[commandline#username|WinSCP command-line]].
===== Examples ===== ===== Examples =====
 +
  sftp://martin:mypassword@example.com/   sftp://martin:mypassword@example.com/
  sftp://root@example.com:2222/   sftp://root@example.com:2222/
 +  sftp://martin%40example.com:4pRte!ai%253@example.com/
  ftp://127.0.0.1:2121/   ftp://127.0.0.1:2121/
  ftp://[2001:db8:85a3:8d3:1319:8a2e:370:7348]: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/+  sftp://martin;fingerprint=ssh-rsa-2EP3avJqmpRtSRaUIqwrzavm15vssrhHxJWh9mBaz8M=@example.com/ 
 +··http://martin@example.com/dav/ 
 + 
 + 
 +===== [[file]] Directory or File URL ===== 
 + 
 +A [[commandline#session|URL specified on command-line]] can include an initial remote path (the path has to end with a slash): \\ 
 +''%%sftp://username@example.com/remote/path/%%'' 
 + 
 +You can also include a file path into the URL: \\ 
 +''sftp://username@example.com/remote/path/file.txt'' 
 + 
 +By default, it will initiate the file  [[task_download#url|download]]. When combined with [[commandline#operations|''/browse'' switch]], the file will instead be selected in a [[ui_file_panel|file panel]]. 
 + 
 +===== [[other]] Other Uses ===== 
 + 
 +You can also [[ui_login#pasting|paste the session URL on Login dialog]] or [[clipboard#url|main window]] or even Windows File Explorer or web browser (if WinSCP is [[integration_url|registered]] to handle file transfer protocol %%URL%% addresses). You can use the session URL as a way to [[config#transfer|transfer site settings]]. 
 + 
 +You can use [[custom_command|custom command]] patterns ''!E'' or ''!S'' to pass a session %%URL%% to other processes.

Last modified: by Petr

Documentation

Support

Associations

Follow Us