VMWare vmcontrol API

From BovineNet

VMWare has several different APIs available to allow third-party developers to interact with their virtualization products and the guest VMs being run by them. This includes:

vmcontrol-based APIs (includes VmCOM and VmPerl) -- This is the oldest of the APIs and can be used for local or remote management of virtual machines. Can be used against VMWare Workstation, VMWare GSX Server, VMWare ESX Server, and VMWare Server.
ViX API -- This is a newer API that VMWare is now recommending in favor of the older vmcontrol-based APIs. In addition to the features supported by vmcontrol, it also adds several new ways to interact with the guest tools installed within Virtual Machines (such as copying files in/out of the VM, executing commands within the guest, etc), disk cloning, and more. As of version ViX 1.1, it can be used against VMWare Workstation and VMWare Server (but not VMWare ESX Server).
Virtual Infrastructure API -- This is a SOAP-based API that is best used in environments with many VMWare Server or VMWare ESX Servers, since it requires a Virtual Center Server installation.

This page will focus on the vmcontrol-based APIs, with a particular emphasis on the underlying vmcontrol library in the context of C/C++ developers.

1 Relationship and status
2 VMControl APIs: top level functions
3 VMControl APIs: Server level objects
- 3.1 VMControl_ServerEnumerate
4 VMControl APIs: VM level objects
5 VMControl interface details

[edit] Relationship and status

The VmCOM API is a Win32 Common Object Model (COM) based interface that can be used from any Windows based programming language that supports COM. This includes, Javascript, VBScript, C#, C/C++, and more.

The VmPerl API is provided for Linux and Win32 as a set of Perl modules

As of late 2006, VMWare has officially declared the VmCOM and VmPerl APIs (and therefore the vmcontrol API) as "deprecated", in favor of their newer ViX API. However, there are still some large limitations with ViX that limit its use.

VMWare publicly only describes the VmCOM and VmPerl APIs, but not the "vmcontrol" API itself. As such, the vmcontrol API is not an officially supported or documented interface by VMWare. However, if you are a C/C++ developer then using the vmcontrol API directory is currently a much better option than any of the others. Although the VmCOM API can technically be used by C/C++ developers, using and registering COM controls has more install and run-time requirements.

[edit] Supported VMWare products

The following VMWare products can be controlled by vmcontrol, VmPerl, and VmCOM:

VMWare Workstation
VMWare GSX Server
VMWare Server 1.x
VMWare ESX Server

Although VMWare's official position is that "VMWare GSX Server" has been discontinued and replaced by "VMWare Server", that is really just marketing. VMWare Server internally still identifies itself as GSX in many places, and is fundamentally just the same product but with a new name.

[edit] Windows vmcontrol

The Windows VmPerl distribution (VMware-VmPerlAPI-1.0.3-44356.exe) is a self-extracting and installing file that gives you the option of installing the VmPerl files. If you select that, in the "C:\Program Files\VMware\VMware VmPerl Scripting API" directory will be a "control-only.zip" that contains the following files:

includeCheck.h
vm_basic_types.h
vmcontrol.h
vmcontrol_constants.h
vmcontrollib.dll
vmcontrollib.lib
libeay32.dll
ssleay32.dll

Only a 32-bit version of the Windows vmcontrol dependences are included.

[edit] Linux vmcontrol

In the Linux VmPerl distribution (VMware-VmPerlAPI-1.0.3-44356.tar.gz) is another tarball called "control-only.tar"m which contains:

includeCheck.h
vm_basic_types.h
vmcontrol_constants.h
vmcontrol.h
libvmcontrol-helper
vmcontrol.o
vmcontrol64.o
libcrypto.so.0.9.7 (not inside control-only.tar, but inside the main tarball)
libssl.so.0.9.7 (not inside control-only.tar, but inside the main tarball)

Use of the Linux vmcontrol generally requires that you compile and link on an older version of Linux. I've confirmed that RedHat 7.2 (Linux 2.4.7, glibc 2.2.4, gcc 2.96) works successfully.

Both 32-bit and 64-bit (AMD64/EM64T) versions of the Linux vmcontrol dependences are included.

