r-train 0.9.1

data/lib/train/transports/ssh_connection.rb

@@ -0,0 +1,216 @@
+# -*- encoding: utf-8 -*-
+#
+# Author:: Fletcher Nichol (<fnichol@nichol.ca>)
+# Author:: Dominik Richter (<dominik.richter@gmail.com>)
+# Author:: Christoph Hartmann (<chris@lollyrock.com>)
+#
+# Copyright (C) 2014, 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 'net/ssh'
+require 'net/scp'
+
+class Train::Transports::SSH
+  # A Connection instance can be generated and re-generated, given new
+  # connection details such as connection port, hostname, credentials, etc.
+  # This object is responsible for carrying out the actions on the remote
+  # host such as executing commands, transferring files, etc.
+  #
+  # @author Fletcher Nichol <fnichol@nichol.ca>
+  class Connection < BaseConnection # rubocop:disable Metrics/ClassLength
+    def initialize(options)
+      super(options)
+      @username               = @options.delete(:username)
+      @hostname               = @options.delete(:hostname)
+      @port                   = @options[:port] # don't delete from options
+      @connection_retries     = @options.delete(:connection_retries)
+      @connection_retry_sleep = @options.delete(:connection_retry_sleep)
+      @max_wait_until_ready   = @options.delete(:max_wait_until_ready)
+      @files                  = {}
+      @session                = nil
+      @transport_options      = @options.delete(:transport_options)
+      @cmd_wrapper            = nil
+      @cmd_wrapper            = CommandWrapper.load(self, @transport_options)
+    end
+
+    # (see Base::Connection#close)
+    def close
+      return if @session.nil?
+      logger.debug("[SSH] closing connection to #{self}")
+      session.close
+    ensure
+      @session = nil
+    end
+
+    def os
+      @os ||= OS.new(self)
+    end
+
+    def file(path)
+      @files[path] ||= LinuxFile.new(self, path)
+    end
+
+    # (see Base::Connection#run_command)
+    def run_command(cmd)
+      stdout = stderr = ''
+      exit_status = nil
+      cmd.force_encoding('binary') if cmd.respond_to?(:force_encoding)
+      logger.debug("[SSH] #{self} (#{cmd})")
+
+      session.open_channel do |channel|
+        # wrap commands if that is configured
+        cmd = @cmd_wrapper.run(cmd) unless @cmd_wrapper.nil?
+
+        channel.exec(cmd) do |_, success|
+          abort 'Couldn\'t execute command on SSH.' unless success
+
+          channel.on_data do |_, data|
+            stdout += data
+          end
+
+          channel.on_extended_data do |_, _type, data|
+            stderr += data
+          end
+
+          channel.on_request('exit-status') do |_, data|
+            exit_status = data.read_long
+          end
+
+          channel.on_request('exit-signal') do |_, data|
+            exit_status = data.read_long
+          end
+        end
+      end
+      @session.loop
+
+      CommandResult.new(stdout, stderr, exit_status)
+    rescue Net::SSH::Exception => ex
+      raise Train::Transports::SSHFailed, "SSH command failed (#{ex.message})"
+    end
+
+    # (see Base::Connection#login_command)
+    def login_command
+      level = logger.debug? ? 'VERBOSE' : 'ERROR'
+      fwd_agent = options[:forward_agent] ? 'yes' : 'no'
+
+      args  = %w{ -o UserKnownHostsFile=/dev/null }
+      args += %w{ -o StrictHostKeyChecking=no }
+      args += %w{ -o IdentitiesOnly=yes } if options[:keys]
+      args += %W( -o LogLevel=#{level} )
+      args += %W( -o ForwardAgent=#{fwd_agent} ) if options.key?(:forward_agent)
+      Array(options[:keys]).each do |ssh_key|
+        args += %W( -i #{ssh_key} )
+      end
+      args += %W( -p #{@port} )
+      args += %W( #{@username}@#{@hostname} )
+
+      LoginCommand.new('ssh', args)
+    end
+
+    # (see Base::Connection#upload)
+    def upload(locals, remote)
+      Array(locals).each do |local|
+        opts = File.directory?(local) ? { recursive: true } : {}
+
+        session.scp.upload!(local, remote, opts) do |_ch, name, sent, total|
+          logger.debug("Uploaded #{name} (#{total} bytes)") if sent == total
+        end
+      end
+    rescue Net::SSH::Exception => ex
+      raise Train::Transports::SSHFailed, "SCP upload failed (#{ex.message})"
+    end
+
+    # (see Base::Connection#wait_until_ready)
+    def wait_until_ready
+      delay = 3
+      session(
+        retries: @max_wait_until_ready / delay,
+        delay:   delay,
+        message: "Waiting for SSH service on #{@hostname}:#{@port}, " \
+                 "retrying in #{delay} seconds",
+      )
+      execute(PING_COMMAND.dup)
+    end
+
+    private
+
+    PING_COMMAND = "echo '[SSH] Established'".freeze
+
+    RESCUE_EXCEPTIONS_ON_ESTABLISH = [
+      Errno::EACCES, Errno::EADDRINUSE, Errno::ECONNREFUSED, Errno::ETIMEDOUT,
+      Errno::ECONNRESET, Errno::ENETUNREACH, Errno::EHOSTUNREACH,
+      Net::SSH::Disconnect, Net::SSH::AuthenticationFailed, Timeout::Error
+    ].freeze
+
+    # Establish an SSH session on the remote host.
+    #
+    # @param opts [Hash] retry options
+    # @option opts [Integer] :retries the number of times to retry before
+    #   failing
+    # @option opts [Float] :delay the number of seconds to wait until
+    #   attempting a retry
+    # @option opts [String] :message an optional message to be logged on
+    #   debug (overriding the default) when a rescuable exception is raised
+    # @return [Net::SSH::Connection::Session] the SSH connection session
+    # @api private
+    def establish_connection(opts)
+      logger.debug("[SSH] opening connection to #{self}")
+      Net::SSH.start(@hostname, @username, @options)
+    rescue *RESCUE_EXCEPTIONS_ON_ESTABLISH => e
+      if (opts[:retries] -= 1) <= 0
+        logger.warn("[SSH] connection failed, terminating (#{e.inspect})")
+        raise Train::Transports::SSHFailed, 'SSH session could not be established'
+      end
+
+      if opts[:message]
+        logger.debug("[SSH] connection failed (#{e.inspect})")
+        message = opts[:message]
+      else
+        message = "[SSH] connection failed, retrying in #{opts[:delay]}"\
+                  " seconds (#{e.inspect})"
+      end
+      logger.info(message)
+
+      sleep(opts[:delay])
+      retry
+    end
+
+    # Returns a connection session, or establishes one when invoked the
+    # first time.
+    #
+    # @param retry_options [Hash] retry options for the initial connection
+    # @return [Net::SSH::Connection::Session] the SSH connection session
+    # @api private
+    def session(retry_options = {})
+      @session ||= establish_connection({
+        retries: @connection_retries.to_i,
+        delay:   @connection_retry_sleep.to_i,
+      }.merge(retry_options))
+    end
+
+    # String representation of object, reporting its connection details and
+    # configuration.
+    #
+    # @api private
+    def to_s
+      "#{@username}@#{@hostname}<#{@options.inspect}>"
+    end
+
+    class OS < OSCommon
+      def initialize(backend)
+        super(backend, { family: 'unix' })
+      end
+    end
+  end
+end

data/lib/train/transports/winrm.rb

@@ -0,0 +1,187 @@
+# -*- encoding: utf-8 -*-
+#
+# Author:: Salim Afiune (<salim@afiunemaya.com.mx>)
+# Author:: Matt Wrock (<matt@mattwrock.com>)
+# Author:: Fletcher Nichol (<fnichol@nichol.ca>)
+# Author:: Dominik Richter (<dominik.richter@gmail.com>)
+# Author:: Christoph Hartmann (<chris@lollyrock.com>)
+#
+# Copyright (C) 2014, Salim Afiune
+#
+# 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 'rbconfig'
+require 'uri'
+require 'train/errors'
+
+module Train::Transports
+  # Wrapped exception for any internally raised WinRM-related errors.
+  #
+  # @author Fletcher Nichol <fnichol@nichol.ca>
+  class WinRMFailed < Train::TransportError; end
+
+  # A Transport which uses WinRM to execute commands and transfer files.
+  #
+  # @author Matt Wrock <matt@mattwrock.com>
+  # @author Salim Afiune <salim@afiunemaya.com.mx>
+  # @author Fletcher Nichol <fnichol@nichol.ca>
+  class WinRM < Train.plugin(1) # rubocop:disable Metrics/ClassLength
+    name 'winrm'
+
+    autoload :Connection, 'train/transports/winrm_connection'
+
+    # common target configuration
+    option :host, required: true
+    option :port
+    option :user, default: 'administrator', required: true
+    option :password, nil
+    option :path, default: '/wsman'
+    option :ssl, default: false
+    option :self_signed, default: false
+
+    # additional winrm options
+    option :rdp_port, default: 3389
+    option :connection_retries, default: 5
+    option :connection_retry_sleep, default: 1
+    option :max_wait_until_ready, default: 600
+
+    def initialize(opts)
+      super(opts)
+      load_needed_dependencies!
+    end
+
+    # (see Base#connection)
+    def connection(state = nil, &block)
+      opts = merge_options(options, state || {})
+      validate_options(opts)
+      conn_opts = connection_options(opts)
+
+      if @connection && @connection_options == conn_opts
+        reuse_connection(&block)
+      else
+        create_new_connection(conn_opts, &block)
+      end
+    end
+
+    private
+
+    def validate_options(opts)
+      super(opts)
+
+      # set scheme and port based on ssl activation
+      scheme = opts[:ssl] ? 'https' : 'http'
+      port = opts[:port]
+      port = (opts[:ssl] ? 5986 : 5985) if port.nil?
+
+      # remove leading '/'
+      path = (opts[:path] || '').sub(%r{^/+}, '')
+
+      opts[:endpoint] = "#{scheme}://#{opts[:host]}:#{port}/#{path}"
+    end
+
+    WINRM_TRANSPORT_SPEC_VERSION = '~> 1.0'.freeze
+
+    # Builds the hash of options needed by the Connection object on
+    # construction.
+    #
+    # @param data [Hash] merged configuration and mutable state data
+    # @return [Hash] hash of connection options
+    # @api private
+    def connection_options(opts)
+      {
+        logger:                   logger,
+        winrm_transport:          :plaintext,
+        disable_sspi:             true,
+        basic_auth_only:          true,
+        endpoint:                 opts[:endpoint],
+        user:                     opts[:user],
+        pass:                     opts[:password],
+        rdp_port:                 opts[:rdp_port],
+        connection_retries:       opts[:connection_retries],
+        connection_retry_sleep:   opts[:connection_retry_sleep],
+        max_wait_until_ready:     opts[:max_wait_until_ready],
+        no_ssl_peer_verification: opts[:self_signed],
+      }
+    end
+
+    # Creates a new WinRM Connection instance and save it for potential
+    # future reuse.
+    #
+    # @param options [Hash] conneciton options
+    # @return [WinRM::Connection] a WinRM Connection instance
+    # @api private
+    def create_new_connection(options, &block)
+      if @connection
+        logger.debug("[WinRM] shutting previous connection #{@connection}")
+        @connection.close
+      end
+
+      @connection_options = options
+      @connection = Connection.new(options, &block)
+    end
+
+    # (see Base#load_needed_dependencies!)
+    def load_needed_dependencies!
+      spec_version = WINRM_TRANSPORT_SPEC_VERSION.dup
+      logger.debug('Winrm Transport requested,' \
+        " loading WinRM::Transport gem (#{spec_version})")
+      gem 'winrm-transport', spec_version
+      first_load = require 'winrm/transport/version'
+      load_winrm_transport!
+
+      version = ::WinRM::Transport::VERSION
+      if first_load
+        logger.debug("WinRM::Transport #{version} library loaded")
+      else
+        logger.debug("WinRM::Transport #{version} previously loaded")
+      end
+    rescue LoadError => e
+      logger.fatal(
+        "The `winrm-transport' gem is missing and must" \
+        ' be installed or cannot be properly activated. Run' \
+        " `gem install winrm-transport --version '#{spec_version}'`" \
+        ' or add the following to your Gemfile if you are using Bundler:' \
+        " `gem 'winrm-transport', '#{spec_version}'`.",
+      )
+      raise Train::UserError,
+            "Could not load or activate WinRM::Transport (#{e.message})"
+    end
+
+    # Load WinRM::Transport code.
+    #
+    # @api private
+    def load_winrm_transport!
+      silence_warnings { require 'winrm' }
+      require 'winrm/transport/shell_closer'
+      require 'winrm/transport/command_executor'
+      require 'winrm/transport/file_transporter'
+    end
+
+    # Return the last saved WinRM connection instance.
+    #
+    # @return [Winrm::Connection] a WinRM Connection instance
+    # @api private
+    def reuse_connection
+      logger.debug("[WinRM] reusing existing connection #{@connection}")
+      yield @connection if block_given?
+      @connection
+    end
+
+    def silence_warnings
+      old_verbose, $VERBOSE = $VERBOSE, nil
+      yield
+    ensure
+      $VERBOSE = old_verbose
+    end
+  end
+end

data/lib/train/transports/winrm_connection.rb

@@ -0,0 +1,258 @@
+# -*- encoding: utf-8 -*-
+#
+# Author:: Salim Afiune (<salim@afiunemaya.com.mx>)
+# Author:: Matt Wrock (<matt@mattwrock.com>)
+# Author:: Fletcher Nichol (<fnichol@nichol.ca>)
+# Author:: Dominik Richter (<dominik.richter@gmail.com>)
+# Author:: Christoph Hartmann (<chris@lollyrock.com>)
+#
+# Copyright (C) 2014, Salim Afiune
+#
+# 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.
+
+class Train::Transports::WinRM
+  # A Connection instance can be generated and re-generated, given new
+  # connection details such as connection port, hostname, credentials, etc.
+  # This object is responsible for carrying out the actions on the remote
+  # host such as executing commands, transferring files, etc.
+  #
+  # @author Fletcher Nichol <fnichol@nichol.ca>
+  class Connection < BaseConnection # rubocop:disable Metrics/ClassLength
+    def initialize(options)
+      super(options)
+      @endpoint               = @options.delete(:endpoint)
+      @rdp_port               = @options.delete(:rdp_port)
+      @winrm_transport        = @options.delete(:winrm_transport)
+      @connection_retries     = @options.delete(:connection_retries)
+      @connection_retry_sleep = @options.delete(:connection_retry_sleep)
+      @max_wait_until_ready   = @options.delete(:max_wait_until_ready)
+      @files                  = {}
+    end
+
+    # (see Base::Connection#close)
+    def close
+      return if @session.nil?
+      shell_id = session.shell
+      logger.debug("[WinRM] closing remote shell #{shell_id} on #{self}")
+      session.close
+      logger.debug("[WinRM] remote shell #{shell_id} closed")
+    ensure
+      @session = nil
+    end
+
+    def os
+      @os ||= OS.new(self)
+    end
+
+    def file(path)
+      @files[path] ||= WindowsFile.new(self, path)
+    end
+
+    def run_command(command)
+      return if command.nil?
+      logger.debug("[WinRM] #{self} (#{command})")
+      out = ''
+
+      response = session.run_powershell_script(command) do |stdout, _|
+        out << stdout if stdout
+      end
+
+      CommandResult.new(out, response.stderr, response[:exitcode])
+    end
+
+    # (see Base::Connection#login_command)
+    def login_command
+      case RbConfig::CONFIG['host_os']
+      when /darwin/
+        login_command_for_mac
+      when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
+        login_command_for_windows
+      when /linux/
+        login_command_for_linux
+      else
+        fail ActionFailed,
+             "Remote login not supported in #{self.class} " \
+             "from host OS '#{RbConfig::CONFIG['host_os']}'."
+      end
+    end
+
+    # (see Base::Connection#upload)
+    def upload(locals, remote)
+      file_transporter.upload(locals, remote)
+    end
+
+    # (see Base::Connection#wait_until_ready)
+    def wait_until_ready
+      delay = 3
+      session(
+        retries: @max_wait_until_ready / delay,
+        delay:   delay,
+        message: "Waiting for WinRM service on #{endpoint}, "\
+                 "retrying in #{delay} seconds",
+      )
+      execute(PING_COMMAND.dup)
+    end
+
+    private
+
+    PING_COMMAND = "Write-Host '[WinRM] Established\n'".freeze
+
+    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
+
+    # Create a local RDP document and return it
+    #
+    # @param opts [Hash] configuration options
+    # @option opts [true,false] :mac whether or not the document is for a
+    #   Mac system
+    # @api private
+    def rdp_doc(opts = {})
+      host = URI.parse(@endpoint).host
+      content = [
+        "full address:s:#{host}:#{@rdp_port}",
+        'prompt for credentials:i:1',
+        "username:s:#{options[:user]}",
+      ].join("\n")
+
+      content.prepend("drivestoredirect:s:*\n") if opts[:mac]
+
+      content
+    end
+
+    # Establish a remote shell session on the remote host.
+    #
+    # @param opts [Hash] retry options
+    # @option opts [Integer] :retries the number of times to retry before
+    #   failing
+    # @option opts [Float] :delay the number of seconds to wait until
+    #   attempting a retry
+    # @option opts [String] :message an optional message to be logged on
+    #   debug (overriding the default) when a rescuable exception is raised
+    # @return [Winrm::CommandExecutor] the command executor session
+    # @api private
+    def establish_shell(opts)
+      service_args = [@endpoint, @winrm_transport, options]
+      @service = ::WinRM::WinRMWebService.new(*service_args)
+      closer = WinRM::Transport::ShellCloser.new("#{self}", false, service_args)
+
+      executor = WinRM::Transport::CommandExecutor.new(@service, logger, closer)
+      retryable(opts) do
+        logger.debug("[WinRM] opening remote shell on #{self}")
+        shell_id = executor.open
+        logger.debug("[WinRM] remote shell #{shell_id} is open on #{self}")
+      end
+      executor
+    end
+
+    # @return [Winrm::FileTransporter] a file transporter
+    # @api private
+    def file_transporter
+      @file_transporter ||= WinRM::Transport::FileTransporter.new(session, logger)
+    end
+
+    # Builds a `LoginCommand` for use by Linux-based platforms.
+    #
+    # TODO: determine whether or not `desktop` exists
+    #
+    # @return [LoginCommand] a login command
+    # @api private
+    def login_command_for_linux
+      args  = %W( -u #{options[:user]} )
+      args += %W( -p #{options[:pass]} ) if options.key?(:pass)
+      args += %W( #{URI.parse(@endpoint).host}:#{@rdp_port} )
+      LoginCommand.new('rdesktop', args)
+    end
+
+    # Builds a `LoginCommand` for use by Mac-based platforms.
+    #
+    # @return [LoginCommand] a login command
+    # @api private
+    def login_command_for_mac
+      LoginCommand.new('open', rdp_doc(mac: true))
+    end
+
+    # Builds a `LoginCommand` for use by Windows-based platforms.
+    #
+    # @return [LoginCommand] a login command
+    # @api private
+    def login_command_for_windows
+      LoginCommand.new('mstsc', rdp_doc)
+    end
+
+    # Yields to a block and reties the block if certain rescuable
+    # exceptions are raised.
+    #
+    # @param opts [Hash] retry options
+    # @option opts [Integer] :retries the number of times to retry before
+    #   failing
+    # @option opts [Float] :delay the number of seconds to wait until
+    #   attempting a retry
+    # @option opts [String] :message an optional message to be logged on
+    #   debug (overriding the default) when a rescuable exception is raised
+    # @return [Winrm::CommandExecutor] the command executor session
+    # @api private
+    def retryable(opts)
+      yield
+    rescue *RESCUE_EXCEPTIONS_ON_ESTABLISH.call => e
+      if (opts[:retries] -= 1) <= 0
+        logger.warn("[WinRM] connection failed, terminating (#{e.inspect})")
+        raise
+      end
+
+      if opts[:message]
+        logger.debug("[WinRM] connection failed (#{e.inspect})")
+        message = opts[:message]
+      else
+        message = '[WinRM] connection failed, '\
+                  "retrying in #{opts[:delay]} seconds (#{e.inspect})"
+      end
+      logger.info(message)
+      sleep(opts[:delay])
+      retry
+    end
+
+    # Establishes a remote shell session, or establishes one when invoked
+    # the first time.
+    #
+    # @param retry_options [Hash] retry options for the initial connection
+    # @return [Winrm::CommandExecutor] the command executor session
+    # @api private
+    def session(retry_options = {})
+      @session ||= establish_shell({
+        retries: @connection_retries.to_i,
+        delay:   @connection_retry_sleep.to_i,
+      }.merge(retry_options))
+    end
+
+    # String representation of object, reporting its connection details and
+    # configuration.
+    #
+    # @api private
+    def to_s
+      "#{@winrm_transport}::#{@endpoint}<#{options.inspect}>"
+    end
+
+    class OS < OSCommon
+      def initialize(backend)
+        super(backend, { family: 'windows' })
+      end
+    end
+  end
+end