Class: Remotus::WinrmConnection

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/remotus/winrm_connection.rb

Overview

Class representing a WinRM connection to a host

Constant Summary collapse

REMOTE_PORT =

Standard WinRM remote port

5985

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(host, port = REMOTE_PORT, host_pool: nil) ⇒ WinrmConnection

Creates a WinrmConnection

Parameters:

  • host (String) —

    hostname

  • port (Integer) (defaults to: REMOTE_PORT) —

    remote port

  • host_pool (Remotus::HostPool) (defaults to: nil) —

    associated host pool



42
43
44
45
46
47
 
# File 'lib/remotus/winrm_connection.rb', line 42

def initialize(host, port = REMOTE_PORT, host_pool: nil)
  @host = host
  @port = port
  @host_pool = host_pool
  @shell = :powershell
end

Instance Attribute Details

#host ⇒ String (readonly)

Returns host hostname.

Returns:



24
25
26
 
# File 'lib/remotus/winrm_connection.rb', line 24

def host
  @host
end

#host_pool ⇒ Remotus::HostPool (readonly)

Returns host_pool associated host pool.

Returns:



30
31
32
 
# File 'lib/remotus/winrm_connection.rb', line 30

def host_pool
  @host_pool
end

#port ⇒ Integer (readonly)

Returns Remote port.

Returns:

  • (Integer) —

    Remote port



21
22
23
 
# File 'lib/remotus/winrm_connection.rb', line 21

def port
  @port
end

#shell ⇒ String (readonly)

Returns shell type.

Returns:



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

def shell
  @shell
end

Instance Method Details

#base_connection(reload: false) ⇒ WinRM::Connection

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

Returns:

  • (WinRM::Connection) —

    base WinRM remote connection



64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/remotus/winrm_connection.rb', line 64

def base_connection(reload: false)
  return @base_connection if !reload && !restart_base_connection?

  # Close any active connections
  close

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

#close ⇒ Object

Closes the current WinRM connection if it is active



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

def close
  @connection&.close
  @connection = nil
  @base_connection = nil
end

#connection(shell = :powershell) ⇒ WinRM::Shells::Powershell, WinRM::Shells::Elevated

Retrieves/creates the WinRM shell connection for the host

If the connection already exists, the existing connection will be retrieved

Parameters:

  • shell (symbol) (defaults to: :powershell) —

    connection shell type, defaults to :powershell

Returns:



87
88
89
90
91
92
 
# File 'lib/remotus/winrm_connection.rb', line 87

def connection(shell = :powershell)
  return @connection unless restart_connection?(shell: shell)

  @shell = shell
  @connection = base_connection(reload: true).shell(@shell)
end

#download(remote_path, local_path, _options = {}) ⇒ String

Downloads a file from the remote host to the local host

Parameters:

  • remote_path (String) —

    remote path to download the file from (source)

  • local_path (String) —

    local path to download the file to (destination)

  • _options (Hash) (defaults to: {}) —

    unused download options

Returns:



169
170
171
172
173
 
# File 'lib/remotus/winrm_connection.rb', line 169

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) ⇒ Boolean

Checks if a remote file or directory exists

Parameters:

  • remote_path (String) —

    remote path to the file or directory

  • _options (Hash) —

    unused command options

Returns:

  • (Boolean) —

    true if the file or directory exists, false otherwise



183
184
185
186
 
# File 'lib/remotus/winrm_connection.rb', line 183

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? ⇒ Boolean

Whether the remote host's WinRM port is available

Returns:

  • (Boolean) —

    true if available, false otherwise



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

def port_open?
  Remotus.port_open?(remote_host, @port)
end

#run(command, *args, **options) ⇒ Remotus::Result

Runs a command on the host

Parameters:

  • command (String) —

    command to run

  • args (Array) —

    command arguments

  • options (Hash) —

    command options

Options Hash (**options):

  • :shell (Symbol) —

    shell type to use for the connection

Returns:

  • (Remotus::Result) —

    result describing the stdout, stderr, and exit status of the command



122
123
124
125
126
127
128
 
# File 'lib/remotus/winrm_connection.rb', line 122

def run(command, *args, **options)
  command = "#{command}#{args.empty? ? "" : " "}#{args.join(" ")}"
  run_result = options[:shell].nil? ? connection.run(command) : connection(options[:shell]).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) ⇒ Remotus::Result

Uploads a script and runs it on the host

Parameters:

  • local_path (String) —

    local path of the script (source)

  • remote_path (String) —

    remote path for the script (destination)

  • args (Array) —

    script arguments

  • options (Hash) —

    command options

Returns:

  • (Remotus::Result) —

    result describing the stdout, stderr, and exit status of the command



140
141
142
143
 
# File 'lib/remotus/winrm_connection.rb', line 140

def run_script(local_path, remote_path, *args, **options)
  upload(local_path, remote_path)
  run(remote_path, *args, **options)
end

#type ⇒ Symbol

Connection type

Returns:

  • (Symbol) —

    returns :winrm



54
55
56
 
# File 'lib/remotus/winrm_connection.rb', line 54

def type
  :winrm
end

#upload(local_path, remote_path, _options = {}) ⇒ String

Uploads a file from the local host to the remote host

Parameters:

  • local_path (String) —

    local path to upload the file from (source)

  • remote_path (String) —

    remote path to upload the file to (destination)

  • _options (Hash) (defaults to: {}) —

    unused upload options

Returns:



154
155
156
157
158
 
# File 'lib/remotus/winrm_connection.rb', line 154

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