Table of Contents

Class SshClient

Namespace
SshSharp
Assembly
SshSharp.dll

An authenticated SSH client connection: run commands over it. Create one with ConnectAsync(Stream, SshClientOptions, bool, CancellationToken).

public sealed class SshClient : IAsyncDisposable
Inheritance
SshClient
Implements
Inherited Members
Extension Methods

Properties

Algorithms

The algorithms in use: key exchange (and whether it is post-quantum, IsPostQuantum), host key signature, ciphers and MACs. A key re-exchange can change them; each read returns the current ones.

ConnectionClosed

Cancelled when the connection ends for any reason, so pending work can stop or reconnect. ConnectionError says why.

ConnectionError

Why the connection ended (an SshException, usually), or null while it is up.

DynamicForwardings

The DynamicForward SOCKS proxies started from ssh_config; disposed with the client.

HostKey

The host key the server proved possession of.

IsConnected

Whether the connection is still up: false once the server disconnected, the connection failed (including a missed keep-alive, see KeepAliveInterval), or the client was disposed.

LocalForwardings

The LocalForward forwardings started from ssh_config (StartForwardings); disposed with the client.

RemoteForwardings

The RemoteForward forwardings started from ssh_config; disposed with the client.

RemoteSocketForwardings

The RemoteForward forwardings of a Unix socket on the server (RemoteForward /path target) started from ssh_config.

ServerIdentification

The server's identification string, for example SSH-2.0-OpenSSH_9.9.

Methods

ConnectAsync(Stream, SshClientOptions, bool, CancellationToken)

Runs the SSH protocol over an existing stream (a socket, a WebSocket wrapper, a tunnel from another connection, ...).

ConnectAsync(string, SshConfigConnectOptions?, CancellationToken)

