Getting Started

The VIX API allows you to automate virtual machine operations on VMware Server or VMware Workstation.

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.

The VIX API runs on Microsoft Windows (Windows95 or later) and Linux platforms (kernel 2.4.x or later recommended). It supports programs written in C, Perl, and COM (Visual Basic, VBscript, C#).

Compatibility

This release of the VIX API is compatible with VMware Server 2.0 and VMware Workstation 6.5.

Compatible Platform Products

VMware Workstation 6.0

VMware Workstation 6.0.1 or earlier

VMware Workstation 6.0.2 or earlier

VMware Workstation 6.0.3 or earlier

VMware Workstation 6.0.4 or earlier

VMware Server 2.0 or earlier

Workstation 6.5 or earlier

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 VMware Server, you can run Vix programs remotely. With VMware Workstation, Vix programs usually run on the host.

64-Bit Library Support

The VIX API provides 64-bit libraries for Linux only. Windows 32-bit libraries may work in 64-bit emulation mode.

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 and VixAllProductsd.lib
• vix.lib and vix.dll
• vixCOM.dll
• libvixAllProducts.so
• 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 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 the VMware Server or VMware Workstation host, 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 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 the 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:

Download the installer program to your Desktop.

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 tar-gzip package. For example:
2. As superuser, extract the package:
3. Change directory and, as superuser, run the VMware installer:
4. Read the EULA and type «yes» if you agree to its terms. You can accept most defaults by typing Enter when prompted.

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

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.

Compiling on Windows with Wrapper Library

1. Add the header file to an include statement in your source code:
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.
   • kernel32.lib
   • user32.lib
   • advapi32.lib
   • ole32.lib
   • oleaut32.lib
   • ws2_32.lib
   • shell32.lib

Compiling on Linux with 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:
2. Compile your application, linking to the wrapper library and dynamic load library:

Compiling on Windows Without 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 program to connect to. Workstation 6.x has the additional capability to link a debug version of the C runtime library.

To compile your 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\Workstation-6.5.0\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:
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 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 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:
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 code to link in vix.lib statically.

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

Compiling on Linux Without 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:
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:
   • To link the VMware Server 2.0 library on a 32-bit machine:
   • To link the old VMware Server 1.x library:

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.

To remove the Perl component, type make uninstall.

Источник

mbbx6spp / VMWARE_VIX_API.md

VMWARE VIX API and SDK

Currently the installations I use of VMWare vCenter Server are version 5.1.x which is requires we use the following SDK version:

If or when we upgrade to v5.5.x we will be looking at the following:

Setting Up Development Environment

Since we are systems people we shouldn’t be adverse to getting down and dirty with C when needed, but the goal of my work will be to build a light Ruby wrapper around the C code to allow people in TechOps that are less comfortable with with common systems engineering practices (i.e. writing sane C code) to write glue for their automation much easier AND be able to write automated unit, functional, and integration tests which they really ought to. This is the main reason to use Ruby which it’s mature set of testing libraries readily available over shell scripts or the Perl bindings available (the benefit isn’t subjective «beauty» of code like some may taut as it’s value add, that is a bogus argument).

However, this is a walk through of how I am setting up my development environment for building the Ruby/C extension and providing links to appropriate API references from VMWare so people can follow along very easily.

1. You actually need to create an account on VMWare to download the VIX SDK for Linux x86_64. OMGUGHBBQ: https://my.vmware.com/group/vmware/details?downloadGroup=VIXAPI112&productId=353
2. Then you have to trust it is legit by sudo sh-ing it: sudo sh VMware-VIX-1.12.0-812388.x86_64.bundle
3. Now follow the instructions.

Note: Don’t worry I will download the bundle and put it somewhere within Jive and update this doc when it’s available

For sample programs in C check out: /usr/share/doc/vmware-vix/VMwareVix/samples/

To uninstall it you can run:

Now it’s as simple as adding the include and lib paths to your compiler and linker settings and adding #include «vix.h» when using the APIs.

Next, a whirl wind tour of the API.

There are five core «things» the API exposes, the rest are auxiliary types:

• Virtual Machine (this can be in on or off state)
• Job
• Event
• Snapshot
• Host

These should be self explanatory.

Handles are reference counted. This is pretty common practice in C APIs. This should not be weird, just clean up after yourself with:

You always need to open and release handles when you need to reference an entity from VMWare via the API, e.g. Virtual Machine, Job, Snapshot, Host, etc.

Error Codes in VIX

Don’t bother doing your won bit masking, it’s error prone and much more likely to be subject to change in different versions of the API. Instead use the VIX defines:

• VIX_ERROR_CODE(err)
• VIX_SUCCEEDED(err)
• VIX_FAILED(err)

So many APIs return error values which can then be passed into the above defines so you can add your required logic, e.g.:

While VMware claims Vix objects are thread safe, always double check your assumptions. Never trust a vendor. I know this all to well, especially in C/C++ and Java APIs. 🙂

Источник