Module: Remotus

Defined in:
lib/remotus.rb,
lib/remotus/auth.rb,
lib/remotus/pool.rb,
lib/remotus/logger.rb,
lib/remotus/result.rb,
lib/remotus/version.rb,
lib/remotus/host_pool.rb,
lib/remotus/auth/store.rb,
lib/remotus/ssh_connection.rb,
lib/remotus/auth/credential.rb,
lib/remotus/auth/hash_store.rb,
lib/remotus/core_ext/string.rb,
lib/remotus/winrm_connection.rb,
lib/remotus/core_ext/elevated.rb

Overview

Contains classes and methods for creating remote connections and running commands

Defined Under Namespace

Modules: Auth, CoreExt Classes: AuthenticationError, Error, HostPool, HostTypeDeterminationError, InvalidMetadataKey, Logger, MissingCredential, MissingOverride, MissingSudoPassword, Pool, PtyError, Result, ResultError, SshConnection, WinrmConnection

Constant Summary collapse

VERSION =

Remotus gem version

"1.2.0"

Class Method Summary collapse

Class Method Details

.clear ⇒ Integer

Removes all host pools from the pool in a thread-safe manner

Returns:

  • (Integer) —

    number of host pools removed



45
46
47
 
# File 'lib/remotus.rb', line 45

def self.clear
  Remotus::Pool.clear
end

.connect(host, **options) ⇒ Remotus::HostPool

Creates/gets a host pool for the host that can be used to perform remote operations. After creation, the host pool will persist for future connections.

Parameters:

  • host (String) —

    hostname

  • options (Hash) —

    options hash

Options Hash (**options):

  • :size (Integer) —

    number of connections in the pool

  • :timeout (Integer) —

    amount of time to wait for a connection from the pool

  • :port (Integer) —

    port to use for the connection

  • :proto (Symbol) —

    protocol to use for the connection (:winrm, :ssh), must be specified if port is specified

  • :ip (String) —

    IP to use for the connection, preferred over the hostname if set. This should be used if the hostname is required for credential retrieval but the hostname cannot be resolved by DNS.

Returns:



27
28
29
 
# File 'lib/remotus.rb', line 27

def self.connect(host, **options)
  Remotus::Pool.connect(host, **options)
end

.count ⇒ Integer

Number of host pools in the connection pool

Returns:

  • (Integer) —

    number of host pools



36
37
38
 
# File 'lib/remotus.rb', line 36

def self.count
  Remotus::Pool.count
end

.host_type(host, timeout: 1) ⇒ Symbol?

Determine remote host type by checking common ports

Parameters:

  • host (String) —

    hostname

  • timeout (Integer) (defaults to: 1) —

    amount of time to wait in seconds

Returns:

  • (Symbol, nil) —

    :ssh, :winrm, or nil if it cannot be determined



74
75
76
77
78
79
80
 
# File 'lib/remotus.rb', line 74

def self.host_type(host, timeout: 1)
  return :ssh if port_open?(host, SshConnection::REMOTE_PORT, timeout: timeout)

  return :winrm if port_open?(host, WinrmConnection::REMOTE_PORT, timeout: timeout)

  nil
end

.log_formatter ⇒ ::Logger::Formatter

Gets the remotus log formatter

Returns:

  • (::Logger::Formatter) —

    current log formatter



109
110
111
 
# File 'lib/remotus.rb', line 109

def self.log_formatter
  @log_formatter ||= logger.formatter
end

.log_formatter=(log_formatter) ⇒ Object

Sets the remotus log formatter

Parameters:

  • log_formatter (::Logger::Formatter) —

    new log formatter



118
119
120
121
 
# File 'lib/remotus.rb', line 118

def self.log_formatter=(log_formatter)
  @log_formatter = log_formatter
  logger.formatter = log_formatter
end

.logger ⇒ Remotus::Logger

Gets the remotus logger

Returns:



87
88
89
 
# File 'lib/remotus.rb', line 87

def self.logger
  @logger ||= Remotus::Logger.new($stdout, level: Logger::INFO)
end

.logger=(logger) ⇒ Object

Sets the remotus logger

Parameters:

  • logger (::Logger) —

    logger to set



96
97
98
99
100
101
102
 
# File 'lib/remotus.rb', line 96

def self.logger=(logger)
  if logger.nil?
    self.logger.level = Logger::FATAL
    return self.logger
  end
  @logger = logger
end

.port_open?(host, port, timeout: 1) ⇒ Boolean

Checks if a remote port is open

Parameters:

  • host (String) —

    remote host

  • port (Integer) —

    remote port

  • timeout (Integer) (defaults to: 1) —

    amount of time to wait in seconds

Returns:

  • (Boolean) —

    true if port is open, false otherwise



58
59
60
61
62
63
64
 
# File 'lib/remotus.rb', line 58

def self.port_open?(host, port, timeout: 1)
  logger.debug { "Checking if #{host}:#{port} is accessible" }
  Socket.tcp(host, port, connect_timeout: timeout) { true }
rescue StandardError
  logger.debug { "#{host}:#{port} is inaccessible" }
  false
end