class Net::SSH::Connection::Session

A session class representing the connection service running on top of the
SSH transport layer. It manages the creation
of channels (see open_channel), and the
dispatching of messages to the various channels. It also encapsulates the
SSH event loop (via loop and process), and serves as a central
point-of-reference for all SSH-related services (e.g. port forwarding,
SFTP, SCP, etc.).

You will rarely (if ever) need to instantiate this class directly; rather,
you'll almost always use Net::SSH.start to initialize a new
network connection, authenticate a user, and return a new connection
session, all in one call.

Net::SSH.start("localhost", "user") do|ssh|# 'ssh' is an instance of Net::SSH::Connection::Sessionssh.exec!"/etc/init.d/some_process start"end

Constants

DEFAULT_IO_SELECT_TIMEOUT

Default IO.select timeout threshold

MAP

Attributes

options[R]

The map of options that were used to initialize this instance.

properties[R]

The collection of custom properties for this instance. (See [] and []=).

Returns true if there are any channels currently active on
this session. By default, this will not include “invisible” channels (such
as those created by forwarding ports and such), but if you pass a
true value for include_invisible, then those will
be counted.

This can be useful for determining whether the event loop should continue
to be run.

Returns true if the underlying transport has been closed. Note that this
can be a little misleading, since if the remote server has closed the
connection, the local end will still think it is open until the next
operation on the socket. Nevertheless, this method can be useful if you
just want to know if you have closed the connection.

A convenience method for executing a command and interacting with it. If no
block is given, all output is printed via $stdout and $stderr. Otherwise,
the block is called for each data and extended data packet, with three
arguments: the channel object, a symbol indicating the data type (:stdout
or :stderr), and the data (as a string).

Note that this method returns immediately, and requires an event loop (see
#loop) in order for the command to
actually execute.

The main event loop. Calls process until process returns false. If a block
is given, it is passed to process, otherwise a default proc
is used that just returns true if there are any channels active (see busy?). The # wait
parameter is also passed through to process (where it is interpreted
as the maximum number of seconds to wait for IO.select to return).

# loop for as long as there are any channels activessh.loop# loop for as long as there are any channels active, but make sure# the event loop runs at least once per 0.1 secondssh.loop(0.1)
# loop until ctrl-C is pressedint_pressed = falsetrap("INT") { int_pressed = true }
ssh.loop(0.1) { notint_pressed }

Registers a handler to be invoked when the server sends a global request of
the given type. The callback receives the request data as the first
parameter, and true/false as the second (indicating whether a response is
required). If the callback sends the response, it should return :sent.
Otherwise, if it returns true, REQUEST_SUCCESS will be sent, and if it
returns false, REQUEST_FAILURE will be sent.

Registers a handler to be invoked when the server wants to open a channel
on the client. The callback receives the connection object, the new channel
object, and the packet itself as arguments, and should raise ChannelOpenFailed if it is unable to
open the channel for some reason. Otherwise, the channel will be opened and
a confirmation message sent to the server.

This is used by the Net::SSH::Service::Forward service to
open a channel when a remote forwarded port receives a connection. However,
you are welcome to register handlers for other channel types, as needed.

Requests that a new channel be opened. By default, the channel will be of
type “session”, but if you know what you're doing you can select any of
the channel types supported by the SSH
protocol. The extra parameters must be even in number and
conform to the same format as described for Net::SSH::Buffer.from. If a
callback is given, it will be invoked when the server confirms that the
channel opened successfully. The sole parameter for the callback is the
channel object itself.

In general, you'll use open_channel without any
arguments; the only time you'd want to set the channel type or pass
additional initialization data is if you were implementing an SSH extension.

This is called internally as part of process. It dispatches any
available incoming packets, and then runs Net::SSH::Connection::Channel#process
for any active channels. If a block is given, it is invoked at the start of
the method and again at the end, and if the block ever returns false, this
method returns false. Otherwise, it returns true.

The core of the event loop. It processes a single iteration of the event
loop. If a block is given, it should return false when the processing
should abort, which causes process to return false.
Otherwise, process returns
true. The session itself is yielded to the block as its only argument.

If wait is nil (the default), this method will block until any
of the monitored IO objects are ready to be read from or written to. If you
want it to not block, you can pass 0, or you can pass any other numeric
value to indicate that it should block for no more than that many seconds.
Passing 0 is a good way to poll the connection, but if you do it too
frequently it can make your CPU quite busy!

Send a global request of the given type. The extra parameters
must be even in number, and conform to the same format as described for Net::SSH::Buffer.from. If a
callback is not specified, the request will not require a response from the
server, otherwise the server is required to respond and indicate whether
the request was successful or not. This success or failure is indicated by
the callback being invoked, with the first parameter being true or false
(success, or failure), and the second being the packet itself.

Generally, Net::SSH will manage global
requests that need to be sent (e.g. port forward requests and such are
handled in the Net::SSH::Service::Forward class, for
instance). However, there may be times when you need to send a global
request that isn't explicitly handled by Net::SSH, and so this method is available to you.

Enqueues a message to be sent to the server as soon as the socket is
available for writing. Most programs will never need to call this, but if
you are implementing an extension to the SSH
protocol, or if you need to send a packet that Net::SSH does not directly support, you can use
this to send it.

Performs a “hard” shutdown of the connection. In general, this should never
be done, but it might be necessary (in a rescue clause, for instance, when
the connection needs to close but you don't know the status of the
underlying protocol's state).