Method: Net::SSH.start
- Defined in:
- lib/net/ssh.rb
.start(host, user = nil, options = {}, &block) ⇒ Object
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
-
:bind_address => the IP address on the connecting machine to use in establishing connection. (:bind_address is discarded if :proxy is set.)
-
:check_host_ip => Also ckeck IP address when connecting to remote host. Defaults to
true
. -
: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 tofalse
to not load them, or to a file-name (or array of file-names) to load those specific configuration files. Defaults totrue
. -
:encryption => the encryption cipher (or ciphers) to use
-
:forward_agent => set to true if you want the SSH agent connection to be forwarded
-
:known_hosts => a custom object holding known hosts records. It must implement #search_for and ‘add` in a similiar manner as KnownHosts.
-
: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/ssh_known_hosts /etc/ssh/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. -
:keepalive => set to
true
to send a keepalive packet to the SSH server when there’s no traffic between the SSH server and Net::SSH client for the keepalive_interval seconds. Defaults tofalse
. -
:keepalive_interval => the interval seconds for keepalive. Defaults to
300
seconds. -
:keepalive_maxcount => the maximun number of keepalive packet miss allowed. Defaults to 3
-
: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
-
:keycerts => an array of file names of key certificates to use
with publickey authentication
-
:key_data => an array of strings, with each element of the array being a raw private key in PEM format.
-
:keys_only => set to
true
to use only private keys fromkeys
andkey_data
parameters, even if ssh-agent offers more identities. This option is intended for situations where ssh-agent offers many different identites. -
:logger => the logger instance to use when logging
-
:max_pkt_size => maximum size we tell the other side that is supported per packet. Default is 0x8000 (32768 bytes). Increase to 0x10000 (65536 bytes) for better performance if your SSH server supports it (most do).
-
:max_win_size => maximum size we tell the other side that is supported for the window.
-
:non_interactive => set to true if your app is non interactive and prefers authentication failure vs password prompt. Non-interactive applications should set it to true to prefer failing a password/etc auth methods vs. asking for password.
-
:paranoid => deprecated alias for :verify_host_key
-
: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
-
:pubkey_algorithms => the public key authentication algorithms to use for this connection. Valid values are ‘[email protected]’, ‘[email protected]’, ‘rsa-sha2-256’, ‘ssh-rsa’. Currently, this option is only used for RSA public key authentication and ignored for other types.
-
: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
-
:send_env => an array of local environment variable names to export to the remote environment. Names may be given as String or Regexp.
-
:set_env => a hash of environment variable names and values to set to the remote environment. Override the ones if specified in
send_env
. -
: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. -
:remote_user => used for substitution into the ‘%r’ part of a ProxyCommand
-
: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).
-
:use_agent => Set false to disable the use of ssh-agent. Defaults to true
-
:identity_agent => the path to the ssh-agent’s UNIX socket
-
: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.
-
:append_all_supported_algorithms => set to
true
to append all supported algorithms by net-ssh. Was the default behaviour until 2.10 -
:number_of_password_prompts => Number of prompts for the password authentication method defaults to 3 set to 0 to disable prompt for password auth method
-
:password_prompt => a custom prompt object with ask method. See Net::SSH::Prompt
-
:agent_socket_factory => enables the user to pass a lambda/block that will serve as the socket factory
Net::SSH.start(host,user,agent_socket_factory: ->{ UNIXSocket.open('/foo/bar') }) example: ->{ UNIXSocket.open('/foo/bar')}
-
:verify_host_key => specify how strict host-key verification should be. In order of increasing strictness:
-
:never (very insecure) ::Net::SSH::Verifiers::Never
-
:accept_new_or_local_tunnel (insecure) ::Net::SSH::Verifiers::AcceptNewOrLocalTunnel
-
:accept_new (insecure) ::Net::SSH::Verifiers::AcceptNew
-
:always (secure) ::Net::SSH::Verifiers::Always
You can also provide an own Object which responds to
verify
. The argument given toverify
is a hash consisting of the:key
, the:key_blob
, the:fingerprint
and the:session
. Returning true accepts the host key, returning false declines it and closes the connection. -
-
:fingerprint_hash => ‘MD5’ or ‘SHA256’, defaults to ‘SHA256’
If user
parameter is nil it defaults to USER from ssh_config, or local username
223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 |
# File 'lib/net/ssh.rb', line 223 def self.start(host, user = nil, = {}, &block) = .keys - VALID_OPTIONS if .any? raise ArgumentError, "invalid option(s): #{.join(', ')}" end assign_defaults() () [:user] = user if user = configuration_for(host, .fetch(:config, true)).merge() host = .fetch(:host_name, host) [:check_host_ip] = true unless .key?(:check_host_ip) if [:non_interactive] [:number_of_password_prompts] = 0 end _support_deprecated_option_paranoid() if [:verbose] [:logger].level = case [:verbose] when Integer then [:verbose] when :debug then Logger::DEBUG when :info then Logger::INFO when :warn then Logger::WARN when :error then Logger::ERROR when :fatal then Logger::FATAL else raise ArgumentError, "can't convert #{[:verbose].inspect} to any of the Logger level constants" end end transport = Transport::Session.new(host, ) auth = Authentication::Session.new(transport, ) user = .fetch(:user, user) || Etc.getpwuid.name if auth.authenticate("ssh-connection", user, [:password]) connection = Connection::Session.new(transport, ) if block_given? begin yield connection ensure connection.close unless connection.closed? end else return connection end else transport.close raise AuthenticationFailed, "Authentication failed for user #{user}@#{host}" end end |