Common Tasks |
|
This chapter explains how to use the VIX API for common virtual machine management tasks. The following tasks are described:
To work with a virtual machine, you must first connect to the host where the virtual machine is stored. If the virtual machine is on a host running Workstation, you can connect to it only from a client on the same host. If the virtual machine is on an ESX/ESXi host, you can connect to that remote host by supplying credentials. If the virtual machine is on a host running VMware Server, you can connect to that host whether it is a local or remote host. In other words, Workstation requires local connection, and vSphere requires remote connections.
In all cases, you connect to a host using the VixHost_Connect() function. You specify the type of host with the hostType parameter for VixHost_Connect(). Pass one of the following values:
The hostType parameter describes the VMware software running on the host where the virtual machine is located, regardless of where the client is running. If you are using VMware Server to connect to a remote host, it does not matter which VMware product (if any) is running on the local host.
If you do not know in advance which VMware product the host will be running, you can pass VIX_SERVICEPROVIDER_DEFAULT for the hostType parameter. Although this no longer works for VMware Server 1.0.x, when you pass VIX_SERVICEPROVIDER_DEFAULT, the Vix library tries to determine which VMware product is installed on the host.
You can use the VixHost_Connect() function in three different ways, subject to the restrictions described above:
VixHost_Connect() is an asynchronous function, so the function call must be completed with a callback function or a call to VixJob_Wait().
This allows you to access, from a single client machine, any networked ESX/ESXi host or VMware Server. If the host is running VMware Workstation, you must use the procedure Connecting to the Local Host as the Current User.
For clients connecting through a firewall, open ports 8222 and 8333 for VMware Server on Windows, ports 80 and 442 for ESX/ESXi, or ports 80 and 443 (and possibly 902) for VMware Server on Linux. This is assuming vmware-hostd listens on the default ports. If you changed ports at installation time or with vmware-config.pl, open your ports instead.
#include "vix.h" int main(int argc, char * argv[]) { VixHandle hostHandle = VIX_INVALID_HANDLE; VixHandle jobHandle = VIX_INVALID_HANDLE; VixError err; // Connect to specified host. jobHandle = VixHost_Connect(VIX_API_VERSION, VIX_SERVICEPROVIDER_VI_SERVER, argv[1], // hostName 0, // hostPort argv[2], // userName argv[3], // password, 0, // options VIX_INVALID_HANDLE, // propertyListHandle NULL, // callbackProc NULL); // clientData err = VixJob_Wait(jobHandle, VIX_PROPERTY_JOB_RESULT_HANDLE, &hostHandle, VIX_PROPERTY_NONE); if (VIX_OK != err) { // Handle the error... goto abort; } Vix_ReleaseHandle(jobHandle); jobHandle = VIX_INVALID_HANDLE; // Other code goes here... abort: VixHost_Disconnect(hostHandle); }
If you specify the host when you connect to VMware Server, you can also choose to specify the port number. The port number defaults to 902, which is correct for most installations of VMware Server. Some installations might be configured to use a different port number, if port 902 is already in use on the host.
This allows your client to run on any host machine running VMware Server that has a given user account. For example, you could create a client script that a system administrator could use on any machine to shut down all virtual machines owned by a given user. The example shown below allows you to choose a user account when you run the script.
This form of connection is supported by VMware Server. If the host is running VMware Workstation, you must use the procedure Connecting to the Local Host as the Current User.
#include "vix.h" int main(int argc, char * argv[]) { VixHandle hostHandle = VIX_INVALID_HANDLE; VixHandle jobHandle = VIX_INVALID_HANDLE; VixError err; // Connect as specified user on local host. jobHandle = VixHost_Connect(VIX_API_VERSION, VIX_SERVICEPROVIDER_VMWARE_SERVER, NULL, // hostName 0, // hostPort argv[1], // userName argv[2], // password, 0, // options VIX_INVALID_HANDLE, // propertyListHandle NULL, // callbackProc NULL); // clientData err = VixJob_Wait(jobHandle, VIX_PROPERTY_JOB_RESULT_HANDLE, &hostHandle, VIX_PROPERTY_NONE); if (VIX_OK != err) { // Handle the error... goto abort; } Vix_ReleaseHandle(jobHandle); jobHandle = VIX_INVALID_HANDLE; // Other code goes here... abort: VixHost_Disconnect(hostHandle); }
This option allows you to connect a Vix client to a VMware product running on the same host. You can use this option with a host running either VMware Workstation or VMware Server.
This option maximizes portability. You can run the client on any host machine, without limiting yourself to a particular user account and without having to specify a user account at run time. However, you must be sure that the current user has appropriate permissions to use one or more virtual machines on the local host.
#include "vix.h" int main(int argc, char * argv[]) { VixHandle hostHandle = VIX_INVALID_HANDLE; VixHandle jobHandle = VIX_INVALID_HANDLE; VixError err; // Connect as current user on local host. jobHandle = VixHost_Connect(VIX_API_VERSION, VIX_SERVICEPROVIDER_VMWARE_WORKSTATION, NULL, // hostName 0, // hostPort NULL, // userName NULL, // password, 0, // options VIX_INVALID_HANDLE, // propertyListHandle NULL, // callbackProc NULL); // clientData err = VixJob_Wait(jobHandle, VIX_PROPERTY_JOB_RESULT_HANDLE, &hostHandle, VIX_PROPERTY_NONE); if (VIX_OK != err) { // Handle the error... goto abort; } Vix_ReleaseHandle(jobHandle); jobHandle = VIX_INVALID_HANDLE; // Other code goes here... abort: VixHost_Disconnect(hostHandle); }
ESX/ESXi and VMware Server require that a virtual machine be present in the "inventory" before virtual machine use. The virtual machine inventory is a list of virtual machines that the local host is able to run.
Conversely, if you remove a virtual machine from VMware Server's inventory, it is not available for any virtual machine operations. This is a convenient way to prevent virtual machines from being modified while they are not in regular use. You can also keep an unregistered virtual machine as a "gold" standard from which you can make copies as needed.
VMware Player and Workstation do not support registering virtual machines.
Registering or unregistering a virtual machine does not require a handle to the virtual machine, but it does require a path to the virtual machine's configuration (.vmx) file. The client must also provide a handle to the host machine where the virtual machine is to be registered or unregistered.
VixHost_RegisterVM() and VixHost_UnregisterVM() are asynchronous functions, so the function call must be completed with a callback function or a call to VixJob_Wait().
This feature is supported by ESX/ESXi and VMware Server.
VixHandle jobHandle = VIX_INVALID_HANDLE; char vmxFilePath[] = "c:\\Virtual Machines\\vm1\\win2000.vmx"; VixError err; // Add virtual machine to host's inventory. jobHandle = VixHost_RegisterVM(hostHandle, vmxFilePath, NULL, // callbackProc, NULL); // clientData err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE); if (VIX_OK != err) { // Handle the error... goto abort; } Vix_ReleaseHandle(jobHandle); jobHandle = VIX_INVALID_HANDLE;
This feature is supported by ESX/ESXi and VMware Server.
To unregister a virtual machine
VixHandle jobHandle = VIX_INVALID_HANDLE; char vmxFilePath[] = "c:\\Virtual Machines\\vm1\\win2000.vmx"; VixError err; // Remove virtual machine from host's inventory. jobHandle = VixHost_UnregisterVM(hostHandle, vmxFilePath, NULL, // callbackProc, NULL); // clientData err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE); if (VIX_OK != err) { // Handle the error... goto abort; } Vix_ReleaseHandle(jobHandle); jobHandle = VIX_INVALID_HANDLE;
Most virtual machine operations require a handle to identify the virtual machine. The VixVM_Open() function converts a path name to a handle, which you can use in subsequent function calls. VixVM_Open() is an asynchronous function, so the function call must be completed with a callback function or a call to VixJob_Wait().
To get a handle to a virtual machine
VixHandle jobHandle = VIX_INVALID_HANDLE; VixHandle vmHandle = VIX_INVALID_HANDLE; char vmxFilePath[] = "c:\\Virtual Machines\\vm1\\win2000.vmx"; VixError err; // Open virtual machine and get a handle. jobHandle = VixVM_Open(hostHandle, vmxFilePath, NULL, // callbackProc NULL); // clientData err = VixJob_Wait(jobHandle, VIX_PROPERTY_JOB_RESULT_HANDLE, &vmHandle, VIX_PROPERTY_NONE); if (VIX_OK != err) { // Handle the error... goto abort; } Vix_ReleaseHandle(jobHandle); jobHandle = VIX_INVALID_HANDLE; // ...Use vmHandle in subsequent code...
The VixVM_PowerOn() function has two purposes:
There is no separate Resume function in the VIX API. The VixVM_PowerOn() function must be used instead.
VixVM_PowerOn() is an asynchronous function, so the function call must be completed with a callback function or a call to VixJob_Wait().
For most purposes (especially if you want to do operations in the guest operating system) you must wait for VMware Tools to become active in the guest. Until the VMware Tools utility is ready, no guest operations using the VIX API can complete. See Installing VMware Tools in a Virtual Machine for more information about VMware Tools.
The VixVM_WaitForToolsInGuest() function allows you to wait until the VMware Tools utility is responding. There is a timeout parameter available for the function. You should generally set the timeout somewhat longer than the typical time it takes the guest operating system to finish booting.
VixError err = VIX_OK; VixHandle jobHandle = VIX_INVALID_HANDLE; // Power on the virtual machine. jobHandle = VixVM_PowerOn(vmHandle, 0, // powerOnOptions, VIX_INVALID_HANDLE, // propertyListHandle, NULL, // callbackProc, NULL); // clientData err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE); if (VIX_OK != err) { // Handle the error... goto abort; } Vix_ReleaseHandle(jobHandle); jobHandle = VIX_INVALID_HANDLE; // Wait for VMware Tools to be active. jobHandle = VixVM_WaitForToolsInGuest(vmHandle, 120, // timeoutInSeconds, NULL, // callbackProc, NULL); // clientData err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE); if (VIX_OK != err) { // Handle the timeout... } Vix_ReleaseHandle(jobHandle); jobHandle = VIX_INVALID_HANDLE;
To resume a suspended virtual machine:
Generally, VMware Tools was already active in the guest operating system when the virtual machine was suspended.
VixError err = VIX_OK; VixHandle jobHandle = VIX_INVALID_HANDLE; int toolsState = 0; // Resume suspended virtual machine. jobHandle = VixVM_PowerOn(vmHandle, 0, // powerOnOptions, VIX_INVALID_HANDLE, // propertyListHandle, NULL, // callbackProc, NULL); // clientData err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE); if (VIX_OK != err) { // Handle the error... goto abort; } Vix_ReleaseHandle(jobHandle); jobHandle = VIX_INVALID_HANDLE; // Check if VMware Tools active. err = Vix_GetProperties(vmHandle, VIX_PROPERTY_VM_TOOLS_STATE, &toolsState, VIX_PROPERTY_NONE); if (VIX_OK != err) { // Handle the error... goto abort; } Vix_ReleaseHandle(jobHandle); jobHandle = VIX_INVALID_HANDLE; if (VIX_TOOLSSTATE_RUNNING != toolsState) { // Wait for VMware Tools to be active. jobHandle = VixVM_WaitForToolsInGuest(VixHandle vmHandle, 120, // timeoutInSeconds, NULL, // callbackProc, NULL); // clientData err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE); if (VIX_OK != err) { // Handle the timeout... } Vix_ReleaseHandle(jobHandle); jobHandle = VIX_INVALID_HANDLE; }
VMware Tools is a suite of utilities and drivers to enhance the performance and functionality of your guest operating system. For instance, VMware Tools provides a mouse driver and an SVGA driver for the virtual machine.
VMware Tools also implements some of the functionality required for doing Vix functions that affect the guest operating system, such as VixVM_RunProgramInGuest(). You need to install VMware Tools before calling guest functions in the VIX API.
You can install VMware Tools manually by following the procedure described in the documentation for your VMware platform product. Or you can use the VIX API to do some or all of the installation steps from the host.
To begin the Tools installation process, you call the Vix function VixVM_InstallTools(). This function mounts a CD image containing the VMware Tools installer.
If the guest operating system has the autorun feature enabled, the installer starts automatically. Many guest operating systems require manual intervention to complete the Tools installation. You can connect a console window to the virtual machine and use the mouse or keyboard to complete the procedure as described in the documentation for your VMware platform product.
The VixVM_InstallTools() function is also useful for updating the version of VMware Tools installed in a virtual machine. When a newer version of the API is available, VMware recommends that you run the Tools installation on your virtual machines to make sure you are working with the latest version.
VixVM_InstallTools() is an asynchronous function, so the function call must be completed with a callback function or a call to VixJob_Wait().
VixError err = VIX_OK; VixHandle jobHandle = VIX_INVALID_HANDLE; // Mount virtual CD-ROM with VMware Tools installer. jobHandle = VixVM_InstallTools(vmHandle, 0, // options NULL, // commandLineArgs NULL, // callbackProc NULL); // clientData err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE); if (VIX_OK != err) { // Handle the error... goto abort; } Vix_ReleaseHandle(jobHandle); jobHandle = VIX_INVALID_HANDLE;
This section discusses several operations that provide access to the guest operating system.
All functions that execute in a guest operating system require VMware Tools to be installed and running. See Installing VMware Tools in a Virtual Machine for information on installing VMware Tools.
All functions that modify a file system in the guest operating system or that execute code in a guest operating system require the client to authenticate as a user account known to the guest. The following list shows the functions that require client authentication.
A client uses VixVM_LoginInGuest() to authenticate with the guest operating system. Once authenticated, the client may continue to perform guest operations until one of the following takes place:
If a virtual machine is suspended while a client is authenticated with the guest operating system, the client may resume guest operations after resuming virtual machine execution. However, this is true only as long as the client continues running while the virtual machine is suspended.
To authenticate with the guest operating system:
VixError err = VIX_OK; VixHandle jobHandle = VIX_INVALID_HANDLE; // Authenticate with guest operating system. jobHandle = VixVM_LoginInGuest(vmHandle, "Administrator", // userName "secret", // password 0, // options NULL, // callbackProc NULL); // clientData err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE); if (VIX_OK != err) { // Handle the error... goto abort; } Vix_ReleaseHandle(jobHandle); jobHandle = VIX_INVALID_HANDLE;
You may sometimes choose to provide a predefined string in place of an actual user name when calling VixVM_LoginInGuest(). The Vix header file provides the define VIX_CONSOLE_USER_NAME as a substitute for an actual user name. You must use this substitute for authentication with a Windows guest operating system if you plan to launch a graphical user interface in the guest.
Before calling VixVM_LoginInGuest() with VIX_CONSOLE_USER_NAME, you need to be sure that a user is currently logged in to the guest operating system. The user must log in through a graphical console connection to the virtual machine.
VixVM_LoginInGuest() establishes credentials for API operations but does not do an actual login to the guest.Using VIX_CONSOLE_USER_NAME is similar to making a second console connection to a virtual machine. When a user has logged in through one console connection, a second connection to the same virtual machine shares the display with the first connection and takes advantage of the first user's login account.
VIX_CONSOLE_USER_NAME is needed prior to calling these functions:
The password for VIX_CONSOLE_USER_NAME is always NULL.
VixError err = VIX_OK; VixHandle jobHandle = VIX_INVALID_HANDLE; // Authenticate with guest operating system. jobHandle = VixVM_LoginInGuest(vmHandle, CONSOLE_USER_NAME, // Use console ID NULL, // no password needed 0, // options NULL, // callbackProc NULL); // clientData err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE); if (VIX_OK != err) { // Handle the error... goto abort; } Vix_ReleaseHandle(jobHandle); jobHandle = VIX_INVALID_HANDLE;
This section discusses the operations used to power off or suspend a virtual machine.
You can stop virtual machine execution in several ways. Whether you choose to power off or to suspend a virtual machine depends on your purpose.
The suspend operation also saves the virtual machine's state on disk, allowing you to reboot the host or move the virtual machine to a new location without shutting down the guest operating system in the virtual machine.
Power functions are asynchronous, so they must be completed with a callback function or a call to VixJob_Wait().
To power off a virtual machine
VixError err = VIX_OK; VixHandle jobHandle = VIX_INVALID_HANDLE; // Power off the virtual machine. jobHandle = VixVM_PowerOff(vmHandle, VIX_VMPOWEROP_FROM_GUEST, // powerOffOptions NULL, // callbackProc NULL); // clientData err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE); if (VIX_OK != err) { // Handle the error... goto abort; } Vix_ReleaseHandle(jobHandle); jobHandle = VIX_INVALID_HANDLE;
VixError err = VIX_OK; VixHandle jobHandle = VIX_INVALID_HANDLE; // Suspend the virtual machine. jobHandle = VixVM_Suspend(vmHandle, 0, // powerOffOptions NULL, // callbackProc NULL); // clientData err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE); if (VIX_OK != err) { // Handle the error... goto abort; } Vix_ReleaseHandle(jobHandle); jobHandle = VIX_INVALID_HANDLE;
The VIX API allows you to run some legacy virtual machines, with some loss of functionality that depends on the virtual hardware version. A legacy virtual machine is one created by an earlier version of VMware software.
The properties of a virtual machine include a virtual hardware version that determine the capabilities of the virtual machine. VMware products generally support the current virtual hardware version and the previous virtual hardware version. Virtual machines older than the previous virtual hardware version are best upgraded, as they are not supported and they might fail to run.
Virtual machines created with ESX/ESXi host may also be used with the VIX API if they are first exported to the file formats used by Workstation and VMware Server. Refer to your ESX/ESXi documentation for information on exporting virtual machines.
When using legacy virtual machines, you can upgrade the virtual hardware by calling the VixVM_UpgradeVirtualHardware() function. This function upgrades the virtual hardware to the same level as virtual machines created with the current release.
To upgrade the virtual hardware version of your virtual machine
VixError err = VIX_OK; VixHandle jobHandle = VIX_INVALID_HANDLE; // Upgrade the virtual hardware. jobHandle = VixVM_UpgradeVirtualHardware(vmHandle, 0, // options NULL, // callbackProc NULL); // clientData err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE); if (VIX_OK != err) { // Handle the error... goto abort; } Vix_ReleaseHandle(jobHandle); jobHandle = VIX_INVALID_HANDLE;
Once you have upgraded the virtual hardware of a legacy virtual machine, you can no longer use that virtual machine with older VMware products – those that require a previous virtual hardware version. If you have any doubts about upgrading, make a copy of the legacy virtual machine before you upgrade the virtual hardware version.