class Remotus::WinrmConnection

Class representing a WinRM connection to a host

Constants

REMOTE_PORT

Standard WinRM remote port

Attributes

host[R]

@return [String] host hostname

host_pool[R]

@return [Remotus::HostPool] host_pool associated host pool

port[R]

@return [Integer] Remote port

Public Class Methods

new(host, port = REMOTE_PORT, host_pool: nil) click to toggle source

Creates a WinrmConnection

@param [String] host hostname @param [Integer] port remote port @param [Remotus::HostPool] host_pool associated host pool

# File lib/remotus/winrm_connection.rb, line 37
def initialize(host, port = REMOTE_PORT, host_pool: nil)
  @host = host
  @port = port
  @host_pool = host_pool
end

Public Instance Methods

base_connection(reload: false) click to toggle source

Retrieves/creates the base WinRM connection for the host If the base connection already exists, the existing connection will be retrieved

@return [WinRM::Connection] base WinRM remote connection

# File lib/remotus/winrm_connection.rb, line 58
def base_connection(reload: false)
  return @base_connection if !reload && !restart_base_connection?

  Remotus.logger.debug { "Initializing WinRM connection to #{Remotus::Auth.credential(self).user}@#{@host}:#{@port}" }
  @base_connection = WinRM::Connection.new(
    endpoint: "http://#{@host}:#{@port}/wsman",
    transport: :negotiate,
    user: Remotus::Auth.credential(self).user,
    password: Remotus::Auth.credential(self).password
  )
end
connection() click to toggle source

Retrieves/creates the WinRM shell connection for the host If the connection already exists, the existing connection will be retrieved

@return [WinRM::Shells::Powershell] remote connection

# File lib/remotus/winrm_connection.rb, line 76
def connection
  return @connection unless restart_connection?

  @connection = base_connection(reload: true).shell(:powershell)
end
download(remote_path, local_path, _options = {}) click to toggle source

Downloads a file from the remote host to the local host

@param [String] remote_path remote path to download the file from (source) @param [String] local_path local path to download the file to (destination) @param [Hash] _options unused download options

@return [String] local path

# File lib/remotus/winrm_connection.rb, line 147
def download(remote_path, local_path, _options = {})
  Remotus.logger.debug { "Downloading file #{local_path} from #{@host}:#{remote_path}" }
  WinRM::FS::FileManager.new(base_connection).download(remote_path, local_path)
  local_path
end
file_exist?(remote_path, **_options) click to toggle source

Checks if a remote file or directory exists

@param [String] remote_path remote path to the file or directory @param [Hash] _options unused command options

@return [Boolean] true if the file or directory exists, false otherwise

# File lib/remotus/winrm_connection.rb, line 161
def file_exist?(remote_path, **_options)
  Remotus.logger.debug { "Checking if file #{remote_path} exists on #{@host}" }
  WinRM::FS::FileManager.new(base_connection).exists?(remote_path)
end
port_open?() click to toggle source

Whether the remote host's WinRM port is available

@return [Boolean] true if available, false otherwise

# File lib/remotus/winrm_connection.rb, line 87
def port_open?
  Remotus.port_open?(@host, @port)
end
run(command, *args, **_options) click to toggle source

Runs a command on the host

@param [String] command command to run @param [Array] args command arguments @param [Hash] _options unused command options

@return [Remotus::Result] result describing the stdout, stderr, and exit status of the command

# File lib/remotus/winrm_connection.rb, line 100
def run(command, *args, **_options)
  command = "#{command}#{args.empty? ? "" : " "}#{args.join(" ")}"
  run_result = connection.run(command)
  Remotus::Result.new(command, run_result.stdout, run_result.stderr, run_result.output, run_result.exitcode)
rescue WinRM::WinRMAuthorizationError => e
  raise Remotus::AuthenticationError, e.to_s
end
run_script(local_path, remote_path, *args, **options) click to toggle source

Uploads a script and runs it on the host

@param [String] local_path local path of the script (source) @param [String] remote_path remote path for the script (destination) @param [Array] args script arguments @param [Hash] options command options

@return [Remotus::Result] result describing the stdout, stderr, and exit status of the command

# File lib/remotus/winrm_connection.rb, line 118
def run_script(local_path, remote_path, *args, **options)
  upload(local_path, remote_path)
  run(remote_path, *args, **options)
end
type() click to toggle source

Connection type

@return [Symbol] returns :winrm

# File lib/remotus/winrm_connection.rb, line 48
def type
  :winrm
end
upload(local_path, remote_path, _options = {}) click to toggle source

Uploads a file from the local host to the remote host

@param [String] local_path local path to upload the file from (source) @param [String] remote_path remote path to upload the file to (destination) @param [Hash] _options unused upload options

@return [String] remote path

# File lib/remotus/winrm_connection.rb, line 132
def upload(local_path, remote_path, _options = {})
  Remotus.logger.debug { "Uploading file #{local_path} to #{@host}:#{remote_path}" }
  WinRM::FS::FileManager.new(base_connection).upload(local_path, remote_path)
  remote_path
end

Private Instance Methods

restart_base_connection?() click to toggle source

Whether to restart the current WinRM base connection

@return [Boolean] whether to restart the current base connection

# File lib/remotus/winrm_connection.rb, line 173
def restart_base_connection?
  return restart_connection? if @connection
  return true unless @base_connection
  return true if @host != @base_connection.instance_values["connection_opts"][:endpoint].scan(%r{//(.*):}).flatten.first
  return true if Remotus::Auth.credential(self).user != @base_connection.instance_values["connection_opts"][:user]
  return true if Remotus::Auth.credential(self).password != @base_connection.instance_values["connection_opts"][:password]

  false
end
restart_connection?() click to toggle source

Whether to restart the current WinRM connection

@return [Boolean] whether to restart the current connection

# File lib/remotus/winrm_connection.rb, line 188
def restart_connection?
  return true unless @connection
  return true if @host != @connection.connection_opts[:endpoint].scan(%r{//(.*):}).flatten.first
  return true if Remotus::Auth.credential(self).user != @connection.connection_opts[:user]
  return true if Remotus::Auth.credential(self).password != @connection.connection_opts[:password]

  false
end