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.
Net::SSH.start("host", "user", :password => "password") do |ssh|
result = ssh.exec!("ls -l")
puts result
end
Net::SSH.start("host", "user", :password => "password") do |ssh|
ssh.forward.local(1234, "www.google.com", 80)
ssh.loop { true }
end
Net::SSH.start("host", "user", :password => "password") do |ssh|
ssh.forward.remote(80, "www.google.com", 1234)
ssh.loop { true }
end
| 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. | |
| 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. | |
| 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. |
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.
# File lib/net/ssh.rb, line 205
205: def self.configuration_for(host, use_ssh_config=true)
206: files = case use_ssh_config
207: when true then Net::SSH::Config.default_files
208: when false, nil then return {}
209: else Array(use_ssh_config)
210: end
211:
212: Net::SSH::Config.for(host, files)
213: end
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.
# File lib/net/ssh.rb, line 205
205: def self.configuration_for(host, use_ssh_config=true)
206: files = case use_ssh_config
207: when true then Net::SSH::Config.default_files
208: when false, nil then return {}
209: else Array(use_ssh_config)
210: end
211:
212: Net::SSH::Config.for(host, files)
213: end
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):
# File lib/net/ssh.rb, line 152
152: def self.start(host, user, options={}, &block)
153: invalid_options = options.keys - VALID_OPTIONS
154: if invalid_options.any?
155: raise ArgumentError, "invalid option(s): #{invalid_options.join(', ')}"
156: end
157:
158: options[:user] = user if user
159: options = configuration_for(host, options.fetch(:config, true)).merge(options)
160: host = options.fetch(:host_name, host)
161:
162: if !options.key?(:logger)
163: options[:logger] = Logger.new(STDERR)
164: options[:logger].level = Logger::FATAL
165: end
166:
167: if options[:verbose]
168: options[:logger].level = case options[:verbose]
169: when Fixnum then options[:verbose]
170: when :debug then Logger::DEBUG
171: when :info then Logger::INFO
172: when :warn then Logger::WARN
173: when :error then Logger::ERROR
174: when :fatal then Logger::FATAL
175: else raise ArgumentError, "can't convert #{options[:verbose].inspect} to any of the Logger level constants"
176: end
177: end
178:
179: transport = Transport::Session.new(host, options)
180: auth = Authentication::Session.new(transport, options)
181:
182: user = options.fetch(:user, user)
183: if auth.authenticate("ssh-connection", user, options[:password])
184: connection = Connection::Session.new(transport, options)
185: if block_given?
186: yield connection
187: connection.close
188: else
189: return connection
190: end
191: else
192: raise AuthenticationFailed, user
193: end
194: end
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):
# File lib/net/ssh.rb, line 152
152: def self.start(host, user, options={}, &block)
153: invalid_options = options.keys - VALID_OPTIONS
154: if invalid_options.any?
155: raise ArgumentError, "invalid option(s): #{invalid_options.join(', ')}"
156: end
157:
158: options[:user] = user if user
159: options = configuration_for(host, options.fetch(:config, true)).merge(options)
160: host = options.fetch(:host_name, host)
161:
162: if !options.key?(:logger)
163: options[:logger] = Logger.new(STDERR)
164: options[:logger].level = Logger::FATAL
165: end
166:
167: if options[:verbose]
168: options[:logger].level = case options[:verbose]
169: when Fixnum then options[:verbose]
170: when :debug then Logger::DEBUG
171: when :info then Logger::INFO
172: when :warn then Logger::WARN
173: when :error then Logger::ERROR
174: when :fatal then Logger::FATAL
175: else raise ArgumentError, "can't convert #{options[:verbose].inspect} to any of the Logger level constants"
176: end
177: end
178:
179: transport = Transport::Session.new(host, options)
180: auth = Authentication::Session.new(transport, options)
181:
182: user = options.fetch(:user, user)
183: if auth.authenticate("ssh-connection", user, options[:password])
184: connection = Connection::Session.new(transport, options)
185: if block_given?
186: yield connection
187: connection.close
188: else
189: return connection
190: end
191: else
192: raise AuthenticationFailed, user
193: end
194: end