VMware

 

VIX API Version 1.5 Release Notes

For Server 2.0 and Workstation 6.5 Beta 2


Released 23-June-2008

The VIX API allows development of scripts and programs to automate virtual machine operations. The API is high-level, easy to use, and practical for script writers and application programmers. The package includes:

  • C API – This release includes C language functions that allow you to register, power virtual machines on or off, and run programs in guest operating systems.
  • Perl API – This release also includes a simplified API available in the Perl language.
  • COM API – This release includes a COM binding, for development of C#, Visual Basic, and VBScript clients.
  • Command-line Utility – Included with the installation is the vmrun command-line utility, based on the VIX API.

This document contains the following sections:


New in This Release

  • VIX libraries in Server 2.0 beta are not compatible with Workstation beta. For the Workstation 6.5 beta, you should use the VIX API that came with Workstation, or the standalone installer from that beta page. For the Server 2.0 beta, you should use the VIX API that came with Server. This restriction is applicable only to beta versions of the VIX API.

  • New vmrun commands and features.
    See the new manual, Using vmrun to Control Virtual Machines.

  • New API calls including Record and Replay.
    The following new C functions were added for both Workstation and Server:
    • VixVM_ReadVariable
    • VixVM_WriteVariable
    The following new C functions were added for Workstation only:
    • VixVM_BeginRecording
    • VixVM_BeginReplay
    • VixVM_Clone
    • VixVM_EndRecording
    • VixVM_EndReplay
    • VixVM_Pause
    • VixVM_Unpause
    The following new COM bindings were added:
    • DeleteFileInGuest
    • ReadVariable
    • WriteVariable
    The following new Perl routines were added:
    • FindItems
    • FindRunningVMs
    • VMReadVariable
    • VMWriteVariable

  • Library files located in new directories. Shared libraries and vix.lib are in the Workstation-6.5.0 directory now, not ws-3 as in previous releases. To compile a VIX client on without using the recommended wrapper library, make libraries available to your program from VMware VIX\Workstation-6.5.0\32bit or vmware-vix/Workstation-6.5.0/32bit. For Server, substitute VIServer-2.0.0 for Workstation-6.5.0. Installed documentation might contain the wrong pathnames, but this has been corrected in the vmware.com Web version.


Issues Resolved in This Release

  • Server 2.0 removes snapshot promptly. After a call to VixVM_RemoveSnapshot, the wait period and erroneous VIX_OK return from VixVM_GetRootSnapshot have been eliminated.

  • Clone option of vmrun exits with powered-on guest. Executing the vmrun clone option on a powered-on guest now produces an error message, instead of making an invalid snapshot.

  • Upgrading hardware version 3 to 4 in VMware Server. Calling VixVM_UpgradeVirtualHardware or vmrun upgradevm on a virtual machine created with Workstation 4.x (hardware version 3) works in Server 2.0, but not in Workstation 6.5 yet.

  • Host Agent service continues running on Windows 2003. On Server 2.0 in long-running tests on Windows 2003, the VMware Host Agent service no longer terminates prematurely in a RegisterVM or similar operation.

  • Can use VixVM_Clone with Vix_PumpEvents to create a clone of a powered-off virtual machine. Creating a full clone of a powered-off parent no longer throws an exception when used with Vix_PumpEvents().

  • The setSharedFolderState option available in vmrun. The vmrun option setSharedFolderState is now implemented.

  • Support in vmrun for Vista interactive logon. When using vmrun RunProgramInGuest for a Windows Vista guest operating system. use the -interactive option to make your program visible in the console window.

  • Opening child snapshots created by the UI. When creating a snapshot through the Workstation UI, VixSnapshot_GetChild() returns the snapshot correctly now.

  • The vix-perl package includes required libraries. On both Windows and Linux, the vix-perl package now includes all required libraries, so you do not have to set Path or LD_LIBRARY_PATH.

  • Upgrading virtual hardware and user confirmation dialog. When you call the VixVM_UpgradeVirtualHardware() function, the dialog box to confirm virtual-machine upgrade appears only for interactive sessions.

  • HostConnect with event pump option in VMware Server. You can now safely call VixHost_Connect() with the VIX_HOSTOPTION_USE_EVENT_PUMP option on VMware Server. The VixJob_CheckCompletion() function will return.

  • Microsoft Windows 95 guest operations supported. Functions such as guest file operations, getting and setting of guest environment variables, and running programs in the guest, now work properly for Microsoft Windows 95 guests.

  • The vmrun utility and snapshots of the same name. When snapshots have the same name, use the path-to-VMX option of vmrun to distinguish them.

  • Issue with background resume feature fixed. If the background resume feature is enabled for a virtual machine, Vix no longer reports too early that the resume operation is complete.


