VMware

VIX API 1.12 Release Notes

for Workstation 9 and Fusion 5 | 24 SEP 2012 | Build 812388
Last document update: 24 SEP 2012.

Contents:

VIX 1.12 is the VIX API release for VMware Fusion 5, Workstation 9, and Player 5. It incorporates compatibility libraries for vSphere 5.x, and was tested with ESXi 5.1. VIX 1.12 also includes earlier VIX libraries delivered for VMware Player and Workstation, without changes to those libraries.

To obtain the VIX 1.12 libraries, click the SDK Download link on the VIX API landing page. The VIX 1.12 libraries are also delivered with VMware Fusion 5 and Workstation 9. For documentation, see the VIX API landing page.

New in This Release

The following features are new or updated since VIX 1.11, the last standalone release.

  • VIX API included with VMware Fusion 5.0.
    VMware Fusion for the Mac now includes the VIX API for virtual machine automation.
  • New temporary-file command for vmrun.
    The createTempFileInGuest command was added to the vmrun utility in this release. For details see the manual Using vmrun to Control Virtual Machines.
  • Added issue about System.View privilege requirement.
    See first item under Compatibility added 1 Mar 2012.
  • Added note about ListProcessesInGuest fix.
    See last item under Resolved Issues added 21 Feb 2012.
  • Added notice about GuestComponentsOutOfDate.
    See item under Compatibility added 9 Dec 2011.

Deprecation Summary

The following features are deprecated or removed in this or the previous 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 ESXi is deprecated in the vSphere 5.0 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.
  • Features removed in VIX 1.11. The Record/Replay facility, the OpenUrlInGuest API, and the Vix_PumpEvents option, were all removed in the previous VIX release.

Compatibility and Interoperability

Developers should note the following constraints and changes.

  • 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).
  • Automatic upgrade of VMware Tools.
    When you run VixVM_InstallTools with VIX_INSTALLTOOLS_AUTO_UPGRADE flag in Workstation 8 and later, if VMware Tools are already up to date, the function returns VIX_OK rather than VIX_E_TOOLS_INSTALL_ALREADY_UP_TO_DATE.
  • Up-to-date VMware Tools required.
    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.
  • 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, and ESX/ESXi 4.x or later. Programs should be compiled using platform product-specific libraries.

Resolved Issues

The following resolved issues pertain only to this release. For a list of issues resolved in the previous release, see the VIX 1.11 Release Notes.

  • VMware Fusion now includes the VIX API.
    The vmrun program was included in earlier versions, and now the VIX API is available in VMware Fusion 5.0 for Mac OS X.
  • Better handling of VMotion in VIX guest libraries.
    VIX guest operations could hang after VMotion or Storage VMotion relocated a virtual machine to a different host or storage location. This was improved in this release by terminating any asynchronous operations.
  • 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 new VIX libraries and upgrade the guest to the latest version of VMware Tools. VIX and VMware Tools were fixed in vSphere 5 to handle long process list information.

Known Issues

The following known issues pertain to this VIX release only.

  • Chrome browser downloads bundle into wrong-name file.
    If you use Chrome to download the VIX 1.12 Linux install bundle, the browser renames the .bundle file with .txt extension. The workaround is to rename the file, then run sudo sh to install.

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

  • 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 uninstalling VIX with Player on Linux, remove configuration files.
    Normal installation of VMware Player and the VIX API works as documented. However, if you ever uninstall the VIX API, select the option to remove its configuration files. Otherwise, a later attempt to re-install VMware Player will fail. If this occurs, the work-around is to remove all files under /etc/vmware-installer.
  • 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 (or possibly later). 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.