VMware

 

VIX API 1.7 Release Notes


For VMware vSphere support | 26 August 2009 | Build 186713

Last document update: 25 August 2009

Check frequently for additions and updates to these release notes.

 

The VIX API allows development of scripts and programs that automate virtual machine operations. This API is high-level, easy to use, and practical for script writers and application programmers. The download 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.
  • Automation Utility – Included with this package is the vmrun command-line utility, based on the VIX API.


Contents:

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

New in This Release

  • More vmrun commands and features.
    Now you can enable or disable shared folders, and remove virtual machines, with the vmrun utility. For details see the manual Using vmrun to Control Virtual Machines.
  • New API call.
    The following new COM binding was added:
    • Close – Inform the host that VIX is done with the virtual machine.
  • Library files located in new directories. Shared libraries and vix.lib are in a new directory now. VMware recommends compiling VIX clients using the wrapper library to avoid the issue of changing library location.

Resolved Issues

  • Many stability improvements to support ESX/ESXi hosts and vCenter Server.
  • Shared folders remain enabled after power cycle.
    Shared folders used to be disabled after powering a virtual machine off and on, but shared folders now persist across power cycles.
  • Host handle cleaned up after disconnect.
    In previous versions of the VIX API, 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.
    The VixVM_ListDirectoryInGuest function now succeeds when listing directories on a network-mapped drive on a Windows guest.

Known Issues

  • Connect to VMware Server 1.0 can fail on Linux clients. On some Linux 32-bit distributions, calling VixHost_Connect to a remote VMware Server 1.0.x host might fail because VIX cannot find the libcrypto-0.9.7.so library. The workaround is to install the same version of VMware Server on the system where you run the VIX client program.
  • Case-insensitive search on vCenter Server 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 cannot distinguish them for opening or registration. A workaround is to substitute the Oracle database server.
  • Snapshots do not always preserve power state. When a snapshot is created in a powered-on virtual machine with option 0 (exclude memory), the power state is not saved as part of the snapshot. Reverting to the snapshot leaves the virtual machine in powered-off state.
  • Power-on of unsupported guest OS returns unknown error. If you create a virtual machine with guest OS type unknown, or if the guest OS otherwise does not match its configuration, vCenter Server refuses to power it on due to UnsupportedGuest error, but VIX returns VIX_E_FAIL (Unknown error) instead.
  • Failures when connecting or disconnecting host handles from multiple threads simultaneously. When calling VixHost_Connect or VixHost_Disconnect from multiple threads in a single client, a crash or hang might occur. This was encountered in stress testing with 10 - 20 simultaneous threads.
  • Misreported power state of virtual machine suspended without VIX. If a virtual machine is opened by a client process using the VIX API, and the virtual machine is suspended by another process, VIX in the client process shows the virtual machine as powered-off instead of suspended.
  • Cannot simultaneously connect to different host types. VIX programs running on any type of host should not call VixHost_Connect multiple times in the same process with different hostType values. In other words, a VIX client process cannot simultaneously connect to both a Workstation host and to vSphere (ESX/ESXi or vCenter Server). This is because different DLLs or shared-objects are loaded for connecting to each host type, and it is a problem to load different libraries from the same process.
  • VIX Perl scripts might fail with Windows 7. On Windows 7, vix-perl scripts might fail with the error “Can't load VixBinding.dll” perhaps due to an old Perl version.
  • 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.

Automating ESX Guest Operations

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

You can use this version of Server-compatible VIX to control guest virtual machines on ESX/ESXi hosts. VIX 1.7 does not work on versions earlier than ESX 3.5 U3. Your 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.

Note: VIX libraries are not intended for the VMware ESX Service Console. For VMware vCenter and VMware ESX/ESXi, the VIX API is designed to be used remotely. It does not install in the VMware ESX Service Console operating system.

Using the VMware Downloads page, you can obtain the VMware-vix-1.7.0 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 VSphere-4.0 libraries, which are what you need to work with ESX/ESXi and VMware vCenter.

Follow programming documentation for VMware Server 2.0 or ESX/ESXi. Host type must be VIX_SERVICEPROVIDER_VMWARE_VI_SERVER. Credentials are required for remote connections from your client to the ESX host. For example, this function call connects to port 443 of an ESX host named esx, while 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://esx.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 C, Perl, or COM programs. Here is a command that copies a file from a (possibly networkless) guest virtual machine to its ESX host:

vmrun -T esx -h https://esx.example.com:443/sdk -u root -p rootpw -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 vSphere 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.