Module: Net::SSH

Module | Net::SSH
In: | lib/net/ssh.rb lib/net/ssh/authentication/agent.rb lib/net/ssh/authentication/constants.rb lib/net/ssh/authentication/key_manager.rb lib/net/ssh/authentication/methods/abstract.rb lib/net/ssh/authentication/methods/hostbased.rb lib/net/ssh/authentication/methods/keyboard_interactive.rb lib/net/ssh/authentication/methods/password.rb lib/net/ssh/authentication/methods/publickey.rb lib/net/ssh/authentication/pageant.rb lib/net/ssh/authentication/session.rb lib/net/ssh/buffer.rb lib/net/ssh/buffered_io.rb lib/net/ssh/config.rb lib/net/ssh/connection/channel.rb lib/net/ssh/connection/constants.rb lib/net/ssh/connection/session.rb lib/net/ssh/connection/term.rb lib/net/ssh/errors.rb lib/net/ssh/key_factory.rb lib/net/ssh/known_hosts.rb lib/net/ssh/loggable.rb lib/net/ssh/packet.rb lib/net/ssh/prompt.rb lib/net/ssh/proxy/errors.rb lib/net/ssh/proxy/http.rb lib/net/ssh/proxy/socks4.rb lib/net/ssh/proxy/socks5.rb lib/net/ssh/ruby_compat.rb lib/net/ssh/service/forward.rb lib/net/ssh/test.rb lib/net/ssh/test/channel.rb lib/net/ssh/test/extensions.rb lib/net/ssh/test/kex.rb lib/net/ssh/test/local_packet.rb lib/net/ssh/test/packet.rb lib/net/ssh/test/remote_packet.rb lib/net/ssh/test/script.rb lib/net/ssh/test/socket.rb lib/net/ssh/transport/algorithms.rb lib/net/ssh/transport/cipher_factory.rb lib/net/ssh/transport/constants.rb lib/net/ssh/transport/hmac/abstract.rb lib/net/ssh/transport/identity_cipher.rb lib/net/ssh/transport/kex/diffie_hellman_group1_sha1.rb lib/net/ssh/transport/packet_stream.rb lib/net/ssh/transport/server_version.rb lib/net/ssh/transport/session.rb lib/net/ssh/transport/state.rb lib/net/ssh/verifiers/lenient.rb lib/net/ssh/verifiers/null.rb lib/net/ssh/verifiers/strict.rb lib/net/ssh/version.rb

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

### Methods

configuration_for start

### Classes and Modules

Module Net::SSH::Authentication
Module Net::SSH::BufferedIo
Module Net::SSH::Connection
Module Net::SSH::Loggable
Module Net::SSH::PromptMethods
Module Net::SSH::Proxy
Module Net::SSH::Service
Module Net::SSH::Test
Module Net::SSH::Transport
Module Net::SSH::Verifiers
Class Net::SSH::AuthenticationFailed
Class Net::SSH::Buffer
Class Net::SSH::ChannelOpenFailed
Class Net::SSH::ChannelRequestFailed
Class Net::SSH::Compat
Class Net::SSH::Config
Class Net::SSH::Disconnect
Class Net::SSH::Exception
Class Net::SSH::HostKeyMismatch
Class Net::SSH::KeyFactory
Class Net::SSH::KnownHosts
Class Net::SSH::Packet
Class Net::SSH::Version

### Constants

