Differences
This shows you the differences between the selected revisions of the page.
| scriptcommand_open 2022-06-16 | scriptcommand_open 2024-03-26 (current) | ||
| Line 17: | Line 17: | ||
| Switches: | Switches: | ||
| ^ Switch ^ Description ^ | ^ Switch ^ Description ^ | ||
| - | | ''-==privatekey===%%<file>%%'' | [[public_key#private|SSH private key]] path. \\ Alternatively a hex dump of SSH private key file contents prefixed with ''@''. &recent_feature(5.20.1) \\ [[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. | |
| | ''-==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. | | | ''-==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. | | ||
| | ''-==clientcert===%%<file>%%'' | [[tls#client_certificate|TLS/SSL client certificate]] path. \\ [[ftps|FTPS]] and [[webdav|WebDAVS]] protocols only. | | | ''-==clientcert===%%<file>%%'' | [[tls#client_certificate|TLS/SSL client certificate]] path. \\ [[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. 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. 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. | | ||
| - | | ''-==passphrase===<phrase>'' | Passphrase for encrypted private keys and client certificates. \\ SFTP, SCP, FTPS and WebDAVS protocols 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'' | Selects [[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). | | ||
| Line 27: | Line 27: | ||
| | ''-==timeout===<sec>'' | Server response timeout. | | | ''-==timeout===<sec>'' | Server response timeout. | | ||
| | ''-==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]]. | | | ''-==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. | | + | | ''-==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]]. | |
| - | | ''-==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. | | + | | ''-==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. | | | ''-==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. | | ||
| Line 59: | Line 60: | ||
| 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 ''[[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.WebdavSecure = true''.)) Alternatively, you can use ''[[library_sessionoptions_parseurl|SessionOptions.ParseUrl]]'' method. | + | 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 70: | Line 71: | ||
| | ''-certificate'' | Set ''[[library_sessionoptions#tlshostcertificatefingerprint|SessionOptions.TlsHostCertificateFingerprint]]''. | | | ''-certificate'' | Set ''[[library_sessionoptions#tlshostcertificatefingerprint|SessionOptions.TlsHostCertificateFingerprint]]''. | | ||
| | ''-passphrase'' | Set ''[[library_sessionoptions#privatekeypassphrase|SessionOptions.PrivateKeyPassphrase]]''. | | | ''-passphrase'' | Set ''[[library_sessionoptions#privatekeypassphrase|SessionOptions.PrivateKeyPassphrase]]''. | | ||
| - | | ''-passive'' | Set ''[[library_sessionoptions#ftpmode|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#ftpsecure|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). | | ||
| | ''-explicit'' | Set ''[[library_sessionoptions#ftpsecure|SessionOptions.FtpSecure]]'' to ''FtpSecure.Explicit'' (''[WinSCP.FtpSecure]::Explicit''). | | | ''-explicit'' | Set ''[[library_sessionoptions#ftpsecure|SessionOptions.FtpSecure]]'' to ''FtpSecure.Explicit'' (''[WinSCP.FtpSecure]::Explicit''). | | ||
| | ''-timeout'' | Set ''[[library_sessionoptions#timeout|SessionOptions.Timeout]]''. | | | ''-timeout'' | Set ''[[library_sessionoptions#timeout|SessionOptions.Timeout]]''. | | ||
| + | | ''-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. | | | ''-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. | | | ''-filezilla'' | Convert the full equivalent syntax suggested, when the ''open'' command is executed. | | ||