Introduction to the VIX API
 

The VIX API 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:

The VIX API runs on Microsoft Windows (Win95 or later) and Linux platforms (kernel 2.4.x or later recommended). This release supports clients written in C, Perl, and COM.

Compatibility

This release of the VIX API is compatible with VMware Server and VMware Workstation 6.x.

Product Compatibility

VIX API Version

Compatible Platform Products

Library Location

1.0

VMware Server 1.0

server-1

1.1

VMware Workstation 6.0 or Server 1.0

ws-3

1.1.1

VMware Workstation 6.0.1 or earlier

ws-3

1.1.2

VMware Workstation 6.0.2 or earlier

ws-3

1.1.3

VMware Workstation 6.0.3 or earlier

ws-3 or ws-5 on Windows

1.5

VMware Server 2.0, Workstation 6.5, or earlier

ws_server_esx-4

The library location is not important if you use the wrapper library as recommended.

Version 1.x 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.x provide the 1.x versions of the VIX API.

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

  • You cannot use the new functions available in this release to interact with a VMware Server 1.0 host.
  • If you copied Vix client libraries from a VMware Server 1.0, you should replace them with newer libraries.

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:

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. It includes components for both client and server. With VMware Server, the client can be a virtual machine. VMware Workstation acts as client and server.

Using the Windows Standalone Installer

To install the VIX API client files:

  1. Download the installer program to your Desktop.
  2. 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

  1. Download the installer package. For example: 
    wget http://www.vmware.com/downloads/ws/VMware-vix-xxx-nnnnn.i386.tar.gz
  2. Decompress and unpack the tar file. For example: 
    tar zxf VMware-vix-xxx-nnnnn.i386.tar.gz
  3. Change to the resulting directory. 
    cd vmware-vix-distrib/
  4. Run the installation script. 
    ./vmware-install.pl
  5. 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 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 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 the following locations.

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 cannot use some of the functions provided by a newer server.

Compiling Vix Clients

Vix includes a wrapper library, which enables your Vix program to work with multiple supported VMware products and versions. If you link your program with this library, it dynamically loads 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 product compatible with the VIX API, 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

  1. Add the header file to an include statement in your source code:
    2. #include "vix.h"
    ... client code here ...
  2. Compile for, and link with, the multithreaded version of the C runtime library. For Workstation 6.0.1 and later, you may use either the debug or the non-debug version of this library. For Workstation 6.0.0 and earlier, you must use the non-debug version.
    • To compile and link with the debug version (libcmtd.lib) use compiler options /MTd /nodefaultlib:libcmtd.lib with Microsoft Visual Studio.
    • To compile and link with the non-debug version (libcmt.lib) use compiler options /MT /nodefaultlib:libcmt.lib with Microsoft Visual Studio.
  3. Compile your client code to link in these files statically:
    • VixAllProducts.lib for non-debug, or VixAllProductsd.lib for debug.
    • kernel32.lib
    • user32.lib
    • advapi32.lib
    • ole32.lib
    • oleaut32.lib
    • ws2_32.lib
    • shell32.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 connect to. Workstation 6.x has the additional capability to link a debug version of the C runtime library.

To compile your client code for use with Workstation 6.x:

  1. Make the following DLL files available to your program, either by placing them in the same directory as your executable, or by placing them in your system directory (C:\WINNT). By default, you can find these files in the directory C:\Program Files\VMware\VMware VIX\ws_server_esx-4\32bit (for Workstation 6.0.x use ws-3 or ws-5)
    • vix.dll (or vixd.dll if you are using debug C runtime library)
    • iconv.dll (or inconvd.dll if you are using debug C runtime library)
    • libxml2.dll (or libxml2d.dll if you are using debug C runtime library)
    • ssleay32.dll
    • libeay32.dll
    • libeay32.dll
    • vmcryptolib.dll
    • zlib1.dll
  2. Add the header file to an include statement in your source code: 
    #include "vix.h"
    ... client code here ...
  3. Compile your client code to link in vix.lib statically.
  4. Compile for, and link with, the multithreaded version of the C runtime library. You may use either the debug or the non-debug version of this library.
    • To compile and link with the debug version (libcmtd.lib) use compiler options /MTd /nodefaultlib:libcmtd.lib with Microsoft Visual Studio.
    • To compile and link with the non-debug version (libcmt.lib) use compiler options /MT /nodefaultlib:libcmt.lib with Microsoft Visual Studio.

To compile your client code for use with Workstation 6.0:

  1. Make the following DLL files available to your program, either by placing them in the same directory as your executable, or by placing them in your system directory (C:\WINNT). By default, you can find these files in the directory C:\Program Files\VMware\VMware VIX\ws-2\32bit
    • vix.dll
    • ssleay32.dll
    • libeay32.dll
    • iconv.dll
    • libeay32.dll
    • libxml2.dll
    • vmcryptolib.dll
    • zlib1.dll
  2. Add the header file to an include statement in your source code: 
    #include "vix.h"
    ... client code here ...
  3. Compile for, and link with, the multithreaded version of the C runtime library. You must use the non-debug version of this library (libcmt.lib) by using compiler option /MT with Microsoft Visual Studio.
  4. Compile your client code to link in vix.lib statically.

To compile your client code for use with VMware Server 1.0:

  1. Make the following DLL files available to your program, either by placing them in the same directory as your executable, or by placing them in your system directory (C:\WINNT). By default, you can find these files in the directory C:\Program Files\VMware\VMware VIX\server-1\32bit
    • vix.dll
    • ssleay32.dll
    • libeay32.dll
  2. Add the header file to an include statement in your source code: 
    #include "vix.h"
    ... client code here ...
  3. 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.

  1. Add the header file to an #include statement in your source code: 
    #include "vix.h"
    ... client code here ...
  2. Compile your application to link to the wrapper library: 
    $ gcc vixapp.c -lvixAllProducts -ldl

Compiling a Client on a Linux Machine Without the Wrapper Library

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

  1. Add the header file to an include statement in your source code: 
    #include "vix.h"
    ... client code here ...
  2. 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