VMware

VIX API 1.9 and 1.10.3 Release Notes

for Workstation 7.1.x and vSphere 4.1 | 29 March 2011 | Build 368992
Last document update: 28 March 2011

Contents:

VIX 1.9 was the VIX API release for Workstation 7.1 and Player 3.1.

VIX 1.10.3 is the standalone VIX API release that integrates compatibility libraries for ESX/ESXi 4.1 (and VMware vSphere) with other platform products. VIX 1.10 includes earlier VIX libraries delivered for VMware Player and Workstation, without changes to those libraries. VIX 1.10.3 now includes support for:

  • Player 3.1.1, Player 3.1.2, Player 3.1.3, and Player 3.1.4
  • Workstation 7.1.1, Workstation 7.1.2, Workstation 7.1.3, and Workstation 7.1.4

To obtain the VIX 1.10.3 libraries, click the Download link on the VIX API landing page. The VIX 1.9.x libraries are also delivered with Workstation 7.1.x.

These release notes give compatibility information for ESX/ESXi 4.1 and VMware vSphere. To find compatibility information for Workstation and VMware Server, see the VIX 1.8.1 Release Notes. Client libraries for those hosted products are revised on a separate train.

New in This Release

The following features are new or updated since VIX 1.8.1, the last standalone release of the VIX API.

  • Simplified URL for host connect.
    The vmrun command now accepts an -h option, and the VixHost_Connect function takes a hostName parameter, containing just the DNS name or IP address and optional port number. VIX supplies the leading “https://” and trailing “/sdk” if not included in the URL. Use the vmrun -T server option, not -T esx for this.
  • Improvements to vmrun.
    The runScriptInGuest command of the vmrun utility now supports the -nowait option. See the manual Using vmrun to Control Virtual Machines for details.
  • Encrypted virtual machines.
    The VixHost_OpenVM function, introduced in VIX API 1.8, provides support for encrypted virtual machines. With vmrun, you can specify encryption password with the -vp flag.
  • VMware Player.
    You can use VIX 1.8 and later to automate operations with VMware Player. See the technical note Getting Started with the VIX API for VMware Player for details.

Compatibility and Interoperability

The same or similar VIX source code (written in C, C++, Perl, or COM) runs on all VMware platform products that support it, including Workstation 6.0.5 and later, Player 3.x, ESX/ESXi 4.x, and vSphere. Programs should be compiled using platform product-specific libraries. The vmrun program is available for Fusion 3.x, additionally.

Deprecation Summary

  • The OpenUrlInGuest interface was deprecated in the VIX 1.8 release, but remains available.
  • The Event Pump option of host-connect was deprecated in the VIX 1.8 release, and should be avoided.
  • As of the VIX 1.7 release, the host handle was cleaned up after disconnect, thus eliminating handle sharing behavior.

Resolved Issues

  • New vmrun prevents local privilege escalation in Linux.
    VMware vmrun is a utility that performs various tasks on virtual machines. It runs on any platform with VIX libraries installed. VMware Workstation installs it by default. With releases before 1.10.3, in non-standard filesystem configurations, an attacker with the ability to place files into a predefined library path could take execution control of vmrun. For more information, see the knowledge base article Updated version of vmrun. The Common Vulnerabilities and Exposures project (cve.mitre.org) has assigned the name CVE-2011-1126 to this issue.
  • Support for VMware Management Appliance.
    The VIX 1.10 libraries now install correctly on the VMware Management Appliance (vMA).
  • Meaningful error if simultaneously connecting to different host types.
    When VIX programs running on any host call VixHost_Connect multiple times in the same process with different hostType values, they now get a MULTIPLE_SERVICEPROVIDERS error. This is because a VIX client loads different DLLs or shared-objects for connecting to each host type, and conflicting libraries cannot be loaded into a single process.
  • Host handle cleaned up after disconnect.
    In previous versions of the VIX API, when you called VixHost_Connect multiple times for the same host from the same client process, it returned the same host handle. This handle-sharing behavior caused problems because it made it too easy to accidentally use a host handle after it had been disconnected. The handle-sharing behavior has been eliminated. Now, separate calls result in separate handles, even when connecting to the same host.
  • List directory works for Windows network-mapped drives.
    The VixVM_ListDirectoryInGuest function now succeeds when listing directories on a network-mapped drive in a Windows guest.