Issues Resolved Since VIX 1.1

  • Anonymous guest authentication options have been disabled. This change may cause certain client programs to fail, or request credentials, if they depend on anonymous authentication options. The removed options are:
    • VIX_CONSOLE_USER_NAME
    • VIX_ADMINISTRATOR_USER_NAME
    These options were added in an earlier release for the convenience of interactive client programs that needed to take actions in the guest. In version 1.1.3, the options were removed to harden the VIX API against attacks that could compromise the security of operations with VMware virtual machines. The Eclipse Integrated Virtual Debugger and the Visual Studio Integrated Virtual Debugger now prompt for user account credentials to access a guest.

  • VIX API error strings have been localized into Japanese. The error text returned from Vix_GetErrorText() is provided either in English or Japanese, depending on the default locale for the system on which the VIX API client is running. This change is effective only when running the VIX client against Workstation 6.0.1 or later.

  • Ten-folder limit on VixVM_AddSharedFolder() function. The VixVM_AddSharedFolder() function was limited to 10 shared folders. This problem has been corrected.

  • Wrapper library problem on Linux. When using the VIX API on Linux, the wrapper library had problems with missing symbols, which prevented clients from linking with it. This problem has been corrected.

  • Problem linking VixAllProducts.lib to a debug version of the C runtime on Windows. The VixAllProducts.lib library for Microsoft Windows did not function correctly when linked with a debug version of the C runtime libraries. This problem has been corrected; the library vixAllProductsd.lib may be used with debug versions of the C runtime libraries.

  • VixVM_PowerOn() failed when multiple VMware products installed. The VixVM_PowerOn() function previously relied on the VMINSTALL environment variable to locate installed VMware executables. If you first installed a VMware product that supports the VIX API, then you later installed a VMware product that does not support the VIX API, VMINSTALL would point to the later installation. This problem has been corrected for the Workstation 6.0.1 release.

  • Reverting to snapshot leaves virtual machine suspended. If you want to power on a virtual machine after reverting to a snapshot, first revert to the snapshot, then power on as a separate operation.


Recently Discovered Issues

  • On Server 2.0, wait before removing reverted-to snapshot. After a CreateSnapshot and RevertToSnapshot, you must wait about 60 seconds before calling RemoveSnapshot otherwise a VIX_E_VM_NOT_RUNNING error results.

  • On Server 2.0 for 64-bit Windows, listing processes might kill them. On 64-bit Windows platforms only, ListProcessesInGuest might kill 32-bit processes running on the guest operating system.

  • When you upgrade VMware Server 2.0 from Beta2 to RC1 on Linux hosts, downgrade VIX when prompted. If a prompt during installation asks you to downgrade VIX, answer yes. Otherwise you will not get the latest VIX libraries.

  • Cannot build VIX C programs with Visual Studio 2003. They do build with Visual Studio 2005, but stubs for five functions (fstat, wstat, timezone, tzname, ftol2_sse) are missing for Visual Studio 2003. For VIX 1.5 beta, Visual C release 8.0.50727.762 or later is required.

  • Power-off after revert-to-snapshot returns an error. The sequence of VixVM_PowerOn(), VixVM_CreateSnapshot(), VixVM_RevertToSnapshot(), and VixVM_PowerOff() produces error 3006 VIX_E_VM_NOT_RUNNING although the virtual machine is running before power-off. Without VixVM_RevertToSnapshot() in the sequence, VixVM_PowerOff() returns normally.

  • Connect immediately after disconnect sometimes fails. The VixHost_Disconnect() function occasionally returns too soon, in which case VixHost_Connect() called immediately thereafter might fail. A workaround is to wait a second after disconnecting.

  • Issue with vmrun, virtual machine open, and nogui. If a virtual machine is already open in the GUI but not powered on, and you try to start it with the nogui option, vmrun throws an error saying "the file is already in use."

  • Windows guest environment variable is not persistent after power cycle. Contrary to the function reference documentation, setting an environment variable using VixVM_WriteVariable() with type GUEST_ENVIRONMENT_VARIABLE might not be persistent across power cycle of a Windows guest operating system.

