VMware

VIX API 1.11 Release Notes

for Workstation 8 and vSphere 5.0 | 14 SEP 2011 | Build 471780
Last document update: 18 SEP 2012.

Contents:

VIX 1.11 was the VIX API release for Workstation 8.0 and Player 4.0, and incorporated compatibility libraries for ESXi 5.0 and vSphere 5. VIX 1.11 also included earlier VIX libraries delivered for VMware Player and Workstation, without changes to those libraries.

To obtain the VIX 1.11 libraries, click the Download link on the VIX API landing page. The VIX 1.11 libraries are also delivered with Workstation 8.0.x. For documentation, see the VIX API landing page.

New in This Release

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

  • VIX API included with VMware Fusion 5.0.
    The vmrun program was included in earlier versions, and now the VIX API is available in VMware Fusion 5.0 for the Mac.
  • Added issue about System.View privilege requirement.
    See first item under Known Issues added 1 Mar 2012.
  • Added note about ListProcessesInGuest fix.
    See first item under Resolved Issues added 21 Feb 2012.
  • Added notice about GuestComponentsOutOfDate.
    See first item under Compatibility added 9 Dec 2011.
  • VIX libraries available for 64-bit Windows.
    The VIX client for Windows includes 32-bit libraries for all product versions, and new 64-bit libraries for vSphere, Workstation 8.0 and later, or Player 4.0 and later. When running VIX on earlier versions of Workstation or Player, only 32-bit Windows libraries are available.
  • Remote shared mode for Workstation virtual machines.
    VIX connectivity to Workstation-based virtual machines operating in shared mode (through remote connections) is a new feature, intended to replace VMware Server. For details, see the information about “shared mode” on the VIX API Reference page for VixHost_Connect.
  • Solaris and OpenSolaris guests.
    Solaris 10 (all updates) and OpenSolaris 2009.6 are now possible operating systems for VIX API guest operations and may be supported after further testing. VMware Tools for ESXi 5.0 or Workstation 8.0 must be installed or upgraded to enable guest operations on Solaris.
  • Improvements to vmrun.
    The directoryExistsInGuest command was added to the vmrun utility for this release. See the manual Using vmrun to Control Virtual Machines for details.
  • Updates for VMware Player.
    You can use VIX 1.8 and later to automate operations with VMware Player. For details see the technical note Getting Started with the VIX API for VMware Player. Changes described here also apply to Player.

Compatibility and Interoperability

Starting with the vSphere API 5.0, vSphere guest operations require an up-to-date version of VMware Tools. If tools installed on the guest are below minimum version, various GuestOperationsManager methods throw the exception GuestComponentsOutOfDate.

When you run VixVM_InstallTools with VIX_INSTALLTOOLS_AUTO_UPGRADE flag in Workstation 8.0, if VMware Tools are already up to date, the function returns VIX_OK rather than VIX_E_TOOLS_INSTALL_ALREADY_UP_TO_DATE.

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 or later, Player 3.x or later, ESX/ESXi 4.x or later, and vSphere. Programs should be compiled using platform product-specific libraries. The vmrun program is included separately with VMware Fusion 3 and newer versions.

Deprecation Summary

The following features are deprecated or removed in this release.

  • VIX API deprecated in vSphere. In ESXi 5.0, guest operations are available in the vSphere API, under managed objects GuestAuthManager, GuestFileManager, GuestOperationsManager, and GuestProcessManager. JAX-WS based code samples are provided in the Web Services SDK. So VIX API support for vSphere and ESXi is deprecated in this release. Deprecation means that VIX is currently a supported API, but VIX will be unsupported in the second major release after vSphere 5. VIX support will continue for VMware Workstation and Player.
  • Record/Replay not available. The Record/Replay mechanism was deprecated in Workstation 7.1 and is not present in Workstation 8.0. This removes the Recording and Replay commands in the vmrun utility, and four APIs: *BeginRecording, *EndRecording, *BeginReplay, and *EndReplay.
  • OpenUrlInGuest removed. The OpenUrlInGuest interface has been removed. It was deprecated in the VIX 1.8 release.
  • Event Pump removed. The function Vix_PumpEvents has been removed, and the option VIX_HOSTOPTION_USE_EVENT_PUMP is no longer valid for use with VixHost_Connect. The event pump was deprecated in the VIX 1.8 release.
  • In VIX 1.7 and later, the host handle is cleaned up after disconnect, thus eliminating handle sharing behavior. This happened in 2009 but is worth reiterating.