Known Issues

  • Compiling with the wrapper library on Linux now requires the pthread library.
    When linking with the wrapper library vixAllProducts.so, you must now link with the POSIX threads library. Do this by adding -lpthread to the linking command.
  • After installing Player on Linux, if uninstalling VIX, remove its configuration files.
    Normal installation of VMware Player and the VIX API works as documented. However, if you ever uninstall the VIX API, please select the option to remove its configuration files. Otherwise, a later attempt to re-install VMware Player will fail. If this does occur, the work-around is to remove all files under /etc/vmware-installer.
  • Revert-to-snapshot might fail with an unknown error.
    When performing RevertToSnapshot operations concurrently on a large number of VMs residing on the same ESX/ESXi host, an operation could fail with error code 1 VIX_E_FAIL when the snapshot-reverted VMs are powered on. The VMs are reverted successfully, but might be left in suspended state. When this occurs, you can safely power on any suspended VMs.
  • VixCOM Host.CreatePropertyList method returns type mismatch in VBScript.
    The new Host.CreatePropertyList API is supported with C# in Workstation 7.1, but attempting to use it with VBScript results in a type mismatch error. The Host.CreatePropertyList method and COM PropertyList was not documented in the initial Workstation 7.1 release.
  • Misleading error when connecting too frequently.
    When calling VixHost_Connect many times rapidly in a tight loop (approximately 240 or more times before the first call completes) error code 30028 VIX_E_NET_HTTP_OPERATION_TIMEDOUT may result.
  • Host to guest copy might fail with deeply nested subdirectories.
    When calling VixVM_CopyFileFromGuestToHost or VixVM_CopyFileFromHostToGuest on a directory with a very deeply nested set of subdirectories, an error can occur. This could be due to length of the pathname.
  • Installer UI does not start on SUSE and possibly other Linux guests.
    On SUSE 11.2 and possibly other Linux distributions, the sudo command does not preserve the DISPLAY environment, so the VIX installer UI fails to start. In this case, the installer still runs fine in console (non-UI) mode. A workaround for UI mode is adding this line to the /etc/sudoers file:
    Defaults env_keep+="DISPLAY"
  • With host under stress, revert to snapshot might fail.
    A call to VixVM_RevertToSnapshot can fail if the ESX/ESXi host is under very heavy load, for example, when calling VixVM_RevertToSnapshot simultaneously for a large number of virtual machines. This happens only when reverting to a snapshot that was taken of a powered-on virtual machine.
  • When removing a shared folder, the change is not immediately visible in the guest.
    After removing a shared folder with VixVM_RemoveSharedFolders, there can be a delay of several seconds before the change is visible within the guest and to functions such as VixVM_DirectoryExistsInGuest. Due to caching, the VIX libraries might say the directory still exists.
  • Connecting remotely to VMware Server 1.0 can fail on Linux clients.
    On some Linux 32-bit distributions, calling VixHost_Connect to a remote VMware Server 1.0.x host might fail because VIX cannot find the libcrypto-0.9.7.so library. The workaround is to install the same version of VMware Server on the system where you run the VIX client program.
  • Case-insensitive search on vCenter Server with SQL database.
    The default SQL Server for vCenter Server performs case-insensitive database searches, which affects the VixVM_Open and VixHost_UnregisterVM functions. For example, if you have two VM pathnames, [datastore]VM/VM.vmx and [datastore]vm/vm.vmx, the VIX API cannot distinguish between them for opening or registration. A workaround is to substitute the Oracle database server. This is fixed in vCenter Server 4.1 but not for earlier vCenter Servers.
  • On Windows 7, build VIX Perl with Visual Studio 2008.
    On Windows 7, you need to build the vix-perl library with Visual Studio 2008. If you use an earlier version of Visual Studio, scripts often fail with the “Can't load VixBinding.dll” error message.
  • Soft power operations not immediately available after power-on.
    After VMware Tools begin running in the guest, there might be a short delay before soft power operations are available. These include VixVM_PowerOff and VixVM_Reset when the argument PowerOptionsincludes the bit flag VIX_VMPOWEROP_FROM_GUEST. The short delay could cause a job to return error code 3009, VIX_E_POWEROP_SCRIPTS_NOT_AVAILABLE. As a workaround, you can insert a short wait if you call either function immediately after a virtual machine is powered on and tools become available in the guest.
  • RunScriptInGuest does not execute script with cscript.exe interpreter.
    The cscript.exe interpreter relies on a file's extension to determine what type of scripting engine to run. VixVM_RunScriptInGuest copies text of the script into a file with .tmp extension, so cscript.exe is unable to determine what type of script it is.
  • Guest operations can hang if a hard reset occurs while Tools are processing the operation.
    The VixVM_Reset function can cause confusion of tools state, even when VixVM_WaitForToolsInGuest returns successfully. This is most noticeable with RunScriptInGuest and RunProgramInGuest because they take time to complete. The virtual machine does not discard commands during a hard reset, but the reset might cause VMware Tools to lose state, get out of sequence, and fail to complete the guest operations.