Class: Capistrano::SSH

Class | Capistrano::SSH
In: | lib/capistrano/ssh.rb lib/capistrano/ssh.rb
Parent: | Object

A helper class for dealing with SSH connections.

### Methods

connect connect connection_strategy connection_strategy

### Public Class methods

connect(server, options={})

An abstraction to make it possible to connect to the server via public key without prompting for the password. If the public key authentication fails this will fall back to password authentication.

`server` must be an instance of ServerDefinition.

If a block is given, the new session is yielded to it, otherwise the new session is returned.

If an :ssh_options key exists in `options`, it is passed to the Net::SSH constructor. Values in `options` are then merged into it, and any connection information in `server` is added last, so that `server` info takes precedence over `options`, which takes precendence over ssh_options.

[Source]

        # File lib/capistrano/ssh.rb, line 39
    39:     def self.connect(server, options={})
    40:       connection_strategy(server, options) do |host, user, connection_options|
    41:         connection = Net::SSH.start(host, user, connection_options)
    42:         Server.apply_to(connection, server)
    43:       end
    44:     end

connect(server, options={})

An abstraction to make it possible to connect to the server via public key without prompting for the password. If the public key authentication fails this will fall back to password authentication.

`server` must be an instance of ServerDefinition.

If a block is given, the new session is yielded to it, otherwise the new session is returned.

If an :ssh_options key exists in `options`, it is passed to the Net::SSH constructor. Values in `options` are then merged into it, and any connection information in `server` is added last, so that `server` info takes precedence over `options`, which takes precendence over ssh_options.

[Source]

        # File lib/capistrano/ssh.rb, line 39
    39:     def self.connect(server, options={})
    40:       connection_strategy(server, options) do |host, user, connection_options|
    41:         connection = Net::SSH.start(host, user, connection_options)
    42:         Server.apply_to(connection, server)
    43:       end
    44:     end

connection_strategy(server, options={}) {|host, user, connection_options| ...}

Abstracts the logic for establishing an SSH connection (which includes testing for connection failures and retrying with a password, and so forth, mostly made complicated because of the fact that some of these variables might be lazily evaluated and try to do something like prompt the user, which should only happen when absolutely necessary.

This will yield the hostname, username, and a hash of connection options to the given block, which should return a new connection.

[Source]

        # File lib/capistrano/ssh.rb, line 54
    54:     def self.connection_strategy(server, options={}, &block)
    55:       methods = [ %w(publickey hostbased), %w(password keyboard-interactive) ]
    56:       password_value = nil
    57:
    58:       # construct the hash of ssh options that should be passed more-or-less
    59:       # directly to Net::SSH. This will be the general ssh options, merged with
    60:       # the server-specific ssh-options.
    61:       ssh_options = (options[:ssh_options] || {}).merge(server.options[:ssh_options] || {})
    62:
    63:       # load any SSH configuration files that were specified in the SSH options. This
    64:       # will load from ~/.ssh/config and /etc/ssh_config by default (see Net::SSH
    65:       # for details). Merge the explicitly given ssh_options over the top of the info
    66:       # from the config file.
    67:       ssh_options = Net::SSH.configuration_for(server.host, ssh_options.fetch(:config, true)).merge(ssh_options)
    68:
    69:       # Once we've loaded the config, we don't need Net::SSH to do it again.
    70:       ssh_options[:config] = false
    71:
    72:       user = server.user || options[:user] || ssh_options[:username] ||
    73:              ssh_options[:user] || ServerDefinition.default_user
    74:       port = server.port || options[:port] || ssh_options[:port]
    75:
    76:       # the .ssh/config file might have changed the host-name on us
    77:       host = ssh_options.fetch(:host_name, server.host)
    78:
    79:       ssh_options[:port] = port if port
    80:
    81:       # delete these, since we've determined which username to use by this point
    82:       ssh_options.delete(:username)
    83:       ssh_options.delete(:user)
    84:
    85:       begin
    86:         connection_options = ssh_options.merge(
    87:           :password => password_value,
    88:           :auth_methods => ssh_options[:auth_methods] || methods.shift
    89:         )
    90:
    91:         yield host, user, connection_options
    92:       rescue Net::SSH::AuthenticationFailed
    93:         raise if methods.empty? || ssh_options[:auth_methods]
    94:         password_value = options[:password]
    95:         retry
    96:       end
    97:     end

connection_strategy(server, options={}) {|host, user, connection_options| ...}

Abstracts the logic for establishing an SSH connection (which includes testing for connection failures and retrying with a password, and so forth, mostly made complicated because of the fact that some of these variables might be lazily evaluated and try to do something like prompt the user, which should only happen when absolutely necessary.

This will yield the hostname, username, and a hash of connection options to the given block, which should return a new connection.

[Source]

        # File lib/capistrano/ssh.rb, line 54
    54:     def self.connection_strategy(server, options={}, &block)
    55:       methods = [ %w(publickey hostbased), %w(password keyboard-interactive) ]
    56:       password_value = nil
    57:
    58:       # construct the hash of ssh options that should be passed more-or-less
    59:       # directly to Net::SSH. This will be the general ssh options, merged with
    60:       # the server-specific ssh-options.
    61:       ssh_options = (options[:ssh_options] || {}).merge(server.options[:ssh_options] || {})
    62:
    63:       # load any SSH configuration files that were specified in the SSH options. This
    64:       # will load from ~/.ssh/config and /etc/ssh_config by default (see Net::SSH
    65:       # for details). Merge the explicitly given ssh_options over the top of the info
    66:       # from the config file.
    67:       ssh_options = Net::SSH.configuration_for(server.host, ssh_options.fetch(:config, true)).merge(ssh_options)
    68:
    69:       # Once we've loaded the config, we don't need Net::SSH to do it again.
    70:       ssh_options[:config] = false
    71:
    72:       user = server.user || options[:user] || ssh_options[:username] ||
    73:              ssh_options[:user] || ServerDefinition.default_user
    74:       port = server.port || options[:port] || ssh_options[:port]
    75:
    76:       # the .ssh/config file might have changed the host-name on us
    77:       host = ssh_options.fetch(:host_name, server.host)
    78:
    79:       ssh_options[:port] = port if port
    80:
    81:       # delete these, since we've determined which username to use by this point
    82:       ssh_options.delete(:username)
    83:       ssh_options.delete(:user)
    84:
    85:       begin
    86:         connection_options = ssh_options.merge(
    87:           :password => password_value,
    88:           :auth_methods => ssh_options[:auth_methods] || methods.shift
    89:         )
    90:
    91:         yield host, user, connection_options
    92:       rescue Net::SSH::AuthenticationFailed
    93:         raise if methods.empty? || ssh_options[:auth_methods]
    94:         password_value = options[:password]
    95:         retry
    96:       end
    97:     end

[Validate]