Previously Known Issues

  • Wait before calling VixVM_InstallTools(). The function VixVM_InstallTools() sometimes fails to work correctly if you call it immediately after powering on a virtual machine. VixVM_InstallTools() mounts an ISO image containing the VMware Tools installer, but the guest operating system can fail to recognize the mounted image or to execute the autorun file if the guest operating system has not completed its startup process.
    To work around this problem, wait until the guest operating system is fully operational before calling VixVM_InstallTools().

  • Host-find routines reporting all running virtual machines. Calling VixHost_FindItems() with the VIX_FIND_RUNNING_VMS option does not immediately detect all running virtual machines. The same is true for the Perl function FindRunningVMs(). To work around this issue, add a five-second delay after powering on a virtual machine.

  • Unsupported shared folder functions fail silently. Microsoft Windows 95, Windows 98, and Windows ME guest operating systems do not support shared folder functions. Calls to such functions for these guests fail without returning an error code.

  • Inconsistency in Folder and File Characters. The shared folder and file copy functions in the VIX API are inconsistent in the set of characters they allow in folder names. As a result, you can create a shared folder that you subsequently cannot use in a file copy function such as VixVM_CopyFileFromHostToGuest(). To work around this problem, avoid using non-alphanumeric characters in shared folder names.

  • Vix shared folder status subject to delay in Linux guests. The HGFS (host-guest file system) driver for a Linux guest caches information about shared folders. The default caching duration is five seconds. As a consequence, Vix functions that check the status of a shared folder in the HGFS file system will see stale information for five seconds after the state of the shared folder changes. For instance, if you call VixVM_RemoveSharedFolder() to remove a shared folder, then immediately call VixVM_FileExistsInGuest() to test for a file in the shared folder, the file system reports that the file still exists in a subdirectory of /mnt/hgfs. To work around this issue, have a client sleep for five seconds before assuming that the shared folder status is correct.

  • VixVM_EnableSharedFolders() behaves differently depending on the power state. If you call VixVM_EnableSharedFolders() when the virtual machine is powered on, shared folders are enabled only until the next power-off or suspend operation. If you call VixVM_EnableSharedFolders() when the virtual machine is powered off, the enabled setting persists until you change it again.

  • VixVM_ListDirectoryInGuest() failure for outdated Tools. If VMware Tools in the guest operating system is not current, VixVM_ListDirectoryInGuest() may fail with the error code E_INVALID_ARG. To correct the problem, use VixVM_InstallTools() to upgrade to the current version of VMware Tools.

  • RunScriptInGuest does not work with DOS batch commands (.bat or .cmd files). This is the case both in the API and with the vmrun command. Instead, use RunProgramInGuest to run the DOS batch command, or the cmd.exe interpreter on it, as shown in these examples, each typed on one line:

    vmrun -gu administrator -gp AdminPasswd runProgramInGuest
    "C:\My Documents\My Virtual Machines\WinXP\WinXP.vmx" "C:\Workarea\script.bat"

    vmrun -gu administrator -gp AdminPasswd runProgramInGuest
    "C:\My Documents\My Virtual Machines\WinXP\WinXP.vmx"
    "C:\Windows\System32\cmd.exe" "/c C:\Workarea\script.cmd"

  • Timeout range is limited to 2048 seconds. The timeoutInSeconds parameter of VixVM_WaitForTools() is limited to 2048 seconds. Larger values produce unpredictable results.

  • VIX API CopyFileFromHostToGuest() and CopyFileFromGuestToHost() reset permission bits (KB 2318633)

  • VIX API returns undefined error code in some situations (KB 3460454)

  • VIX API does not always report failure of VixVM_CopyFileFromGuestToHost() (KB 3656116)

  • VIX API might crash if client uses an invalid host handle (KB 2416845)

Last updated: 1-July-2008