winrm 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3933c15aee7afe32e53f6b10123238e00b40a41c
-  data.tar.gz: 781c8ba0280a77a5c324428f1f6b08e377142a94
+  metadata.gz: ad05b5c1fe16cfa1586a6a001022d0463e87d9cb
+  data.tar.gz: 07a2d85d2a0a9458049eaac2b23bbd68e518ae2d
 SHA512:
-  metadata.gz: 002b41189de8c7a4a3204a455ea25a720ce478f4a89816f8e4a4de143030610d433f158b757c3b971e7062ade4f5a3e948967c77a54a736a42ac8320e2f747e4
-  data.tar.gz: d2bfc89a6a58381f15371fde4ae6338f256206628d65f09ddc93df6b5b7c2a69fc9fa421fd4c8cbdf7a998bd6c71a0cb5c7fcc98b3fcaf6fb41a7f2dc3f61f4d
+  metadata.gz: c2181da8210604d6703c2f694c3388e9e8f670fba9673a3fac68b1b9d257e2f0e3412f810b3c94966a57e7035e1d1b153ee815a7b993694c71885925d6bff09e
+  data.tar.gz: 47d0c26bfab5a7f096091bf74f042ded6a25fe59683c83829907863176f5bbb337bb6b972fcc4e2d3d5977c150c65c81413c6044a23b75787b82ae8738e1fb38

data/.rubocop.yml

@@ -1,5 +1,6 @@
 AllCops:
   Exclude:
+    - 'appveyor.yml'
     - 'lib/winrm/winrm_service.rb'
 
 Style/Encoding:

data/.travis.yml

@@ -2,4 +2,6 @@ language: ruby
 rvm:
   - 1.9.3
   - 2.0.0
-  - 2.1.0
+  - 2.1.0
+before_install:
+  - gem update bundler

data/README.md

