VMware

 

VIX API Version 1.6 Release Notes


For VMware Server 2.0 RC2 | 19 AUG 2008 | Build 110949

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

  • Server 2.0 misleading install prompt eliminated. There is no longer a confusing prompt during Linux installation of Server 2.0 asking you to downgrade VIX.

  • Server 2.0 for 64-bit Windows and listing processes. On 64-bit Windows platforms, ListProcessesInGuest no longer kills 32-bit processes running on the guest operating system.

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

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

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

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

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

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

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.

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

  • Virtual hardware upgrade might fail. The VixVM_UpgradeVirtualHardware() function occasionally fails just before completion with error code VIX_E_VM_NOT_RUNNING. A workaround is to upgrade manually.

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

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

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

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

  • Resetting virtual machine sometimes confuses tools state. The VixVM_Reset() function can cause confusion of tools state, even when the VixVM_WaitForToolsInGuest() function returns successfully.

  • 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 several seconds after disconnecting.

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

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