The SSH protocol requires that requests for services on a remote machine be made over channels. A single SSH connection may contain multiple channels, all run simultaneously over that connection.

Each channel, in turn, represents the processing of a single service. When you invoke a process on the remote host with Net::SSH, a channel is opened for that invocation, and all input and output relevant to that process is sent through that channel. The connection itself simply manages the packets of all of the channels that it has open.

This means that, for instance, over a single SSH connection you could execute a process, download a file via SFTP, and forward any number of ports, all (seemingly) at the same time!

Naturally, they do not occur simultaneously, but rather work in a “time-share” fashion by sharing the bandwidth of the connection. Nevertheless, the fact that these channels exist make working with the SSH protocol a bit more challenging than simpler protocols (like FTP, HTTP, or Telnet).

Because a session may be composed of multiple simultaneously operating channels, the Net::SSH interface works by means of callbacks. You specify actions that need to occur in response to various events, and when those events occur, the framework invokes the corresonding callbacks.

In order to allow the events to be processed in a continuous manner, you need to be sure to call the loop method of your session handle, after setting up any callbacks that you want to be executed. If you do not call the loop method, your session will terminate as soon as the block is exited, which means none of your carefully laid callbacks will ever be called.

The loop method is easy to invoke:

Net::SSH.start( 'host' ) do |session|
  ...
  session.loop
end

Incidentally, the loop method accepts an optional block, which if specified should return a “false” value when the loop should terminate. In the absense of a block, the loop will continue until there are no more open channels. Sometimes, however, you only want the loop to continue until some action occurs, at which time you then do some processing and then start the loop again.

Each channel has a type. Usually, you will use “session” channels, but there are also “x11” channels, “forwarded-tcpip” channels, and “direct-tcpip” channels. Net::SSH currently has no support for “x11” channels. The “forwarded-tcpip” and “direct-tcpip” channels are managed internally via the port-forwarding interfaces.

The “session” channel type allows for a broad range of actions, including (but not limited to) SFTP requests and remote process execution.

The simplest way to open a channel is via the open_channel method of Net::SSH::Session. By default, the channel will be of type “session”, but you can optionally specify the channel type and any extra data to initialize the channel with. You also pass a block to the open_channel invocation. This block will be called after the server has confirmed that the channel is valid and has been opened successfully.

The open_channel method always returns immediately—all it does is inform the server that a channel needs to be opened and then registers the associated block as the callback to be invoked when the channel is confirmed.

This behavior is typical of most of the methods in the Net::SSH API; they simply send a request to the server and then (optionally) register a callback. Very few of them actually block (pause) until the server responds.

Here is an example of opening a channel:

Net::SSH.start( 'host' ) do |session|
  session.open_channel do |channel|
    puts "channel successfully opened... closing..."
    channel.close
  end

  session.loop
end

Note the use of the close method for the channel. Just like most methods in the Net::SSH API, it does not immediately close the channel, but instead sends a close request to the server and returns. When the server responds that the channel has been closed, the framework will then call any final callbacks for the channel and then remove it.

There are various callbacks that may be registered on a channel. Registering a callback is as simple as invoking the corresponding method on the channel and giving it a block that should be invoked when the named action occurs. The following table describes each callback and how it is used.

In general, you will never need to register callbacks for on_failure, on_request, on_success, or on_window_adjust, unless you are needing to implement support for some subservice or piggy-backed protocol (like SFTP).

Following is an example of registering callbacks on a channel:

Net::SSH.start( 'host' ) do |session|
  session.open_channel do |channel|
    channel.on_close do |ch|
      puts "channel closed successfully."
    end
    puts "closing channel..."
    channel.close
  end

  session.loop
end

There are a variety of operations that may be performed on a channel. Some we’ve already mentioned, like registering callbacks, or closing the channel. Some of the other more common operations are listed (and described) in the following table.

See the API documentation for an exhaustive reference of all available channel operations.