session_url » Revisions »

Differences

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

session_url 2013-10-24 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]] (stored session) &beta 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> ] [ ; &lt;options> ]+To ease assembling the %%URL%%, you can have WinSCP [[ui_generateurl|generate it for you]].
-===== Elements =====+===== [[syntax]] Syntax =====
-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). ((Protocol is ''sftp'' by default, but the default can be changed.)) 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'').+&lt;code&gt; 
 +&lt;protocol&gt; :// [ &lt;username&gt; [ : &lt;password&gt; ] [ ; &lt;advanced&gt; ] @ ] &lt;host&gt; [ : &lt;port&gt; ] / 
 +&lt;/code&gt;
-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]'').+===== [[elements]] Elements =====
-===== [[hostkey]] SSH Host Key Fingerprint =====+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 SFTP/SCP URL can optionally contain expected [[ssh#verifying_the_host_key|SSH host key fingerprint]] with syntax ''fingerprint=&lt;fingerprint&gt;''.+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.
-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.+Most %%URL%%'s will include also ''username''.
-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.+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'').
-Format of the fingerprint for URL 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:+===== [[advanced]] Advanced Settings =====
-  - Drop bit count part (the number after ''ssh-rsa'' or ''ssh-dsa'', typically ''1024'' or ''2048''); +A session %%URL%% can optionally set any advanced session settings using a syntax based on [[rawsettings|raw site settings]].·
-  - 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''.+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]].
-===== Saving URL to Site =====+A syntax to serialize raw site settings is '';x-name1=value1;x-name2=value2'' (inserted after username and password).
-To make WinSCP [[session_configuration#site|save session settings]] provided by URL to a site instead of opening a session, add URL option ''save''.+For example to use an HTTP proxy server ''proxy'', use the following %%URL%%: \\ ''%%sftp://username:password;x-proxymethod=3;x-proxyhost=proxy@example.com/%%''
-Options are separated by a semicolon ('';'') from the actual URL.+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]].
-The ''save'' option can be used, when using session URL on [[commandline|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 [[session_url#hostkey|SSH host key fingerprint in the URL]].+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.
-===== Special Characters =====+===== [[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 42: 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)
 +  * '':'': ''%3A'' (colon)
 +  * '';'': ''%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 
-  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 
 +  sftp://martin:mypassword@example.com/
 +  sftp://root@example.com:2222/
 +  sftp://martin%40example.com:4pRte!ai%253@example.com/
 +  ftp://127.0.0.1:2121/
 +  ftp://[2001:db8:85a3:8d3:1319:8a2e:370:7348]:2121/
 +  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 martin

Documentation

Support

Associations

Follow Us