Copyright (c) 2006-2007 VMware, Inc. All rights reserved. Protected by one or more of U.S. Patent Nos. 6,397,242, 6,496,847, 6,704,925, 6,711,672, 6,725,289, 6,735,601, 6,785,886, 6,789,156, 6,795,966, 6,880,022, 6,944,699, 6,961,806, 6,961,941, 7,069,413, 7,082,598, 7,089,377, 7,111,086, 7,111,145, 7,117,481, 7,149, 843 and 7,155,558; patents pending.

VMware, the VMware "boxes" logo and design, Virtual SMP and VMotion are registered trademarks or trademarks of VMware, Inc. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies.

Introduction to the VIX API Programming Guide

The VIX API Programming Guide describes an API that allows users to automate virtual machine operations on VMware Server or VMware Workstation.

About the VIX API

The VIX API (also known as "Vix") is an API that lets users write scripts and programs to manipulate virtual machines. It is high-level, easy to use, and practical for both script developers and application programmers. The VIX API is designed for three kinds of users:

  • Technically Adventurous Users - Often such a user is a corporation with dedicated IT personnel that build their own in-house tools.
  • Partners - These are typically software tools vendors that use this VIX API to better integrate VMware products with their own products or to build management products specifically for virtual machines.
  • VMware Products - VMware uses the VIX API in its own products as a general abstraction layer between core virtual machine processes and associated service processes.

The VIX API runs on the Microsoft Windows and Linux platforms. This release supports clients written in C.

Compatibility

This release of the VIX API is compatible with VMware Server 1.0 and VMware Workstation 6.0.

 

Product Compatibility

VIX API version

Compatible Platform Products

1.0

VMware Server 1.0

1.1

VMware Workstation 6.0

VMware Server 1.0

Version 1.1 of the VIX API supports Vix clients written to version 1.0 of the VIX API, excepting features present in VMware Server that are not present in VMware Workstation (such as registration of virtual machines). Vix libraries installed with VMware Workstation 6.0 provide the 1.1 version of the VIX API.

Vix libraries installed with VMware Server 1.0 provide the 1.0 version of the VIX API. Version 1.0 of the API does not support a number of new functions available with version 1.1 of the VIX API. Consequently, the following limitations exist when using version 1.0 of the VIX API:

  • You will not be able to use the new functions available in this release to interact with a VMware Server 1.0 host.
  • If you have copied Vix client libraries from a VMware Server 1.0 installation to your client machine, clients running on this machine will be unable to use the new functions, even when communicating with a VMware Workstation 6.0 host. In this case, you should consider replacing the client libraries with the new version available with VMware Workstation 6.0.

For instructions on installing Vix libraries on standalone clients, refer to Installing the VIX API.

64-Bit Client Support

The VIX API provides 64-bit libraries for Linux clients only. Windows clients can compile only 32-bit libraries in this release.

Redistributable code and Sample code

As noted in the End User License Agreement, the VIX API allows you to build and distribute your own client applications. To facilitate this, the following files are designated as redistributable for the purpose of that agreement:

  • VixAllProducts.lib
  • vix.lib
  • vix.dll
  • vixCOM.dll
  • libVixAllProducts.a
  • libvix.so

Redistribution of the open source libraries included with the VIX API is governed by their respective open source license agreements.

The VIX API also includes some sample code, which you may use as a starting point for your own programs. This is included in the "Samples" directory installed with the VIX API.

Installing the VIX API

Vix is easy to install. Vix includes components on both the client machine and the server machine:

  • On the VMware Server or VMware Workstation host machine, you do not need to install any additional VIX API components. When you installed VMware Server or VMware Workstation, the server components for the API were installed automatically.
  • VIX API client libraries are also present by default on a host machine where VMware Server or VMware Workstation is installed. To compile clients on these machines, refer to Compiling Vix Clients.
  • To use the VIX API on a client machine without VMware Server or VMware Workstation installed, you need the header files vix.h and vm_basic_types.h , as well as one or more library files. You can get these files in one of two ways:
  • You can use the VIX API standalone installer to install the files needed to compile a client. Refer to Using the Windows Standalone Installer or Using the Linux Standalone Installer.
  • These files are present on the VMware Server or VMware Workstation host machine. You can copy these files to a client machine and use them as described in the section Compiling Vix Clients.

Using the Windows Standalone Installer

To install the VIX API client files, do the following steps.

Download the installer program to your Desktop.
Double-click on the installer icon to run the graphical installer.

To uninstall the VIX API, go to Start > Settings > Control Panel and use the Add/Remove Programs control panel.

Using the Linux Standalone Installer

To install the VIX API client files, do the following steps as the root user.

Download the installer package. For example:

wget http://www.vmware.com/products/beta/ws/VMware-vix-xxx-nnnnn.i386.tar.gz

Decompress and unpack the tar file. For example:

tar zxf VMware-vix-xxx-nnnnn.i386.tar.gz

Change to the resulting directory.

cd vmware-vix-distrib/

Run the installation script.

./vmware-install.pl

Read the EULA and be sure you agree to the terms. By default, the EULA is installed at /usr/share/doc/vmware-vix/EULA .

less /usr/share/doc/vmware-vix/EULA