[edit] VMControl APIs: top level functions


/* 
 * VMControl -- top level functions
 * --------------------------------
 */

typedef struct {
   void * (*mallocFunction) (size_t size);
   void * (*callocFunction) (size_t n, size_t size);
   void (*freeFunction) (void *buf);
} VMControlInitParameters;

Bool VMControl_Init(void);
Bool VMControl_SetMemoryRoutines(VMControlInitParameters *initParams);
void VMControl_Free(void *p);
const char *VMControl_Version(void);
const char *VMControl_GetErrorMessage(int err);
int VMControl_GetDefaultTCPPort(void);

[edit] VMControl APIs: Server level objects

/*
 * VMControl Server -- functions that act on a VMControlServer object
 * -----------------------------------------------------------
 */

char VMControl_ServerInit(void);

VMControlServer *
VMControl_ServerNew(const char *hostname, int port, const char *username,
                    const char *password);
int VMControl_ServerGetLastError(VMControlServer *s, char **cptr);
Bool VMControl_ServerConnect(VMControlServer *s);
void VMControl_ServerDisconnect(VMControlServer *s);
void VMControl_ServerDestroy(VMControlServer *s);
Bool VMControl_ServerIsConnected(VMControlServer *s);
char **VMControl_ServerEnumerate(VMControlServer *s);
Bool VMControl_ServerIsRegistered(VMControlServer *s, const char *config, Bool *isRegistered);
Bool VMControl_ServerKill(VMControlServer *s, const char *vm); // Not implemented
char *VMControl_ServerExec(VMControlServer *s, const char *xmlargs);
Bool VMControl_ServerShutdown(VMControlServer *s);
Bool VMControl_ServerSingleVMQuery(VMControlServer *s, char *config, char *query, char **result);
Bool VMControl_ServerMultipleVMQuery(VMControlServer *s, char **vmList, int numVmList,
				     char *query, char ***result);
Bool VMControl_ServerVMQuery(VMControlServer *s, char **vmList, int numVmList, 
			     char **queries, int numQueries, char ***results, int *numResults);
Bool VMControl_ServerTest(VMControlServer *s, const char *query);
Bool VMControl_ServerSetAsString(VMControlServer *s, const char *query, const char *value);

char *VMControl_ServerGetResource(VMControlServer *server, char *key);
Bool VMControl_ServerSetResource(VMControlServer *server, char *key, char *newVal);

/*
 * Not sure whether these will be in the final API:
 */
char *VMControl_ServerGetAsString(VMControlServer *s, const char *property);  
Bool VMControl_ServerGetProductInfo(VMControlServer *vm, int infoType, int *result);
Bool VMControl_ServerRegister(VMControlServer *s, const char *configpath);
Bool VMControl_ServerUnregister(VMControlServer *s, const char *configpath);

VMControlServer *VMControl_ServerNewEx(void);
VMControlVM *VMControl_VMNewEx(void);

VMControlConnectParams *
VMControl_ConnectParamsNew(const char *hostname,
                           int port,         
                           const char *username,
                           const char *password);
void VMControl_ConnectParamsDestroy(VMControlConnectParams *params);

Bool VMControl_ServerConnectEx(VMControlServer *s, VMControlConnectParams *cp);
Bool VMControl_VMConnectEx(VMControlVM *s,VMControlConnectParams *cp,
                           const char *config, Bool mks);

Bool VMControl_VMAccessTimeout(VMControlVM *vm,  int timeoutId,
                               const int *timeoutIn, int *timeoutOut);

[edit] VMControl_ServerEnumerate

Return a list of all registered VMs on the server.

   char **enums = VMControl_ServerEnumerate(control->vmServer);
   if (enums != NULL) {
       for (; *enums; enums++) {
           printf("enums: %s\n", *enums);
       }
   }

The returned list is just the full pathnames of the VMX configuration files of the currently registered VMs.

[edit] VMControl APIs: VM level objects

/* 
 * VMControl VM -- functions that act on a VMControlVM object
 * -------------------------------------------------
 */

char VMControl_VMInit(void);

