This is an old revision of the document!
open
Establishes new connection.
Advertisement
Syntax
open <session_url> open <site>
Remarks
Establishes connection to given host. Use session URL or name of the site (stored session) . 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.
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 or site. With SSH you may alternatively use passphrase-less private key or use Pageant. With SSH and FTPS you need to verify the host or certificate.
Switches:
| Switch | Description |
|---|---|
-privatekey=<key> |
Private key path |
-timeout=<sec> |
Server response timeout |
-hostkey="<fingerprint>" |
Specifies fingerprint of expected SSH host key (or several alternative fingerprints separated by semicolon). It makes WinSCP automatically accept hostkey with the fingerprint. As the hostkey fingerprint contains spaces you need to enclose it in quotes. Learn how to obtain host key fingerprint. In exceptional situations, when security is not required, you can use value * to accept any hostkey. In this case, script output and log file will include warning about insecure connection. This feature is available only in the latest beta release. SFTP and SCP protocols only. |
-certificate="<fingerprint>" |
Specifies fingerprint of expected SSL/TLS certificate (or several fingerprints separated by semicolon). It makes WinSCP automatically 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. This feature is available only in the latest beta release. FTPS protocol only. |
-passive=on|off |
Enables passive (=on) or active (=off) transfer mode (FTP protocol only). |
-implicit |
Implicit TLS/SSL (FTPS protocol only) |
-explicitssl |
Explicit SSL (FTPS protocol only) |
-explicittls |
Explicit TLS (FTPS protocol only) |
-rawsettings setting1=value1 setting2=value2 … |
Allows configuring any session settings using raw format as in an INI file. E.g. to enable SSH compression and agent forwarding use -rawsettings Compression=1 AgentFwd=1. |
Advertisement
XML log element: session
Examples
open sftp://martin:mypassword@example.com -hostkey="ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" open scp://test@example.com:2222 -privatekey=mykey.ppk open ftps://martin@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 martin@example.com open example.com open
Converting to .NET Assembly
When converting script to .NET Assembly, map open command to Session.Open method. The Session.Open accepts instance of SessionOptions class, which needs to be populated according to parameters and switches of open command.
Parameters mapping: 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|scp://).
There is no direct mapping for opening stored session/site using site parameter, becase .NET assembly does not share configuration with graphical/scripting mode. You need to configure all your session settings directly in your code (using SessionOptions class).
Switches mapping:
| Switch | Mapping |
|---|---|
-privatekey |
Set SessionOptions.SshPrivateKeyPath. |
-timeout |
Set SessionOptions.Timeout. |
-hostkey |
Set SessionOptions.SshHostKeyFingerprint. |
-certificate |
Set SessionOptions.SslHostCertificateFingerprint. |
-passive |
Set SessionOptions.FtpMode to FtpMode.Passive for on or FtpMode.Active Enumeration syntax in PowerShell is like [WinSCP.FtpMode]::Passive. |
-implicit |
Set SessionOptions.FtpSecure to FtpSecure.Implicit ([WinSCP.FtpSecure]::Implicit in PowerShell). |
-explicitssl |
Set SessionOptions.FtpSecure to FtpSecure.ExplicitSsl ([WinSCP.FtpSecure]::ExplicitSsl). |
-explicittls |
Set SessionOptions.FtpSecure to FtpSecure.ExplicitTls ([WinSCP.FtpSecure]::ExplicitTls). |
-rawsettings |
Call SessionOptions.AddRawSettings for every key/value pair in switch parameters. |
For example, following script snippet:
open sftp://martin:mypassword@example.com -hostkey="ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
Advertisement
maps to following PowerShell code:
$sessionOptions = New-Object WinSCP.SessionOptions # sftp:// $sessionOptions.Protocol = [WinSCP.Protocol]::Sftp $sessionOptions.HostName = "example.com" $sessionOptions.UserName = "martin" $sessionOptions.Password = "mypassword" # -hostkey $sessionOptions.SshHostKeyFingerprint = "ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" $session = New-Object WinSCP.Session # Connect $session.Open($sessionOptions)