VMware

 

VIX API Version 1.6 Release Notes


For VMware Workstation 6.5 RC | 15 AUG 2008 | Build 110068

Last Document Update: 21 AUG 2008

Check frequently for additions and updates to these release notes.

 

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.

Contents:

New in This Release

  • Enhanced 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 or VIServer-2.0.0 directory now, not ws-3 as in VIX 1.1.x releases. To compile a VIX client without using the recommended wrapper library, make libraries available to your program from VMware VIX\Workstation-6.5.0\32bit on Windows or vmware-vix/Workstation-6.5.0/32bit on Linux (substitute 64-bit or VIServer-2.0.0 as appropriate).

Issues Resolved for VIX 1.6

  • 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. You can now call VixVM_UpgradeVirtualHardware or vmrun upgradevm on a virtual machine created with Workstation 4.x (hardware version 3).

  • 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. The vix-perl package now includes all required libraries, so you do not have to set Path or LD_LIBRARY_PATH. Extracted libraries are in VMware VIX\vix-perl on Windows and /usr/lib/vmware-vix/lib/api/vix-perl on Linux.

  • 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.

  • 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 in VIX 1.1.x Releases

  • 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.

  • Ten-folder limit on VixVM_AddSharedFolder() function. The VixVM_AddSharedFolder() function was formerly 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.

Issues Discovered in VIX 1.6

  • Opening URL requires interactive environment for guest login. Before calling VixVM_OpenUrlInGuest(), you should run VixVM_LoginInGuest() with the VIX_LOGIN_IN_GUEST_REQUIRE_INTERACTIVE_ENVIRONMENT option, and enable autologin on the guest operating system.

  • Guest operations can hang if a hard reset occurs during Tools processing. This is noticeable mostly with RunScriptInGuest and RunProgramInGuest, because other operations complete much more quickly. The virtual machine does not discard commands during a hard reset, but VMware Tools lose state during reset, so they discontinue commands for which the virtual machine is waiting.

  • List directory fails for network-mapped drive on Windows guest. The VixVM_ListDirectoryInGuest() function fails when trying to list a directory on a Windows network-mapped drive.

  • Power-on is not recognized while a virtual machine is open. If you open a powered-off virtual machine with VixVM_Open() and subsequently power-on that virtual machine, the change is not reflected by VIX_PROPERTY_VM_POWER_STATE. Power-off can be recognized when the automation socket closes, but power-on cannot be recognized.

  • Windows Vista requires administrator for certain operations. The vmrun commands copyFileFromHostToGuest and deleteFileInGuest do not allow regular users, even those with administrator privileges, to modify system directories. Only the Administrator account can do this. This is also true of the VIX functions VixVM_CopyFileFromHostToGuest() and VixVM_DeleteFileInGuest().

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

  • 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."

  • Guest functions return TOOLS_NOT_RUNNING during a recording. Functions VixVM_RunProgramInGuest() and VixVM_ListProcessesInGuest() return error VIX_E_TOOLS_NOT_RUNNING when a virtual machine is in record mode. This is probably due to slow virtual machine response during a recording. The workaround is to impose a wait by inserting a sleep() statement or a longer timeout in the VixVM_WaitForToolsInGuest() function.

  • Perl make does not uninstall on Linux. The /usr/lib/vmware-vix/lib/api/vix-perl/README file tells you how to build and install VIX Perl. Afterwards, make uninstall does not uninstall on most Linux systems, it only tells you how to do so. On Red Hat, uninstall fails prematurely with an ExtUtils/Install.pm error.

  • 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.

Issues Known in VIX 1.1.x Releases

  • 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().

  • 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.

  • 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.

  • 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.

  • 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)