VMControlVM *VMControl_VMNew(VMControlServer *s, const char *config);
int VMControl_VMGetLastError(VMControlVM *vm, char **cptr);
Bool VMControl_VMConnect(VMControlVM *vm, Bool mks);
void VMControl_VMDisconnect(VMControlVM *vm);
void VMControl_VMDestroy(VMControlVM *vm);
char *VMControl_VMGetConfigFileName(VMControlVM *vm);
int VMControl_VMGetTimeout(VMControlVM *vm);
int VMControl_VMSetTimeout(VMControlVM *vm, int timeout);

Bool VMControl_VMIsConnected(VMControlVM *vm);
Bool VMControl_VMAnswerQuestion(VMControlVM *vm, int sequence, int choicenum);
Bool VMControl_VMStart(VMControlVM *vm, int mode);
Bool VMControl_VMRequestStop(VMControlVM *vm, Bool force);
Bool VMControl_VMRequestReset(VMControlVM *vm, Bool force);
Bool VMControl_VMStop(VMControlVM *vm, Bool force);
Bool VMControl_VMReset(VMControlVM *vm, Bool force);
Bool VMControl_VMSuspendToDisk(VMControlVM *vm, int mode);
char ** VMControl_VMInfo(VMControlVM *vm);
Bool VMControl_VMSaveAs(VMControlVM *vm, const char *config);  // Not implemented
Bool VMControl_VMExit(VMControlVM *vm);  // Not implemented
Bool VMControl_VMCommit(VMControlVM *vm, const char *disk, int level,
			Bool freeze, Bool wait);
Bool VMControl_VMAddRedo(VMControlVM *vm, const char *disk);

Bool VMControl_VMSetConfigChanges(VMControlVM * vm,
                                  const char * const * assignments);
Bool VMControl_VMSaveConfig(VMControlVM *vm);

Bool VMControl_VMDeviceConnect(VMControlVM *vm, const char *device);
Bool VMControl_VMDeviceDisconnect(VMControlVM *vm, const char *device);
Bool VMControl_VMToolsInstallBegin(VMControlVM *vm);
Bool VMControl_VMToolsInstallEnd(VMControlVM *vm);
Bool VMControl_VMToolsLastActive(VMControlVM *vm, int *seconds);


/*
 * Not sure whether these will be in the final API:
 */
char * VMControl_VMGetAsString(VMControlVM *vm, const char *var);
char * VMControl_VMGetAsStringServerd(VMControlVM *vm, const char *var);
Bool VMControl_VMSetAsString(VMControlVM *vm, const char *var, const char *value);  
char ** VMControl_VMWho(VMControlVM *vm);
Bool VMControl_VMReloadConfig(VMControlVM *vm);
void VMControl_VMSetError(VMControlVM *vm, int err, const char *str);

/*
 * MKS
 */

Bool VMControl_MKSInsertKeyEvent(VMControlVM *vm, int scancode, Bool down);
Bool VMControl_MKSSaveSreenshot(VMControlVM *vm, const char *filename,
                                const char *fileType);
Bool VMControl_MKSTargetScreenshot(VMControlVM *vm,
                                   const char *filename,
                                   const char *maskFilename,
                                   const char *fileType,
                                   const char *maskFileType,
                                   int tolerance);
int VMControl_MKSMatchScreenshot(VMControlVM *vm, int timeout);
Bool VMControl_MKSSaveScreenshot(VMControlVM *vm, const char *filename,
				 const char *fileType);

/*
 * Callbacks
 */

typedef void (*VMControlVMCallback) (VMControlVM *vm, void* args);

typedef enum VMControlVMCallbackType {
   VMC_CALLBACK_POWER,
   VMC_CALLBACK_DIALOG,
   VMC_CALLBACK_ANSWER,
   VMC_CALLBACK_DEVICE
} VMControlVMCallbackType;

Bool VMControl_VMRegisterCallback(VMControlVMCallbackType type, VMControlVMCallback c);
Bool VMControl_VMUnregisterCallback(VMControlVMCallbackType type, VMControlVMCallback callback);

