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:

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

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