VMWare vmserverd API

From BovineNet

The "vmserverd" is a service that is provided with many of VMWare's current virtualization products. Although VMWare does not document this service separately or describe its function, this document may be useful to those people who are curious about it.

1 Service details
2 API overview
- 2.1 Calling arbitrary XML functions with vmcontrol
3 Listing of XML functions
4 Found bugs

[edit] Service 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.

The "vmware-authd" service is gateway service that performs some lightweight authentication of the connection. If you are connecting to the local machine (by passing NULL for the hostname, username, and password of the VMControl connect function), then vmware-authd performs special validation to ensure you are originating from localhost and what Windows/Linux user your program is running as.

After being validated by "vmware-authd", the request is transparently passed to the "vmserverd" service for actual processing. There is no way to directly communicate with the vmserverd service, because it is not listing on any network socket--it instead connects vmware-authd and maintains a persistent network connection to allow it to receive requests as they arrive.

[edit] API overview

All API functions called by the vmcontrol library are actually sending a lightweight XML command to the server for processing, and the XML response is parsed by the library and returned. Note that the vmcontrol network protocol is not actually SOAP or XML-RPC, even though the concept is similar. The vmcontrol API network protocol does not include any datatype information and does not attempt to be fully self-describing. For example, the following is an example of the actual XML being sent:

  <exec>
     <op>FileManager_MakeDir</op>
     <in>
       <directories><directory>C:\My Directory\New Subdirectory</directory></directories>
       <owner_mode>rwx</owner_mode>
       <group_mode>rwx</group_mode>
       <other_mode>rwx</other_mode>
       <makeParents>0</makeParents>
     </in>
  </exec>

[edit] Calling arbitrary XML functions with vmcontrol

Not all of the functions available in "vmserverd" are actually exposed through the vmcontrol API. Fortunately, the vmcontrol API does provide the VMControl_ServerExec function that lets you send arbitrary XML and execute any vmserverd function that you like. However, you will be responsible for composing the XML request and parsing the XML response.

Here is a very simple example that uses the "inc" opcode to increment an integer:

char *result = VMControl_ServerExec(control->vmServer,
       "<exec><op>inc</op><in><number>42</number></in></exec>");
printf("result = %s\n", result);

The output of the above when you run it looks like this on VMWare Server (note that this shows that it is still internally "GSX"):

result = <exec><product id="GSX"><title>VMware Server</title> 
   <version>1.0.3 build-44356</version><build>44356</build></product>
   <returncode>1</returncode><out><number>43</number></out></exec>

[edit] Listing of XML functions

To see a list of all of the "opcodes" being provided by the vmserverd service, look near the top of the C:\Windows\Temp\vmware-serverd.log file for lines that look like this on VMWare Server 1.0.3:

