VMware

 

VIX API Version 1.6 Release Notes


For VMware Server 2.0 | 29 OCT 2008 | Build 122956

Last Document Update: 31 DEC 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). On Server 2.0 for Linux, insert /lib after vmware-vix.

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.

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

  • Suspend gives misleading error for out of disk space. When the host lacks space to store a suspended virtual machine, the VixVM_SuspendVM() function returns error 13 VIX_E_FILE_ACCESS_ERROR instead of error 8 VIX_E_DISK_FULL.

  • Problems upgrading virtual hardware. After calling VixVM_UpgradeVirtualHardware() on a guest virtual machine, the VixVM_PowerOn() function sometimes fails. Occasionally, VixVM_UpgradeVirtualHardware() itself fails with error code VIX_E_VM_NOT_RUNNING. The workaround is to power-on or upgrade manually.

  • Snapshot takes time to create. On Windows hosts, calling VixVM_GetCurrentSnapshot() shortly after VixVM_CreateSnapshot() occasionally results in error 13003 VIX_E_SNAPSHOT_NOTFOUND. The snapshot eventually appears.

  • Open URL in Linux guest fails to return. On some Linux guests such as 64-bit RHEL4 and Red Hat 9.0, calling VixVM_OpenUrlInGuest() opens a web browser but does not return, or returns VIX_OK without opening a web browser. The error might be either 3006 VIX_E_VM_NOT_RUNNING or “non-existent implementation library.”

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

  • Resetting virtual machine sometimes confuses tools state. The VixVM_Reset() function can cause confusion of tools state, even when VixVM_WaitForToolsInGuest() returns successfully. This is noticeable with RunScriptInGuest and RunProgramInGuest because they take time to complete. The virtual machine does not discard commands during a hard reset, but reset causes VMware Tools to lose state and get out of sequence.

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

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

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

  • Cannot create guest directory on an NFS share. When trying to create a directory on an NFS mounted partition, the VixVM_CreateDirectoryInGuest() function fails with error code 13 VIX_E_FILE_ACCESS_ERROR.

  • Killed process takes time to disappear. On Windows guests, calling VixVM_ListProcessesInGuest() shortly after VixVM_KillProcessInGuest() sometimes continues showing the killed process. The process eventually disappears.

  • Same-name snapshots do not behave as documented. Calling VixVM_GetNamedSnapshot() with a duplicated snapshot name returns error 13017 VIX_E_SNAPSHOT_NONUNIQUE_NAME instead of the first match as documented. The workaround is to specify the full path to a same-named snapshot.

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

  • Cannot unregister a virtual machine with special characters in path. The VixHost_Unregister() function might not work well when the path-to-VMX contains non-alphanumeric characters.

  • 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 requires null interpreter for cmd.exe batch scripts. To use cmd.exe as the interpreter for batch scripts, specify the RunProgramInGuest interpreter parameter as null. Do this both in the API and the vmrun command. This example runs a batch script and keeps the cmd window active:

    vmrun -gu Administrator -gp AdminPasswd runScriptInGuest
    "C:\My VMs \WinXP\WinXP.vmx" "" "cmd.exe /k \"C:\\bin\\script.bat\" x86"


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