winrm 1.3.0.dev.2 → 1.3.0.dev.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cd79ebba5bae6d5d3a3149b46ec99c8bef9ddfac
-  data.tar.gz: 080075faa797bbfacd52383b8f5c3847ce1f6ee4
+  metadata.gz: 19e0ee9ca403a8fe7b5385edd2a055e040aa69fe
+  data.tar.gz: 7c66ac5aa2b9b02fa2245f52f1f61f770f929287
 SHA512:
-  metadata.gz: 37c993dab7b631fd83e13eb9dffcd0aec1c9769c9ff21af1bbe1ba8e8db88a2e7b94c2174096e591268525f9ff942be8a4dc8b47a57e9f3fb77f47bb4403cd1b
-  data.tar.gz: 68589e411195257d6380409938e5ee311d5001f747d5727f96f95df4c0a044c4d975b4fdfcc4ece08d8e0fd28359b6a01adb0a1efa19aacf5dc7aecefb0fd47d
+  metadata.gz: d2e8e8dddd4eb89fb2a19ff72ee2413cd39599c6c7198e1b8d3761f095739631ab73bb11467073d555a9fa059a723c081ce0d3d91188f2176143c65461770801
+  data.tar.gz: dcbd77c85f639859fdfbd60ba9a26b82ef7676139f9878853b8c4d64a85f8a1bff5e6051acb6f96d6c268025ed901ee7e7a054f4197886893e95954ed07de55a

data/.gitignore

@@ -8,3 +8,4 @@ spec/spec/creds*.json
 spec/config.yml
 traces/
 Gemfile.lock
+.vagrant

data/README.md

@@ -73,21 +73,29 @@ WinRM::WinRMWebService.new(endpoint, :kerberos, :realm => 'MYREALM.COM')
 ```
 
 ### Uploading files
-Files may be copied from the local machine to the winrm endpoint. Individual files or directories may be specified:
+Files may be copied from the local machine to the winrm endpoint. Individual
+files or directories may be specified:
 ```ruby
