VIX API Version 1.6 Release Notes
For VMware Workstation 6.5.1 | 21 NOV 2008 | Build 126130
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.
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:
The following new C functions were added for Workstation only:
The following new COM bindings were added:
The following new Perl routines were added:
- 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
Clone option of vmrun exits with powered-on guest.
Executing the vmrun clone option on a powered-on guest
now produces an error message, instead of making an invalid snapshot.
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).
Can use VixVM_Clone with Vix_PumpEvents
to create a clone of a powered-off virtual machine.
Creating a full clone of a powered-off parent no longer throws an exception
when used with Vix_PumpEvents().
The setSharedFolderState option available in vmrun.
The vmrun option setSharedFolderState is now implemented.
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.
Opening child snapshots created by the UI.
When creating a snapshot through the Workstation UI,
VixSnapshot_GetChild() returns the snapshot correctly now.
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.
The vmrun utility and snapshots of the same name.
When snapshots have the same name, use the path-to-VMX option of vmrun to distinguish them.
Issue with background resume feature fixed.
If the background resume feature is enabled for a virtual machine,
VIX no longer reports too early that the resume operation is complete.
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:
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.
Ten-folder limit on VixVM_AddSharedFolder() function.
The VixVM_AddSharedFolder() function was formerly limited to 10 shared folders.
This problem has been corrected.
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
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.
Power-on is not recognized while a virtual machine is open.
If you open a powered-off virtual machine with VixVM_Open()
and subsequently power-on that virtual machine,
the change is not reflected by VIX_PROPERTY_VM_POWER_STATE.
Power-off can be recognized when the automation socket closes,
but power-on cannot be recognized.
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.
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.
Cloning a suspended virtual machine misreports power state.
Calling VixVM_Clone() with the VIX_CLONETYPE_LINKED option
on a suspended virtual machine results in an VIX_E_VM_IS_RUNNING error.
This is because a suspended virtual machine retains its memory state,
so proceeding with the clone could cause loss of data.
Issue with vmrun, virtual machine open, and nogui.
If a virtual machine is already open in the GUI but not powered on,
and you try to start it with the nogui option,
vmrun throws an error saying "the file is already in use."
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.
Guest functions return TOOLS_NOT_RUNNING during a recording.
Functions VixVM_RunProgramInGuest() and VixVM_ListProcessesInGuest()
return error VIX_E_TOOLS_NOT_RUNNING when a virtual machine is in record mode.
This is probably due to slow virtual machine response during a recording.
The workaround is to impose a wait by inserting a sleep() statement
or a longer timeout in the VixVM_WaitForToolsInGuest() function.
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().
Unsupported shared folder functions fail silently.
Microsoft Windows 95, Windows 98, and Windows ME guest operating systems
do not support shared folder functions.
Calls to such functions for these guests fail without returning an error code.
VIX shared folder status subject to delay in Linux guests.
The HGFS (host-guest file system) driver for a Linux guest caches information about shared folders.
The default caching duration is five seconds.
As a consequence, VIX functions that check the status of a shared folder in the HGFS file system
will see stale information for five seconds after the state of the shared folder changes.
For instance, if you call VixVM_RemoveSharedFolder() to remove a shared folder,
then immediately call VixVM_FileExistsInGuest() to test for a file in the shared folder,
the file system reports that the file still exists in a subdirectory of /mnt/hgfs.
To work around this issue, have a client sleep for five seconds before assuming
that the shared folder status is correct.
VixVM_EnableSharedFolders() behaves differently depending on the power state.
If you call VixVM_EnableSharedFolders() when the virtual machine is powered on,
shared folders are enabled only until the next power-off or suspend operation.
If you call VixVM_EnableSharedFolders() when the virtual machine is powered off,
the enabled setting persists until you change it again.
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.
VIX API returns undefined error code in some situations.
VIX API does not always report failure of VixVM_CopyFileFromGuestToHost().
VIX API might crash if client uses an invalid host handle.