VALID_OPTIONS | = | [ :auth_methods, :compression, :compression_level, :config, :encryption, :forward_agent, :hmac, :host_key, :kex, :keys, :key_data, :languages, :logger, :paranoid, :password, :port, :proxy, :rekey_blocks_limit, :rekey_limit, :rekey_packet_limit, :timeout, :verbose, :global_known_hosts_file, :user_known_hosts_file, :host_key_alias, :host_name, :user, :properties, :passphrase |  | This is the set of options that Net::SSH.start recognizes. See Net::SSH.start for a description of each option.
Prompt | = | begin require 'highline' |  | Try to load Highline and Termios in turn, selecting the corresponding PromptMethods module to use. If neither are available, choose PromptMethods::Clear.

### Public Class methods

configuration_for(host, use_ssh_config=true)

Returns a hash of the configuration options for the given host, as read from the SSH configuration file(s). If `use_ssh_config` is true (the default), this will load configuration from both ~/.ssh/config and /etc/ssh_config. If `use_ssh_config` is nil or false, nothing will be loaded (and an empty hash returned). Otherwise, `use_ssh_config` may be a file name (or array of file names) of SSH configuration file(s) to read.

See Net::SSH::Config for the full description of all supported options.

start(host, user, options={}) {|connection| ...}

The standard means of starting a new SSH connection. When used with a block, the connection will be closed when the block terminates, otherwise the connection will just be returned. The yielded (or returned) value will be an instance of Net::SSH::Connection::Session (q.v.). (See also Net::SSH::Connection::Channel and Net::SSH::Service::Forward.)

      Net::SSH.start("host", "user") do |ssh|
        ssh.exec! "cp /some/file /another/location"
        hostname = ssh.exec!("hostname")

        ssh.open_channel do |ch|
          ch.exec "sudo -p 'sudo password: ' ls" do |ch, success|
            abort "could not execute sudo ls" unless success

            ch.on_data do |ch, data|
              print data
              if data =~ /sudo password: /
                ch.send_data("password\n")
              end
            end
          end
        end

        ssh.loop
      end

This method accepts the following options (all are optional):

- :auth_methods => an array of authentication methods to try
- :compression => the compression algorithm to use, or `true` to use whatever is supported.
- :compression_level => the compression level to use when sending data
- :config => set to `true` to load the default OpenSSH config files (~/.ssh/config, /etc/ssh_config), or to `false` to not load them, or to a file-name (or array of file-names) to load those specific configuration files. Defaults to `true`.
- :encryption => the encryption cipher (or ciphers) to use
- :forward_agent => set to true if you want the SSH agent connection to be forwarded
- :global_known_hosts_file => the location of the global known hosts file. Set to an array if you want to specify multiple global known hosts files. Defaults to %w(/etc/ssh/known_hosts /etc/ssh/known_hosts2).
- :hmac => the hmac algorithm (or algorithms) to use
- :host_key => the host key algorithm (or algorithms) to use
- :host_key_alias => the host name to use when looking up or adding a host to a known_hosts dictionary file
- :host_name => the real host name or IP to log into. This is used instead of the `host` parameter, and is primarily only useful when specified in an SSH configuration file. It lets you specify an "alias", similarly to adding an entry in /etc/hosts but without needing to modify /etc/hosts.
- :kex => the key exchange algorithm (or algorithms) to use
- :keys => an array of file names of private keys to use for publickey and hostbased authentication
- :key_data => an array of strings, with each element of the array being a raw private key in PEM format.
- :logger => the logger instance to use when logging
- :paranoid => either true, false, or :very, specifying how strict host-key verification should be
- :passphrase => the passphrase to use when loading a private key (default is `nil`, for no passphrase)
- :password => the password to use to login
- :port => the port to use when connecting to the remote host
- :properties => a hash of key/value pairs to add to the new connection‘s properties (see Net::SSH::Connection::Session#properties)
- :proxy => a proxy instance (see Proxy) to use when connecting
- :rekey_blocks_limit => the max number of blocks to process before rekeying
- :rekey_limit => the max number of bytes to process before rekeying
- :rekey_packet_limit => the max number of packets to process before rekeying
- :timeout => how long to wait for the initial connection to be made
- :user => the user name to log in as; this overrides the `user` parameter, and is primarily only useful when provided via an SSH configuration file.
- :user_known_hosts_file => the location of the user known hosts file. Set to an array to specify multiple user known hosts files. Defaults to %w(~/.ssh/known_hosts ~/.ssh/known_hosts2).
- :verbose => how verbose to be (Logger verbosity constants, Logger::DEBUG is very verbose, Logger::FATAL is all but silent). Logger::FATAL is the default. The symbols :debug, :info, :warn, :error, and :fatal are also supported and are translated to the corresponding Logger constant.

[Validate]