train-vsphere-gom 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4836ba3be5bd955bdb834325a38d79d6dd05c0f9fee8e735cd7a2de1de9c7c94
+  data.tar.gz: a76b3ec3cbcb66e743989c03a072095a6fd191c7e1d9f487530b4b00ba62c03c
+SHA512:
+  metadata.gz: c6b9c54a5e7939c40a1c20cf18e6fe6a92f3904968f3f0361dd0300b4ed9e1b86a7f6505ae4f85f6308dd05f5592da3bab6c0d28df1e823a78a098038de23df3
+  data.tar.gz: 13430dd8a4d44f36e076cb54c2c8de94f05bd4bd7facd1ea09f985d85c4c66697936b376079cb7a14694541e8a60185cb982ccc1e37c2784c2386aa25624a028

data/Gemfile

@@ -0,0 +1,15 @@
+source "https://rubygems.org"
+
+gemspec
+
+group :development do
+  gem "bump", "~> 0.10"
+  gem "bundler-audit", "~> 0.7"
+  gem "chefstyle", "~> 1.7"
+  gem "guard", "~> 2.16"
+  gem "mdl", "~> 0.11"
+  gem "pry", "~> 0.14"
+  gem "rake", "~> 13.0"
+  gem "train", "~> 3.5"
+  gem "yard", "~> 0.9"
+end

data/README.md