@@ -1,6 +1,7 @@
 # Windows Remote Management (WinRM) for Ruby
 [![Build Status](https://travis-ci.org/WinRb/WinRM.svg?branch=master)](https://travis-ci.org/WinRb/WinRM)
 [![Gem Version](https://badge.fury.io/rb/winrm.svg)](http://badge.fury.io/rb/winrm)
+[![Build status](https://ci.appveyor.com/api/projects/status/ods9tvos78k5c15h?svg=true)](https://ci.appveyor.com/project/winrb/winrm)
 
 This is a SOAP library that uses the functionality in Windows Remote
 Management(WinRM) to call native object in Windows.  This includes, but is
@@ -20,9 +21,11 @@ require 'winrm'
 endpoint = 'http://mywinrmhost:5985/wsman'
 krb5_realm = 'EXAMPLE.COM'
 winrm = WinRM::WinRMWebService.new(endpoint, :kerberos, :realm => krb5_realm)
-winrm.cmd('ipconfig /all') do |stdout, stderr|
-  STDOUT.print stdout
-  STDERR.print stderr
+winrm.create_executor do |executor|
+  executor.run_cmd('ipconfig /all') do |stdout, stderr|
+    STDOUT.print stdout
+    STDERR.print stderr
+  end
 end
 ```
 
@@ -30,6 +33,11 @@ There are various connection types you can specify upon initialization:
 
 It is recommended that you <code>:disable_sspi => true</code> if you are using the plaintext or ssl transport.
 
+### Deprecated methods
+As of version 1.5.0 `WinRM::WinRMWebService` methods `cmd`, `run_cmd`, `powershell`, and `run_powershell_script` have been deprecated and will be removed from the next major version of the WinRM gem.
+
+Use the `run_cmd` and `run_powershell_script` of the `WinRM::CommandExecutor` class instead. The `CommandExecutor` allows multiple commands to be run from the same WinRM shell providing a significant performance improvement when issuing multiple calls.
+
 #### Plaintext
 ```ruby
 WinRM::WinRMWebService.new(endpoint, :plaintext, :user => myuser, :pass => mypass, :disable_sspi => true)
@@ -52,10 +60,13 @@ WinRM::WinRMWebService.new(endpoint, :ssl, :user => myuser, :pass => mypass, :ba
 # Enabling no_ssl_peer_verification is not recommended. HTTPS connections are still encrypted,
 # but the WinRM gem is not able to detect forged replies or man in the middle attacks.
 WinRM::WinRMWebService.new(endpoint, :ssl, :user => myuser, :pass => mypass, :basic_auth_only => true, :no_ssl_peer_verification => true)
+
+# Verify against a known fingerprint
+WinRM::WinRMWebService.new(endpoint, :ssl, :user => myuser, :pass => mypass, :basic_auth_only => true, :ssl_peer_fingerprint => '6C04B1A997BA19454B0CD31C65D7020A6FC2669D')
 ```
 
 ##### Create a self signed cert for WinRM
-You may want to create a self signed certificate for servicing https WinRM connections. First you must install makecert.exe from the Windows SDK, then you can use the following PowerShell script to create a cert and enable the WinRM HTTPS listener.
+You may want to create a self signed certificate for servicing https WinRM connections. You can use the following PowerShell script to create a cert and enable the WinRM HTTPS listener. Unless you are running windows server 2012 R2 or later, you must install makecert.exe from the Windows SDK, otherwise use `New-SelfSignedCertificate`.
 
 ```powershell
 $hostname = $Env:ComputerName
@@ -63,6 +74,10 @@ $hostname = $Env:ComputerName
 C:\"Program Files"\"Microsoft SDKs"\Windows\v7.1\Bin\makecert.exe -r -pe -n "CN=$hostname,O=vagrant" -eku 1.3.6.1.5.5.7.3.1 -ss my -sr localMachine -sky exchange -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12 "$hostname.cer"
  
 $thumbprint = (& ls cert:LocalMachine/my).Thumbprint
+
+# Windows 2012R2 and above can use New-SelfSignedCertificate
+$thumbprint = (New-SelfSignedCertificate -DnsName $hostname -CertStoreLocation cert:\LocalMachine\my).Thumbprint
+
 $cmd = "winrm create winrm/config/Listener?Address=*+Transport=HTTPS '@{Hostname=`"$hostname`";CertificateThumbprint=`"$thumbprint`"}'"
 iex $cmd
 ```
@@ -72,6 +87,29 @@ iex $cmd
 WinRM::WinRMWebService.new(endpoint, :kerberos, :realm => 'MYREALM.COM')
 ```
 
+## Retries and opening a shell
+Especially if provisioning a new machine, it's possible the winrm service is not yet running when first attempting to connect. The `WinRMWebService` accepts the options `:retry_limit` and `:retry_delay` to specify the maximum number of attempts to make and how long to wait in between. These default to 3 attempts and a 10 second delay.
+```ruby
+WinRM::WinRMWebService.new(endpoint, :ssl, :user => myuser, :pass => mypass, :retry_limit => 30, :retry_delay => 10)
+```
+
+## Logging
+The `WinRMWebService` exposes a `logger` attribute and uses the [logging](https://rubygems.org/gems/logging) gem to manage logging behavior. By default this appends to `STDOUT` and has a level of `:warn`, but one can adjust the level or add additional appenders.
+```ruby
+winrm = WinRM::WinRMWebService.new(endpoint, :ssl, :user => myuser, :pass => mypass)
+
+# suppress warnings
+winrm.logger.warn = :error
+
+# Log to a file
+winrm.logger.add_appenders(Logging.appenders.file('error.log'))
+```
+
+If a consuming application uses its own logger that complies to the logging API, you can simply swap it in:
+```ruby
+winrm.logger = my_logger
+```
+
 ## Troubleshooting
 You may have some errors like ```WinRM::WinRMAuthorizationError```.
 You can run the following commands on the server to try to solve the problem:
@@ -82,6 +120,8 @@ winrm set winrm/config/service @{AllowUnencrypted="true"}
 ```
 You can read more about that on issue [#29](https://github.com/WinRb/WinRM/issues/29)
 
+Also see [this post](http://www.hurryupandwait.io/blog/understanding-and-troubleshooting-winrm-connection-and-authentication-a-thrill-seekers-guide-to-adventure) for more general tips related to winrm connection and authentication issues.
+
 
 ## Current features
 
@@ -128,7 +168,7 @@ Once you have the dependencies, you can run the unit tests with `rake`:
 $ bundle exec rake spec
 ```
 
-To run the integration tests you will need a Windows box with the WinRM service properly configured. Its easiest to use a Vagrant Windows box.
+To run the integration tests you will need a Windows box with the WinRM service properly configured. Its easiest to use a Vagrant Windows box (mwrock/Windows2012R2 is public on [atlas](https://atlas.hashicorp.com/mwrock/boxes/Windows2012R2) with an evaluation version of Windows 2012 R2).
 
 1. Create a Windows VM with WinRM configured (see above).
 2. Copy the config-example.yml to config.yml - edit this file with your WinRM connection details.

data/appveyor.yml

@@ -0,0 +1,51 @@
+version: "master-{build}"
+
+os: Windows Server 2012 R2
+platform:
+  - x64
+
+environment:
+  winrm_user: test_user
+  winrm_pass: Pass@word1
+
+  matrix:
+    - ruby_version: "21"
+      winrm_endpoint: http://localhost:5985/wsman
+
+    - ruby_version: "21"
+      winrm_auth_type: ssl
+      winrm_endpoint: https://localhost:5986/wsman
+      winrm_no_ssl_peer_verification: true
+
+    - ruby_version: "21"
+      winrm_auth_type: ssl
+      winrm_endpoint: https://localhost:5986/wsman
+      use_ssl_peer_fingerprint: true
+
+clone_folder: c:\projects\winrm
+clone_depth: 1
+branches:
+  only:
+    - master
+
+install:
+  - ps: net user /add $env:winrm_user $env:winrm_pass
+  - ps: net localgroup administrators $env:winrm_user /add
+  - ps: $env:winrm_cert = (New-SelfSignedCertificate -DnsName localhost -CertStoreLocation cert:\localmachine\my).Thumbprint
+  - ps: winrm create winrm/config/Listener?Address=*+Transport=HTTPS "@{Hostname=`"localhost`";CertificateThumbprint=`"$($env:winrm_cert)`"}"
+  - ps: winrm set winrm/config/client/auth '@{Basic="true"}'
+  - ps: winrm set winrm/config/service/auth '@{Basic="true"}'
+  - ps: winrm set winrm/config/service '@{AllowUnencrypted="true"}'
+  - ps: $env:PATH="C:\Ruby$env:ruby_version\bin;$env:PATH"
+  - ps: Write-Host $env:PATH
+  - ps: ruby --version
+  - ps: gem --version
+  - ps: gem install bundler --quiet --no-ri --no-rdoc
+  - ps: bundler --version
+
+build_script:
+  - bundle install || bundle install || bundle install
+
+test_script:
+  - SET SPEC_OPTS=--format progress
+  - bundle exec rake integration

data/changelog.md

@@ -1,5 +1,14 @@
 # WinRM Gem Changelog
 
+# 1.5.0
+- Deprecating `WinRM::WinRMWebService` methods `cmd`, `run_cmd`, `powershell`, and `run_powershell_script` in favor of the `run_cmd` and `run_powershell_script` methods of the `WinRM::CommandExecutor` class. The `CommandExecutor` allows multiple commands to be run from the same WinRM shell providing a significant performance improvement when issuing multiple calls.
+- Added an `:ssl_peer_fingerprint` option to be used instead of `:no_ssl_peer_verification` and allows a specific certificate to be verified.
+- Opening a winrm shell is retriable with configurable delay and retry limit.
+- Logging apends to `stdout` by default and can be replaced with a logger from a consuming application.
+
+# 1.4.0
+- Added WinRM::Version so the gem version is available at runtime for consumers.
+
 # 1.3.6
 - Remove BOM from response (Issue #159) added by Windows 2008R2
 

data/lib/winrm/command_executor.rb

@@ -0,0 +1,242 @@
+# -*- encoding: utf-8 -*-
+#
+# Copyright 2015 Shawn Neal <sneal@sneal.net>
+# Copyright 2015 Matt Wrock <matt@mattwrock.com>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module WinRM
+  # Object which can execute multiple commands and Powershell scripts in
+  # one shared remote shell session. The maximum number of commands per
+  # shell is determined by interrogating the remote host when the session
+  # is opened and the remote shell is automatically recycled before the
+  # threshold is reached.
+  #
+  # @author Shawn Neal <sneal@sneal.net>
+  # @author Matt Wrock <matt@mattwrock.com>
+  # @author Fletcher Nichol <fnichol@nichol.ca>
+  class CommandExecutor
+    # Closes an open remote shell session left open
+    # after a command executor is garbage collecyted.
+    #
+    # @param shell_id [String] the remote shell identifier
+    # @param service [WinRM::WinRMWebService] a winrm web service object
+    def self.finalize(shell_id, service)
+      proc { service.close_shell(shell_id) }
+    end
+
+    # @return [Integer,nil] the safe maximum number of commands that can
+    #   be executed in one remote shell session, or `nil` if the
+    #   threshold has not yet been determined
+    attr_reader :max_commands
+
+    # @return [WinRM::WinRMWebService] a WinRM web service object
+    attr_reader :service
+
+    # @return [String,nil] the identifier for the current open remote
+    #   shell session, or `nil` if the session is not open
+    attr_reader :shell
+
+    # Creates a CommandExecutor given a `WinRM::WinRMWebService` object.
+    #
+    # @param service [WinRM::WinRMWebService] a winrm web service object
+    #   responds to `#debug` and `#info` (default: `nil`)
+    def initialize(service)
+      @service = service
+      @logger = service.logger
+      @command_count = 0
+    end
+
+    # Closes the open remote shell session. This method can be called
+    # multiple times, even if there is no open session.
+    def close
+      return if shell.nil?
+
+      service.close_shell(shell)
+      remove_finalizer
+      @shell = nil
+    end
+
+    # Opens a remote shell session for reuse. The maxiumum
+    # command-per-shell threshold is also determined the first time this
+    # method is invoked and cached for later invocations.
+    #
+    # @return [String] the remote shell session indentifier
+    def open
+      close
+      retryable(service.retry_limit, service.retry_delay) { @shell = service.open_shell }
+      add_finalizer(shell)
+      @command_count = 0
+      determine_max_commands unless max_commands
+      shell
+    end
+
+    # Runs a CMD command.
+    #
+    # @param command [String] the command to run on the remote system
+    # @param arguments [Array<String>] arguments to the command
+    # @yield [stdout, stderr] yields more live access the standard
+    #   output and standard error streams as they are returns, if
+    #   streaming behavior is desired
+    # @return [WinRM::Output] output object with stdout, stderr, and
+    #   exit code
+    def run_cmd(command, arguments = [], &block)
+      reset if command_count_exceeded?
+      ensure_open_shell!
+
+      @command_count += 1
+      result = nil
+      service.run_command(shell, command, arguments) do |command_id|
+        result = service.get_command_output(shell, command_id, &block)
+      end
+      result
+    end
+
+    # Run a Powershell script that resides on the local box.
+    #
+    # @param script_file [IO,String] an IO reference for reading the
+    #   Powershell script or the actual file contents
+    # @yield [stdout, stderr] yields more live access the standard
+    #   output and standard error streams as they are returns, if
+    #   streaming behavior is desired
+    # @return [WinRM::Output] output object with stdout, stderr, and
+    #   exit code
+    def run_powershell_script(script_file, &block)
+      # this code looks overly compact in an attempt to limit local
+      # variable assignments that may contain large strings and
+      # consequently bloat the Ruby VM
+      run_cmd(
+        'powershell',
+        [
+          '-encodedCommand',
+          ::WinRM::PowershellScript.new(
+            safe_script(script_file.is_a?(IO) ? script_file.read : script_file)
+          ).encoded
+        ],
+        &block
+      )
+    end
+
+    private
+
+    # @return [Integer] the default maximum number of commands which can be
+    #   executed in one remote shell session on "older" versions of Windows
+    # @api private
+    LEGACY_LIMIT = 15
+
+    # @return [Integer] the default maximum number of commands which can be
+    #   executed in one remote shell session on "modern" versions of Windows
+    # @api private
+    MODERN_LIMIT = 1500
+
+    # @return [String] the PowerShell command used to determine the version
+    #   of Windows
+    # @api private
+    PS1_OS_VERSION = '[environment]::OSVersion.Version.tostring()'.freeze
+
+    # @return [Integer] the number of executed commands on the remote
+    #   shell session
+    # @api private
+    attr_accessor :command_count
+
+    # @return [#debug,#info] the logger
+    # @api private
+    attr_reader :logger
+
+    # Creates a finalizer for this connection which will close the open
+    # remote shell session when the object is garabage collected or on
+    # Ruby VM shutdown.
+    #
+    # @param shell_id [String] the remote shell identifier
+    # @api private
+    def add_finalizer(shell_id)
+      ObjectSpace.define_finalizer(self, self.class.finalize(shell_id, service))
+    end
+
+    # @return [true,false] whether or not the number of exeecuted commands
+    #   have exceeded the maxiumum threshold
+    # @api private
+    def command_count_exceeded?
+      command_count > max_commands.to_i
+    end
+
+    # Ensures that there is an open remote shell session.
+    #
+    # @raise [WinRM::WinRMError] if there is no open shell
+    # @api private
+    def ensure_open_shell!
+      fail ::WinRM::WinRMError, "#{self.class}#open must be called " \
+        'before any run methods are invoked' if shell.nil?
+    end
+
+    # Determines the safe maximum number of commands that can be executed
+    # on a remote shell session by interrogating the remote host.
+    #
+    # @api private
+    def determine_max_commands
+      os_version = run_powershell_script(PS1_OS_VERSION).stdout.chomp
+      @max_commands = os_version < '6.2' ? LEGACY_LIMIT : MODERN_LIMIT
+      @max_commands -= 2 # to be safe
+    end
+
+    # Removes any finalizers for this connection.
+    #
+    # @api private
+    def remove_finalizer
+      ObjectSpace.undefine_finalizer(self)
+    end
+
+    # Closes the remote shell session and opens a new one.
+    #
+    # @api private
+    def reset
+      logger.debug("Resetting WinRM shell (Max command limit is #{max_commands})")
+      open
+    end
+
+    # Yields to a block and reties the block if certain rescuable
+    # exceptions are raised.
+    #
+    # @param retries [Integer] the number of times to retry before failing
+    # @option delay [Float] the number of seconds to wait until
+    #   attempting a retry
+    # @api private
+    def retryable(retries, delay)
+      yield
+    rescue *RESCUE_EXCEPTIONS_ON_ESTABLISH.call => e
+      if (retries -= 1) > 0
+        logger.info("[WinRM] connection failed. retrying in #{delay} seconds (#{e.inspect})")
+        sleep(delay)
+        retry
+      else
+        logger.warn("[WinRM] connection failed, terminating (#{e.inspect})")
+        raise
+      end
+    end
+
+    RESCUE_EXCEPTIONS_ON_ESTABLISH = lambda do
+      [
+        Errno::EACCES, Errno::EADDRINUSE, Errno::ECONNREFUSED,
+        Errno::ECONNRESET, Errno::ENETUNREACH, Errno::EHOSTUNREACH,
+        ::WinRM::WinRMHTTPTransportError, ::WinRM::WinRMAuthorizationError,
+        HTTPClient::KeepAliveDisconnected,
+        HTTPClient::ConnectTimeoutError
+      ].freeze
+    end
+
+    # suppress the progress stream from leaking to stderr
+    def safe_script(script)
+      "$ProgressPreference='SilentlyContinue';" + script
+    end
+  end
+end

data/lib/winrm/http/transport.rb

@@ -40,12 +40,13 @@ module WinRM
       # @param [String] The XML SOAP message
       # @returns [REXML::Document] The parsed response body
       def send_request(message)
+        ssl_peer_fingerprint_verification!
         log_soap_message(message)
-        hdr = {
-          'Content-Type' => 'application/soap+xml;charset=UTF-8',
-          'Content-Length' => message.length }
+        hdr = { 'Content-Type' => 'application/soap+xml;charset=UTF-8',
+                'Content-Length' => message.length }
         resp = @httpcli.post(@endpoint, message, hdr)
         log_soap_message(resp.http_body.content)
+        verify_ssl_fingerprint(resp.peer_cert)
         handler = WinRM::ResponseHandler.new(resp.http_body.content, resp.status)
         handler.parse_to_xml
       end
@@ -67,6 +68,41 @@ module WinRM
         @httpcli.ssl_config.verify_mode = OpenSSL::SSL::VERIFY_NONE
       end
 
+      # SSL Peer Fingerprint Verification prior to connecting
+      def ssl_peer_fingerprint_verification!
+        return unless @ssl_peer_fingerprint && ! @ssl_peer_fingerprint_verified
+
+        with_untrusted_ssl_connection do |connection|
+          connection_cert = connection.peer_cert_chain.last
+          verify_ssl_fingerprint(connection_cert)
+        end
+        @logger.info("initial ssl fingerprint #{@ssl_peer_fingerprint} verified\n")
+        @ssl_peer_fingerprint_verified = true
+        no_ssl_peer_verification!
+      end
+
+      # Connect without verification to retrieve untrusted ssl context
+      def with_untrusted_ssl_connection
+        noverify_peer_context = OpenSSL::SSL::SSLContext.new
+        noverify_peer_context.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        tcp_connection = TCPSocket.new(@endpoint.host, @endpoint.port)
+        begin
+          ssl_connection = OpenSSL::SSL::SSLSocket.new(tcp_connection, noverify_peer_context)
+          ssl_connection.connect
+          yield ssl_connection
+        ensure
+          tcp_connection.close
+        end
+      end
+
+      # compare @ssl_peer_fingerprint to current ssl context
+      def verify_ssl_fingerprint(cert)
+        return unless @ssl_peer_fingerprint
+        conn_fingerprint = OpenSSL::Digest::SHA1.new(cert.to_der).to_s
+        return unless @ssl_peer_fingerprint.casecmp(conn_fingerprint) != 0
+        fail "ssl fingerprint mismatch!!!!\n"
+      end
+
       # HTTP Client receive timeout. How long should a remote call wait for a
       # for a response from WinRM?
       def receive_timeout=(sec)
@@ -112,6 +148,7 @@ module WinRM
         no_sspi_auth! if opts[:disable_sspi]
         basic_auth_only! if opts[:basic_auth_only]
         no_ssl_peer_verification! if opts[:no_ssl_peer_verification]
+        @ssl_peer_fingerprint = opts[:ssl_peer_fingerprint]
       end
     end
 

data/lib/winrm/version.rb

@@ -3,5 +3,5 @@
 # WinRM module
 module WinRM
   # The version of the WinRM library
-  VERSION = '1.4.0'
+  VERSION = '1.5.0'
 end

data/lib/winrm/winrm_service.rb

@@ -16,6 +16,7 @@
 
 require 'nori'
 require 'rexml/document'
+require 'winrm/command_executor'
 require_relative 'helpers/powershell_script'
 
 module WinRM
@@ -26,7 +27,9 @@ module WinRM
     DEFAULT_MAX_ENV_SIZE = 153600
     DEFAULT_LOCALE = 'en-US'
 
-    attr_reader :endpoint, :timeout
+    attr_reader :endpoint, :timeout, :retry_limit, :retry_delay
+
+    attr_accessor :logger
 
     # @param [String,URI] endpoint the WinRM webservice endpoint
     # @param [Symbol] transport either :kerberos(default)/:ssl/:plaintext
@@ -39,7 +42,8 @@ module WinRM
       @timeout = DEFAULT_TIMEOUT
       @max_env_sz = DEFAULT_MAX_ENV_SIZE
       @locale = DEFAULT_LOCALE
-      @logger = Logging.logger[self]
+      setup_logger
+      configure_retries(opts)
       case transport
       when :kerberos
         require 'gssapi'
@@ -94,6 +98,7 @@ module WinRM
     #   :env_vars => {:myvar1 => 'val1', :myvar2 => 'var2'}
     # @return [String] The ShellId from the SOAP response.  This is our open shell instance on the remote machine.
     def open_shell(shell_opts = {}, &block)
+      logger.debug("[WinRM] opening remote shell on #{@endpoint}")
       i_stream = shell_opts.has_key?(:i_stream) ? shell_opts[:i_stream] : 'stdin'
       o_stream = shell_opts.has_key?(:o_stream) ? shell_opts[:o_stream] : 'stdout stderr'
       codepage = shell_opts.has_key?(:codepage) ? shell_opts[:codepage] : 65001 # utf8 as default codepage (from https://msdn.microsoft.com/en-us/library/dd317756(VS.85).aspx)
@@ -125,6 +130,7 @@ module WinRM
 
       resp_doc = send_message(builder.target!)
       shell_id = REXML::XPath.first(resp_doc, "//*[@Name='ShellId']").text
+      logger.debug("[WinRM] remote shell #{shell_id} is open on #{@endpoint}")
 
       if block_given?
         begin
@@ -279,6 +285,7 @@ module WinRM
     # @param [String] shell_id The shell id on the remote machine.  See #open_shell
     # @return [true] This should have more error checking but it just returns true for now.
     def close_shell(shell_id)
+      logger.debug("[WinRM] closing remote shell #{shell_id} on #{@endpoint}")
       builder = Builder::XmlMarkup.new
       builder.instruct!(:xml, :encoding => 'UTF-8')
 
@@ -288,38 +295,57 @@ module WinRM
       end
 
       resp = send_message(builder.target!)
+      logger.debug("[WinRM] remote shell #{shell_id} closed")
       true
     end
 
+    # DEPRECATED: Use WinRM::CommandExecutor#run_cmd instead
     # Run a CMD command
     # @param [String] command The command to run on the remote system
     # @param [Array <String>] arguments arguments to the command
     # @param [String] an existing and open shell id to reuse
     # @return [Hash] :stdout and :stderr
     def run_cmd(command, arguments = [], &block)
-      command_output = nil
-      open_shell do |shell_id|
-        run_command(shell_id, command, arguments) do |command_id|
-          command_output = get_command_output(shell_id, command_id, &block)
-        end
+      logger.warn("WinRM::WinRMWebService#run_cmd is deprecated. Use WinRM::CommandExecutor#run_cmd instead")
+      create_executor do |executor|
+        executor.run_cmd(command, arguments, &block)
       end
-      command_output
     end
     alias :cmd :run_cmd
 
-
+    # DEPRECATED: Use WinRM::CommandExecutor#run_powershell_script instead
     # Run a Powershell script that resides on the local box.
     # @param [IO,String] script_file an IO reference for reading the Powershell script or the actual file contents
     # @param [String] an existing and open shell id to reuse
     # @return [Hash] :stdout and :stderr
     def run_powershell_script(script_file, &block)
-      # if an IO object is passed read it..otherwise assume the contents of the file were passed
-      script_text = script_file.respond_to?(:read) ? script_file.read : script_file
-      script = WinRM::PowershellScript.new(script_text)
-      run_cmd("powershell -encodedCommand #{script.encoded()}", &block)
+      logger.warn("WinRM::WinRMWebService#run_powershell_script is deprecated. Use WinRM::CommandExecutor#run_cmd instead")
+      create_executor do |executor|
+        executor.run_powershell_script(script_file, &block)
+      end
     end
     alias :powershell :run_powershell_script
 
+    # Creates a CommandExecutor initialized with this WinRMWebService
+    # If called with a block, create_executor yields an executor and
+    # ensures that the executor is closed after the block completes.
+    # The CommandExecutor is simply returned if no block is given.
+    # @yieldparam [CommandExecutor] a CommandExecutor instance
+    # @return [CommandExecutor] a CommandExecutor instance
+    def create_executor(&block)
+      executor = CommandExecutor.new(self)
+      executor.open
+
+      if block_given?
+        begin
+          yield executor
+        ensure
+          executor.close
+        end
+      else
+        executor
+      end
+    end
 
     # Run a WQL Query
     # @see http://msdn.microsoft.com/en-us/library/aa394606(VS.85).aspx
@@ -362,12 +388,23 @@ module WinRM
     alias :wql :run_wql
 
     def toggle_nori_type_casting(to)
-      @logger.warn('toggle_nori_type_casting is deprecated and has no effect, ' +
+      logger.warn('toggle_nori_type_casting is deprecated and has no effect, ' +
         'please remove calls to it')
     end
 
     private
 
+    def setup_logger
+      @logger = Logging.logger[self]
+      @logger.level = :warn
+      @logger.add_appenders(Logging.appenders.stdout)
+    end
+
+    def configure_retries(opts)
+      @retry_delay = opts[:retry_delay] || 10
+      @retry_limit = opts[:retry_limit] || 3
+    end
+
     def namespaces
       {
         'xmlns:xsd' => 'http://www.w3.org/2001/XMLSchema',

data/spec/command_executor_spec.rb

@@ -0,0 +1,440 @@
+# -*- encoding: utf-8 -*-
+#
+# Author:: Fletcher (<fnichol@nichol.ca>)
+#
+# Copyright (C) 2015, Fletcher Nichol
+#
+# Licensed under the Apache License, Version 2.0 (the 'License');
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an 'AS IS' BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'winrm/command_executor'
+
+require 'base64'
+require 'securerandom'
+
+describe WinRM::CommandExecutor, unit: true do
+  let(:logged_output)   { StringIO.new }
+  let(:shell_id)        { 'shell-123' }
+  let(:executor_args)   { [service, logger] }
+  let(:executor) { WinRM::CommandExecutor.new(service) }
+  let(:service) do
+    double(
+      'winrm_service',
+      logger: Logging.logger['test'],
+      retry_limit: 1,
+      retry_delay: 1
+    )
+  end
+
+  let(:version_output) do
+    o = ::WinRM::Output.new
+    o[:exitcode] = 0
+    o[:data].concat([{ stdout: '6.3.9600.0\r\n' }])
+    o
+  end
+
+  before do
+    allow(service).to receive(:open_shell).and_return(shell_id)
+
+    stub_powershell_script(
+      shell_id,
+      "$ProgressPreference='SilentlyContinue';[environment]::OSVersion.Version.tostring()",
+      version_output
+    )
+  end
+
+  describe '#close' do
+    it 'calls service#close_shell' do
+      executor.open
+      expect(service).to receive(:close_shell).with(shell_id)
+
+      executor.close
+    end
+
+    it 'only calls service#close_shell once for multiple calls' do
+      executor.open
+      expect(service).to receive(:close_shell).with(shell_id).once
+
+      executor.close
+      executor.close
+      executor.close
+    end
+
+    it 'undefines finalizer' do
+      allow(service).to receive(:close_shell)
+      allow(ObjectSpace).to receive(:define_finalizer) { |e, _| e == executor }
+      expect(ObjectSpace).to receive(:undefine_finalizer).with(executor)
+      executor.open
+
+      executor.close
+    end
+  end
+
+  describe '#open' do
+    it 'calls service#open_shell' do
+      expect(service).to receive(:open_shell).and_return(shell_id)
+
+      executor.open
+    end
+
+    it 'defines a finalizer' do
+      expect(ObjectSpace).to receive(:define_finalizer) do |e, _|
+        expect(e).to eq(executor)
+      end
+
+      executor.open
+    end
+
+    it 'returns a shell id as a string' do
+      expect(executor.open).to eq shell_id
+    end
+
+    describe 'failed connection attempts' do
+      let(:error) { HTTPClient::ConnectTimeoutError }
+      let(:limit) { 3 }
+      let(:delay) { 0.1 }
+
+      before do
+        allow(service).to receive(:open_shell).and_raise(error)
+        allow(service).to receive(:retry_delay).and_return(delay)
+        allow(service).to receive(:retry_limit).and_return(limit)
+      end
+
+      it 'attempts to connect :retry_limit times' do
+        begin
+          allow(service).to receive(:open_shell).exactly.times(limit)
+          executor.open
+        rescue # rubocop:disable Lint/HandleExceptions
+          # the raise is not what is being tested here, rather its side-effect
+        end
+      end
+
+      it 'raises the inner error after retries' do
+        expect { executor.open }.to raise_error(error)
+      end
+    end
+
+    describe 'for modern windows distributions' do
+      let(:version_output) do
+        o = ::WinRM::Output.new
+        o[:exitcode] = 0
+        o[:data].concat([{ stdout: '6.3.9600.0\r\n' }])
+        o
+      end
+
+      it 'sets #max_commands to 1500 - 2' do
+        expect(executor.max_commands).to eq nil
+        executor.open
+
+        expect(executor.max_commands).to eq(1500 - 2)
+      end
+    end
+
+    describe 'for older/legacy windows distributions' do
+      let(:version_output) do
+        o = ::WinRM::Output.new
+        o[:exitcode] = 0
+        o[:data].concat([{ stdout: '6.1.8500.0\r\n' }])
+        o
+      end
+
+      it 'sets #max_commands to 15 - 2' do
+        expect(executor.max_commands).to eq nil
+        executor.open
+
+        expect(executor.max_commands).to eq(15 - 2)
+      end
+    end
+  end
+
+  describe '#run_cmd' do
+    describe 'when #open has not been previously called' do
+      it 'raises a WinRMError error' do
+        expect { executor.run_cmd('nope') }.to raise_error(
+          ::WinRM::WinRMError,
+          "#{executor.class}#open must be called before any run methods are invoked"
+        )
+      end
+    end
+
+    describe 'when #open has been previously called' do
+      let(:command_id) { 'command-123' }
+
+      let(:echo_output) do
+        o = ::WinRM::Output.new
+        o[:exitcode] = 0
+        o[:data].concat([
+          { stdout: 'Hello\r\n' },
+          { stderr: 'Psst\r\n' }
+        ])
+        o
+      end
+
+      before do
+        stub_cmd(shell_id, 'echo', ['Hello'], echo_output, command_id)
+
+        executor.open
+      end
+
+      it 'calls service#run_command' do
+        expect(service).to receive(:run_command).with(shell_id, 'echo', ['Hello'])
+
+        executor.run_cmd('echo', ['Hello'])
+      end
+
+      it 'calls service#get_command_output to get results' do
+        expect(service).to receive(:get_command_output).with(shell_id, command_id)
+
+        executor.run_cmd('echo', ['Hello'])
+      end
+
+      it 'calls service#get_command_output with a block to get results' do
+        blk = proc { |_, _| 'something' }
+        expect(service).to receive(:get_command_output).with(shell_id, command_id, &blk)
+
+        executor.run_cmd('echo', ['Hello'], &blk)
+      end
+
+      it 'returns an Output object hash' do
+        expect(executor.run_cmd('echo', ['Hello'])).to eq echo_output
+      end
+
+      it 'runs the block  in #get_command_output when given' do
+        io_out = StringIO.new
+        io_err = StringIO.new
+        stub_cmd(
+          shell_id,
+          'echo',
+          ['Hello'],
+          echo_output,
+          command_id
+        ).and_yield(echo_output.stdout, echo_output.stderr)
+        output = executor.run_cmd('echo', ['Hello']) do |stdout, stderr|
+          io_out << stdout if stdout
+          io_err << stderr if stderr
+        end
+
+        expect(io_out.string).to eq 'Hello\r\n'
+        expect(io_err.string).to eq 'Psst\r\n'
+        expect(output).to eq echo_output
+      end
+    end
+
+    describe 'when called many times over time' do
+      # use a 'old' version of windows with lower max_commands threshold
+      # to trigger quicker shell recyles
+      let(:version_output) do
+        o = ::WinRM::Output.new
+        o[:exitcode] = 0
+        o[:data].concat([{ stdout: '6.1.8500.0\r\n' }])
+        o
+      end
+
+      let(:echo_output) do
+        o = ::WinRM::Output.new
+        o[:exitcode] = 0
+        o[:data].concat([{ stdout: 'Hello\r\n' }])
+        o
+      end
+
+      before do
+        allow(service).to receive(:open_shell).and_return('s1', 's2')
+        allow(service).to receive(:close_shell)
+        allow(service).to receive(:run_command).and_yield('command-xxx')
+        allow(service).to receive(:get_command_output).and_return(echo_output)
+        stub_powershell_script(
+          's1',
+          "$ProgressPreference='SilentlyContinue';[environment]::OSVersion.Version.tostring()",
+          version_output
+        )
+      end
+
+      it 'resets the shell when #max_commands threshold is tripped' do
+        iterations = 35
+        reset_times = iterations / (15 - 2)
+
+        expect(service).to receive(:close_shell).exactly(reset_times).times
+        executor.open
+        iterations.times { executor.run_cmd('echo', ['Hello']) }
+      end
+    end
+  end
+
+  describe '#run_powershell_script' do
+    describe 'when #open has not been previously called' do
+      it 'raises a WinRMError error' do
+        expect { executor.run_powershell_script('nope') }.to raise_error(
+          ::WinRM::WinRMError,
+          "#{executor.class}#open must be called before any run methods are invoked"
+        )
+      end
+    end
+
+    describe 'when #open has been previously called' do
+      let(:command_id) { 'command-123' }
+
+      let(:echo_output) do
+        o = ::WinRM::Output.new
+        o[:exitcode] = 0
+        o[:data].concat([
+          { stdout: 'Hello\r\n' },
+          { stderr: 'Psst\r\n' }
+        ])
+        o
+      end
+
+      before do
+        stub_powershell_script(
+          shell_id,
+          "$ProgressPreference='SilentlyContinue';echo Hello",
+          echo_output,
+          command_id
+        )
+
+        executor.open
+      end
+
+      it 'calls service#run_command' do
+        expect(service).to receive(:run_command).with(
+          shell_id,
+          'powershell',
+          [
+            '-encodedCommand',
+            ::WinRM::PowershellScript.new("$ProgressPreference='SilentlyContinue';echo Hello")
+              .encoded
+          ]
+        )
+
+        executor.run_powershell_script('echo Hello')
+      end
+
+      it 'calls service#get_command_output to get results' do
+        expect(service).to receive(:get_command_output).with(shell_id, command_id)
+
+        executor.run_powershell_script('echo Hello')
+      end
+
+      it 'calls service#get_command_output with a block to get results' do
+        blk = proc { |_, _| 'something' }
+        expect(service).to receive(:get_command_output).with(shell_id, command_id, &blk)
+
+        executor.run_powershell_script('echo Hello', &blk)
+      end
+
+      it 'returns an Output object hash' do
+        expect(executor.run_powershell_script('echo Hello')).to eq echo_output
+      end
+
+      it 'runs the block  in #get_command_output when given' do
+        io_out = StringIO.new
+        io_err = StringIO.new
+        stub_cmd(shell_id, 'echo', ['Hello'], echo_output, command_id)
+          .and_yield(echo_output.stdout, echo_output.stderr)
+        output = executor.run_powershell_script('echo Hello') do |stdout, stderr|
+          io_out << stdout if stdout
+          io_err << stderr if stderr
+        end
+
+        expect(io_out.string).to eq 'Hello\r\n'
+        expect(io_err.string).to eq 'Psst\r\n'
+        expect(output).to eq echo_output
+      end
+    end
+
+    describe 'when called many times over time' do
+      # use a 'old' version of windows with lower max_commands threshold
+      # to trigger quicker shell recyles
+      let(:version_output) do
+        o = ::WinRM::Output.new
+        o[:exitcode] = 0
+        o[:data].concat([{ stdout: '6.1.8500.0\r\n' }])
+        o
+      end
+
+      let(:echo_output) do
+        o = ::WinRM::Output.new
+        o[:exitcode] = 0
+        o[:data].concat([{ stdout: 'Hello\r\n' }])
+        o
+      end
+
+      before do
+        allow(service).to receive(:open_shell).and_return('s1', 's2')
+        allow(service).to receive(:close_shell)
+        allow(service).to receive(:run_command).and_yield('command-xxx')
+        allow(service).to receive(:get_command_output).and_return(echo_output)
+        stub_powershell_script(
+          's1',
+          "$ProgressPreference='SilentlyContinue';[environment]::OSVersion.Version.tostring()",
+          version_output
+        )
+      end
+
+      it 'resets the shell when #max_commands threshold is tripped' do
+        iterations = 35
+        reset_times = iterations / (15 - 2)
+
+        expect(service).to receive(:close_shell).exactly(reset_times).times
+        executor.open
+        iterations.times { executor.run_powershell_script('echo Hello') }
+      end
+    end
+  end
+
+  describe '#shell' do
+    it 'is initially nil' do
+      expect(executor.shell).to eq nil
+    end
+
+    it 'is set after #open is called' do
+      executor.open
+
+      expect(executor.shell).to eq shell_id
+    end
+  end
+
+  def decode(powershell)
+    Base64.strict_decode64(powershell).encode('UTF-8', 'UTF-16LE')
+  end
+
+  def debug_line_with(msg)
+    /^D, .* : #{Regexp.escape(msg)}/
+  end
+
+  def regexify(string)
+    Regexp.new(Regexp.escape(string))
+  end
+
+  def regexify_line(string)
+    Regexp.new("^#{Regexp.escape(string)}$")
+  end
+
+  # rubocop:disable Metrics/ParameterLists
+  def stub_cmd(shell_id, cmd, args, output, command_id = nil, &block)
+    command_id ||= SecureRandom.uuid
+
+    allow(service).to receive(:run_command).with(shell_id, cmd, args).and_yield(command_id)
+    allow(service).to receive(:get_command_output).with(shell_id, command_id, &block)
+      .and_return(output)
+  end
+
+  def stub_powershell_script(shell_id, script, output, command_id = nil)
+    stub_cmd(
+      shell_id,
+      'powershell',
+      ['-encodedCommand', ::WinRM::PowershellScript.new(script).encoded],
+      output,
+      command_id
+    )
+  end
+  # rubocop:enable Metrics/ParameterLists
+end

data/spec/issue_59_spec.rb

@@ -6,10 +6,10 @@ describe 'issue 59', integration: true do
 
   describe 'long running script without output' do
     it 'should not error' do
-      output = @winrm.powershell('sleep 60; Write-Host "Hello"')
-      expect(output).to have_exit_code 0
-      expect(output).to have_stdout_match(/Hello/)
-      expect(output).to have_no_stderr
+      out = @winrm.powershell('$ProgressPreference="SilentlyContinue";sleep 60; Write-Host "Hello"')
+      expect(out).to have_exit_code 0
+      expect(out).to have_stdout_match(/Hello/)
+      expect(out).to have_no_stderr
     end
   end
 end

data/spec/powershell_spec.rb

@@ -4,12 +4,6 @@ describe 'winrm client powershell', integration: true do
     @winrm = winrm_connection
   end
 
-  describe 'empty string' do
-    subject(:output) { @winrm.powershell('') }
-    it { should have_exit_code 4_294_770_688 }
-    it { should have_stderr_match(/Cannot process the command because of a missing parameter/) }
-  end
-
   describe 'ipconfig' do
     subject(:output) { @winrm.powershell('ipconfig') }
     it { should have_exit_code 0 }

data/spec/spec_helper.rb

@@ -7,13 +7,39 @@ require_relative 'matchers'
 
 # Creates a WinRM connection for integration tests
 module ConnectionHelper
+  # rubocop:disable AbcSize
   def winrm_connection
-    config = symbolize_keys(YAML.load(File.read(winrm_config_path)))
-    config[:options].merge!(basic_auth_only: true) unless config[:auth_type].eql? :kerberos
     winrm = WinRM::WinRMWebService.new(
       config[:endpoint], config[:auth_type].to_sym, config[:options])
+    winrm.logger.level = :error
     winrm
   end
+  # rubocop:enable AbcSize
+
+  def config
+    @config ||= begin
+      cfg = symbolize_keys(YAML.load(File.read(winrm_config_path)))
+      cfg[:options].merge!(basic_auth_only: true) unless cfg[:auth_type].eql? :kerberos
+      merge_environment!(cfg)
+      cfg
+    end
+  end
+
+  def merge_environment!(config)
+    merge_config_option_from_environment(config, 'user')
+    merge_config_option_from_environment(config, 'pass')
+    merge_config_option_from_environment(config, 'no_ssl_peer_verification')
+    if ENV['use_ssl_peer_fingerprint']
+      config[:options][:ssl_peer_fingerprint] = ENV['winrm_cert']
+    end
+    config[:endpoint] = ENV['winrm_endpoint'] if ENV['winrm_endpoint']
+    config[:auth_type] = ENV['winrm_auth_type'] if ENV['winrm_auth_type']
+  end
+
+  def merge_config_option_from_environment(config, key)
+    env_key = 'winrm_' + key
+    config[:options][key.to_sym] = ENV[env_key] if ENV[env_key]
+  end
 
   def winrm_config_path
     # Copy config-example.yml to config.yml and edit for your local configuration

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: winrm
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Dan Wanek
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-12-09 00:00:00.000000000 Z
+date: 2016-01-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: gssapi
@@ -198,9 +198,11 @@ files:
 - README.md
 - Rakefile
 - Vagrantfile
+- appveyor.yml
 - bin/rwinrm
 - changelog.md
 - lib/winrm.rb
+- lib/winrm/command_executor.rb
 - lib/winrm/exceptions/exceptions.rb
 - lib/winrm/helpers/iso8601_duration.rb
 - lib/winrm/helpers/powershell_script.rb
@@ -213,6 +215,7 @@ files:
 - preamble
 - spec/auth_timeout_spec.rb
 - spec/cmd_spec.rb
+- spec/command_executor_spec.rb
 - spec/config-example.yml
 - spec/exception_spec.rb
 - spec/issue_59_spec.rb
@@ -254,7 +257,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: Ruby library for Windows Remote Management