Resolved Issues

The following resolved issues pertain only to this release.

  • ListProcessesInGuest can now cope with long process lists.
    If the VixVM_ListProcessesInGuest function is executed against a guest operating system that is either running a large number of processes, or has processes with a large number of command line arguments, then it is possible for the VMware Tools process to fail with an ASSERT, resulting in “VMware Tools are not running in the guest” log messages. In this case, you should recompile programs with VIX 1.11 libraries and upgrade the guest to the latest version of VMware Tools. In vSphere 5.0, VIX and VMware Tools were fixed to handle long process list information.
  • With host under stress, revert to snapshot works correctly.
    When performing RevertToSnapshot operations concurrently on a large number of VMs residing on an ESX/ESXi host under heavy load, operations used to fail with error code 1 VIX_E_FAIL if the snapshots were taken of a powered-on VM, or when snapshot-reverted VMs were powered on. Usually the VMs were reverted successfully, but left in suspended state. This has been fixed.
  • More robust behavior when connecting very 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 sometimes occurred. This has been fixed.
  • Host to guest copy now works with deeply nested subdirectories.
    If calling VixVM_CopyFileFromGuestToHost or VixVM_CopyFileFromHostToGuest on a directory with a very deeply nested set of subdirectories, an error could occur, perhaps due to length of the pathname. This has been fixed.
  • Installer UI did start on SUSE and possibly other Linux guests.
    On SUSE 11.2 and possibly other Linux distributions, the sudo command did not preserve the DISPLAY environment, so the VIX installer UI failed to start. In this case, the installer still runs fine in console (non-UI) mode. This has been fixed.
  • Case-insensitive search on vCenter Server works 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 could not distinguish between them for opening or registration. This is fixed in vCenter Server 4.1 and later.
  • Guest operations with hard reset while VMware Tools process the operation.
    The VixVM_Reset function sometimes caused confusion of tools state, even when VixVM_WaitForToolsInGuest returned successfully. This was most noticeable with RunScriptInGuest and RunProgramInGuest because they take time to complete. In this release, VMware Tools is more robust for guest operations if a hard reset occurs.

The following resolved issues pertain to this VIX release and to previous releases.

  • Support for VMware Management Appliance.
    As of VIX 1.9, libraries install correctly on the VMware Management Appliance (vMA).
  • Meaningful error with simultaneous connect to different host types.
    When VIX programs running on any host call VixHost_Connect multiple times in the same process with different hostType values, as of VIX 1.10 they 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 versions before VIX 1.7, 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.
    As of VIX 1.8 the VixVM_ListDirectoryInGuest function succeeds when listing directories on a network-mapped drive in a Windows guest.

Known Issues

The following known issues pertain to this VIX release.

  • Opening a virtual machine requires System.View datacenter privilege.
    The connecting user must have the vSphere System.View privilege to successfully run any of the following APIs: VixHost_UnregisterVM (Perl/COM UnregisterVM), VixHost_OpenVM (Perl HostOpenVM or COM OpenVMEx), and VixVM_Open (Perl VMOpen or COM OpenVM). The connecting user is specified in the VixHost_Connect call (Perl HostConnect or COM Connect).
  • Interactive guest login does not work after fast user switch.
    Because the VMware Tools daemon vmtoolsd is not started for the second user, with fast user switching in a Windows virtual machine running on ESXi 5.0, the VixVM_LoginInGuest option VIX_LOGIN_IN_GUEST_REQUIRE_INTERACTIVE_ENVIRONMENT does not work. Windows fast user switching is enabled by default, except with domain authentication, when it is unavailable.
  • Power operations from guest can fail when called immediately after VixVM_WaitForToolsInGuest.
    Calling VixVM_PowerOff immediately after VixVM_WaitForToolsInGuest with option VIX_VMPOWEROP_FROM_GUEST could fail with unknown error, VIX_E_FAIL. The workaround is to add a small delay between these two operations.
  • Compiling with the wrapper library on Linux requires pthreads.
    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 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.

The following known issues pertain to this VIX release and to previous releases.

  • After snapshot revert, delay before correct snapshot is returned.
    After calling VixVM_RevertToSnapshot, there is some delay (possibly more than a minute) before VixVM_GetCurrentSnapshot correctly returns the current snapshot.
  • VixCOM Host.CreatePropertyList method returns VBScript type mismatch.
    The new Host.CreatePropertyList API is supported with C# as of 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.
  • 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.
  • 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.
  • 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.