VIX API Version 1.1.4 (for Workstation 6.0.4) Release Notes
Released 29-May-2008 | Build 93057
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 both script writers and application programmers.
The VIX API includes:
- C APIThis release of the API is available in the C language. API functions allow you to register, power on or off virtual machines, and run programs in the guest operating systems.
- Perl APIThis release also includes a simplified API available in the Perl language.
- COM APIThis 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.
This document contains the following sections:
New in This Release
New in the 1.1.3 Release
- Windows DLL files located in new directory.
Ten DLL files and vix.lib are in ws-5 now.
To compile a VIX client on Microsoft Windows without using the recommended wrapper library,
make DLL files available to your program from C:\Program Files\VMware\VMware VIX\ws-5\32bit,
not ws-3\32bit as in previous 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.
Issues Resolved in Previous Releases
- 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.
This change is effective only when running the VIX client against
Workstation 6.0.1 or later.
-
Ten-folder limit on VixVM_AddSharedFolder() function.
The VixVM_AddSharedFolder() function was 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.
-
VixVM_PowerOn() failed when multiple VMware products installed. The VixVM_PowerOn() function previously relied on the VMINSTALL environment variable
to locate installed VMware executables.
If you first installed a VMware product that supports the VIX API, then
you later installed a VMware product that does not support the VIX API,
VMINSTALL would point to the later installation.
This problem has been corrected for the Workstation 6.0.1 release.
Known Issues
-
The FindRunningVMs() function does not return appropriately on failure.
When the VIX API Perl function FindRunningVMs() succeeds, it returns VIX_OK and a host handle. However, when this function fails, it returns an empty list rather than an appropriate error message.
-
The VixVM_EnableSharedFolders() function 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.
-
VixHost_FindItems() does not consistently report all running virtual machines. Calling VixHost_FindItems() with the VIX_FIND_RUNNING_VMS option does not always detect all running virtual machines. The same is true for the Perl function FindRunningVMs(). To work around this issue, add a five-second delay after powering on a virtual machine.
-
RunScriptInGuest does not work with DOS batch commands (.bat or .cmd files). This is the case both in the API and with the vmrun command. Instead, use RunProgramInGuest to run the DOS batch command, or the cmd.exe interpreter on it, as shown in these examples, each typed on one line:
vmrun -gu administrator -gp AdminPasswd runProgramInGuest
"C:\My Documents\My Virtual Machines\WinXP\WinXP.vmx" "C:\Workarea\script.bat"
vmrun -gu administrator -gp AdminPasswd runProgramInGuest
"C:\My Documents\My Virtual Machines\WinXP\WinXP.vmx"
"C:\Windows\System32\cmd.exe" "/c C:\Workarea\script.cmd"
-
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.
- The VixVM_LoginInGuest() function fails when given an empty string
as a password. This is a security feature in Windows XP guest operating systems. For more information, visit:
http://support.microsoft.com/?id=303846
To work around this issue, create a new user account with a non-empty password, or change the password for the user account you use
to authenticate for guest operating system functions.
-
Timeout range is limited to 2048 seconds. The timeoutInSeconds parameter of
VixVM_WaitForTools() is limited to 2048 seconds.
Larger values produce unpredictable results.
-
VixVM_ListDirectoryInGuest() failure for outdated Tools.
If VMware Tools in the guest operating system is not current,
VixVM_ListDirectoryInGuest() may fail with the error code
E_INVALID_ARG. To correct the problem, use
VixVM_InstallTools() to upgrade to the current version of
VMware Tools.
- Issue with vmrun, virtual machine power-on, and snapshot.
The vmrun utility does not power on a virtual machine
if you revert to a snapshot that was taken while the virtual
machine was powered on. Instead, the virtual machine reverts
to the snapshot state but remains suspended.
-
Issue with background resume feature. If the background resume feature is enabled for a virtual machine, Vix might report too early that the resume operation is complete.
To work around this problem, disable the background resume feature (assuming it has been enabledby default, background resume is disabled).
-
The vmrun utility cant distinguish between snapshots with the same name. The Vix libraries identify snapshots with unique handles, but vmrun identifies snapshots by user-visible name, which need not be unique. If you give the same name to two snapshots, there is no way to identify them uniquely to vmrun.
-
Inconsistency in Folder and File Characters.
The shared folder and file copy functions in the VIX API
are inconsistent in the set of characters they allow in folder names.
As a result, you can create a shared folder that you subsequently
cant use in a file copy function such as
VixVM_CopyFileFromHostToGuest().
To work around this problem, avoid using non-alphanumeric characters
in shared folder names.
-
Vix shared folder status subject to delay in Linux guests.
The HGFS (host-guest file system) driver for a Linux guest caches information
related to 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 if you
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, a client should sleep for five seconds before
assuming the shared folder status is correct.
- Microsoft Windows 95 guest operations not supported.
Most guest operations, including guest file operations, getting and
setting of environment variables, and running programs in the guest,
will not work properly for Microsoft Windows 95 guests.
-
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, you should wait until the guest operating system
is fully operational before calling VixVM_InstallTools().
- VIX API 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)
|
Last updated: 19-May-2008 5:00 pm
|