To uninstall the VIX API, run the vmware-uninstall-vix.pl script. By default, the uninstaller is at /usr/bin/vmware-uninstall-vix.pl .


Upgrading an Earlier Installation

If you are using older client libraries, VMware recommends that you upgrade your client libraries using the standalone installer. The standalone installer provides a current version of the wrapper library, which allows clients to communicate with any VIX API server, regardless of version.

If you choose not to use the wrapper library, you will need to link your clients to a VIX library file that matches the version of the server. If your client communicates with more than one server version, you will need to change the dynamic library linkage whenever you run the client with a different server version.

The standalone installer does not remove the old client library file. By default, the old library file was installed at /usr/lib/libvmware-vix.so.0 . The wrapper library dynamically links to the old library file when you call VixHost_Connect() specifying VIX_SERVICEPROVIDER_VMWARE_SERVER. If you specify VIX_SERVICEPROVIDER_VMWARE_WORKSTATION , the wrapper library dynamically links to the new library file. The new library file is selected by the installer to match the architecture of the client machine. You can find it from a symlink, which is installed by default at /usr/lib/vmware-vix/lib/libvix.so .

You should replace the older header files (vix.h and vm_basic_types.h from version 1.0) with the newer header files, and compile those into your client. You can get copies of the newer header files from a host with Workstation 6 installed. By default, the header files are installed at these locations:

  • On a Windows machine:
    • C:\Program Files\VMware\VMware VIX\vix.h
    • C:\Program Files\VMware\VMware VIX\vm_basic_types.h
  • On a Linux machine:
    • /usr/include/vmware-vix/vix.h
    • /usr/include/vmware-vix/vm_basic_types.h

Whether or not you use the wrapper library, your clients can call only the functions supported by the server. If you communicate with an older server, you will not be able to use some of the functions provided by a newer server.

Compiling Vix Clients

Vix includes a wrapper library, which will enable your Vix program to work with multiple supported VMware products and versions. If you link your program with this library, it will dynamically load the appropriate Vix library to connect to the VMware product at run-time, when you call VixHost_Connect.

You can compile a Vix client with or without the wrapper library. VMware recommends that you use the wrapper library, which allows clients to communicate with any VIX API compatible product, regardless of version.

Compiling a Client on a Microsoft Windows Machine Using the Wrapper Library

To compile your client code on a Microsoft Windows machine using the wrapper library, use the following steps. By default, you can find the files in the directory:

C:\Program Files\VMware\VMware VIX

Add the header file to an include statement in your source code:

#include "vix.h"

... client code here ...

Compile your client code to link in these files statically:
  • VixAllProducts.lib
  • kernel32.lib
  • user32.lib
  • advapi32.lib
  • ws2_32.lib

Compiling a Client on a Microsoft Windows Machine Without the Wrapper Library

If you do not use the wrapper, you need to link to the appropriate Vix libraries for the VMware product that you want your Vix client program to talk to.

To compile your client code on a Microsoft Windows machine without the wrapper library, use the following steps.

To make your Vix client program work with Workstation 6.0, use the libraries in the ws-2 directory. By default, you can find the files in the directory:

C:\Program Files\VMware\VMware VIX\ws-2\32bit

Make the following DLL files available to your program, by placing them in the same directory as your executable, or by placing them in your system directory ( C:\WINNT ).
  • vix.dll
  • ssleay32.dll
  • libeay32.dll
  • iconv.dll
  • libeay32.dll
  • libxml2.dll
  • vmcryptolib.dll
  • zlib1.dll
Add the header file to an include statement in your source code:

#include "vix.h"

... client code here ...

Compile your client code to link in vix.lib statically.

To make your Vix client program work with Server 1.0, use the libraries in the server-1 directory. By default, you can find the files in the directory:

C:\Program Files\VMware\VMware VIX\server-1\32bit

Make the following DLL files available to your program, by placing them in the same directory as your executable, or by placing them in your system directory ( C:\WINNT ).
  • vix.dll
  • ssleay32.dll
  • libeay32.dll
Add the header file to an include statement in your source code:

#include "vix.h"

... client code here ...

Compile your client code to link in vix.lib statically.

Compiling a Client on a Linux Machine Using the Wrapper Library

This procedure assumes that you have installed the VIX client files in the default directories. If you made different choices during the installation, specify those directories instead.

Add the header file to an #include statement in your source code:

#include "vix.h"

... client code here ...

Compile your application with static linkage to the wrapper file:

$ gcc vixapp.c libVixAllProducts.a -ldl

Compiling a Client on a Linux Machine Without the Wrapper Library

To compile your client code with VMware Server or VMware Workstation installed:

Add the header file to an include statement in your source code:

#include "vix.h"

... client code here ...

Compile your client code to link in libvmwarevix.so statically, as in the following examples:
  • To link the VMware Workstation client library on a 32-bit client machine:

gcc -I/usr/include/vmware-vix -o myprogram main.c \

/usr/lib/vmware-vix/lib/ws-2/32bit/libvix.so

  • To link the VMware Server client library :

gcc -I/usr/include/vmware-vix -o myprogram main.c \

/usr/lib/vmware-vix/lib/server-1/32bit/libvix.so