session_url » Revisions »
Differences
This shows you the differences between the selected revisions of the page.
| session_url 2011-05-23 | session_url 2024-10-31 (current) | ||
| Line 1: | Line 1: | ||
| ====== Session URL ====== | ====== Session URL ====== | ||
| - | On [[commandline|command-line]] and in parameters of scripting command ''[[script_commands#open|open]]'', you can, in addition to using stored-session 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. |
| - | The syntax is: | + | 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|scp:// ][ <user> [ :password ] @ ] <host> [ :<port> ] | + | |
| - | The ''host'' can either be a host name (such as ''example.com'') or an IP address (such as ''127.0.0.1''). | + | To ease assembling the %%URL%%, you can have WinSCP [[ui_generateurl|generate it for you]]. |
| - | Special characters (like ''@'' in username) can be encoded using ''%XX'' syntax, where ''XX'' is hexadecimal ASCII code. | + | ===== [[syntax]] Syntax ===== |
| - | Some common examples: | + | <code> |
| + | <protocol> :// [ <username> [ : <password> ] [ ; <advanced> ] @ ] <host> [ : <port> ] / | ||
| + | </code> | ||
| + | |||
| + | ===== [[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]''). | ||
| + | |||
| + | 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''. | ||
| + | |||
| + | 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''). | ||
| + | |||
| + | ===== [[advanced]] Advanced Settings ===== | ||
| + | |||
| + | A session %%URL%% can optionally set any advanced session settings using a syntax based on [[rawsettings|raw site settings]]. | ||
| + | |||
| + | 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]]. | ||
| + | |||
| + | A syntax to serialize raw site settings is '';x-name1=value1;x-name2=value2'' (inserted after username and password). | ||
| + | |||
| + | For example to use an HTTP proxy server ''proxy'', use the following %%URL%%: \\ ''%%sftp://username:password;x-proxymethod=3;x-proxyhost=proxy@example.com/%%'' | ||
| + | |||
| + | 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''.)) | ||
| + | |||
| + | Common special characters are: | ||
| * 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 ===== | ||
| + | |||
| + | |||
| + | 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. | ||