typedef struct VMControlPowerTransition {
   const char *username;
   const char *oldState;
   const char *newState;
} VMControlPowerTransition;

typedef struct VMControlQuestion {
   int sequence;
   const char * type; // info, warning, error, question
   const char * text;
   const char ** choices;
} VMControlQuestion;

typedef struct VMControlAnswer {
   VMControlQuestion *q;
   const char *username;
   int choice;
} VMControlAnswer;

typedef struct VMControlConfigDevice {
   char *name;
   char *connection;
   Bool connected;
} VMControlConfigDevice;

/* 
 * VMControl Profiler -- functions that act on a Profiler object
 * -------------------------------------------------
 */

unsigned long VMControl_ProfilerGetTime(void);

/*
 *------------------------------------------------------------------------
 *  New interfaces for scripting bindings (VmComScript and VmPerlScript)
 *------------------------------------------------------------------------
 */

typedef struct {
   const char *hostname;
   int port;              // Port number where vmauthd is listening
   const char *username;
   char *password;
} VMControlConnectParams;

typedef struct {
   long  id;
   char *text;
   char **choices;
} VMControlExternalQuestion;

char *VMControl_VMGetConfig(VMControlVM *vm, char *key);
Bool VMControl_VMSetConfig(VMControlVM *vm, char *key, char *newVal);

char *VMControl_VMGetResource(VMControlVM *vm, char *key);
Bool VMControl_VMSetResource(VMControlVM *vm, char *key, char *newVal);

Bool VMControl_VMGetId(VMControlVM *vm, unsigned int *id);
Bool VMControl_VMGetPid(VMControlVM *vm, unsigned int *pid); 

Bool VMControl_VMGetCapabilities(VMControlVM *vm, unsigned int *capabilities);
Bool VMControl_VMGetRemoteConnections(VMControlVM *vm, unsigned int *numConnections);

VMControlExternalQuestion *VMControl_VMGetExternalQuestion(VMControlVM *vm);
void VMControl_VMDestroyExternalQuestion(VMControlExternalQuestion *q);

Bool VMControl_VMGetProductInfo(VMControlVM *vm, int infoType, int *result);
Bool VMControl_VMDeviceIsConnected(VMControlVM *vm, const char *devName, Bool *result);

Bool VMControl_VMStopOrReset(VMControlVM *vm, Bool stop, int mode);

Bool VMControl_VMCreateSnapshot(VMControlVM *vm);
Bool VMControl_VMHasSnapshot(VMControlVM *vm, Bool *hasSnapshot);
Bool VMControl_VMRevertSnapshot(VMControlVM *vm);
Bool VMControl_VMDeleteSnapshot(VMControlVM *vm);

Bool VMControl_VMGetRunAsUser(VMControlVM *vm, char **username);
Bool VMControl_VMSetRunAsUser(VMControlVM *vm, const char *username,
                              const char *password, Bool checkValid);

[edit] VMControl_VMGetUptime

