session_url » Revisions »
Differences
This shows you the differences between the selected revisions of the page.
| session_url 2019-05-28 | 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 specify basis session settings using session URL. | + | On [[commandline|command-line]] and in parameter of scripting command ''[[scriptcommand_open|open]]'', you can specify basic session settings using session URL. |
| 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]]''. | 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]]''. | ||
| Line 6: | Line 6: | ||
| To ease assembling the %%URL%%, you can have WinSCP [[ui_generateurl|generate it for you]]. | To ease assembling the %%URL%%, you can have WinSCP [[ui_generateurl|generate it for you]]. | ||
| - | ===== Syntax ===== | + | ===== [[syntax]] Syntax ===== |
| <code> | <code> | ||
| Line 12: | Line 12: | ||
| </code> | </code> | ||
| - | ===== Elements ===== | + | ===== [[elements]] 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]''). | + | 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]''). |
| - | 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. | + | 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. |
| Most %%URL%%'s will include also ''username''. | Most %%URL%%'s will include also ''username''. | ||
| Line 33: | Line 33: | ||
| 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]]. | 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 ===== | ===== [[hostkey]] SSH Host Key Fingerprint ===== | ||
| Line 40: | Line 42: | ||
| 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. | 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://tools.ietf.org/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: | + | 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'' or ''ssh-dss'', typically ''2048'' or ''1024''); | + | - Drop bit count part (the number after ''ssh-rsa'', ''ssh-dss'', etc., typically ''2048'' or ''1024''); |
| - | - Replace the remaining space with a dash sign (''-'').((In case you are still using MD5 fingerprints, replace all colons ('':'') with a dash sign (''-'') too. Though you should switch to SHA-256 fingerprints.)) | + | - 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=''. | + | For example WinSCP fingerprint ''ssh-rsa 2048 2EP3avJqmpRtSRaUIqwrzavm15vssrhHxJWh9mBaz8M'' converts to ''ssh-rsa-2EP3avJqmpRtSRaUIqwrzavm15vssrhHxJWh9mBaz8M''. |
| ===== [[special]] Special Characters ===== | ===== [[special]] Special Characters ===== | ||
| Line 64: | Line 67: | ||
| 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. | 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>''. | + | 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). | 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 ===== | ||
| Line 73: | Line 78: | ||
| 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/ | ||
| Line 79: | Line 85: | ||
| - | ===== Other Uses ===== | + | ===== [[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 paste session %%URL%% on [[ui_login|Login dialog]] or 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 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]] pattern ''!S'' to pass a session %%URL%% to other processes. | + | You can use [[custom_command|custom command]] patterns ''!E'' or ''!S'' to pass a session %%URL%% to other processes. |