Class ScpClient

Namespace

Renci.SshNet

Assembly

Renci.SshNet.dll

Provides SCP client functionality.

public class ScpClient : BaseClient, IBaseClient, IDisposable

Inheritance

object

BaseClient

ScpClient

Implements

IBaseClient

IDisposable

Inherited Members

BaseClient.ConnectionInfo

BaseClient.IsConnected

BaseClient.KeepAliveInterval

BaseClient.ErrorOccurred

BaseClient.HostKeyReceived

BaseClient.ServerIdentificationReceived

BaseClient.Connect()

BaseClient.ConnectAsync(CancellationToken)

BaseClient.Disconnect()

BaseClient.SendKeepAlive()

BaseClient.OnConnecting()

BaseClient.OnConnected()

BaseClient.OnDisconnecting()

BaseClient.OnDisconnected()

BaseClient.Dispose()

BaseClient.Dispose(bool)

BaseClient.CheckDisposed()

object.Equals(object?)

object.Equals(object?, object?)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object?, object?)

object.ToString()

Remarks

More information on the SCP protocol is available here: https://github.com/net-ssh/net-scp/blob/master/lib/net/scp.rb.

Known issues in OpenSSH:

• Recursive download (-prf) does not deal well with specific UTF-8 and newline characters.Recursive update does not support empty path for uploading to home directory.

caution

SCP performs a transfer by running scp on the server with the remote path embedded in the command. How that path must be encoded depends on the kind of server:

• On a shell-based server the command is interpreted by a shell, so the path must be quoted or escaped according to that shell's rules. An unsuitable transformation can allow a crafted path to be executed as a command on the server.
• On a non-shell-based server the path is used literally and must not be quoted or escaped (see Renci.SshNet.RemotePathTransformation.None); otherwise the quoting or escape characters end up as part of the file or directory path.

Choose the Renci.SshNet.ScpClient.RemotePathTransformation supplied to the constructor to suit the remote server and the trust you place in the paths you pass. Prefer Renci.SshNet.SftpClient, which does not involve a remote shell, where possible.

Constructors

ScpClient(ConnectionInfo, IRemotePathTransformation)

Initializes a new instance of the Renci.SshNet.ScpClient class.

public ScpClient(ConnectionInfo connectionInfo, IRemotePathTransformation remotePathTransformation)

Parameters

connectionInfo ConnectionInfo

The connection info.

remotePathTransformation IRemotePathTransformation

The transformation to apply to remote paths.

Exceptions

ArgumentNullException

connectionInfo is null.

ScpClient(string, int, string, string, IRemotePathTransformation)

Initializes a new instance of the Renci.SshNet.ScpClient class.

public ScpClient(string host, int port, string username, string password, IRemotePathTransformation remotePathTransformation)

Parameters

host string

Connection host.

port int

Connection port.

username string

Authentication username.

password string

Authentication password.

remotePathTransformation IRemotePathTransformation

The transformation to apply to remote paths.

Exceptions

ArgumentNullException

password is null.

ArgumentException

host is invalid, or username is null or contains only whitespace characters.

ArgumentOutOfRangeException

port is not within System.Net.IPEndPoint.MinPort and System.Net.IPEndPoint.MaxPort.

ScpClient(string, string, string, IRemotePathTransformation)

Initializes a new instance of the Renci.SshNet.ScpClient class.

public ScpClient(string host, string username, string password, IRemotePathTransformation remotePathTransformation)

Parameters

host string

Connection host.

username string

Authentication username.

password string

Authentication password.

remotePathTransformation IRemotePathTransformation

The transformation to apply to remote paths.

Exceptions

ArgumentNullException

password is null.

ArgumentException

host is invalid, or username is null or contains only whitespace characters.

ScpClient(string, int, string, IRemotePathTransformation, params IPrivateKeySource[])

Initializes a new instance of the Renci.SshNet.ScpClient class.

public ScpClient(string host, int port, string username, IRemotePathTransformation remotePathTransformation, params IPrivateKeySource[] keyFiles)

Parameters

host string

Connection host.

port int

Connection port.

username string

Authentication username.

remotePathTransformation IRemotePathTransformation

The transformation to apply to remote paths.

keyFiles IPrivateKeySource[]

Authentication private key file(s) .

Exceptions

ArgumentNullException

keyFiles is null.

ArgumentException

host is invalid, -or- username is null or contains only whitespace characters.

ArgumentOutOfRangeException

port is not within System.Net.IPEndPoint.MinPort and System.Net.IPEndPoint.MaxPort.

ScpClient(string, string, IRemotePathTransformation, params IPrivateKeySource[])

Initializes a new instance of the Renci.SshNet.ScpClient class.