Returns how long the VM has been running, measured in seconds. If the VM is not currently running, then the function returns false and [#VMControl_VMGetLastError] may be used to retrieve a description of the error.

Bool VMControl_VMGetUptime(VMControlVM *vm, unsigned int *result);

Example code:

   unsigned int uptime = 0;
   if (!VMControl_VMGetUptime(vm, &uptime)) {
       printf("uptime returned false.\n");
   }
   printf("Uptime is %d\n", uptime);

[edit] VMControl_VMGetHeartbeat

Return whether the VM is active and responding??

Bool VMControl_VMGetHeartbeat(VMControlVM *vm, unsigned int *result);

Example code:

   unsigned int heartbeat = 0;
   if (!VMControl_VMGetHeartbeat(vm, &heartbeat)) {
       printf("heartbeat returned false.\n");
   }
   printf("heartbeat is %d\n", heartbeat);

[edit] VMControl_VMGetGuestInfo

Query a "guestinfo" variable, which can be used for data exchange between the inside and outside of the VM. Accessing these variables requires that the VMWare Tools be running within the Guest OS.

   char *VMControl_VMGetGuestInfo(VMControlVM *vm, char *key);

Example code:

   // Get the IP Address of the Guest via "Config.guestinfo.ip"
   char *ip = VMControl_VMGetGuestInfo(vm, "ip");
   if (ip != NULL) {
       printf("guest ip = %s\n", ip);
   } else {
       printf("failed to get ip\n");
   }

Notice that the "ip" variable is a special value that is automatically set by the VMWare Tools once the Guest OS has finished booting and has network connectivity. There are some code examples in the Perl API documentation that describe the need for the user to explicitly set the "ip" variable from within the VM after parsing the output of ipconfig/ifconfig, however those steps actually seem unnecessary due to it being automatically set by the VMWare Tools.

Other custom variables with arbitrary names can be defined by using these command-line utilities:

	Outside VM	Inside VM
Set	`vmware-cmd config.vmx setguestinfo {PROPERTY_NAME} {PROPERTY_VALUE}`	`vmware-guestd --cmd 'info-set {PROPERTY_NAME}, {VALUE}'`
Get	`vmware-cmd config.vmx getguestinfo {PROPERTY_NAME}`	`vmware-guestd --cmd 'info-get {PROPERTY_NAME}'`

[edit] VMControl_VMSetGuestInfo

Set a "guestinfo" variable, which can be used for data exchange between the inside and outside of the VM. Accessing these variables requires that the VMWare Tools be running within the Guest OS.

 Bool VMControl_VMSetGuestInfo(VMControlVM *vm, char *key, char *newVal);

See [#VMControl_VMGetGuestInfo] for more details.

[edit] VMControl_VMGetExecutionState

Retrieve whether the VM is currently running, stopped, suspended, etc.

Bool VMControl_VMGetExecutionState(VMControlVM *vm, int *retVal);

Example code:

   int execstate = 0;
   if (!VMControl_VMGetExecutionState(vm, &execstate)) {
       printf("execution state returned false.\n");
   }
   printf("execution state is %d\n", execstate);

[edit] VMControl_VMToolsLastActive

Check whether the VMWare Tools are installed and running within the VM.

   int toolsactive = 0; 
   if (!VMControl_VMToolsLastActive(vm, &toolsactive)) {
       printf("tools active returned false.\n");
   }
   printf("tools active is %d\n", toolsactive);

The value returned in the output parameter is supposedly in seconds, but it seems to just be boolean that indicates whether the Tools are running or not.

[edit] VMControl_VMInfo

Retrieve some basic information about the VMX configuration file of the specified VM.

   char ** info = VMControl_VMInfo(vm);
   if (info != NULL) {
       for (; *info; info += 2) {
           printf("info: %s = %s\n", *(info), *(info + 1));
       }
   }

The function returns a list representing pairs of variables and values. It seems to only return a very limited set of values, and not everything that is in the VMX configuration file. On VMWare Server 1.0.3 for Windows, the above code produces only the following 4 entries:

info: Config.filename = c:\virtual machines\sles9\sles.vmx
info: Config.guestOS = sles
info: Config.memsize = 256
info: Config.log.filename = (null)

[edit] VMControl interface details

The VMControl API opens a TCP network connection to the "vmware-authd" service of specified VMWare product, usually over the default TCP port of 902. A network connection to localhost is used even if you are requesting control of the local machine.

For details on this interface see VMWare vmserverd API

Retrieved from "http://jeff.bovine.net/VMWare_vmcontrol_API"

Category: Technology

VMWare vmcontrol API

From BovineNet

Contents

[edit] Relationship and status

[edit] Supported VMWare products

[edit] Windows vmcontrol

[edit] Linux vmcontrol

[edit] VMControl APIs: top level functions

[edit] VMControl APIs: Server level objects

[edit] VMControl_ServerEnumerate

[edit] VMControl APIs: VM level objects

[edit] VMControl_VMGetUptime

[edit] VMControl_VMGetHeartbeat

[edit] VMControl_VMGetGuestInfo

[edit] VMControl_VMSetGuestInfo

[edit] VMControl_VMGetExecutionState

[edit] VMControl_VMToolsLastActive

[edit] VMControl_VMInfo

[edit] VMControl interface details