This API has a deprecated equivalent from v7.0U1.
Get Tools
Get the properties of VMware Tools.
Request
URLURL
https://{api_host}/api/vcenter/vm/{vm}/tools
Path Parameters
Path Parameters
string
vm
Required
Identifier of the virtual machine. The parameter must be an identifier for the resource type: VirtualMachine.
Header Parameters
Header Parameters
string
vmware-api-session-id
Required
Required session ID, acquired from Create Session API under CIS product
vmware-api-session-id example
"b00db39f948d13ea1e59b4d6fce56389"
Authentication
This operation uses the following authentication methods.
Response
Response
Response BodyResponse Body
200 OK returns
VmToolsInfo
of type application/json
VMware Tools properties.
{
"auto_update_supported": false,
"error": {},
"install_attempt_count": 0,
"install_type": "UNKNOWN",
"run_state": "NOT_RUNNING",
"upgrade_policy": "MANUAL",
"version": "string",
"version_number": 0,
"version_status": "NOT_INSTALLED"
}
boolean
auto_update_supported
Required
Set if the virtual machine supports auto-upgrading Tools via Tools.UpgradePolicy.
run_state
Required
Current run state of VMware Tools in the guest operating system.
NOT_RUNNING : VMware Tools is not running.
RUNNING : VMware Tools is running.
EXECUTING_SCRIPTS : VMware Tools is running scripts as part of a state transition.
Possible values are: NOT_RUNNING , RUNNING , EXECUTING_SCRIPTS
upgrade_policy
Required
The Tools.UpgradePolicy enumerated type defines when Tools are auto-upgraded for a virtual machine.
MANUAL : No auto-upgrades for Tools will be performed for this virtual machine. Users must manually invoke the Tools.upgrade operation to update Tools.
UPGRADE_AT_POWER_CYCLE : When the virtual machine is power-cycled, the system checks for a newer version of Tools when the virtual machine is powered on. If it is available, a Tools upgrade is automatically performed on the virtual machine and it is rebooted if necessary.
Possible values are: MANUAL , UPGRADE_AT_POWER_CYCLE
object
error
Optional
Error that happened, if any, during last attempt to upgrade or install Tools. This field will be unset if a the last Tools install or upgrade attempt succeeded.
integer
install_attempt_count
Optional
Number of attempts that have been made to install or upgrade the version of Tools installed on this virtual machine. This field will be unset if there have been no Tools install or upgrade attempt.
install_type
Optional
The Tools.ToolsInstallType enumerated type defines the installation type of the Tools in the guest operating system.
UNKNOWN : Installation type is not known. Most likely tools have been installed by OSPs or open-vm-tools, but a version that does not report its install type or an install type that we do not recognize.
MSI : MSI is the installation type used for VMware Tools on Windows.
TAR : Tools have been installed by the tar installer.
OSP : OSPs are RPM or Debian packages tailored for the OS in the VM. See http://packages.vmware.com
OPEN_VM_TOOLS : open-vm-tools are the open-source version of VMware Tools, may have been packaged by the OS vendor.
Possible values are: UNKNOWN , MSI , TAR , OSP , OPEN_VM_TOOLS
string
version
Optional
Version of VMware Tools installed on the guest operating system. This is a human-readable value that should not be parsed. This field wil be unset if VMWare Tools is not installed.
integer
version_number
Optional
Version of VMware Tools installed on the guest operating system. This field wil be unset if VMWare Tools is not installed. This is an integer constructed as follows: (((MJR) << 10) + ((MNR) << 5) + (REV)) Where MJR is tha major verson, MNR is the minor version and REV is the revision. Tools version = T Tools Version Major = MJR = (T / 1024) Tools Version Minor = MNR = ((T % 1024) / 32) Tools Version Revision = BASE = ((T % 1024) % 32) Tools actual version = MJR.MNR.REV
version_status
Optional
The Tools.VersionStatus enumerated type defines the version status types of VMware Tools installed in the guest operating system.
NOT_INSTALLED : VMware Tools has never been installed.
CURRENT : VMware Tools is installed, and the version is current.
UNMANAGED : VMware Tools is installed, but it is not managed by VMware. This includes open-vm-tools or OSPs which should be managed by the guest operating system.
TOO_OLD_UNSUPPORTED : VMware Tools is installed, but the version is too old.
SUPPORTED_OLD : VMware Tools is installed, supported, but a newer version is available.
SUPPORTED_NEW : VMware Tools is installed, supported, and newer than the version available on the host.
TOO_NEW : VMware Tools is installed, and the version is known to be too new to work correctly with this virtual machine.
BLACKLISTED : VMware Tools is installed, but the installed version is known to have a grave bug and should be immediately upgraded.
Possible values are: NOT_INSTALLED , CURRENT , UNMANAGED , TOO_OLD_UNSUPPORTED , SUPPORTED_OLD , more...
Errors
500
com.vmware.vapi.std.errors.error : if the system reports an error while responding to the request.
default
‘Default’ means this response is used for all HTTP codes that are not covered individually for this operation.
Code Samples
PowerCLI Client SDK Example
Invoke-GetVmTools -Vm "MyVm"
cURL Command
curl -H "vmware-api-session-id: b00db39f948d13ea1e59b4d6fce56389" https://{api_host}/api/vcenter/vm/{vm}/tools
Vendor Extensions
This operation contains the following vendor extensions defined in the spec:
x-vmw-doc-deprecated-method: get
x-vmw-doc-deprecated-path: /rest/vcenter/vm/{vm}/tools
x-vmw-doc-operation: get
Availability
Added in 7.0U2