public ScpClient(string host, string username, IRemotePathTransformation remotePathTransformation, params IPrivateKeySource[] keyFiles)

Parameters

host string

Connection host.

username string

Authentication username.

remotePathTransformation IRemotePathTransformation

The transformation to apply to remote paths.

keyFiles IPrivateKeySource[]

Authentication private key file(s) .

Exceptions

ArgumentNullException

keyFiles is null.

ArgumentException

host is invalid, -or- username is null or contains only whitespace characters.

ScpClient(ConnectionInfo) Deprecated

SCP with insufficiently-escaped paths can allow remote command injection. Use a constructor taking an IRemotePathTransformation which suits the escaping rules of the remote server and the trust environment in which this code runs, and consider using SFTP where possible.

Initializes a new instance of the Renci.SshNet.ScpClient class.

[Obsolete("SCP with insufficiently-escaped paths can allow remote command injection. Use a constructor taking an IRemotePathTransformation which suits the escaping rules of the remote server and the trust environment in which this code runs, and consider using SFTP where possible.")]
public ScpClient(ConnectionInfo connectionInfo)

Parameters

connectionInfo ConnectionInfo

The connection info.

Exceptions

ArgumentNullException

connectionInfo is null.

ScpClient(string, int, string, string) Deprecated

SCP with insufficiently-escaped paths can allow remote command injection. Use a constructor taking an IRemotePathTransformation which suits the escaping rules of the remote server and the trust environment in which this code runs, and consider using SFTP where possible.

Initializes a new instance of the Renci.SshNet.ScpClient class.

[Obsolete("SCP with insufficiently-escaped paths can allow remote command injection. Use a constructor taking an IRemotePathTransformation which suits the escaping rules of the remote server and the trust environment in which this code runs, and consider using SFTP where possible.")]
public ScpClient(string host, int port, string username, string password)

Parameters

host string

Connection host.

port int

Connection port.

username string

Authentication username.

password string

Authentication password.

Exceptions

ArgumentNullException

password is null.

ArgumentException

host is invalid, or username is null or contains only whitespace characters.

ArgumentOutOfRangeException

port is not within System.Net.IPEndPoint.MinPort and System.Net.IPEndPoint.MaxPort.

ScpClient(string, string, string) Deprecated

SCP with insufficiently-escaped paths can allow remote command injection. Use a constructor taking an IRemotePathTransformation which suits the escaping rules of the remote server and the trust environment in which this code runs, and consider using SFTP where possible.

Initializes a new instance of the Renci.SshNet.ScpClient class.

[Obsolete("SCP with insufficiently-escaped paths can allow remote command injection. Use a constructor taking an IRemotePathTransformation which suits the escaping rules of the remote server and the trust environment in which this code runs, and consider using SFTP where possible.")]
public ScpClient(string host, string username, string password)

Parameters

host string

Connection host.

username string

Authentication username.

password string

Authentication password.

Exceptions

ArgumentNullException

password is null.

ArgumentException

host is invalid, or username is null or contains only whitespace characters.

ScpClient(string, int, string, params IPrivateKeySource[]) Deprecated

SCP with insufficiently-escaped paths can allow remote command injection. Use a constructor taking an IRemotePathTransformation which suits the escaping rules of the remote server and the trust environment in which this code runs, and consider using SFTP where possible.

Initializes a new instance of the Renci.SshNet.ScpClient class.

[Obsolete("SCP with insufficiently-escaped paths can allow remote command injection. Use a constructor taking an IRemotePathTransformation which suits the escaping rules of the remote server and the trust environment in which this code runs, and consider using SFTP where possible.")]
public ScpClient(string host, int port, string username, params IPrivateKeySource[] keyFiles)

Parameters

host string

Connection host.

port int

Connection port.

username string

Authentication username.

keyFiles IPrivateKeySource[]

Authentication private key file(s) .

Exceptions

ArgumentNullException

keyFiles is null.

ArgumentException

host is invalid, -or- username is null or contains only whitespace characters.

ArgumentOutOfRangeException

port is not within System.Net.IPEndPoint.MinPort and System.Net.IPEndPoint.MaxPort.

ScpClient(string, string, params IPrivateKeySource[]) Deprecated

SCP with insufficiently-escaped paths can allow remote command injection. Use a constructor taking an IRemotePathTransformation which suits the escaping rules of the remote server and the trust environment in which this code runs, and consider using SFTP where possible.

Initializes a new instance of the Renci.SshNet.ScpClient class.

[Obsolete("SCP with insufficiently-escaped paths can allow remote command injection. Use a constructor taking an IRemotePathTransformation which suits the escaping rules of the remote server and the trust environment in which this code runs, and consider using SFTP where possible.")]
public ScpClient(string host, string username, params IPrivateKeySource[] keyFiles)

