Secure shell protocol (version 2) predefines several channel types.

Below classes wrap up the generic SshChannel class to provide easy-to-use interfaces to these specialized channels.

class Scp : public SshChannel

This class encapsulates an SSH2 secure copy channel. It provides a means for securely transferring files between local host and a remote host. Scp class is derived from SshChannel class, and has pick semantics.

bool SaveFile(const char *path, const String& data)

Saves the content of data to remote path. Returns true on success. WhenProgress gate can be used to track data transfer.

String LoadFile(const char *path)

Returns the content of the remote path. WhenProgress gate can be used to track data transfer.

bool SaveFile(const char *path, Stream& in)

Saves the content of in to remote path . Returns true on success. WhenProgress gate can be used to track data transfer.

bool LoadFile(Stream& out, const char *path)

Returns the content of remote path into out. Returns true on success. WhenProgress gate can be used to track data transfer.

Gate<int64, int64> WhenProgress

If defined, this gate allows tracking of data transfers. The first parameter provides the amount of data that has already been transferred. The second parameter provides the total amount of data to be transferred. Returning true will abort the current data transfer.

Scp(SshSession& session)

Constructor. Binds the Scp instance to session.

class SshExec : public SshChannel

This class encapsulates an SSH2 remote process execution (exec) channel. It provides a means for executing a single shell command on a remote host. Note that SshExec objects can only be used once, since the protocol does not allow the reuse of exec channels. If you need to run a real-time, interactive command line interface, you should consider using SshShell class instead. SshExec class is derived from SshChannel class, and has pick semantics.

int Execute(const String& cmd, String& out, String& err)

int operator()(const String& cmd, String& out, String& err)

Executes a remote process defined by the cmd command line,returns its standard output in out, its standard error output in err, and its exit code as the return value. A negative return value means protocol or internal error.

SshExec(SshSession& session)

Constructor. Binds the SshExec instance to session.

int SshExecute(SshSession& session, const String& cmd, String& out, String& err)

Executes a remote process defined by the cmd command line, returns its standard output in out, its standard error output in err, and its exit code as the return value. A negative return value means protocol or internal error. This helper function will use the timeout value provided by the session.

int SshExecute(SshSession& session, const String& cmd, String& out)

Executes a remote process defined by the cmd command line, returns its output (stdout/stderr) in out, and its exit code as the return value. A negative return value means protocol or internal error. This helper function will use the timeout value provided by the session.

String SshExecute(SshSession& session, const String& cmd)

Executes a remote process defined by the cmd command line. and returns its output on success, and String::GetVoid() on failure. This helper function will use the timeout value provided by the session.

class SshTunnel : public SshChannel

This class encapsulates the SSH2 TCP/IP and port forwarding mechanisms. It provides a means for TCP tunneling from both client to server and server to client directions, acting as a secure network proxy. SshTunnel class is derived from SshChannel class, and has pick semantics.

bool Connect(const String& url)

bool Connect(const String& host, int port)

Attempts a tunnelled TCP/IP connection to target host at port. Returns true on success. url must contain the target host name and port information. (E.g. "localhost:1080"). Please note that while the client to SSH server communication remains encrypted, communication from the SSH server to target host is not.

bool Listen(int port, int listen_count = 5)

bool Listen(const String& host, int port, int* bound_port, int listen_count = 5)

Instructs the remote SSH server to begin listening for inbound TCP/IP connections at port. Returns true on success. If the listen port is set to 0, the SSH server will select the first available dynamic port. If a dynamic port is requested, bound_port will be populated with the actual bound port assigned by the server. host  can be used to specify what interfaces to listen on. If host is not specified, or explicilty set to "0.0.0.0", all available addresses will be used to bind on. New connections will be queued until accepted using the Accept() method. listen_count can be used to set the maximum number of pending connections to queue before rejecting further attempts.

bool Accept(SshTunnel& listener)

Accepts a connection from the listener. Returns true on success.

SshTunnel(SshSession& session)

Constructor. Binds the SshTunnel instance to session.

class SshShell : public SshChannel

This class encapsulates an SSH2 interactive shell channel, providing a means for secure interaction with a remote command line interface in real-time with X11 forwarding support. SshShell class is derived from SshChannel class, and has pick semantics. If you need to execute a single command with no interaction, you should consider using SshExec class. Also note that the shell object needs to be put into blocking mode if it is not planned to run as a timed session.

bool Run(const String& terminal, Size pagesize, const String& tmodes = Null)

bool Run(const String& terminal, int width, int height, const String& tmodes = Null)

Runs a generic remote command line interface. Returns true on successful exit. terminal should be set to preferred terminal emulation (ansi, vt100, xterm, etc.). The dimensions of the terminal view (as character cells) can be set using the width and height, or pagesize parameters. Terminal modes can be specified using the tmodes string (see below table for details).

bool Console(const String& terminal, const String& tmodes = Null)

Requires console-based applications.

Runs a console-based remote command line interface. Returns true on successful exit. terminal should be set to preferred terminal emulation (ansi, vt100, xterm, etc.). Terminal modes can be specified using the tmodes string (see below table for details). Note that in console mode SshShell automatically takes care of the local console page resizing.

SshShell& ForwardX11(const String& host = Null, int display = 0, int screen = 0, int bufsize = 1024 * 1024)

POSIX only. Requires a running X server.

Enables X11 forwarding for the given shell instance. host and display can be used to connect to local X server. (defaulted values simply mean "[localhost]:0"). screen can be used to select the X11 screen to forward. bufsize specifies the size of read/write buffer for the associated UNIX sockets. Default buffer size is 1 MB (increasing the read/write buffer may result in smoother performance). Returns *this for method chaining.

bool AcceptX11(SshX11Handle xhandle)

POSIX only. Requires a running X server.

Accepts an X11 connection. Return true on success. This method requires X11 forwarding to be enabled, and is meant to be used with SshSession:WhenX11 event. Note that each shell instance can forward multiple X11 connections.

void Send(int c)

void Send(const char* s)

void Send(const String& s)

Puts a single character, or multiple characters, into the input queue.

SshShell& PageSize(Size sz)

Sets the terminal view size as character cells to sz. Returns *this for method chaining.

Size GetPageSize() const

Returns the current SSH terminal view size in character cells.

Size GetConsolePageSize()

This helper method returns the actual page size of the local console, and is meant to be used in console mode. Returns Null on failure.

Event<> WhenInput

This event is emitted when writing to shell channel becomes possible. Send() method can be used to send data over the channel.

Event<const void*, int> WhenOutput

This event is emitted whenever data is read from the shell.

SshShell(SshSession& session)

Constructor. Binds the SshShell instance to session.

Below is a list of terminal modes currently supported by the SSH2 protocol. Current implementation requires that the terminal modes be encoded into a byte stream. SSH package uses a String for this purpose. This string should consists of opcode-argument pairs wherein the opcode is a byte value. Opcodes 1 to 159 have a single uint32 argument. This byte stream should terminate with a TTY_OP_END, i.e 0x00 value. Client should put any mode that it knows about, and server can ignore any mode that it does not recognise. See RFC-4254 for details.

Do you want to contribute?