Differences
This shows you the differences between the selected revisions of the page.
| scriptcommand_open 2014-10-29 | scriptcommand_open 2024-03-26 (current) | ||
| Line 1: | Line 1: | ||
| - | ====== open ====== | + | ====== open command ====== |
| Establishes new connection. | Establishes new connection. | ||
| - | ===== Syntax ===== | + | ===== [[syntax]] Syntax ===== |
| open <session_url> | open <session_url> | ||
| open <site> | open <site> | ||
| - | ===== Remarks ===== | + | ===== [[remarks]] Remarks ===== |
| - | Establishes connection to given host. Use [[session_url|session URL]] or name of the [[session_configuration#site|site]]. To open site, stored in folder, use path syntax “folder/site”. Using session URL is preferred as it makes your script independent on the persisted configuration. With session %%URL%%, you typically specify a protocol, host name, username and password, optionally also a port number and SSH host key fingerprint. | + | Establishes connection to given host. Use [[session_url|session URL]] or name of the [[session_configuration#site|site]]. To open site, stored in folder, use path syntax “folder/site”. Using session URL is preferred as it makes your script [[scripting#configuration|independent on the persisted configuration]]. With session %%URL%%, you typically specify a protocol, host name, username and password, optionally also a port number and SSH host key fingerprint. |
| - | Note that to allow the session be opened automatically without interaction, you need to make sure you provide all details, including all credentials. Generally, you need to provide a password in your [[session_url|session URL]] or [[session_configuration#site|site]]. With [[ssh|SSH]] you may alternatively use private key. With SSH and [[ftps|FTPS]] you need to [[scripting#hostkey|verify the host or certificate]]. | + | You can use //[[ui_generateurl|Generate Session URL/Code]]// command to generate the ''open'' command for a given stored site. |
| + | |||
| + | Note that to allow the session be opened automatically without interaction, you need to make sure you provide all details, including all credentials. Generally, you need to provide a password in your [[session_url|session URL]] or [[session_configuration#site|site]]. With [[ssh|SSH]] you may alternatively use private key. With SSH, [[ftps|FTPS]] or WebDAVS you need to [[scripting#hostkey|verify the host or certificate]]. | ||
| Switches: | Switches: | ||
| ^ Switch ^ Description ^ | ^ Switch ^ Description ^ | ||
| - | | ''-privatekey=<key>'' | [[public_key#private|SSH private key]] path. \\ [[SFTP]] and [[SCP]] protocols only. | | + | | ''-==privatekey===%%<file>%%'' | [[public_key#private|SSH private key]] path. \\ Alternatively a hex dump of SSH private key file contents prefixed with ''@''. \\ [[SFTP]] and [[SCP]] protocols only. | |
| - | | ''-passphrase=<phrase>'' | Passphrase for encrypted private keys. &beta_feature \\ [[SFTP]] and [[SCP]] protocols only. | | + | | ''-==hostkey===%%"<fingerprint>"%%'' | Specifies fingerprint of expected [[ssh_verifying_the_host_key|SSH host key]] (or several alternative fingerprints separated by semicolon). It makes WinSCP automatically [[scripting#hostkey|accept host key]] with the fingerprint. Use SHA-256 fingerprint of the host key. As the host key fingerprint contains spaces you need to surround it by quotes. //Learn how to [[faq_hostkey|obtain host key fingerprint]]//. \\ Use the ''acceptnew'' keyword instead of the ''fingerprint'' to make WinSCP automatically accept host key of new hosts. When this is combined with [[config#no|no configuration mode]], it forces use of registry for the host key cache. \\ In exceptional situations, when security is not required, you can use value ''*'' to accept any host key. In this case, script output and log file will include warning about insecure connection. \\ [[SFTP]] and [[SCP]] protocols only. | |
| - | | ''-timeout=<sec>'' | Server response timeout | | + | | ''-==clientcert===%%<file>%%'' | [[tls#client_certificate|TLS/SSL client certificate]] path. \\ [[ftps|FTPS]] and [[webdav|WebDAVS]] protocols only. | |
| - | | ''%%-hostkey="<fingerprint>"%%'' | Specifies fingerprint of expected [[ssh_verifying_the_host_key|SSH host key]] (or several alternative fingerprints separated by semicolon). It makes WinSCP automatically [[scripting#hostkey|accept host key]] with the fingerprint. As the host key fingerprint contains spaces you need to surround it by quotes. //Learn how to [[faq_script_hostkey|obtain host key fingerprint]]//. \\ In exceptional situations, when security is not required, you can use value ''*'' to accept any host key. In this case, script output and log file will include warning about insecure connection. \\ [[SFTP]] and [[SCP]] protocols only. | | + | | ''-==certificate===%%"<fingerprint>"%%'' | Specifies fingerprint of expected [[tls#certificate|TLS/SSL certificate]] (or several fingerprints separated by semicolon). It makes WinSCP automatically [[scripting#hostkey|accept certificate]] with the fingerprint. Use SHA-256 fingerprint of the certificate. \\ In exceptional situations, when security is not required, you can use value ''*'' to accept any certificate. In this case, script output and log file will include warning about insecure connection. \\ [[ftps|FTPS]] and [[webdav|WebDAVS]] protocols only. | |
| - | | ''%%-certificate="<fingerprint>"%%'' | Specifies fingerprint of expected [[tls#certificate|TLS/SSL certificate]] (or several fingerprints separated by semicolon). It makes WinSCP automatically [[scripting#hostkey|accept certificate]] with the fingerprint. \\ In exceptional situations, when security is not required, you can use value ''*'' to accept any certificate. In this case, script output and log file will include warning about insecure connection. \\ [[ftps|FTPS]] and [[webdav|WebDAVS]] protocol only. | | + | | ''-==passphrase===<phrase>'' | Passphrase for encrypted private keys and client certificates. \\ SFTP, SCP, FTPS and WebDAVS protocols only. \\ The passphrase [[#passwordsfromfiles|can be read from a file]]. | |
| - | | ''-passive=on%%|%%off'' | Enables [[ui_login_connection#connection|passive]] (''=on'') or active (''=off'') transfer mode ([[FTP]] protocol only). | | + | | ''-==passive===on%%|%%off'' | Selects [[ui_login_connection#connection|passive]] (''on'') or active (''off'') transfer mode ([[FTP]] protocol only). | |
| - | | ''-implicit'' | Implicit TLS/SSL ([[ftps|FTPS protocol]] only) | | + | | ''-==implicit=='' | Implicit TLS/SSL ([[ftps|FTPS protocol]] only). | |
| - | | ''-explicittls'' ············| Explicit TLS ([[ftps|FTPS protocol]] only) | | + | | ''-==explicit=='' ···············| Explicit %%TLS/SSL%% ([[ftps|FTPS protocol]] only). | |
| - | | ''-explicitssl'' ············| Explicit SSL ([[ftps|FTPS protocol]] only) | | + | | ''-==timeout===<sec>'' ··········| Server response timeout. | |
| - | | ''-rawsettings setting1=value1 setting2=value2 ...'' | Allows configuring any site settings using [[rawsettings|raw format]] as in an INI file. E.g. to enable SSH compression and agent forwarding use ''-rawsettings Compression=1 AgentFwd=1''. The switch must come after session URL. | | + | | ''-==username===%%<user>%%'' | An alternative way to provide a username. The username is normally part of the [[session_url|session URL]]. Using this switch has the advantage of not needing to [[session_url#special|URL-encode special characters]]. | |
| + | | ''-==password===%%<pass>%%'' | An alternative way to provide a password. The password is normally part of the session URL. Using this switch has the advantage of not needing to URL-encode special characters. \\ The password [[#passwordsfromfiles|can be read from a file]]. | | ||
| + | | ''-==passwordsfromfiles=='' | Interpret values of [[#password|''-password'']], [[#passphrase|''-passphrase'']] and in general all passwords from all sources as paths to files, where the actual passwords are read from. The files must use UTF-8 or UTF-16 encoding.((With UTF-8 encoding use of BOM is optional. With UTF-16 the BOM is mandatory. Only the first line of the file is considered. Use of more lines is reserved for the future.)) | | ||
| + | | ''-==rawsettings== setting1=value1 setting2=value2 ...'' | Allows configuring any site settings using [[rawsettings|raw format]] as in an INI file (with optional use of [[rawsettings#keywords|keywords]]). E.g. to enable SSH compression and agent forwarding use ''-rawsettings Compression=on AgentFwd=on''. The switch must come after session URL. | | ||
| + | | ''-==filezilla=='' | Load ''site'' from FileZilla site manager.((WinSCP looks for sites in ''C:\Users\username\AppData\Roaming\FileZilla\sitemanager.xml''. &winpath)) \\ Additionally it prints a full syntax to use to open an identical session without relying on an external FileZilla configuration. | | ||
| XML log element: ''[[logging_xml|session]]'' | XML log element: ''[[logging_xml|session]]'' | ||
| - | ===== Examples ===== | + | ===== [[examples]] Examples ===== |
| <code winscp> | <code winscp> | ||
| - | open sftp://martin:mypassword@example.com/ -hostkey="ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" | + | open sftp://martin:mypassword@example.com/ -hostkey="ssh-rsa 2048 xxxxxxxxxxx..." |
| </code> | </code> | ||
| <code winscp> | <code winscp> | ||
| Line 36: | Line 42: | ||
| </code> | </code> | ||
| <code winscp> | <code winscp> | ||
| - | open ftps://martin:mypassword@example.com/ -implicit -certificate="xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" | + | open ftps://martin:mypassword@example.com/ -implicit -certificate="xx:xx:xx:xx:xx:xx:xx:xx..." |
| </code> | </code> | ||
| <code winscp> | <code winscp> | ||
| Line 46: | Line 52: | ||
| <code winscp> | <code winscp> | ||
| open sftp://example.com/ | open sftp://example.com/ | ||
| + | </code> | ||
| + | <code winscp> | ||
| + | open ftp://martin:mypassword@example.com/ | ||
| </code> | </code> | ||
| - | ===== Converting to .NET Assembly ===== | + | ===== [[net]] Converting to .NET Assembly ===== |
| When [[library_from_script|converting script to .NET Assembly]], map ''open'' command to ''[[library_session_open|Session.Open]]'' method. The ''Session.Open'' accepts instance of ''[[library_sessionoptions|SessionOptions]]'' class, which needs to be populated according to parameters and switches of ''open'' command. | When [[library_from_script|converting script to .NET Assembly]], map ''open'' command to ''[[library_session_open|Session.Open]]'' method. The ''Session.Open'' accepts instance of ''[[library_sessionoptions|SessionOptions]]'' class, which needs to be populated according to parameters and switches of ''open'' command. | ||
| - | Parameters mapping: [[session_url|Session URL]] in command parameter ''session_url'' needs to be separated to its components, which are to be stored into ''SessionOptions.HostName'' (''host'' component), ''SessionOptions.UserName'' (''username''), ''SessionOptions.Password'' (''password''), ''SessionOptions.PortNumber'' (''port'') and ''SessionOptions.Protocol'' (''sftp|ftp|ftps|http|https|scp:%%//%%''((For ''https:%%//%%'', use ''SessionOptions.Protocol = Protocol.Webdav'' and ''SessionOptions.WebdavSecure = true''.))). | + | Parameters mapping: [[session_url|Session URL]] in command parameter ''session_url'' needs to be separated to its components, which are to be stored into ''[[library_sessionoptions#hostname|SessionOptions.HostName]]'' (''host'' component), ''[[library_sessionoptions#username|SessionOptions.UserName]]'' (''username''), ''[[library_sessionoptions#password|SessionOptions.Password]]'' (''password''), ''[[library_sessionoptions#portnumber|SessionOptions.PortNumber]]'' (''port'') and ''[[library_sessionoptions#protocol|SessionOptions.Protocol]]'' (''sftp|ftp|ftps|ftpes|http|https|s3|scp:%%//%%'').((For ''ftpes:%%//%%'' and ''ftps:%%//%%'', use ''SessionOptions.Protocol = Protocol.Ftp'' and ''SessionOptions.FtpSecure = FtpSecure.Explicit'' (or ''FtpSecure.Implicit''). For ''https:%%//%%'', use ''SessionOptions.Protocol = Protocol.Webdav'' and ''SessionOptions.Secure = true''.)) Alternatively, you can use ''[[library_sessionoptions_parseurl|SessionOptions.ParseUrl]]'' method. |
| There is no direct mapping for opening stored site using ''site'' parameter, because .NET assembly [[library_from_script#default_config|does not share configuration]] with graphical/scripting mode. You need to configure all your site settings directly in your code (using ''[[library_sessionoptions|SessionOptions]]'' class). | There is no direct mapping for opening stored site using ''site'' parameter, because .NET assembly [[library_from_script#default_config|does not share configuration]] with graphical/scripting mode. You need to configure all your site settings directly in your code (using ''[[library_sessionoptions|SessionOptions]]'' class). | ||
| Line 57: | Line 66: | ||
| Switches mapping: | Switches mapping: | ||
| ^ Switch ^ Mapping ^ | ^ Switch ^ Mapping ^ | ||
| - | | ''-privatekey'' | Set ''[[library_sessionoptions|SessionOptions.SshPrivateKeyPath]]''. | | + | | ''-privatekey'' | When the value is an SSH private key path, set ''[[library_sessionoptions#sshprivatekeypath|SessionOptions.SshPrivateKeyPath]]''. \\ When the value is a hex dump of SSH private key file contents, store the contents (not the hex dump) to ''[[library_sessionoptions#sshprivatekey|SessionOptions.SshPrivateKey]]''. | |
| - | | ''-passphrase'' ···| Set ''[[library_sessionoptions|SessionOptions.SshPrivateKeyPassphrase]]''. | | + | | ''-hostkey'' ······| Set ''[[library_sessionoptions#sshhostkeyfingerprint|SessionOptions.SshHostKeyFingerprint]]''. \\ For special values ''*'' and ''acceptnew'', set [[library_sessionoptions#sshhostkeypolicy|''SessionOptions.SshHostKeyPolicy'']] to ''SshHostKeyPolicy.GiveUpSecurityAndAcceptAny'' or ''SshHostKeyPolicy.AcceptNew'', respectively. | |
| - | | ''-timeout'' ······| Set ''[[library_sessionoptions|SessionOptions.Timeout]]''. | | + | | ''-clientcert'' ···| Set ''[[library_sessionoptions#tlsclientcertificatepath|SessionOptions.TlsClientCertificatePath]]''. | |
| - | | ''-hostkey'' ······| Set ''[[library_sessionoptions|SessionOptions.SshHostKeyFingerprint]]''. | | + | | ''-certificate'' ··| Set ''[[library_sessionoptions#tlshostcertificatefingerprint|SessionOptions.TlsHostCertificateFingerprint]]''. | |
| - | | ''-certificate'' ··| Set ''[[library_sessionoptions|SessionOptions.TlsHostCertificateFingerprint]]''. | | + | | ''-passphrase'' ···| Set ''[[library_sessionoptions#privatekeypassphrase|SessionOptions.PrivateKeyPassphrase]]''. | |
| - | | ''-passive'' | Set ''[[library_sessionoptions|SessionOptions.FtpMode]]'' to ''FtpMode.Passive'' for ''on'' or ''FtpMode.Active'' \\ [[library_powershell#enums|Enumeration syntax]] in PowerShell is like ''[WinSCP.FtpMode]::Passive''. | | + | | ''-passive'' | Set ''[[library_sessionoptions#ftpmode|SessionOptions.FtpMode]]'' to ''FtpMode.Passive'' for ''on'' or ''FtpMode.Active'' for ''off''. \\ [[library_powershell#enums|Enumeration syntax]] in PowerShell is like ''[WinSCP.FtpMode]::Passive''. | |
| - | | ''-implicit'' | Set ''[[library_sessionoptions|SessionOptions.FtpSecure]]'' to ''FtpSecure.Implicit'' (''[WinSCP.FtpSecure]::Implicit'' in PowerShell). | | + | | ''-implicit'' | Set ''[[library_sessionoptions#ftpsecure|SessionOptions.FtpSecure]]'' to ''FtpSecure.Implicit'' (''[WinSCP.FtpSecure]::Implicit'' in PowerShell). | |
| - | | ''-explicittls'' ··| Set ''[[library_sessionoptions|SessionOptions.FtpSecure]]'' to ''FtpSecure.ExplicitTls'' (''[WinSCP.FtpSecure]::ExplicitTls''). | | + | | ''-explicit'' ·····| Set ''[[library_sessionoptions#ftpsecure|SessionOptions.FtpSecure]]'' to ''FtpSecure.Explicit'' (''[WinSCP.FtpSecure]::Explicit''). | |
| - | | ''-explicitssl'' ··| Set ''[[library_sessionoptions|SessionOptions.FtpSecure]]'' to ''FtpSecure.ExplicitSsl'' (''[WinSCP.FtpSecure]::ExplicitSsl''). | | + | | ''-timeout'' ······| Set ''[[library_sessionoptions#timeout|SessionOptions.Timeout]]''. | |
| - | | ''-rawsettings'' | Call ''[[library_sessionoptions|SessionOptions.AddRawSettings]]'' for every key/value pair in switch parameters. | | + | | ''-username'' | Set ''[[library_sessionoptions#username|SessionOptions.UserName]]''. | |
| + | | ''-password'' | Set ''[[library_sessionoptions#password|SessionOptions.Password]]''. | | ||
| + | | ''-passwordsfromfiles'' | Read the file in your code and assign a respective property. \\ PowerShell example: ''$sessionOptions.Password = (Get-Content $path)[0]'' | | ||
| + | | ''-rawsettings'' | Call ''[[library_sessionoptions_addrawsettings|SessionOptions.AddRawSettings]]'' for every key/value pair in switch parameters. | | ||
| + | | ''-filezilla'' | Convert the full equivalent syntax suggested, when the ''open'' command is executed. | | ||
| For example, following script snippet: | For example, following script snippet: | ||
| <code winscp> | <code winscp> | ||
| - | open sftp://martin:mypassword@example.com/ -hostkey="ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" | + | open sftp://martin:mypassword@example.com/ -hostkey="ssh-rsa 2048 xxxxxxxxxxx..." |
| </code> | </code> | ||
| Line 77: | Line 90: | ||
| <code powershell> | <code powershell> | ||
| - | $sessionOptions = New-Object WinSCP.SessionOptions | + | $sessionOptions = New-Object WinSCP.SessionOptions -Property @{ |
| - | # sftp:// | + | ····# sftp:// |
| - | $sessionOptions.Protocol = [WinSCP.Protocol]::Sftp | + | ····Protocol = [WinSCP.Protocol]::Sftp |
| - | $sessionOptions.HostName = "example.com" | + | ····HostName = "example.com" |
| - | $sessionOptions.UserName = "martin" | + | ····UserName = "martin" |
| - | $sessionOptions.Password = "mypassword" | + | ····Password = "mypassword" |
| - | # -hostkey | + | ····# -hostkey |
| - | $sessionOptions.SshHostKeyFingerprint = "ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" | + | ····SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..." |
| + | } | ||
| $session = New-Object WinSCP.Session | $session = New-Object WinSCP.Session | ||