@@ -0,0 +1,88 @@
+# Train-vsphere-gom
+
+`train-vsphere-gom` is a Train plugin and is used as a Train OS Transport to
+connect to virtual machines via VMware Tools.
+
+This allows working with machines in different network segments, without
+adding routes, NAT or firewall routes.
+
+vSphere Guest Operations Manager covers various use cases within a target VM,
+including file transfers, Windows registry access and command execution. It is
+used by various 3rd party tools to monitor and manage VMs.
+
+## Requirements
+
+- VMware vSphere 5.0 or higher
+
+## Permissions
+
+Needs login credentials for vCenter (API) as well as the target machine (OS).
+
+Mandatory privileges in vCenter:
+
+- VirtualMachine.GuestOperations.Query
+- VirtualMachine.GuestOperations.Execute
+- VirtualMachine.GuestOperations.Modify (for file uploads)
+
+## Installation
+
+Install this Gem from rubygems.org:
+
+```bash
+gem install train-vsphere-gom
+```
+
+## Transport parameters
+
+| Option             | Explanation                                            | Default    | Env. Vars     |
+|--------------------|--------------------------------------------------------|------------|---------------|
+| `host`             | VM to connect (`host` for Train compatibility)         | _required_ | `VI_VM`       |
+| `user`             | VM username for login                                  | _required_ |               |
+| `password`         | VM password  for login                                 | _required_ |               |
+| `vcenter_server`   | VCenter server                                         | _required_ | `VI_SERVER`   |
+| `vcenter_username` | VCenter username                                       | _required_ | `VI_USERNAME` |
+| `vcenter_password` | VCenter password                                       | _required_ | `VI_PASSWORD` |
+| `vcenter_insecure` | Allow connections when SSL certificate is not matching | `false`    |               |
+| `logger`           | Logger instance                                        | $stdout, info |            |
+| `quick`            | Enable quick mode                                      | `false`    |               |
+| `shell_type`       | Shell type ("auto", "linux", "cmd", "powershell")      | `auto`     |               |
+| `timeout`          | Timeout in seconds                                     | `60`       |               |
+
+By design, Train VSphere GOM requires two authentication steps: One to get access to the VCenter API and one
+to get access to the guest VM with local credentials.
+
+VMs can be searched by their IP address, their UUID, their VMware inventory path or by DNS name.
+
+The environment variables are aligned to those from VMware SDK and ESXCLI.
+
+## Quick Mode
+
+In quick mode, non-essential operations are omitted to save time over slow connections.
+
+- no deletion of temporary files (in system temp directory)
+- no checking for file existance before trying to read
+- only reading standard error, if exit code was not zero
+
+## Limitations
+
+- SSPI based guest VM logins are not supported yet
+- using PowerShell via GOM is very slow (7-10 seconds roundtrip)
+
+## Example use
+
+```ruby
+require 'train-vsphere-gom'
+
+train  = Train.create('vsphere-gom', {
+            # Relying on VI_* variables for VCenter configuration
+            host:     '10.20.30.40'
+            username: 'Administrator',
+            password: 'Password'
+         })
+conn   = train.connection
+conn.run_command("Write-Host 'Inside the VM'")
+```
+
+## References
+
+- [vSphere Web Services: GOM](https://code.vmware.com/docs/5722/vsphere-web-services-api-reference/doc/vim.vm.guest.GuestOperationsManager.html)

data/lib/train-vsphere-gom.rb

@@ -0,0 +1,3 @@
+require "train-vsphere-gom/version"
+require "train-vsphere-gom/transport"
+require "train-vsphere-gom/connection"

data/lib/train-vsphere-gom/connection.rb

@@ -0,0 +1,191 @@
+require "resolv" unless defined?(Resolv)
+require "rbvmomi" unless defined?(RbVmomi)
+
+require_relative "guest_operations"
+
+module TrainPlugins
+  module VsphereGom
+    class Connection < Train::Plugins::Transport::BaseConnection
+      attr_reader :options, :config
+
+      attr_writer :logger, :vim, :vm, :vm_guest
+
+      def initialize(config = {})
+        @config = config
+
+        unless vm
+          logger.error format("[VSphere-GOM] Could not find VM for '%<id>s'. Check power status, if searched via IP", id: config[:host])
+          return
+        end
+
+        logger.debug format("[VSphere-GOM] Found %<id>s for %<search_type>s %<search>s",
+                            id: @vm._ref,
+                            search: config[:host],
+                            search_type: search_type(config[:host]))
+
+        super(config)
+      end
+
+      def close
+        return unless vim
+
+        vim.close
+        logger.info format("[VSphere-GOM] Closed connection to %<vm>s (VCenter %<vcenter>s)",
+                           vm: options[:host],
+                           vcenter: options[:vcenter_server])
+      end
+
+      def uri
+        "vsphere-gom://#{options[:user]}@#{options[:vcenter_server]}/#{options[:host]}"
+      end
+
+      def file_via_connection(path, *args)
+        if windows?
+          Train::File::Remote::Windows.new(self, path, *args)
+        else
+          Train::File::Remote::Unix.new(self, path, *args)
+        end
+      end
+
+      def upload(locals, remote)
+        logger.debug format("[VSphere-GOM] Copy %<locals>s to %<remote>s",
+                            locals: Array(locals).join(", "),
+                            remote: remote)
+
+        # Collect recursive list of directories and files
+        all = Array(locals).map do |local|
+          File.directory?(local) ? Dir.glob("#{local}/**/*") : local
+        end.flatten
+
+        dirs = all.select { |obj| File.directory? obj }
+        dirs.each { |dir| tools.create_dir(dir) }
+
+        # Then upload all files
+        files = all.select { |obj| File.file? obj }
+        files.each do |local|
+          remotefile = path(remote, File.basename(local))
+          vm_guest.upload_file(local, remotefile)
+        end
+      end
+
+      def download(remotes, local)
+        logger.debug format("[VSphere-GOM] Download %<remotes>s to %<local>s",
+                            remotes: Array(Remotes).join(","),
+                            local: local)
+
+        Array(remotes).each do |remote|
+          localfile = File.join(local, File.basename(remote))
+          vm_guest.download_file(remote, localfile)
+        end
+      end
+
+      def run_command_via_connection(command)
+        logger.debug format("[VSphere-GOM] Sending command to %<vm>s (VCenter %<vcenter>s)",
+                            vm: options[:host],
+                            vcenter: options[:vcenter_server])
+
+        result = vm_guest.run(command, shell_type: config[:shell_type].to_sym, timeout: config[:timeout].to_i)
+
+        if windows? && result.exit_status != 0
+          logger.debug format("[VSphere-GOM] Received Windows exit code: %<hexcode>s",
+                              hexcode: hexit_code(result.exit_status))
+        end
+
+        result
+      end
+
+      private
+
+      def vim
+        @vim ||= RbVmomi::VIM.connect(
+          user: config[:vcenter_username],
+          password: config[:vcenter_password],
+          insecure: config[:vcenter_insecure],
+          host: config[:vcenter_server]
+        )
+      end
+
+      def vm
+        @vm ||= find_vm(config[:host])
+      end
+
+      def logger
+        return @logger if @logger
+
+        @logger = config[:logger] || Logger.new($stdout, level: :info)
+      end
+
+      def vm_guest
+        return @vm_guest if @vm_guest
+
+        username   = config[:user] || config[:username]
+        password   = config[:password]
+        ssl_verify = !config[:vcenter_insecure]
+        quick      = config[:quick]
+
+        @vm_guest = Support::GuestOperations.new(vim, vm, username, password, ssl_verify: ssl_verify, quick: quick)
+        @vm_guest.logger = logger
+        @vm_guest
+      end
+
+      def os_family
+        return vm.guest.guestFamily == "windowsGuest" ? :windows : :linux if vm.guest.guestFamily
+
+        # VMware tools are not initialized or missing, infer from Guest Id
+        vm.config&.guestId =~ /^[Ww]in/ ? :windows : :linux
+      end
+
+      def linux?
+        os_family == :linux
+      end
+
+      def windows?
+        os_family == :windows
+      end
+
+      def hexit_code(exit_code)
+        exit_code += 2.pow(32) if exit_code < 0
+
+        "0x" + exit_code.to_s(16).upcase
+      end
+
+      def find_vm(needle)
+        root_folder = vim.serviceInstance.content.rootFolder
+
+        if ip?(needle)
+          root_folder.findByIp(config[:host])
+        elsif uuid?(needle)
+          root_folder.findByUuid(config[:host])
+        elsif inventory_path?(needle)
+          root_folder.findByInventoryPath(config[:host])
+        else
+          root_folder.findByDnsName(config[:host])
+        end
+      end
+
+      def ip?(ip_string)
+        ip_string.match? Resolv::IPv4::Regex
+      end
+
+      def uuid?(uuid)
+        uuid.downcase.match?(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/)
+      end
+
+      def inventory_path?(path)
+        path.include? "/"
+      end
+
+      def moref?(ref)
+        ref.match?(/vm-[0-9]*/)
+      end
+
+      def search_type(needle)
+        return "IP" if ip?(needle)
+        return "UUID" if uuid?(needle)
+        return "PATH" if inventory_path?(needle)
+
+        "DNS"
+      end
+    end
+  end
+end

data/lib/train-vsphere-gom/guest_operations.rb

@@ -0,0 +1,261 @@
+require "rbvmomi" unless defined?(RbVmomi)
+require "net/http" unless defined?(Net::HTTP)
+
+class Support
+  # Encapsulate VMware Tools GOM interaction, originally inspired by github:dnuffer/raidopt
+  class GuestOperations
+    SHELL_TYPES = {
+      linux: {
+        suffix: ".sh",
+        cmd:    "/bin/sh",
+        args:   '-c ". %<cmdfile>s" > %<outfile>s 2> %<errfile>s',
+      },
+
+      # BUG: Includes prompt
+      cmd: {
+        suffix: ".cmd",
+        cmd:    "cmd.exe",
+        args:   '/s /c "%<cmdfile>s" > %<outfile>s 2> %<errfile>s',
+      },
+
+      # Invoking PS via cmd seems the only way to get this to work
+      powershell: {
+        suffix: ".ps1",
+        cmd:    "cmd.exe",
+        args:   "/C powershell -NonInteractive -ExecutionPolicy Bypass -File %<cmdfile>s >%<outfile>s 2>%<errfile>s",
+      },
+    }.freeze
+
+    attr_writer :gom, :logger
+
+    def initialize(vim, vm, username, password, ssl_verify: true, logger: nil, quick: false)
+      @vim = vim
+      @vm = vm
+
+      @guest_auth = RbVmomi::VIM::NamePasswordAuthentication(interactiveSession: false, username: username, password: password)
+
+      @ssl_verify = ssl_verify
+      @quick = quick
+    end
+
+    # Required privileges: VirtualMachine.GuestOperations.Execute, VirtualMachine.GuestOperations.Modify
+    def run(command, shell_type: :auto, timeout: 60.0)
+      logger.debug format("Running `%s` remotely", command)
+
+      if shell_type == :auto
+        shell_type = :linux if linux?
+        shell_type = :powershell if windows?
+      end
+
+      shell = SHELL_TYPES[shell_type]
+      raise "Unsupported shell type #{shell_type}" unless shell
+
+      logger.warn "Command execution on Windows is very slow" unless @warned || linux?
+      @warned = true
+
+      temp_file = write_temp_file(command, suffix: shell[:suffix] || "")
+      temp_out  = "#{temp_file}-out.txt"
+      temp_err  = "#{temp_file}-err.txt"
+
+      begin
+        args = format(shell[:args], cmdfile: temp_file, outfile: temp_out, errfile: temp_err)
+        exit_code = run_program(shell[:cmd], args, timeout)
+      rescue StandardError
+        proc_err = read_file(temp_err)
+        raise format("Error executing command %s. Exit code: %d. StdErr %s", command, exit_code || -1, proc_err)
+      end
+
+      stdout = read_file(temp_out)
+      stdout = ascii_only(stdout) if bom?(stdout)
+
+      stderr = read_file(temp_err) unless exit_code == 0 && @quick
+
+      unless @quick
+        delete_file(temp_file)
+        delete_file(temp_out)
+        delete_file(temp_err)
+      end
+
+      ::Train::Extras::CommandResult.new(stdout, stderr || "", exit_code)
+    end
+
+    # Required privilege: VirtualMachine.GuestOperations.Query
+    def exist?(remote_file)
+      logger.debug format("Checking for remote file %s", remote_file)
+
+      gom.fileManager.ListFilesInGuest(vm: @vm, auth: @guest_auth, filePath: remote_file)
+
+      true
+    rescue RbVmomi::Fault
+      false
+    end
+
+    def read_file(remote_file)
+      return "" unless @quick || exist?(remote_file)
+
+      download_file(remote_file, nil) || ""
+    end
+
+    # Required privilege: VirtualMachine.GuestOperations.Modify
+    def write_file(remote_file, contents)
+      logger.debug format("Writing to remote file %s", remote_file)
+
+      put_url = gom.fileManager.InitiateFileTransferToGuest(
+        vm: @vm,
+        auth: @guest_auth,
+        guestFilePath: remote_file,
+        fileAttributes: RbVmomi::VIM::GuestFileAttributes(),
+        fileSize: contents.size,
+        overwrite: true
+      )
+
+      # VCenter internal name might mismatch the external, so fix it
+      put_url = put_url.gsub(%r{^https://\*:}, format("https://%s:%s", @vm._connection.host, put_url))
+      uri = URI.parse(put_url)
+
+      request = Net::HTTP::Put.new(uri.request_uri)
+      request["Transfer-Encoding"] = "chunked"
+      request["Content-Length"] = contents.size
+      request.body = contents
+
+      http_request(put_url, request)
+    rescue RbVmomi::Fault => e
+      logger.error "Error during upload, check permissions on remote system: '" + e.message + "'"
+    end
+
+    # Required privilege: VirtualMachine.GuestOperations.Modify
+    def write_temp_file(contents, prefix: "", suffix: "")
+      logger.debug format("Writing to temporary remote file")
+
+      temp_name = gom.fileManager.CreateTemporaryFileInGuest(vm: @vm, auth: @guest_auth, prefix: prefix, suffix: suffix)
+      write_file(temp_name, contents)
+
+      temp_name
+    end
+
+    # Required privilege: VirtualMachine.GuestOperations.Modify
+    def upload_file(local_file, remote_file)
+      logger.debug format("Uploading %s to remote file %s", local_file, remote_file)
+
+      write_file(remote_file, File.open(local_file, "rb").read)
+    end
+
+    # Required privilege: VirtualMachine.GuestOperations.Modify
+    def download_file(remote_file, local_file)
+      logger.debug format("Downloading remote file %s to %s", local_file, remote_file)
+
+      info = gom.fileManager.InitiateFileTransferFromGuest(vm: @vm, auth: @guest_auth, guestFilePath: remote_file)
+      uri = URI.parse(info.url)
+
+      request = Net::HTTP::Get.new(uri.request_uri)
+      response = http_request(info.url, request)
+
+      if response.body.size != info.size
+        raise format("Downloaded file has different size than reported: %s (%d bytes instead of %d bytes)", remote_file, response.body.size, info.size)
+      end
+
+      local_file.nil? ? response.body : File.open(local_file, "w") { |file| file.write(response.body) }
+    end
+
+    # Required privilege: VirtualMachine.GuestOperations.Modify
+    def delete_file(remote_file)
+      logger.debug format("Deleting remote file %s", remote_file)
+
+      gom.fileManager.DeleteFileInGuest(vm: @vm, auth: @guest_auth, filePath: remote_file)
+
+      true
+    rescue RbVmomi::Fault => e
+      raise unless e.message.start_with? "FileNotFound:"
+
+      false
+    end
+
+    # Required privilege: VirtualMachine.GuestOperations.Modify
+    def delete_directory(remote_dir, recursive: true)
+      logger.debug format("Deleting remote directory %s", remote_dir)
+
+      gom.fileManager.DeleteDirectoryInGuest(vm: @vm, auth: @guest_auth, directoryPath: remote_dir, recursive: recursive)
+
+      true
+    rescue RbVmomi::Fault => e
+      raise if e.message.start_with? "NotADirectory:"
+
+      false
+    end
+
+    private
+
+    def gom
+      @gom ||= @vim.serviceContent.guestOperationsManager
+    end
+
+    def logger
+      @logger ||= Logger.new($stdout, level: :info)
+    end
+
+    def ascii_only(string)
+      string.bytes[2..].map(&:chr).join.delete("\000")
+    end
+
+    def bom?(string)
+      string.bytes[0..1] == [0xFF, 0xFE]
+    end
+
+    def http_request(url, request_data)
+      uri = URI.parse(url)
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.verify_mode = @ssl_verify ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+
+      http.request(request_data)
+    end
+
+    def linux?
+      os_family == :linux
+    end
+
+    def windows?
+      os_family == :windows
+    end
+
+    def os_family
+      return @vm.guest.guestFamily == "windowsGuest" ? :windows : :linux if @vm.guest.guestFamily
+
+      # VMware tools are not initialized or missing, infer from Guest ID
+      @vm.config&.guestId&.match(/^win/) ? :windows : :linux
+    end
+
+    def run_program(path, args = "", timeout = 60.0)
+      logger.debug format("Running %s %s", path, args)
+
+      gp_spec = RbVmomi::VIM::GuestProgramSpec.new(programPath: path, arguments: args)
+      pid = gom.processManager.StartProgramInGuest(vm: @vm, auth: @guest_auth, spec: gp_spec)
+
+      wait_for_process_exit(pid, timeout)
+      process_exit_code(pid)
+    end
+
+    def wait_for_process_exit(pid, timeout = 60.0, interval = 1.0)
+      start = Time.new
+
+      loop do
+        return unless process_running?(pid)
+        break if (Time.new - start) >= timeout
+
+        sleep interval
+      end
+
+      raise format("Timeout waiting for process %d to exit after %d seconds", pid, timeout) if (Time.new - start) >= timeout
+    end
+
+    def process_running?(pid)
+      procs = gom.processManager.ListProcessesInGuest(vm: @vm, auth: @guest_auth, pids: [pid])
+      procs.empty? || procs.any? { |gpi| gpi.exitCode.nil? }
+    end
+
+    def process_exit_code(pid)
+      gom.processManager.ListProcessesInGuest(vm: @vm, auth: @guest_auth, pids: [pid])&.first&.exitCode
+    end
+  end
+end

data/lib/train-vsphere-gom/transport.rb

@@ -0,0 +1,29 @@
+require "train"
+require "train/plugins"
+require "train-vsphere-gom/connection"
+
+module TrainPlugins
+  module VsphereGom
+    class Transport < Train.plugin(1)
+      name "vsphere-gom"
+
+      option :vcenter_server, required: true, default: ENV["VI_SERVER"]
+      option :vcenter_username, required: true, default: ENV["VI_USERNAME"]
+      option :vcenter_password, required: true, default: ENV["VI_PASSWORD"]
+      option :vcenter_insecure, required: false, default: true
+
+      option :host, default: ENV["VI_VM"], required: true
+      option :user, required: true
+      option :password, required: true
+
+      option :quick, default: false
+      option :shell_type, default: :auto
+      option :timeout, default: 60
+
+      # inspec -t vsphere-gom://
+      def connection(_instance_opts = nil)
+        @connection ||= TrainPlugins::VsphereGom::Connection.new(@options)
+      end
+    end
+  end
+end

data/lib/train-vsphere-gom/version.rb

@@ -0,0 +1,5 @@
+module TrainPlugins
+  module VsphereGom
+    VERSION = "0.1.0".freeze
+  end
+end

data/train-vsphere-gom.gemspec

@@ -0,0 +1,30 @@
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "train-vsphere-gom"
+
+Gem::Specification.new do |spec|
+  spec.name          = "train-vsphere-gom"
+  spec.version       = TrainPlugins::VsphereGom::VERSION
+  spec.authors       = ["Thomas Heinen"]
+  spec.email         = ["theinen@tecracer.de"]
+  spec.summary       = "Train transport for vSphere GOM"
+  spec.description   = "Execute commands via VMware Tools (without need for network)"
+  spec.homepage      = "https://github.com/tecracer-chef/train-vsphere-gom"
+  spec.license       = "Apache-2.0"
+
+  spec.files = %w{
+    README.md train-vsphere-gom.gemspec Gemfile
+  } + Dir.glob(
+    "lib/**/*", File::FNM_DOTMATCH
+  ).reject { |f| File.directory?(f) }
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = "~> 2.6"
+
+  # If you only need certain gems during development or testing, list
+  # them in Gemfile, not here.
+
+  # Do not list inspec as a dependency of a train plugin.
+  # Do not list train or train-core as a dependency of a train plugin.
+  spec.add_dependency "rbvmomi", "~> 3.0"
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: train-vsphere-gom
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Thomas Heinen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2021-02-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rbvmomi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Execute commands via VMware Tools (without need for network)
+email:
+- theinen@tecracer.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- lib/train-vsphere-gom.rb
+- lib/train-vsphere-gom/connection.rb
+- lib/train-vsphere-gom/guest_operations.rb
+- lib/train-vsphere-gom/transport.rb
+- lib/train-vsphere-gom/version.rb
+- train-vsphere-gom.gemspec
+homepage: https://github.com/tecracer-chef/train-vsphere-gom
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Train transport for vSphere GOM
+test_files: []