Class: Bolt::Transport::WinRM
- Defined in:
- lib/bolt/transport/winrm.rb,
lib/bolt/transport/winrm/connection.rb
Defined Under Namespace
Classes: Connection
Constant Summary collapse
- OPTIONS =
{ "cacert" => "The path to the CA certificate.", "connect-timeout" => "How long Bolt should wait when establishing connections.", "extensions" => "List of file extensions that are accepted for scripts or tasks. "\ "Scripts with these file extensions rely on the target's file type "\ "association to run. For example, if Python is installed on the system, "\ "a `.py` script runs with `python.exe`. The extensions `.ps1`, `.rb`, and "\ "`.pp` are always allowed and run via hard-coded executables.", "file-protocol" => "Which file transfer protocol to use. Either `winrm` or `smb`. Using `smb` is "\ "recommended for large file transfers.", "host" => "Host name.", "interpreters" => "A map of an extension name to the absolute path of an executable, "\ "enabling you to override the shebang defined in a task executable. The "\ "extension can optionally be specified with the `.` character (`.py` and "\ "`py` both map to a task executable `task.py`) and the extension is case "\ "sensitive. When a target's name is `localhost`, Ruby tasks run with the "\ "Bolt Ruby interpreter by default.", "password" => "Login password. **Required unless using Kerberos.**", "port" => "Connection port.", "realm" => "Kerberos realm (Active Directory domain) to authenticate against.", "smb-port" => "With file-protocol set to smb, this is the port to establish a connection on.", "ssl" => "When true, Bolt uses secure https connections for WinRM.", "ssl-verify" => "When true, verifies the targets certificate matches the cacert.", "tmpdir" => "The directory to upload and execute temporary files on the target.", "user" => "Login user. **Required unless using Kerberos.**" }.freeze
Constants inherited from Base
Base::ENVIRONMENT_METHODS, Base::STDIN_METHODS
Instance Attribute Summary
Attributes inherited from Base
Class Method Summary collapse
Instance Method Summary collapse
- #connected?(target) ⇒ Boolean
- #default_input_method(executable) ⇒ Object
-
#initialize ⇒ WinRM
constructor
A new instance of WinRM.
- #provided_features ⇒ Object
- #run_command(target, command, _options = {}) ⇒ Object
- #run_script(target, script, arguments, _options = {}) ⇒ Object
- #run_task(target, task, arguments, _options = {}) ⇒ Object
- #upload(target, source, destination, _options = {}) ⇒ Object
- #with_connection(target) ⇒ Object
Methods inherited from Base
#assert_batch_size_one, #batch_command, #batch_connected?, #batch_script, #batch_task, #batch_upload, #batches, #envify_params, filter_options, #select_implementation, #select_interpreter, #unwrap_sensitive_args, #with_events
Constructor Details
#initialize ⇒ WinRM
Returns a new instance of WinRM.
85 86 87 88 89 90 91 92 |
# File 'lib/bolt/transport/winrm.rb', line 85 def initialize super require 'winrm' require 'winrm-fs' @transport_logger = Logging.logger[::WinRM] @transport_logger.level = :warn end |
Class Method Details
.default_options ⇒ Object
41 42 43 44 45 46 47 48 |
# File 'lib/bolt/transport/winrm.rb', line 41 def self. { 'connect-timeout' => 10, 'ssl' => true, 'ssl-verify' => true, 'file-protocol' => 'winrm' } end |
.options ⇒ Object
37 38 39 |
# File 'lib/bolt/transport/winrm.rb', line 37 def self. OPTIONS.keys end |
.validate(options) ⇒ Object
59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 |
# File 'lib/bolt/transport/winrm.rb', line 59 def self.validate() ssl_flag = ['ssl'] unless !!ssl_flag == ssl_flag raise Bolt::ValidationError, 'ssl option must be a Boolean true or false' end if ssl_flag && (['file-protocol'] == 'smb') raise Bolt::ValidationError, 'SMB file transfers are not allowed with SSL enabled' end if ssl_flag && (ca_path = ['cacert']) Bolt::Util.validate_file('cacert', ca_path) end ssl_verify_flag = ['ssl-verify'] unless !!ssl_verify_flag == ssl_verify_flag raise Bolt::ValidationError, 'ssl-verify option must be a Boolean true or false' end timeout_value = ['connect-timeout'] unless timeout_value.is_a?(Integer) || timeout_value.nil? error_msg = "connect-timeout value must be an Integer, received #{timeout_value}:#{timeout_value.class}" raise Bolt::ValidationError, error_msg end end |
Instance Method Details
#connected?(target) ⇒ Boolean
207 208 209 210 211 |
# File 'lib/bolt/transport/winrm.rb', line 207 def connected?(target) with_connection(target) { true } rescue Bolt::Node::ConnectError false end |
#default_input_method(executable) ⇒ Object
54 55 56 57 |
# File 'lib/bolt/transport/winrm.rb', line 54 def default_input_method(executable) input_method ||= Powershell.powershell_file?(executable) ? 'powershell' : 'both' input_method end |
#provided_features ⇒ Object
50 51 52 |
# File 'lib/bolt/transport/winrm.rb', line 50 def provided_features ['powershell'] end |
#run_command(target, command, _options = {}) ⇒ Object
113 114 115 116 117 118 119 120 121 122 |
# File 'lib/bolt/transport/winrm.rb', line 113 def run_command(target, command, = {}) with_connection(target) do |conn| output = conn.execute(command) Bolt::Result.for_command(target, output.stdout.string, output.stderr.string, output.exit_code, 'command', command) end end |
#run_script(target, script, arguments, _options = {}) ⇒ Object
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 |
# File 'lib/bolt/transport/winrm.rb', line 124 def run_script(target, script, arguments, = {}) # unpack any Sensitive data arguments = unwrap_sensitive_args(arguments) with_connection(target) do |conn| conn.with_remote_tempdir do |dir| remote_path = conn.write_remote_executable(dir, script) if Powershell.powershell_file?(remote_path) output = conn.execute(Powershell.run_script(arguments, remote_path)) else path, args = *Powershell.process_from_extension(remote_path) args += Powershell.escape_arguments(arguments) output = conn.execute_process(path, args) end Bolt::Result.for_command(target, output.stdout.string, output.stderr.string, output.exit_code, 'script', script) end end end |
#run_task(target, task, arguments, _options = {}) ⇒ Object
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 |
# File 'lib/bolt/transport/winrm.rb', line 146 def run_task(target, task, arguments, = {}) implementation = select_implementation(target, task) executable = implementation['path'] input_method = implementation['input_method'] extra_files = implementation['files'] input_method ||= Powershell.powershell_file?(executable) ? 'powershell' : 'both' # unpack any Sensitive data arguments = unwrap_sensitive_args(arguments) with_connection(target) do |conn| conn.with_remote_tempdir do |dir| if extra_files.empty? task_dir = dir else # TODO: optimize upload of directories arguments['_installdir'] = dir task_dir = File.join(dir, task.tasks_dir) conn.mkdirs([task_dir] + extra_files.map { |file| File.join(dir, File.dirname(file['name'])) }) extra_files.each do |file| conn.write_remote_file(file['path'], File.join(dir, file['name'])) end end remote_task_path = conn.write_remote_executable(task_dir, executable) if STDIN_METHODS.include?(input_method) stdin = JSON.dump(arguments) end if ENVIRONMENT_METHODS.include?(input_method) envify_params(arguments).each do |(arg, val)| cmd = Powershell.set_env(arg, val) result = conn.execute(cmd) if result.exit_code != 0 raise Bolt::Node::EnvironmentVarError.new(arg, val) end end end conn.shell_init output = if Powershell.powershell_file?(remote_task_path) && stdin.nil? conn.execute(Powershell.run_ps_task(arguments, remote_task_path, input_method)) else if (interpreter = select_interpreter(remote_task_path, target.['interpreters'])) path = interpreter args = [remote_task_path] else path, args = *Powershell.process_from_extension(remote_task_path) end conn.execute_process(path, args, stdin) end Bolt::Result.for_task(target, output.stdout.string, output.stderr.string, output.exit_code, task.name) end end end |
#upload(target, source, destination, _options = {}) ⇒ Object
106 107 108 109 110 111 |
# File 'lib/bolt/transport/winrm.rb', line 106 def upload(target, source, destination, = {}) with_connection(target) do |conn| conn.write_remote_file(source, destination) Bolt::Result.for_upload(target, source, destination) end end |
#with_connection(target) ⇒ Object
94 95 96 97 98 99 100 101 102 103 104 |
# File 'lib/bolt/transport/winrm.rb', line 94 def with_connection(target) conn = Connection.new(target, @transport_logger) conn.connect yield conn ensure begin conn&.disconnect rescue StandardError => e logger.info("Failed to close connection to #{target.safe_name} : #{e.}") end end |