Class
Net::SSH::Connection::Channel

The channel abstraction. Multiple “channels” can be multiplexed
onto a single SSH channel, each operating
independently and seemingly in parallel. This class represents a single
such channel. Most operations performed with the Net::SSH library will involve using one or more
channels.

Channels are intended to be used asynchronously. You request that one be
opened (via Connection::Session#open_channel), and when
it is opened, your callback is invoked. Then, you set various other
callbacks on the newly opened channel, which are called in response to the
corresponding events. Programming with Net::SSH works best if you think of your programs
as state machines. Complex programs are best implemented as objects that
wrap a channel. See Net::SCP and Net::SFTP for examples of how complex
state machines can be built on top of the SSH
protocol.

Channels also have a basic hash-like interface, that allows programs to
store arbitrary state information on a channel object. This helps simplify
the writing of state machines, especially when you may be juggling multiple
open channels at the same time.

Note that data sent across SSH channels are
governed by maximum packet sizes and maximum window sizes. These details
are managed internally by Net::SSH::Connection::Channel, so you may remain
blissfully ignorant if you so desire, but you can always inspect the
current maximums, as well as the remaining window size, using the reader
attributes for those values.

The maximum amount of data that the local end of this channel can receive.
This is a total, not per-packet.

local_window_size

[R]

This is the remaining window size on the local end of this channel. When
this reaches zero, no more data can be received.

properties

[R]

A hash of properties for this channel. These can be used to store state
information about this channel. See also #[] and #[]=.

remote_id

[R]

The remote id for this channel, assigned by the remote host.

remote_maximum_packet_size

[R]

The maximum packet size that the remote host can receive.

remote_maximum_window_size

[R]

The maximum amount of data that the remote end of this channel can receive.
This is a total, not per-packet.

remote_window_size

[R]

This is the remaining window size on the remote end of this channel. When
this reaches zero, no more data can be sent.

type

[R]

The type of this channel, usually “session”.

Public class methods

new(connection, type, local_id, &on_confirm_open)

Instantiates a new channel on the given connection, of the given type, and
with the given id. If a block is given, it will be remembered until the
channel is confirmed open by the server, and will be invoked at that time
(see do_open_confirmation).

This also sets the default maximum packet size and maximum window size.

Requests that the channel be closed. If the channel is already closing,
this does nothing, nor does it do anything if the channel has not yet been
confirmed open (see do_open_confirmation). Otherwise, it sends a
CHANNEL_CLOSE message and marks the channel as closing.

Returns true if the channel is currently closing, but not actually closed.
A channel is closing when, for instance, close has been invoked, but the server has
not yet responded with a CHANNEL_CLOSE packet of its own.

Invokes the on_extended_data callback
when the server sends extended data to the channel. This will reduce the
available window size on the local end. The callback is invoked with the
channel, type, and data.

Invoked when the server failed to open the channel. If an on_open_failed callback was specified, it
will be invoked with the channel, reason code, and description as
arguments. Otherwise, a ChannelOpenFailed exception will be
raised.

Syntactic sugar for setting an environment variable in the remote
process’ environment. Note that for security reasons, the server may
refuse to set certain environment variables, or all, at the server’s
discretion. If you are connecting to an OpenSSH server, you will need to
update the AcceptEnv setting in the sshd_config to include the environment
variables you want to send.

Tells the remote end of the channel that no more data is forthcoming from
this end of the channel. The remote end may still send data. The
CHANNEL_EOF packet will be sent once the output buffer is empty.

Syntactic sugar for executing a command. Sends a channel request asking
that the given command be invoked. If the block is given, it will be called
when the server responds. The first parameter will be the channel, and the
second will be true or false, indicating whether the request succeeded or
not. In this case, success means that the command is being executed, not
that it has completed, and failure means that the command altogether failed
to be executed.

channel.exec "ls -l /home" do |ch, success|
if success
puts "command has begun executing..."
# this is a good place to hang callbacks like #on_data...
else
puts "alas! the command could not be invoked!"
end
end

Registers a callback to be invoked when the server indicates that no more
data will be sent to the channel (although the channel can still send data
to the server). The channel is the sole argument to the callback.

Registers a callback to be invoked when extended data packets are received
by the channel. The callback is called with the channel as the first
argument, the data type (as an integer) as the second, and the data as the
third. Extended data is almost exclusively used to send stderr
data (type == 1). Other extended data types are not defined by the
SSH protocol.

Registers a callback to be invoked when the server was unable to open the
requested channel. The channel itself will be passed to the block, along
with the integer “reason code” for the failure, and a textual
description of the failure from the server.

Registers a callback to be invoked for each pass of the event loop for this
channel. There are no guarantees on timeliness in the event loop, but it
will be called roughly once for each packet received by the connection (not
the channel). This callback is invoked with the channel as the sole
argument.

Here’s an example that accumulates the channel data into a variable
on the channel itself, and displays individual lines in the input one at a
time when the channel is processed:

Registers a callback to be invoked when a channel request of the given type
is received. The callback will receive the channel as the first argument,
and the associated (unparsed) data as the second. The data will be a Net::SSH::Buffer that you will need to parse,
yourself, according to the kind of request you are watching.

By default, if the request wants a reply, Net::SSH will send a CHANNEL_SUCCESS response for
any request that was handled by a registered callback, and CHANNEL_FAILURE
for any that wasn’t, but if you want your registered callback to
result in a CHANNEL_FAILURE response, just raise Net::SSH::ChannelRequestFailed.

Some common channel requests that your programs might want to listen for
are:

“exit-status” : the exit status of the remote process will be
reported as a long integer in the data buffer, which you can grab via
data.read_long.

“exit-signal” : if the remote process died as a result of a
signal being sent to it, the signal will be reported as a string in the
data, via data.read_string. (Not all SSH
servers support this channel request type.)

If an on_process handler has been set
up, this will cause it to be invoked (passing the channel itself as an
argument). It also causes all pending output to be enqueued as CHANNEL_DATA
packets (see enqueue_pending_output).

Requests that a pseudo-tty (or “pty”) be made available for
this channel. This is useful when you want to invoke and interact with some
kind of screen-based program (e.g., vim, or some menuing system).

Note, that without a pty some programs (e.g. sudo, or subversion) on some
systems, will not be able to run interactively, and will error instead of
prompt if they ever need some user interaction.

Note, too, that when a pty is requested, user’s shell configuration
scripts (.bashrc and such) are not run by default, whereas they are run
when a pty is not present.

Sends a new channel request with the given name. The extra data
parameter must either be empty, or consist of an even number of arguments.
See Net::SSH::Buffer.from for a
description of their format. If a block is given, it is registered as a
callback for a pending request, and the packet will be flagged so that the
server knows a reply is required. If no block is given, the server will
send no response to this request. Responses, where required, will cause the
callback to be invoked with the channel as the first argument, and either
true or false as the second, depending on whether the request succeeded or
not. The meaning of “success” and “failure” in this
context is dependent on the specific request that was sent.

Sends data to the channel’s remote endpoint. This usually has the
effect of sending the given string to the remote process’ stdin
stream. Note that it does not immediately send the data across the channel,
but instead merely appends the given data to the channel’s output
buffer, preparatory to being packaged up and sent out the next time the
connection is accepting data. (A connection might not be accepting data if,
for instance, it has filled its data window and has not yet been resized by
the remote end-point.)

This will raise an exception if the channel has previously declared that no
more data will be sent (see eof!).

Syntactic sugar for requesting that a subsystem be started. Subsystems are
a way for other protocols (like SFTP) to be run, using SSH as the transport. Generally, you’ll
never need to call this directly unless you are the implementor of
something that consumes an SSH subsystem, like
SFTP.

channel.subsystem("sftp") do |ch, success|
if success
puts "subsystem successfully started"
else
puts "subsystem could not be started"
end
end