You can retrieve commonly used information about virtual machines that match specific criteria. You can retrieve information for up to 4000 virtual machines in a single

vCenter Server

instance.

You can retrieve a list of virtual machines in a single

vCenter Server

instance by filtering the results based on a specific requirement. For example, you can use as filter criteria the power state of the virtual machines, or the host, cluster, data center, folder, or resource pool that must contain the virtual machines. In case you specify multiple filter criteria, only virtual machines that match all filter criteria are returned.

VMware Tools is a set of drivers and utilities that you install on the guest operating system of a virtual machine to enhance the performance of the guest OS. VMware Tools also improves the management of the virtual machine. For each guest OS, VMware provides a specific binary-compatible version of VMware Tools.

Before you install VMware tools, you must install and boot the guest operating system.

To mount and unmount the VMware Tools installer CD as a CD-ROM for the guest operating system, use the connect and disconnect operations of the

tools/installer

service.

To mount the VMware Tools, use the

POST https://<

api_host

>/api/vcenter/vm/<

vm

>/tools/installer?action=connect

HTTP request. On Windows guest operating systems with activated Autorun feature, this request automatically initiates the installation of the VMware Tools and requires a user input to complete. On other guest operating systems, this method only mounts the VMware Tools disk image on the virtual CD/DVD drive and the user is required to do some guest OS-specific actions. For example, for some Linux distributions, the user is required to extract the contents of the VMware Tools installation archive and run the installer.

To unmount the VMware Tools installer CD image from the virtual CD/DVD drive, use the

POST https://<

api_host

>/api/vcenter/vm/<

vm

>/tools/installer?action=disconnect

HTTP request.

To monitor the status of the VMware Tools installation, you can check the

Tools.Info.version-status

and

Tools.Info.run-state

from

Tools.get

.

To upgrade the VMware Tools, use the

POST https://<

api_host

>/api/vcenter/vm/<

vm

>/tools?action=upgrade

HTTP request. The request takes as arguments the ID of the virtual machine on which the VMware Tools is installed and running. Use the

command_line_options

string to specify the command-line options that you want to pass to the installer to modify the tools installation procedure. You can monitor the upgrade operation in the same way you monitor the installation operation.

To update the properties of the VMware Tools, use the

PATCH https://<

api_host

>/api/vcenter/vm/<

vm

>/tools

HTTP request. Pass as argument a

VmToolsUpdateSpec

data structure and define the tools upgrade policy settings for the virtual machine by using the

VmToolsUpgradePolicy

enumerated type.

You can start, stop, reboot, and suspend virtual machines by using the operations of the

Power

service.

A virtual machine can have one of the following power states:

POWERED_ON
- Indicates that the virtual machine is running. If a guest operating system is not currently installed, you can perform the guest OS installation in the same way as for a physical machine.
POWERED_OFF
- Indicates that the virtual machine is not running. You can still update the software on the physical disk of the virtual machine, which is impossible for physical machines.
SUSPENDED
- Indicates that the virtual machine is paused and can be resumed. This state is the same as when a physical machine is in standby or hibernate state.

To perform a power operation on a virtual machine, you can use one of the operations of the

Power

service. Before you use one of the operations to change the power state of a virtual machine, you must first check the current state of the virtual machine by using the

GET https://<

api_host

>/api/vcenter/vm/<

vm

>/power

HTTP request. Pass as argument the virtual machine identifier.

Following is a list if the power operations, which you can use with a

POST

HTTP request:

power?action=start
- Powers on a powered off or suspended virtual machine. The method takes as argument the virtual machine identifier.
power?action=stop
- Powers off a powered on or suspended virtual machine. The method takes as argument the virtual machine identifier.
power?action=suspend
- Pauses all virtual machine activity for a powered on virtual machine. The method takes as argument the virtual machine identifier.
power?action=reset
- Shuts down and restarts the guest operating system without powering off the virtual machine. Although this method functions as a
stop
operation that is followed by a
start
operation, the two operations are atomic with respect to other clients, meaning that other power operations cannot be performed until the
reset
operation completes.

When you create a virtual machine, it becomes part of the

vCenter Server

inventory and is registered to the host and

vCenter Server

. If you remove a virtual machine from the

vCenter Server

inventory, it becomes unusable. Virtual machine files remain in the same datastore but you cannot power on the virtual machine when it is not registered in the inventory.

You can temporarily remove a virtual machine from

vCenter Server

by unregistering it. Virtual machine files are not deleted from the datastore. Though all high-level information about the virtual machine such as statistics, resource pool association, permissions, and alarms, is removed from the host and the

vCenter Server

instance. To remove a virtual machine from the inventory, use the

POST https://<

api_host

>/api/vcenter/vm/<

vm

>?action=unregister

HTTP request and specify the ID of the virtual machine.

To restore a virtual machine to the

vCenter Server

inventory, and make it usable again, use the

POST https://<

api_host

>/api/vcenter/vm/<

vm

>?action=register

HTTP request. You pass as argument a

VMRegisterSpec

data structure that contains information about the current location of the virtual machine files on the datastore. You can also define the location within the

vCenter Server

inventory, for example, the cluster, folder, or the host, where you want to register the virtual machine. After registration, the virtual machine takes its resources (CPU, memory, and so on) from the resource pool or host to which it is registered.

If you no longer need a virtual machine and you want to free up datastore space, you can permanently delete a virtual machine from the inventory. Use the

DELETE https://<

api_host

>/api/vcenter/vm/<

vm

>

HTTP request and specify the ID of the virtual machine. Upon a successful completion of the operation, the virtual machine files are removed from the datastore, including the configuration file and the virtual disk files.