session_url » Revisions »
Differences
This shows you the differences between the selected revisions of the page.
| session_url 2014-07-13 | 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. |
| - | You can also paste session URL on [[ui_login|Login dialog]] or main window. (&beta_feature) | + | 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]]''. |
| - | ===== Syntax ===== | + | To ease assembling the %%URL%%, you can have WinSCP [[ui_generateurl|generate it for you]]. |
| - | ··sftp|ftp|ftps|scp :// [ <username> [ : <password> ] [ ; <fingerprint> ] @ ] <host> [ : <port> ] / | + | ===== [[syntax]] Syntax ===== |
| - | ===== Elements ===== | + | <code> |
| + | <protocol> :// [ <username> [ : <password> ] [ ; <advanced> ] @ ] <host> [ : <port> ] / | ||
| + | </code> | ||
| - | 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]''). | + | ===== [[elements]] Elements ===== |
| - | 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. | + | 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]''). |
| - | Most URL's will include also ''username''. | + | 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. |
| - | 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''). | + | Most %%URL%%'s will include also ''username''. |
| - | ===== [[hostkey]] SSH Host Key Fingerprint ===== | + | 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''). |
| - | The SFTP/SCP URL can optionally contain expected [[ssh_verifying_the_host_key|SSH host key fingerprint]] with syntax ''fingerprint=<fingerprint>''. | + | ===== [[advanced]] Advanced Settings ===== |
| - | 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]]. | + | A session %%URL%% can optionally set any advanced session settings using a syntax based on [[rawsettings|raw site 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. | + | 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 "connection string", such as when passing the current setting settings to a WinSCP [[extension]]. |
| - | 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: | + | A syntax to serialize raw site settings is '';x-name1=value1;x-name2=value2'' (inserted after username and password). |
| - | - Drop bit count part (the number after ''ssh-rsa'' or ''ssh-dsa'', typically ''2048'' or ''1024''); | + | For example to use an HTTP proxy server ''proxy'', use the following %%URL%%: \\ ''%%sftp://username:password;x-proxymethod=3;x-proxyhost=proxy@example.com/%%'' |
| - | ··- 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 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]]. |
| - | ===== Special Characters ===== | + | 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 40: | Line 57: | ||
| * space: ''%20'' or ''+'' | * space: ''%20'' or ''+'' | ||
| + | * ''#'': ''%23'' (number sign/hash) | ||
| * ''%'': ''%25'' (percent sign) | * ''%'': ''%25'' (percent sign) | ||
| * ''+'': ''%2B'' (plus sign) | * ''+'': ''%2B'' (plus sign) | ||
| Line 47: | Line 65: | ||
| * '';'': ''%3B'' (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. | ||
| - | ===== Generating URL ===== | ||
| - | You can have WinSCP [[ui_generateurl|generate session URL]]. &beta_feature | ||