-WinRM::FileTransfer.upload(client, 'c:/dev/my_dir', '$env:AppData')
+service = WinRM::WinRMWebService.new(...
+file_manager = WinRM::FileManager.new(service)
+file_manager.upload('c:/dev/my_dir', '$env:AppData')
 ```
 Or an array of several files and/or directories can be included:
 ```ruby
-WinRM::FileTransfer.upload(client, ['c:/dev/file1.txt','c:/dev/dir1'], '$env:AppData')
+file_manager.upload(['c:/dev/file1.txt','c:/dev/dir1'], '$env:AppData')
 ```
-**Note**:The winrm protocol poseses some limitations that can adversely affect the performance of large file transfers. By default, the above upload call will display a progress bar to indicate the progress of a file transfer currently underway. This progress bar can be suppressed by setting the `:quiet` option to `true`:
+
+#### Handling progress events
+If you want to implemnt your own custom progress handling, you can pass a code
+block and use the proggress data that `upload` yields to this block:
 ```ruby
-WinRM::FileTransfer.upload(client, 'c:/dev/my_dir', '$env:AppData', :quiet => true)
+file_manager.upload('c:/dev/my_dir', '$env:AppData') do |bytes_copied, total_bytes, local_path, remote_path|
+  puts "#{bytes_copied}bytes of #{total_bytes}bytes copied"
+end
 ```
 
 ## Troubleshooting
-You may have some errors like ```WinRM::WinRMHTTPTransportError: Bad HTTP response returned from server (401).```.
+You may have some errors like ```WinRM::WinRMAuthorizationError```.
 You can run the following commands on the server to try to solve the problem:
 ```
 winrm set winrm/config/client/auth @{Basic="true"}

data/Rakefile

@@ -21,4 +21,6 @@ RSpec::Core::RakeTask.new(:integration) do |task|
   task.rspec_opts << '-tintegration'
 end
 
-task :default => "spec"
+task :default => :spec
+
+task :all => [:spec, :integration]

data/VERSION

@@ -1 +1 @@
-1.3.0.dev.2
+1.3.0.dev.3

data/Vagrantfile

@@ -0,0 +1,8 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+VAGRANTFILE_API_VERSION = "2"
+
+Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
+  config.vm.box = "mwrock/Windows2012R2"
+end

data/bin/rwinrm

@@ -17,82 +17,48 @@
 $:.push File.expand_path('../../lib', __FILE__)
 
 require 'readline'
-require 'optparse'
+require 'io/console'
 require 'winrm'
 
+def help_msg
+  puts "Usage: rwinrm user@host"
+  puts ""
+end
+
 def parse_options
   options = {}
+  raise "Missing required options" unless ARGV.length == 1
+  
+  m = /^(?<user>\w+)@{1}(?<host>[a-zA-Z0-9\.]+)(?<port>:[0-9]+)?/.match(ARGV[0])
+  raise "#{ARGV[0]} is an invalid host" unless m
+  options[:user] = m[:user]
+  options[:endpoint] = "http://#{m[:host]}#{m[:port] || ':5985'}/wsman"
+
+  # Get the password
+  print "Password: "
+  options[:pass] = STDIN.noecho(&:gets).chomp
+  puts
+
+  # Set some defaults required by WinRM WS
   options[:auth_type] = :plaintext
   options[:basic_auth_only] = true
-  options[:mode] = :repl
-
-  optparse = OptionParser.new do |opts|
-    opts.banner = "Usage: rwinrm [command] [local_path] [remote_path] endpoint [options]"
-    opts.separator  ""
-    opts.separator  "Commands"
-    opts.separator  "     repl(default)"
-    opts.separator  "     upload"
-    opts.separator  ""
-    opts.separator  "Options"
-
-    opts.on('-u', '--user username', String, 'WinRM user name') do |v|
-      options[:user] = v
-    end
-
-    opts.on('-p', '--pass password', String, 'WinRM user password') do |v|
-      options[:pass] = v
-    end
-
-    opts.on('-h', '--help', 'Display this screen') do
-      puts optparse
-      exit
-    end
-  end
-
-  optparse.parse!
-
-  if ARGV[0] && ARGV[0].downcase !~ /\A#{URI::regexp(['http', 'https'])}\z/
-    options[:mode] = ARGV.shift.downcase.to_sym
-
-    case options[:mode]
-    when :upload
-      options[:local_path] = ARGV.shift
-      options[:remote_path] = ARGV.shift
-
-      raise OptionParser::MissingArgument.new(:local_path) if options[:local_path].nil?
-      raise OptionParser::MissingArgument.new(:remote_path) if options[:remote_path].nil?
-    when :repl
-    else
-      raise OptionParser::InvalidArgument.new(options[:mode])
-    end
-  end
-  options[:endpoint] = ARGV.shift
-
-  raise OptionParser::MissingArgument.new(:endpoint) if options[:endpoint].nil?
 
   options
-rescue OptionParser::InvalidOption, OptionParser::MissingArgument, OptionParser::InvalidArgument
-  puts $!.message
-  puts optparse
+rescue StandardError => e
+  puts e.message
+  help_msg
   exit 1
 end
 
-def winrm_client(options)
-  WinRM::WinRMWebService.new(
-      options[:endpoint],
-      options[:auth_type].to_sym,
-      options)
-end
+def repl(options)
+  client = WinRM::WinRMWebService.new(
+    options[:endpoint],
+    options[:auth_type].to_sym,
+    options)
 
-def upload(client, options)
-  bytes = WinRM::FileTransfer.upload(client, options[:local_path], options[:remote_path])
+  client.set_timeout(3600)
   shell_id = client.open_shell()
-  puts "#{bytes} total bytes transfered"
-end
-
-def repl(client, options)
-  shell_id = client.open_shell()
-  command_id = client.run_command(shell_id, 'cmd')
+  command_id = client.run_command(shell_id, 'cmd', "/K prompt [#{ARGV[0]}]$P$G")
 
   read_thread = Thread.new do
     client.get_command_output(shell_id, command_id) do |stdout, stderr|
@@ -100,6 +66,7 @@ def repl(client, options)
       STDERR.write stderr
     end
   end
+  read_thread.abort_on_exception = true
 
   while buf = Readline.readline('', true)
     if buf =~ /^exit/
@@ -111,17 +78,14 @@ def repl(client, options)
       client.write_stdin(shell_id, command_id, "#{buf}\r\n")
     end
   end
-end
-
-def run(options)
-  client = winrm_client(options)
-  method(options[:mode]).call(client, options)
-  exit 0
 rescue Interrupt
   # ctrl-c
+rescue WinRM::WinRMAuthorizationError
+  puts "Authentication failed, bad user name or password"
+  exit 1
 rescue StandardError => e
   puts e.message
   exit 1
 end
 
-run(parse_options())
+repl(parse_options())

data/lib/winrm/exceptions/exceptions.rb

@@ -20,7 +20,11 @@ module WinRM
   # Authorization Error
   class WinRMAuthorizationError < WinRMError; end
 
-  class WinRMUploadFailed < WinRMError; end
+  # Error that occurs when a file upload fails
+  class WinRMUploadError < WinRMError; end
+
+  # Error that occurs when a file download fails
+  class WinRMDownloadError < WinRMError; end
 
   # A Fault returned in the SOAP response. The XML node is a WSManFault
   class WinRMWSManFault < WinRMError
@@ -34,6 +38,18 @@ module WinRM
     end
   end
 
+  # A Fault returned in the SOAP response. The XML node is a MSFT_WmiError
+  class WinRMWMIError < WinRMError
+    attr_reader :error_code
+    attr_reader :error
+
+    def initialize(error, error_code)
+      @error = error
+      @error_code = error_code
+      super("[WMI ERROR CODE: #{error_code}]: #{error}")
+    end
+  end
+
   # non-200 response without a SOAP fault
   class WinRMHTTPTransportError < WinRMError
     attr_reader :status_code

data/lib/winrm/helpers/powershell_script.rb

@@ -0,0 +1,22 @@
+module WinRM
+  class PowershellScript
+
+    attr_reader :text
+
+    # Creates a new PowershellScript object which can be used to encode
+    # PS scripts for safe transport over WinRM.
+    # @param [String] The PS script text content
+    def initialize(script)
+      @text = script
+    end
+
+    # Encodes the script so that it can be passed to the PowerShell
+    # --EncodedCommand argument.
+    # @return [String] The UTF-16LE base64 encoded script
+    def encoded()
+      encoded_script = text.encode('UTF-16LE', 'UTF-8')
+      Base64.strict_encode64(encoded_script)
+    end
+
+  end
+end

data/lib/winrm/http/response_handler.rb

@@ -46,7 +46,8 @@ module WinRM
     def raise_if_error()
       return if @status_code == 200 
       raise_if_auth_error()
-      raise_if_soap_fault()
+      raise_if_wsman_fault()
+      raise_if_wmi_error()
       raise_transport_error()
     end
 
@@ -54,11 +55,22 @@ module WinRM
       raise WinRMAuthorizationError.new if @status_code == 401 
     end
 
-    def raise_if_soap_fault()
+    def raise_if_wsman_fault()
       soap_errors = REXML::XPath.match(response_xml, "//#{NS_SOAP_ENV}:Body/#{NS_SOAP_ENV}:Fault/*")
       if !soap_errors.empty?
         fault = REXML::XPath.first(soap_errors, "//#{NS_WSMAN_FAULT}:WSManFault")
-        raise WinRMWSManFault.new(fault.to_s, fault.attributes['Code'])
+        raise WinRMWSManFault.new(fault.to_s, fault.attributes['Code']) unless fault.nil?
+      end
+    end
+
+    def raise_if_wmi_error()
+      soap_errors = REXML::XPath.match(response_xml, "//#{NS_SOAP_ENV}:Body/#{NS_SOAP_ENV}:Fault/*")
+      if !soap_errors.empty?
+        error = REXML::XPath.first(soap_errors, "//#{NS_WSMAN_MSFT}:MSFT_WmiError")
+        if !error.nil?
+          error_code = REXML::XPath.first(error, "//#{NS_WSMAN_MSFT}:error_Code").text
+          raise WinRMWMIError.new(error.to_s, error_code)
+        end
       end
     end
 

data/lib/winrm/http/transport.rb

@@ -22,12 +22,15 @@ module WinRM
     # is possible to use GSSAPI with Keep-Alive.
     class HttpTransport
 
+      # Set this to an unreasonable amount because WinRM has its own timeouts
+      DEFAULT_RECEIVE_TIMEOUT = 3600 
+
       attr_reader :endpoint
 
       def initialize(endpoint)
         @endpoint = endpoint.is_a?(String) ? URI.parse(endpoint) : endpoint
         @httpcli = HTTPClient.new(:agent_name => 'Ruby WinRM Client')
-        @httpcli.receive_timeout = 3600 # Set this to an unreasonable amount for now because WinRM has timeouts
+        @httpcli.receive_timeout = DEFAULT_RECEIVE_TIMEOUT
         @logger = Logging.logger[self]
       end
 
@@ -62,6 +65,16 @@ module WinRM
         @httpcli.ssl_config.verify_mode = OpenSSL::SSL::VERIFY_NONE
       end
 
+      # HTTP Client receive timeout. How long should a remote call wait for a
+      # for a response from WinRM?
+      def receive_timeout=(sec)
+        @httpcli.receive_timeout = sec
+      end
+
+      def receive_timeout()
+        @httpcli.receive_timeout
+      end
+
       protected
 
       def log_soap_message(message)

data/lib/winrm/output.rb

@@ -0,0 +1,27 @@
+module WinRM
+  # This class holds raw output as a hash, and has convenience methods to parse.
+  class Output < Hash
+    def initialize
+      super
+      self[:data] = []
+    end
+
+    def output
+      self[:data].flat_map do | line |
+        [line[:stdout], line[:stderr]]
+      end.compact.join
+    end
+
+    def stdout
+      self[:data].map do | line |
+        line[:stdout]
+      end.compact.join
+    end
+
+    def stderr
+      self[:data].map do | line |
+        line[:stderr]
+      end.compact.join
+    end
+  end
+end

data/lib/winrm/winrm_service.rb

@@ -14,6 +14,7 @@
 
 require 'nori'
 require 'rexml/document'
+require_relative 'helpers/powershell_script'
 
 module WinRM
   # This is the main class that does the SOAP request/response logic. There are a few helper classes, but pretty
@@ -41,6 +42,7 @@ module WinRM
       case transport
       when :kerberos
         require 'gssapi'
+        require 'gssapi/extensions'
         @xfer = HTTP::HttpGSSAPI.new(endpoint, opts[:realm], opts[:service], opts[:keytab], opts)
       when :plaintext
         @xfer = HTTP::HttpPlaintext.new(endpoint, opts[:user], opts[:pass], opts)
@@ -51,11 +53,20 @@ module WinRM
       end
     end
 
-    # Operation timeout
+    # Operation timeout.
+    # 
+    # Unless specified the client receive timeout will be 10s + the operation
+    # timeout.
+    #
     # @see http://msdn.microsoft.com/en-us/library/ee916629(v=PROT.13).aspx
-    # @param [Fixnum] sec the number of seconds to set the timeout to. It will be converted to an ISO8601 format.
-    def set_timeout(sec)
-      @timeout = Iso8601Duration.sec_to_dur(sec)
+    #
+    # @param [Fixnum] The number of seconds to set the WinRM operation timeout
+    # @param [Fixnum] The number of seconds to set the Ruby receive timeout
+    # @return [String] The ISO 8601 formatted operation timeout
+    def set_timeout(op_timeout_sec, receive_timeout_sec=nil)
+      @timeout = Iso8601Duration.sec_to_dur(op_timeout_sec)
+      @xfer.receive_timeout = receive_timeout_sec || op_timeout_sec + 10
+      @timeout
     end
     alias :op_timeout :set_timeout
 
@@ -151,12 +162,12 @@ module WinRM
 
       # Grab the command element and unescape any single quotes - issue 69
       xml = builder.target!
-      escaped_cmd = /<#{NS_WIN_SHELL}:Command>(.+)<\/#{NS_WIN_SHELL}:Command>/.match(xml)[1]
+      escaped_cmd = /<#{NS_WIN_SHELL}:Command>(.+)<\/#{NS_WIN_SHELL}:Command>/m.match(xml)[1]
       xml.sub!(escaped_cmd, escaped_cmd.gsub(/&#39;/, "'"))
 
       resp_doc = send_message(xml)
       command_id = REXML::XPath.first(resp_doc, "//#{NS_WIN_SHELL}:CommandId").text
-      
+
       if block_given?
         begin
           yield command_id
@@ -211,7 +222,7 @@ module WinRM
       end
 
       resp_doc = send_message(builder.target!)
-      output = {:data => []}
+      output = Output.new
       REXML::XPath.match(resp_doc, "//#{NS_WIN_SHELL}:Stream").each do |n|
         next if n.text.nil? || n.text.empty?
         stream = { n.attributes['Name'].to_sym => Base64.decode64(n.text) }
@@ -299,10 +310,9 @@ module WinRM
     # @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 = script_file.kind_of?(IO) ? script_file.read : script_file
-      script = script.encode('UTF-16LE', 'UTF-8')
-      script = Base64.strict_encode64(script)
-      run_cmd("powershell -encodedCommand #{script}", &block)
+      script_text = script_file.kind_of?(IO) ? script_file.read : script_file
+      script = WinRM::PowershellScript.new(script_text)
+      run_cmd("powershell -encodedCommand #{script.encoded()}", &block)
     end
     alias :powershell :run_powershell_script
 

data/lib/winrm.rb

@@ -33,6 +33,6 @@ module WinRM
   end
 end
 
+require 'winrm/output'
 require 'winrm/helpers/iso8601_duration'
 require 'winrm/soap_provider'
-require 'winrm/file_transfer'

data/spec/cmd_spec.rb

@@ -24,6 +24,38 @@ describe 'winrm client cmd', :integration => true do
     it { should have_no_stderr }
   end
 
+  describe 'capturing output from stdout and stderr' do
+    subject(:output) do
+      # Note: Multiple lines doesn't work:
+      # script = <<-eos
+      # echo Hello
+      # echo , world! 1>&2
+      # eos
+
+      script = "echo Hello & echo , world! 1>&2"
+
+      @captured_stdout, @captured_stderr = "", ""
+      @winrm.cmd(script) do |stdout, stderr|
+        @captured_stdout << stdout if stdout
+        @captured_stderr << stderr if stderr
+      end
+    end
+
+    it 'should have stdout' do
+      expect(output.stdout).to eq("Hello \r\n")
+      expect(output.stdout).to eq(@captured_stdout)
+    end
+
+    it 'should have stderr' do
+      expect(output.stderr).to eq(", world! \r\n")
+      expect(output.stderr).to eq(@captured_stderr)
+    end
+
+    it 'should have output' do
+      expect(output.output).to eq("Hello \r\n, world! \r\n")
+    end
+  end
+
   describe 'ipconfig with /all argument' do
     subject(:output) { @winrm.cmd('ipconfig', %w{/all}) }
     it { should have_exit_code 0 }

data/spec/config-example.yml

@@ -6,7 +6,7 @@
 
 ## Plain Text
 auth_type: plaintext
-endpoint: "http://localhost:5985/wsman"
+endpoint: "http://localhost:55985/wsman"
 options:
   user: vagrant
   pass: vagrant

data/spec/exception_spec.rb

@@ -32,4 +32,21 @@ describe "Exceptions", :unit => true do
       expect(error).to be_kind_of(WinRM::WinRMError)
     end
   end
+
+  describe WinRM::WinRMWMIError do
+
+    let (:error) { WinRM::WinRMWMIError.new("message text", 77777) }
+
+    it 'exposes the error text as an attribute' do
+      expect(error.error).to eq('message text')
+    end
+
+    it 'exposes the error code as an attribute' do
+      expect(error.error_code).to eq 77777
+    end
+
+    it 'is a winrm error' do
+      expect(error).to be_kind_of(WinRM::WinRMError)
+    end
+  end
 end

data/spec/output_spec.rb

@@ -0,0 +1,106 @@
+describe WinRM::Output, :unit => true do
+  subject { WinRM::Output.new() }
+
+  context "when there is no output" do
+    describe "#stdout" do
+      it "is empty" do
+        expect(subject.stdout).to be_empty
+      end
+    end
+
+    describe "#stderr" do
+      it "is empty" do
+        expect(subject.stderr).to be_empty
+      end
+    end
+
+    describe "#output" do
+      it "is empty" do
+        expect(subject.output).to be_empty
+      end
+    end
+  end
+
+  context "when there is only one line" do
+    describe "#stdout" do
+      it "is equal to that line" do
+        subject[:data] << { :stdout => "foo" }
+        expect(subject.stdout).to eq("foo")
+      end
+    end
+
+    describe "#stderr" do
+      it "is equal to that line" do
+        subject[:data] << { :stderr => "foo" }
+        expect(subject.stderr).to eq("foo")
+      end
+    end
+
+    describe "#output" do
+      it "is equal to stdout" do
+        subject[:data] << { :stdout => "foo" }
+        expect(subject.output).to eq("foo")
+      end
+
+      it "is equal to stderr" do
+        subject[:data] << { :stderr => "foo" }
+        expect(subject.output).to eq("foo")
+      end
+    end
+  end
+
+  context "when there is one line of each type" do
+    before(:each) do
+      subject[:data] << { :stdout => "foo" }
+      subject[:data] << { :stderr => "bar" }
+    end
+
+    describe "#stdout" do
+      it "is equal to that line" do
+        expect(subject.stdout).to eq("foo")
+      end
+    end
+
+    describe "#stderr" do
+      it "is equal to that line" do
+        expect(subject.stderr).to eq("bar")
+      end
+    end
+
+    describe "#output" do
+      it "is equal to stdout + stderr" do
+        expect(subject.output).to eq("foobar")
+      end
+    end
+  end
+
+  context "when there are multiple lines" do
+    before(:each) do
+      subject[:data] << { :stdout => "I can have a newline\nanywhere, " }
+      subject[:data] << { :stderr => "I can also have stderr" }
+      subject[:data] << { :stdout => "or stdout", :stderr => " and stderr" }
+      subject[:data] << { }
+      subject[:data] << { :stdout => " or nothing! (above)" }
+    end
+
+    describe "#stdout" do
+      it "is equal to that line" do
+        expect(subject.stdout).to eq("I can have a newline\nanywhere, or stdout or nothing! (above)")
+      end
+    end
+
+    describe "#stderr" do
+      it "is equal to that line" do
+        expect(subject.stderr).to eq("I can also have stderr and stderr")
+      end
+    end
+
+    describe "#output" do
+      it "is equal to stdout + stderr" do
+        expect(subject.output).to eq("I can have a newline\nanywhere, I can also have stderror stdout and stderr or nothing! (above)")
+      end
+    end
+  end
+
+  pending "parse CLIXML errors and convert to Strings and/or Exceptions"
+end

data/spec/powershell_spec.rb

@@ -55,6 +55,40 @@ describe 'winrm client powershell', :integration => true do
     end
     it { should match(/Windows IP Configuration/) }
   end
+
+  describe 'capturing output from Write-Host and Write-Error' do
+    subject(:output) do
+      script = <<-eos
+      Write-Host 'Hello'
+      $host.ui.WriteErrorLine(', world!')
+      eos
+
+      @captured_stdout, @captured_stderr = "", ""
+      @winrm.powershell(script) do |stdout, stderr|
+        @captured_stdout << stdout if stdout
+        @captured_stderr << stderr if stderr
+      end
+    end
+
+    it 'should have stdout' do
+      expect(output.stdout).to eq("Hello\n")
+      expect(output.stdout).to eq(@captured_stdout)
+    end
+
+    it 'should have stderr' do
+      # TODO: Option to parse CLIXML
+      # expect(output.output).to eq("Hello\n, world!")
+      # expect(output.stderr).to eq(", world!")
+      expect(output.stderr).to eq("#< CLIXML\r\n<Objs Version=\"1.1.0.1\" xmlns=\"http://schemas.microsoft.com/powershell/2004/04\"><S S=\"Error\">, world!_x000D__x000A_</S></Objs>")
+      expect(output.stderr).to eq(@captured_stderr)
+    end
+
+    it 'should have output' do
+      # TODO: Option to parse CLIXML
+      # expect(output.output).to eq("Hello\n, world!")
+      expect(output.output).to eq("Hello\n#< CLIXML\r\n<Objs Version=\"1.1.0.1\" xmlns=\"http://schemas.microsoft.com/powershell/2004/04\"><S S=\"Error\">, world!_x000D__x000A_</S></Objs>")
+    end
+  end
 end