Getting Started

######

# Getting Started

######

The VIX API allows you to automate virtual machine operations on most current VMware platform products.

## About the VIX API

The VIX API (or “Vix”) is a library for writing 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 – For example, dedicated IT personnel in an organization building their own in-house tools.
- Partners – Software vendors using Vix to integrate VMware products with their own products or to build management products specifically for virtual machines.
- VMware Engineering – VMware uses Vix in its own products as a general abstraction layer between core virtual machine processes and associated service processes.

### Client and Guest Support

You can develop VIX API programs on Linux clients or on Microsoft clients (Windows XP and later).

The VIX API supports client programs and scripts written in C, Perl, and COM (Visual Basic, VBscript, C#). For C, a recent version of Visual Studio or Linux libraries, especially `libc`, is required.

VIX API scripts and programs can perform guest operations on the following guest operating systems:

- Linux distributions (kernel 2.4.x or later recommended)
- Microsoft Windows (some functions not supported before Windows XP)
- Solaris 10 (on Intel or AMD) and OpenSolaris 2009.6

This VIX API release provides 64-bit libraries for both Windows and Linux, and 64-bit Vix Perl. In the 1.10 release and before, 64-bit Windows systems had to use 32-bit libraries in emulation mode (WoW64), and Vix Perl provided 32-bit support only.

If you want to create a VIX API support request, you first must collect diagnostic information. For instructions, see the knowledge base article Collecting VIX Diagnostic Information.

### Platform Compatibility

This release of the VIX API is compatible with VMware Workstation, VMware Player, VMware Server, ESX/ESXi hosts, and vCenter Server.

Platform Product Compatibility

VIX API Version | VMware Platform Products | Library Location
--- | --- | ---
1.17.0 | Workstation 15, Fusion 11, Player 15, or earlier | Workstation-15.0.0

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

Vix version 1.x supports programs written to version 1.x of the VIX API. Exceptions are noted on function reference pages. For example, VMware Server does not support record and replay, while VMware Workstation does not support virtual machine registration.

Vix libraries are installed with VMware Server and VMware Workstation and provide API compatibility corresponding to the product release. Vix libraries are downward compatible in most cases. If you upgrade VMware Server or VMware Workstation, you should also upgrade any separately installed Vix libraries. For instructions, see Installing the VIX API. You should also upgrade VMware Tools to match the product release.

With vCenter Server, ESX/ESXi hosts, and VMware Server, you run Vix programs remotely. With VMware Workstation, Vix programs usually run on the host.

### Security Warning

For security reasons, it is not safe to use the VIX API in a `setuid` root program.

### Redistributable Code and Sample Code

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

- `VixAllProducts.lib`, `VixAllProductsd.lib`, `Vix64AllProducts.lib` and `Vix64AllProductsd.lib`
- `VixAllProductsDyn.lib`, `VixAllProductsDyn.dll`, `Vix64AllProductsDyn.lib` and `Vix64AllProductsDyn.dll`
- `vix.lib` and `vix.dll`
- `libvixAllProducts.so`
- `libvix.so`
- `vixwrapper-config.txt`
- `manifest.txt`

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 sample code, which you can use as a starting point for your own programs. Code is delivered in the `Samples` directory installed with VMware VIX. A `Makefile` is provided for Linux, and an `nMakefile` for Windows.

## Installing the VIX API

On VMware Server and Workstation, you do not need to install any additional VIX API components. Vix libraries are installed by default under “VMware VIX” or `vmware-vix`. To compile programs on these systems, see Compiling Vix Programs.

To control ESX/ESXi hosts or VMware Server remotely from another machine, you need 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:

- Use the Vix standalone installer to get the files needed to compile a program. See Using the Windows Standalone Installer or Using the Linux Standalone Installer.
- Copy these files from a VMware Server host, then use them as described in the section Compiling Vix Programs.

### Using the Windows Standalone Installer

To install the VIX API files on Windows:

1. Download the installer program to your Desktop.

2. Double-click 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 files on Linux:

1. Download the bundle install package. For example:

       wget http://www.vmware.com/downloads/server/VMware-VIX-1.17.0-nnnnnn.i386.bundle

2. As superuser, run a shell to install the package:

       sudo sh VMware-VIX-1.17.0-nnnnnn.i386.bundle

3. Read the EULA and click Next if you agree to its terms. Click Install to accept the default bundle installation.

To uninstall the VIX API on Linux, run the following program:

    sudo vmware-installer -u vmware-vix

### Upgrading an Earlier Installation

If you are using older Vix libraries, VMware recommends that you upgrade those libraries using the standalone installer. The standalone installer provides a current version of the wrapper library, which allows programs to communicate with any Vix library, regardless of version or target architecture. The wrapper library dynamically loads appropriate library files at connection time.

Otherwise you must link your program to a Vix library that matches the server version. This gets inconvenient if your program communicates with more than one version of the server.

VMware Tools in virtual machines should be kept up-to-date with the VMware version on the host. When upgrading, also update VMware Tools in all guest operating systems. The VIX API relies on a current matching version of VMware Tools to perform many operations.

Upgrading the Vix libraries replaces the older header files, `vix.h` and `vm_basic_types.h` with newer header files. The header files are installed at the following locations by default:

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

Whether or not you use the wrapper library, your programs may call only the functions supported by the host. If you communicate with an older host, you cannot use newer features.

## Sample Vix Programs

On Windows, the sample programs are installed in `C:\Program Files\VMware\VMware VIX\Samples` by default. An `nMakefile` is provided to compile all sample programs using `nmake` and the Visual Studio C compiler.

On Linux, the sample programs are installed in `/usr/share/doc/vmware-vix/VMwareVix/samples/` by default. A `Makefile` is provided to compile all sample programs using `make` and the GNU C compiler.

## Compiling Vix Programs

Vix includes a wrapper library, which enables Vix programs to work with multiple supported VMware products and versions. If you link your program with this library, it dynamically loads the appropriate Vix library for a VMware product at runtime, during the `VixHost_Connect()` call. VMware recommends that you use the wrapper library, although you can compile Vix programs without it.

For Windows, both a static version and a dynamic version of the wrapper library are provided. The static version of the wrapper library is built with Visual Studio 2008 SP1, and requires use of the same Visual Studio release to build and link your application. For Visual Studio 2008 and later releases, the dynamic version of the wrapper library can be used to build your application.

### Compiling on Windows With the Static Wrapper Library

To compile code on Windows with Visual Studio 2008 SP1 using the static wrapper library, follow this procedure. Files are in the `C:\Program Files\VMware\VMware VIX` folder.

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

    #include "vix.h"

    ... program 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`.
- To compile and link with the non-debug version (`libcmt.lib`) use compiler options `/MT` `/nodefaultlib:libcmt.lib`.

3. Compile code to link with these files:

- `VixAllProducts.lib` for non-debug, or `VixAllProductsd.lib` for debug. (For 64-bit Windows, use `Vix64AllProducts.lib` for non-debug, or `Vix64AllProductsd.lib` for debug.)
- `kernel32.lib`
- `user32.lib`
- `advapi32.lib`
- `ole32.lib`
- `oleaut32.lib`
- `ws2_32.lib`
- `shell32.lib`

### Compiling on Windows With the Dynamic Wrapper Library

To compile code on Windows with Visual Studio 2008 or later using the dynamic wrapper library, follow this procedure. Files are in the `C:\Program Files\VMware\VMware VIX` folder.

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

    #include "vix.h"

    ... program code here ...

2. Compile for, and link with, the multithreaded version of the C runtime library.
3. Unlike the static version step, link `VixAllProductsDyn.lib` with your application code, and link the C runtime the usual default way provided by your Visual Studio release. For example, to compile and link with the static multithreaded C runtime `libcmt.lib`, use compiler option `/MT` but do not specify `/nodefaultlib:libcmt.lib`.
4. Compile code to link with these files:

- `VixAllProductsDyn.lib` (For 64-bit Windows, use `Vix64AllProductsDyn.lib`)
- `kernel32.lib`
- `user32.lib`
- `advapi32.lib`
- `ole32.lib`
- `oleaut32.lib`
- `ws2_32.lib`
- `shell32.lib`

### Compiling on Linux With the Wrapper Library

This procedure assumes that you have installed Vix components in the default directories. If you made different choices during the installation, specify your directory choices instead.

1. Add an include statement in your source code for the header file:

       #include "vix.h"

       ... program code here ...

2. Compile your application, linking to the wrapper library, dynamic load library, and threads library:

       $ gcc -I/usr/include/vmware-vix vixapp.c -o vixapp -lvixAllProducts -ldl -lpthread

### Compiling on Windows Without the Wrapper Library

If you do not use the wrapper, you need to link the appropriate Vix libraries for the VMware product to which your Vix program connects. Workstation is able to link a debug version of the C runtime library.

To compile your code for use with Workstation 7.1:

1. Make the required DLL files available to your program, either by placing them in the same directory as your executable, or by placing them in the system directory (`C:\WINDOWS\system32`). The easiest option is to copy DLL files from the directory `C:\Program Files\VMware\VMware VIX\Workstation-7.1.0\32bit` or `64bit`.
   - `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)
   - `libeay32.dll`
   - `ssleay32.dll`
   - `vmcryptolib.dll`
   - `zlib1.dll`