Connects like ssh destination does: destination ([user@]host, an alias, or ssh://[user@]host[:port]) is resolved with ssh_config, and the connection follows it: HostName, Port, User, IdentityFile keys, known_hosts with StrictHostKeyChecking, Ciphers/KexAlgorithms/HostKeyAlgorithms/MACs, ProxyJump chains, ProxyCommand, ServerAliveInterval/ServerAliveCountMax, ConnectTimeout and AddressFamily.

ConnectAsync(string, int, SshClientOptions, CancellationToken)

Connects to host over TCP, performs the handshake and authenticates.

CreateHttpConnectCallback()

A ConnectCallback that makes HttpClient's connections through this SSH connection (OpenTcpTunnelAsync(string, int, CancellationToken)), so it can reach web services only the server reaches, such as an internal API behind a bastion. Host names are resolved by the server. TLS still runs end to end, from here to the service. Set UseProxy to false: with a system proxy configured, HttpClient would otherwise connect to that proxy, through the server, instead of to the service.

DisposeAsync()

Disconnects and releases the connection.

ForwardDynamicPortAsync(IPEndPoint, CancellationToken)

Dynamic port forwarding (ssh -D): runs a SOCKS proxy on localEndPoint (SOCKS 4, 4a and 5, CONNECT, no authentication). Each application connection names its destination, and the server makes the connection, so host names are resolved on the server's side. Use a loopback address: the proxy has no authentication, so anyone who can reach it can use the server's network.

ForwardLocalPortAsync(IPEndPoint, string, int, CancellationToken)

Local port forwarding (ssh -L): listens on localEndPoint and forwards every connection made to it through the server to remoteHost:remotePort. Use a loopback address unless other machines should be able to use the tunnel, and port 0 to let the system pick a free port (see LocalEndPoint). Forwarding stops when the forwarder or the client is disposed, or the connection ends.

ForwardRemoteDynamicPortAsync(string, int, Func<string, int, bool>?, CancellationToken)

Remote dynamic port forwarding (ssh -R [bind_address:]port with no destination, OpenSSH 7.6 and later): asks the server to listen on bindAddress:remotePort, and answers each connection made to it as a SOCKS proxy (4, 4a and 5, CONNECT, no authentication), connecting to the destination it names from this machine. It gives the server's side outbound access through this machine's network, for example to reach an internal package mirror from a build host.

ForwardRemotePortAsync(string, int, string, int, CancellationToken)

Remote port forwarding (ssh -R): asks the server to listen on bindAddress:remotePort and relays every connection made to it to localHost:localPort, as reached from this machine. The bind address is localhost for the server's loopback only (what ssh uses by default), an address, or empty for every address; sshd's GatewayPorts decides whether it honours anything but loopback. Port 0 lets the server pick one (see RemotePort).

ForwardRemoteUnixSocketAsync(string, string, int, CancellationToken)

Remote Unix-socket forwarding (ssh -R /remote/socket:host:port, streamlocal-forward@openssh.com): asks the server to listen on the Unix socket remoteSocketPath and relays every connection made to it to localHost:localPort, as reached from this machine. For example, a database here becomes a socket that programs on the server can open. sshd's StreamLocalBindUnlink decides whether a stale socket file is replaced.

ForwardRemoteUnixSocketAsync(string, string, CancellationToken)

Remote Unix-socket forwarding to a Unix socket here (ssh -R /remote/socket:/local/socket): for example, a local gpg-agent or Docker socket that programs on the server can use.

OpenTcpTunnelAsync(string, int, CancellationToken)

Opens a TCP connection from the server to host:port (a direct-tcpip channel, what ssh -L and ProxyJump use) and returns it as a stream. The host name is resolved by the server, so it can name machines only the server reaches. Disposing the stream closes the connection.

OpenUnixSocketTunnelAsync(string, CancellationToken)

Opens a connection from the server to the Unix domain socket at path on the server (direct-streamlocal@openssh.com, what ssh -L port:/path uses), for example a database or Docker socket.

PingAsync(CancellationToken)

Measures the round trip to the server and proves the connection is alive. OpenSSH 9.5 and later answer a transport ping (ping@openssh.com); other servers get a keepalive@openssh.com request, whose answer arrives just as quickly.

PreventNewSessionsAsync(CancellationToken)

Opens no more sessions on this connection (commands, shells, SFTP), and tells an OpenSSH server to refuse any as well, as ssh does once it knows it will not open another (OpenSSH's no-more-sessions@openssh.com): a process that later gets hold of this connection cannot quietly start a session on it, and an OpenSSH server drops the connection if one is tried anyway. Sessions already open, port forwarding and tunnels are unaffected. Like ssh, the request goes only to OpenSSH servers (some others abort on it); with others, only this client refuses.

RunCommandAsync(string, CancellationToken)

Runs command on the server and collects its output and exit status.

ScanHostKeysAsync(Func<CancellationToken, ValueTask<Stream>>, SshHostKeyScanOptions?, CancellationToken)

Fetches the server's host keys without authenticating, over streams that connect opens: one per key type, so it is called several times. For a host behind a jump host, open each stream with OpenTcpTunnelAsync(string, int, CancellationToken).

ScanHostKeysAsync(string, int, SshHostKeyScanOptions?, CancellationToken)

Fetches the server's host keys without authenticating, as ssh-keyscan does: one key exchange per key type the server offers, each disconnected before user authentication. Each key is one the server proved it holds (it signed the exchange), but nothing says the server is the one you meant to reach: compare the fingerprints out of band before trusting them, or use host certificates.

StartCommandAsync(string, SshSessionOptions?, CancellationToken)

Starts command with its input and output as streams, for long-running or interactive commands. For a command whose output fits in memory, RunCommandAsync(string, CancellationToken) is simpler.

StartShellAsync(SshSessionOptions?, CancellationToken)

Starts the user's login shell, usually with a terminal (Terminal) for interactive use.

StartSubsystemAsync(string, SshSessionOptions?, CancellationToken)

Starts a subsystem, as ssh -s does: a protocol the server runs by name (sftp, netconf, or one the server configures with sshd's Subsystem), with no shell in between. The session's StandardInput and StandardOutput carry the subsystem's protocol, byte for byte.

Edit this page