Parameters

host string

Connection host.

username string

Authentication username.

keyFiles IPrivateKeySource[]

Authentication private key file(s) .

Exceptions

ArgumentNullException

keyFiles is null.

ArgumentException

host is invalid, -or- username is null or contains only whitespace characters.

Properties

BufferSize

Gets or sets the size of the buffer.

public uint BufferSize { get; set; }

Property Value

uint

OperationTimeout

Gets or sets the operation timeout.

public TimeSpan OperationTimeout { get; set; }

Property Value

TimeSpan

RemotePathTransformation

Gets or sets the transformation to apply to remote paths.

public IRemotePathTransformation RemotePathTransformation { get; set; }

Property Value

IRemotePathTransformation

Remarks

This transformation is applied to the remote file or directory path that is passed to the scp command.

See Renci.SshNet.RemotePathTransformation for the transformations that are supplied out-of-the-box with SSH.NET.

Exceptions

ArgumentNullException

value is null.

UseDirectoryFlag

Gets or sets a value indicating whether the "-d" flag should be passed to the scp process on the server when uploading files. Defaults to true.

public bool UseDirectoryFlag { get; set; }

Property Value

bool

Remarks

The "-d" flag is an undocumented flag that ensures that the target is actually a directory. However, some scp implementations (like Cisco) do not support this flag and will fail. You can set this to false to work around this.

Methods

Download(string, FileInfo)

Downloads the specified file from the remote host to local file.

public void Download(string filename, FileInfo fileInfo)

Parameters

filename string

Remote host file name.

fileInfo FileInfo

Local file information.

Exceptions

ArgumentNullException

fileInfo is null.

ArgumentException

filename is null or empty.

ScpException

filename exists on the remote host, and is not a regular file.

SshException

The secure copy execution request was rejected by the server.

SshConnectionException

Client is not connected.

Download(string, DirectoryInfo)

Downloads the specified directory from the remote host to local directory.

public void Download(string directoryName, DirectoryInfo directoryInfo)

Parameters

directoryName string

Remote host directory name.

directoryInfo DirectoryInfo

Local directory information.

Exceptions

ArgumentException

directoryName is null or empty.

ArgumentNullException

directoryInfo is null.

ScpException

File or directory with the specified path does not exist on the remote host.

SshException

The secure copy execution request was rejected by the server.

SshConnectionException

Client is not connected.

Download(string, Stream)

Downloads the specified file from the remote host to the stream.

public void Download(string filename, Stream destination)

Parameters

filename string

A relative or absolute path for the remote file.

destination Stream

The System.IO.Stream to download the remote file to.

Exceptions

ArgumentException

filename is null or contains only whitespace characters.

ArgumentNullException

destination is null.

ScpException

filename exists on the remote host, and is not a regular file.

SshException

The secure copy execution request was rejected by the server.

SshConnectionException

Client is not connected.

Upload(Stream, string)

Uploads the specified stream to the remote host.

public void Upload(Stream source, string path)

Parameters

source Stream

The System.IO.Stream to upload.

path string

A relative or absolute path for the remote file.

Exceptions

ArgumentNullException

path is null.

ArgumentException

path is a zero-length System.String.

ScpException

A directory with the specified path exists on the remote host.

SshException

The secure copy execution request was rejected by the server.

SshConnectionException

Client is not connected.

Upload(FileInfo, string)

Uploads the specified file to the remote host.

public void Upload(FileInfo fileInfo, string path)

Parameters

fileInfo FileInfo

The file system info.

path string

A relative or absolute path for the remote file.

Exceptions

ArgumentNullException

fileInfo is null.

ArgumentNullException

path is null.

ArgumentException

path is a zero-length System.String.

ScpException

A directory with the specified path exists on the remote host.

SshException

The secure copy execution request was rejected by the server.

SshConnectionException

Client is not connected.

Upload(DirectoryInfo, string)

Uploads the specified directory to the remote host.

public void Upload(DirectoryInfo directoryInfo, string path)

Parameters

directoryInfo DirectoryInfo

The directory info.

path string

A relative or absolute path for the remote directory.

Exceptions

ArgumentNullException

directoryInfo is null.

ArgumentNullException

path is null.

ArgumentException

path is a zero-length string.

ScpException

path does not exist on the remote host, is not a directory or the user does not have the required permission.

SshException

The secure copy execution request was rejected by the server.

SshConnectionException

Client is not connected.

Downloading

Occurs when downloading file.

public event EventHandler<ScpDownloadEventArgs>? Downloading

Event Type

EventHandler<ScpDownloadEventArgs>?

Uploading

Occurs when uploading file.

public event EventHandler<ScpUploadEventArgs>? Uploading

Event Type

EventHandler<ScpUploadEventArgs>?