2. Add the header file to an include statement in your source code:

       #include "vix.h"

       ... program code here ...

3. Compile your 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 option `/MTd` with Microsoft Visual Studio.
- To compile and link with the non-debug version (`libcmt.lib`) use compiler option `/MT` with Microsoft Visual Studio.

To compile your code for use with Workstation 6.0.x:

1. Make the required DLL files available to your program, either by placing them in the same directory as your executable, or by placing them in the system directory (`C:\WINDOWS\system32`). The easiest option is to copy DLL files from the directory `C:\Program Files\VMware\VMware VIX\ws-2\32bit` or `ws-3\32bit`.
   - `vix.dll`
   - `iconv.dll`
   - `libxml2.dll`
   - `libeay32.dll`
   - `ssleay32.dll`
   - `vmcryptolib.dll`
   - `zlib1.dll`
2. Add the header file to an include statement in your source code:

       #include "vix.h"

       ... program code here ...

3. Compile your code to link in `vix.lib` statically.
4. 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.

To compile your 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:\WINDOWS\system32`). The easiest option is to copy DLL files from 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"

       ... program code here ...

3. Compile your code to link in `vix.lib` statically.

### Compiling on Linux Without the Wrapper Library

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

1. Add an include statement in your source code for the header file:

       #include "vix.h"

       ... program code here ...

2. Compile your application, linking statically to `libvix.so`, as in the following examples.
   - To link the VMware Workstation library on a 32-bit machine:

         gcc -I/usr/include/vmware-vix -o vixapp vixapp.c /usr/lib/vmware-vix/Workstation-7.1.0/32bit/libvix.so

   - To link the VMware Server 2.0 library on a 32-bit machine:

         gcc -I/usr/include/vmware-vix -o vixapp vixapp.c /usr/lib/vmware-vix/lib/VIServer-2.0.0/32bit/libvix.so

   - To link the old VMware Server 1.x library:

         gcc -I/usr/include/vmware-vix -o vixapp vixapp.c /usr/lib/vmware-vix/lib/server-1/32bit/libvix.so

## Installing Vix Perl

To install the Perl component of Vix, find the `vix-perl.tar.gz` file on Linux or the `vix-perl.zip` file on Windows, and unpack it. The `README` file describes how to install the `vix-perl` module.