open command

Establishes new connection.

Advertisement

Syntax

open <session_url>
open <site>

Remarks

Establishes connection to given host. Use session URL or name of the 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.

You can use 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 or site. With SSH you may alternatively use private key. With SSH, FTPS or WebDAVS you need to verify the host or certificate.

Switches:

Switch Description
-privatekey=<file> 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 host key (or several alternative fingerprints separated by semicolon). It makes WinSCP automatically 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 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 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/SSL client certificate path.
FTPS and WebDAVS protocols only.
-certificate="<fingerprint>" Specifies fingerprint of expected TLS/SSL certificate (or several fingerprints separated by semicolon). It makes WinSCP automatically 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 and WebDAVS protocols only.
-passphrase=<phrase> Passphrase for encrypted private keys and client certificates.
SFTP, SCP, FTPS and WebDAVS protocols only.
The passphrase can be read from a file.
-passive=on|off Selects passive (on) or active (off) transfer mode (FTP protocol only).
-implicit Implicit TLS/SSL (FTPS protocol only).
-explicit Explicit TLS/SSL (FTPS protocol only).
-timeout=<sec> Server response timeout.
-username=<user> An alternative way to provide a username. The username 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 can be read from a file.
-passwordsfromfiles Interpret values of -password, -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.1
-rawsettings setting1=value1 setting2=value2 Allows configuring any site settings using raw format as in an INI file (with optional use of 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.2
Additionally it prints a full syntax to use to open an identical session without relying on an external FileZilla configuration.

Advertisement

XML log element: session

Examples

open sftp://martin:mypassword@example.com/ -hostkey="ssh-rsa 2048 xxxxxxxxxxx..."
open scp://test@example.com:2222/ -privatekey=mykey.ppk
open ftps://martin:mypassword@example.com/ -implicit -certificate="xx:xx:xx:xx:xx:xx:xx:xx..."
open sftp://martin:mypassword@example.com/ -rawsettings ProxyMethod=3 ProxyHost=proxy
open sftp://martin@example.com/
open sftp://example.com/
open ftp://martin:mypassword@example.com/

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|ftpes|http|https|s3|scp://).3 Alternatively, you can use SessionOptions.ParseUrl method.

There is no direct mapping for opening stored site using site parameter, because .NET assembly does not share configuration with graphical/scripting mode. You need to configure all your site settings directly in your code (using SessionOptions class).

Switches mapping:

Switch Mapping
-privatekey When the value is an SSH private key path, set SessionOptions.SshPrivateKeyPath.
When the value is a hex dump of SSH private key file contents, store the contents (not the hex dump) to SessionOptions.SshPrivateKey.
-hostkey Set SessionOptions.SshHostKeyFingerprint.
For special values * and acceptnew, set SessionOptions.SshHostKeyPolicy to SshHostKeyPolicy.GiveUpSecurityAndAcceptAny or SshHostKeyPolicy.AcceptNew, respectively.
-clientcert Set SessionOptions.TlsClientCertificatePath.
-certificate Set SessionOptions.TlsHostCertificateFingerprint.
-passphrase Set SessionOptions.PrivateKeyPassphrase.
-passive Set SessionOptions.FtpMode to FtpMode.Passive for on or FtpMode.Active for off.
Enumeration syntax in PowerShell is like [WinSCP.FtpMode]::Passive.
-implicit Set SessionOptions.FtpSecure to FtpSecure.Implicit ([WinSCP.FtpSecure]::Implicit in PowerShell).
-explicit Set SessionOptions.FtpSecure to FtpSecure.Explicit ([WinSCP.FtpSecure]::Explicit).
-timeout Set SessionOptions.Timeout.
-username Set SessionOptions.UserName.
-password Set SessionOptions.Password.
-passwordsfromfiles Read the file in your code and assign a respective property.
PowerShell example: $sessionOptions.Password = (Get-Content $path)[0]
-rawsettings Call SessionOptions.AddRawSettings for every key/value pair in switch parameters.
-filezilla Convert the full equivalent syntax suggested, when the open command is executed.

Advertisement

For example, following script snippet:

open sftp://martin:mypassword@example.com/ -hostkey="ssh-rsa 2048 xxxxxxxxxxx..."

maps to following PowerShell code:

$sessionOptions = New-Object WinSCP.SessionOptions -Property @{
    # sftp://
    Protocol = [WinSCP.Protocol]::Sftp
    HostName = "example.com"
    UserName = "martin"
    Password = "mypassword"
    # -hostkey
    SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..."
}
 
$session = New-Object WinSCP.Session
# Connect
$session.Open($sessionOptions)
  1. 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.Back
  2. WinSCP looks for sites in C:\Users\username\AppData\Roaming\FileZilla\sitemanager.xml. Back
  3. 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.Back

Last modified: by martin