Operations defined in function table:
Op CreateCOWDisk -> VMware::VMServerd::Disk::CreateCOWDisk_Handler (authuser)
Op Directory_GetSpaceUsage -> VMware::VMServerd::Handlers::Directory_GetSpaceUsage_Handler (authuser)
Op Directory_List -> VMware::VMServerd::Handlers::Directory_List_Handler (authuser)
Op Directory_Make -> VMware::VMServerd::Handlers::Directory_Make_Handler (authuser)
Op Directory_Remove -> VMware::VMServerd::Handlers::Directory_Remove_Handler (authuser)
Op FileManager_ChangeAttribs -> VMware::VMServerd::FileManager::ChangeAttribs_Handler (authuser)
Op FileManager_ChangeGroup -> VMware::VMServerd::FileManager::ChangeGroup_Handler (authuser)
Op FileManager_ChangeMode -> VMware::VMServerd::FileManager::ChangeMode_Handler (authuser)
Op FileManager_ChangeOwner -> VMware::VMServerd::FileManager::ChangeOwner_Handler (authuser)
Op FileManager_FileCopy -> VMware::VMServerd::FileManager::FileCopy_Handler (authuser)
Op FileManager_FileExists -> VMware::VMServerd::FileManager::FileExists_Handler (authuser)
Op FileManager_FileMakeLink -> VMware::VMServerd::FileManager::FileMakeLink_Handler (authuser)
Op FileManager_FileMove -> VMware::VMServerd::FileManager::FileMove_Handler (authuser)
Op FileManager_FileRemove -> VMware::VMServerd::FileManager::FileRemove_Handler (authuser)
Op FileManager_GetHomeDir -> VMware::VMServerd::FileManager::GetHomeDir_Handler (authuser)
Op FileManager_GetParentDir -> VMware::VMServerd::FileManager::GetParentDir_Handler (authuser)
Op FileManager_ListDir -> VMware::VMServerd::FileManager::ListDir_Handler (authuser)
Op FileManager_ListDirTree -> VMware::VMServerd::FileManager::ListDirTree_Handler (authuser)
Op FileManager_MakeDir -> VMware::VMServerd::FileManager::MakeDir_Handler (authuser)
Op FileManager_RemoveDir -> VMware::VMServerd::FileManager::RemoveDir_Handler (authuser)
Op File_Copy -> VMware::VMServerd::Handlers::File_Copy_Handler (authuser)
Op File_Create -> VMware::VMServerd::Handlers::File_Create_Handler (authuser)
Op File_Delete -> VMware::VMServerd::Handlers::File_Delete_Handler (authuser)
Op File_Exists -> VMware::VMServerd::Handlers::File_Exists_Handler (authuser)
Op File_Read -> VMware::VMServerd::Handlers::File_Read_Handler (authuser)
Op File_ReadLastN -> VMware::VMServerd::Handlers::File_ReadLastN_Handler (authuser)
Op GSXHostInfo_GetDiskSpace -> VMware::VMServerd::GSXHostInfo::GetDiskSpace_Handler (authuser)
Op GSXHostInfo_Query -> VMware::VMServerd::GSXHostInfo::Query_Handler (authuser)
Op Host_GetBridgedNet -> VMware::VMServerd::Handlers::Host_GetBridgedNet_Handler (authuser)
Op Host_GetHostOnlyNet -> VMware::VMServerd::Handlers::Host_GetHostOnlyNet_Handler (authuser)
Op Host_GetVirtualNet -> VMware::VMServerd::Handlers::Host_GetVirtualNet_Handler (authuser)
Op Security_ActivateConfig -> VMware::VMServerd::SecurityEdit::ActivateConfig_Handler (rootonly)
Op Security_CreateCertificate -> VMware::VMServerd::SecurityEdit::CreateCertificate_Handler (rootonly)
Op Security_GetConfig -> VMware::VMServerd::SecurityEdit::GetConfig_Handler (rootonly)
Op TaskManager_DeleteTask -> VMware::VMServerd::TaskManager::DeleteTask_Handler (authuser)
Op TaskManager_StatusOfTask -> VMware::VMServerd::TaskManager::StatusOfTask_Handler (authuser)
Op TaskManager_StopTask -> VMware::VMServerd::TaskManager::StopTask_Handler (authuser)
Op VMConfigDefaults_GetAll -> VMware::VMServerd::VMConfigDefaults::GetAll_Handler (authuser)
Op VMConfigDefaults_GetConfigVersion -> VMware::VMServerd::VMConfigDefaults::GetConfigVersion_Handler (authuser)
Op VMDeleteEdit_DeleteVM -> VMware::VMServerd::VMDeleteEdit::DeleteVM_Handler (authuser)
Op VMDeleteInfo_DeleteVMInfo -> VMware::VMServerd::VMDeleteInfo::DeleteVMInfo_Handler (authuser)
Op VMRegister -> VMware::VMServerd::VMList::Register_Handler (authuser)
Op VMServerd_GetConnectedVMList -> VMware::VMServerd::GetConnectedVMList_Handler (authuser)
Op VMServerd_GetOperationTable -> VMware::VMServerd::GetOperationTable_Handler (authuser)
Op VMServerd_GetProductInfo -> VMware::VMServerd::GetProductInfo_Handler (authuser)
Op VMServerd_GetRequestCount -> VMware::VMServerd::GetRequestCount_Handler (authuser)
Op VMServerd_IsAdminUser -> VMware::VMServerd::IsAdminUser_Handler (authuser)
Op VMUnRegister -> VMware::VMServerd::VMList::UnRegister_Handler (authuser)
Op VM_GetLastNEvents -> VMware::VMServerd::EventLog::VM_GetLastNEvents_Handler (authuser)
Op VM_INFO -> VMware::VMServerd::Info::VM_Info_Handler (authuser)
Op VM_Who -> VMware::VMServerd::Who::VM_Who_Handler (authuser)
Op dec -> main::decrement (authuser)
Op div -> main::divide (authuser)
Op inc -> main::increment (authuser)

The list of vmserverd functions available on other VMWare products or versions will vary. In particular VMWare ESX Server exposes many more functions beyond what is listed above.

The "vmserverd" service is actually a partially-compiled Perl application. On the Windows version of VMWare Server, you can find most of the Perl source code that implements it in: C:\Program Files\VMware\VMware Server\vmserverdRoot, C:\Program Files\VMware\VMware Server\perl5\site_perl\5.005\VMware\VMServerd

The required XML syntax can usually be found by looking through the Perl source files for the "xxxx_Handler" function name that was displayed on the right-side of the "->" in the vmware-serverd.log file shown above.

[edit] Found bugs

This is just an informal listing of some of the bugs I have found while playing with the vmserverd functions.

"FileManager_MakeDir" has a "makeParents" option, however it does not function correctly if set to non-zero. It removes all slashes/backslashes from the requested directory and makes each segment from the root directory. (Asking it to create "C:\test1\test2\test3" causes it to create "C:\test1", "C:\test1test2", and "C:\test1test2test3".) Found on VMWare Server 1.0.3 on Windows.
"FileManager_FileCopy" will fail with a Perl error "Undefined subroutine &VMware::VMServerd::NewTask" if trying to copy across file systems or files greater than 10MB. Found on VMWare Server 1.0.3 on Windows.

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

Category: Technology