module Net::SSH

Net::SSH is a library for interacting, programmatically, with remote processes via the SSH2 protocol. Sessions are always initiated via Net::SSH.start. From there, a program interacts with the new SSH session via the convenience methods on Net::SSH::Connection::Session, by opening and interacting with new channels (Net::SSH::Connection:Session#open_channel and Net::SSH::Connection::Channel), or by forwarding local and/or remote ports through the connection (Net::SSH::Service::Forward).

The SSH protocol is very event-oriented. Requests are sent from the client to the server, and are answered asynchronously. This gives great flexibility (since clients can have multiple requests pending at a time), but it also adds complexity. Net::SSH tries to manage this complexity by providing some simpler methods of synchronous communication (see Net::SSH::Connection::Session#exec!).

In general, though, and if you want to do anything more complicated than simply executing commands and capturing their output, you’ll need to use channels (Net::SSH::Connection::Channel) to build state machines that are executed while the event loop runs (Net::SSH::Connection::Session#loop).

Net::SSH::Connection::Session and Net::SSH::Connection::Channel have more information about this technique.

“Um, all I want to do is X, just show me how!”

X == “execute a command and capture the output”

Net::SSH.start("host", "user", password: "password") do |ssh|
  result = ssh.exec!("ls -l")
  puts result
end

X == “forward connections on a local port to a remote host”

Net::SSH.start("host", "user", password: "password") do |ssh|
  ssh.forward.local(1234, "www.google.com", 80)
  ssh.loop { true }
end

X == “forward connections on a remote port to the local host”

Net::SSH.start("host", "user", password: "password") do |ssh|
  ssh.forward.remote(80, "www.google.com", 1234)
  ssh.loop { true }
end