8.2 Oracle VM Guest Additions Packages

To install the Oracle VM Guest Additions, you first download a set of packages from a yum repository to the virtual machine. You can download the packages from the Unbreakable Linux Network (ULN) or the Oracle Linux Yum Server. After you download the required packages, you use the yum install to install them.

The following table lists the packages for the Oracle VM Guest Additions:

Package	Description	Required or Optional
`libovmapi`	Library that adds support for the Oracle VM API.	Required
`libovmapi-devel`	Library that adds developer support for the Oracle VM API.	Optional
`ovmd`	Daemon that handles configuration events and enables sending and receiving of messages between the virtual machine and Oracle VM Manager.	Required
`python-simplejson`	JSON encoder and decoder for Python.	Required
`xenstoreprovider`	Library that communicates with the Oracle VM API kernel infrastructure.	Required
`ovm-template-config`	Basic operating system configuration scripts.	Required
`ovm-template-config-authentication`	Script for configuring virtual machine authentication.	Optional
`ovm-template-config-datetime`	Script for configuring virtual machine datetime settings.	Optional
`ovm-template-config-firewall`	Script for configuring virtual machine firewall.	Optional
`ovm-template-config-network`	Script for configuring virtual machine network settings.	Optional
`ovm-template-config-selinux`	Script for configuring virtual machine selinux settings.	Optional
`ovm-template-config-ssh`	Script for configuring virtual machine ssh settings.	Optional
`ovm-template-config-system`	Script for configuring virtual machine system settings.	Optional
`ovm-template-config-user`	Script for configuring virtual machine user settings.	Optional

Microsoft Windows Guests

For Microsoft Windows guests, the Oracle VM Guest Additions are included in the Oracle VM Paravirtual Drivers. The implementation of the guest additions consists of these components:

vmapi.dll: a dynamic link library that exposes callable interfaces
ovmsvc: the service that receives and sends events and messages
xenpci: the driver that interacts with the hypervisor
ovmcmd: the command used to invoke the guest additions

vmapi.dll

The vmapi.dll exposes interfaces to functions for communication between Windows applications and the xenpci driver in the Windows guest operating system. Applications load this library and call the exported functions to access xenpci. Normally device I/O controls (IOCTLs) are used to communicate with the xenpci driver. The following table shows function names and their descriptions:

Function	Description
OVMAPI_Register	initializes OVMAPI and optionally registers a callback
OVMAPI_ParamGetValue	retrieves name-value pairs stored within the OVMAPI engine
OVMAPI_ParamSetValue	creates or modifies a name-value pair
OVMAPI_Subscribe	receives particular events in the application registered event handler
OVMAPI_UnSubscribe	blocks particular events in the application registered event handler
OVMAPI_EventComplete	completes the event with a finalizing status code at a later time
OVMAPI_ParamGetValueSize	retrieves the size, in bytes, of a parameter value
OVMAPI_GetSessionFileDescriptors	retrieves the internal file descriptor for use in making special calls to the driver
OVMAPI_UserEventPublish	sends application-specific events to the management server and to other OVMAPI-enabled applications running on the same VM
OVMAPI_ParamGetAllNames	browses for existing parameters that may be of interest to the application
OVMAPI_ParamGetCount	retrieves the number of existing parameters
OVMAPI_UnRegister	terminates OVMAPI usage

ovmsvc

The ovmsvc service starts automatically by default when the Windows VM is booted. The command to install or uninstall this service is ovmsvc install or ovmsvc uninstall respectively. The ovmsvc service monitors messages sent from Oracle VM Manager, and sends Windows VM specific information, such as the operating system version and the VM's IP address. It uses the vmapi.dll to implement communication between the Windows guest and Oracle VM Manager. The following figure shows ovmsvc running inside a Windows VM.

This figure shows a screenshot from inside a Windows VM. It displays the properties of the Oracle VM Service, indicating that the service is in started status.

When ovmsvc is started, it opens the xenpci device and registers a callback function where messages are processed. A thread is created to monitor events corresponding with vmapi messages. The current callback function of ovmsvc processes VM shutdown messages; other messages, for example "snapshot", could be implemented as additional features.

xenpci

Applications exchanging messages with Oracle VM Manager use the xenpci driver, which implements several IOCTLs to process messages. The xenpci driver directly accesses xenstore, a memory area shared by Xen domains. The ovmsvc calls API functions to send or read VM messages to or from xenstore.

The xenpci driver uses the xenbus_watch function to monitor incoming messages. The xenpci driver initialization registers a watch function on the xenstore key "control/oracle-vmapi/to-guest/last-write". Messages sent by Oracle VM Manager are set in this xenstore key. The watch function of xenpci is triggered when this xenstore key changes. The watch function checks and sends out events, a monitor thread acknowledges events, and a callback function processes API messages.

The ovmsvc sends Windows VM messages during its startup process, and uses an IOCTL in xenpci to write the xenstore key "control/oracle-vmapi/from-guest/%d/%s". The ovmsvc updates the message periodically to synchronize the information, such as guest IP address, from the guest to Oracle VM Manager.

Oracle Solaris

The Oracle VM Guest Additions are also available for Oracle Solaris, both on SPARC and x86. They can be optionally installed from a Solaris IPS repository: pkg://solaris/system/management/ovm-guest-additions.