VMware

 

VIX API Version 1.6.2 Release Notes


For VMware Infrastructure support | 3 DEC 2008 | Build 127388

Last Document Update: 12 DEC 2008

Check frequently for additions and updates to these release notes.

 

The VIX API allows development of scripts and programs to automate operations in guest virtual machines. 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.

Contents:

Installing VIX 1.6.2

To obtain the VIX 1.6.2 libraries, click the Download link on the VIX API landing page.

When installing on Windows, you are likely to get a dialog box with error message saying “a later version of this library is already installed.” In this event:

  • If you see this error message with VIX 1.6.1 or earlier installed, the workaround is to uninstall VIX, and click to install VIX 1.6.2 again.
  • If you have installed Workstation 6.5.1 and consequently have VIX 1.6.3, which is more recent, VMware recommends that you do not install VIX 1.6.2, because it is not compatible with Workstation 6.5.1. You can safely install VIX 1.6.2 on a guest virtual machine, but not on the host.

New in This Release

The following features are new in VIX release 1.6.2:

  • Support for ESX/ESXi hosts and VMware Infrastructure.
    You can use VIX 1.6.2 libraries to control virtual machines and guests on ESX/ESXi hosts.
    Caution: ESX/ESXi support is experimental in this release. Interfaces might change in subsequent releases, and backward compatibility is not guaranteed.
  • Library files located in new directories. Shared libraries and vix.lib are in the VIServer-2.0.0 directory, not ws-5 or Workstation-6.5.0 as in earlier releases. To compile a VIX client without using the recommended wrapper library, load libraries program from VMware VIX\VIServer-2.0.0\32bit on Windows or vmware-vix/lib/VIServer-2.0.0/32bit on Linux (substitute 64bit as appropriate).

See the VIX API 1.6.0 Release Notes for Server 2.0 or the VIX API 1.6.1 Release Notes for Workstation 6.5.1 (on the VIX API landing page) to read about new features in earlier 1.6 releases.

Automating ESX Guest Operations

When VMware Server 2.0 was enhanced so customers could manage it with VMware vCenter (formerly VirtualCenter), VIX 1.6 was also extended to support ESX/ESXi hosts and VMware Infrastructure.

You can use this version of Server-compatible VIX to control guest virtual machines on ESX/ESXi hosts. ESX 3.5 U3 and later are supported. VIX 1.6.2 does not work on versions earlier than ESX 3.5 U2. The ESX version does does not need to match the VIX version, although in earlier ESX versions you might encounter bugs that are fixed in later versions.

Using the VMware Downloads page, you can obtain the VMware-vix-1.6.2 package for Linux 32-bit, Linux 64-bit, or Windows. Install it on your client computer by running vmware-install.pl or by double-clicking the .exe file. By design, Workstation 6.5.x does not include the VIServer-2.0.0 libraries, which are what you need to work with ESX/ESXi and VMware vCenter.

Follow programming documentation for VMware Server 2.0, substituting ESX server. Host type must be VIX_SERVICEPROVIDER_VMWARE_VI_SERVER. Credentials are required for remote connections from your client to the ESX server. For example, this function-call connects to port 443 of an ESX server named esx4, providing user name and password as credentials. Port 443 is encoded in the URL, not in the hostPort argument. The /sdk component at the end of the URL connects to the VIX libraries.

jobHandle = VixHost_Connect(VIX_API_VERSION,
                            VIX_SERVICEPROVIDER_VMWARE_VI_SERVER,
                            "https://esx4.example.com:443/sdk", // URL
                            0, // hostPort unused
                            "root", // userName
                            "secretpw", // password,
                            0, // options
                            VIX_INVALID_HANDLE, // propertyListHandle
                            NULL, // callbackProc
                            NULL); // clientData

The vmrun utility is implemented with VIX libraries, covering the most useful range of features. It provides a convenient way to control guest virtual machines without requiring you to write a C, Perl, or COM program. Here is a command that copies a file from a (possibly networkless) guest virtual machine to its ESX host:

vmrun -T esx -h https://esx4.example.com:443/sdk -u root -p secretpw -gu user -gp userpw
  copyFileFromGuestToHost "[storage1] SUSE/SUSE.vmx" /home/user/img.db /tmp/img.db

The root login and password are required to gain access to the ESX host. The guest user login and password are required for file access on the guest operating system. Most vmrun commands require the inventory path to a virtual machine's VMX file, under [storage1] in this case. The copyFileFromGuestToHost command copies img.db from the user's home directory to /tmp on the ESX host.

Network access and firewalls. When using your client computer to communicate with a remote ESX host, VIX programs require two kinds of connections. To use full VIX API functionality, both the following connection ports must be open between your client and the ESX host:

  1. HTTPS connection for VI wire protocol SOAP requests. This is the same port specified in the URL that you passed to VixHost_Connect or as the vmrun -h argument.
  2. Guest operations such as VixVM_CopyFileFromHostToGuest require TCP port 902, the automation port.

Issues Resolved for VIX 1.6.2

  • Many stability improvements to support ESX/ESXi hosts.

Issues Discovered in VIX 1.6.2

  • On ESX 3.5 the vmrun utility cannot revert to a snapshot. Reverting to a snapshot with the revertToSnapshot command fails in the vmrun utility on ESX hosts. Reverting to a snapshot does work correctly on ESX hosts when programs use the C function VixVM_RevertToSnapshot or equivalent in the Perl or COM API.
  • Windows installer can fail to uninstall VIX when upgrading from a previous version of VMware VIX API. If VMware VIX is already installed from VMware Server 2.0 build 116503, the Windows installer can fail with a dialog box error saying “Another version of this product is already installed,” or it can fail after logging “Found existing product” but without showing a dialog box. The workaround is to uninstall VIX manually using Control Panel > Add or Remove Programs.
  • Deleting a snapshot in the tree can produce a misleading error. On ESX 3.5 hosts, the VixVM_RemoveSnapshot function sometimes returns error 4 VIX_E_FILE_NOT_FOUND even after properly deleting the requested snapshot. This happens for example with tree A > B > C, revert to A, create snapshot D, remove B.