8.7 Using the Oracle VM Guest Additions with Microsoft Windows (ovmcmd)

The Oracle VM Guest Additions provide a command line tool named ovmcmd for interacting with their functions, similar to the ovmd command in Linux. The command line tool is distributed during installation of the Oracle VM Paravirtual Drivers, and is located in the folder: C:\Program Files (x86)\Oracle Corporation\Oracle VM Windows PV Drivers.

The Shell

The executable binary file ovmcmd is used with 32-bit Windows, while ovmcmd_64 is used with 64-bit Windows. You can run ovmcmd directly by using the Windows command line. The ovmcmd command provides its own shell mode, which is convenient for setting multiple variables. Enter ovmcmd without any parameter to display the list of supported interfaces.

This figure shows a screenshot of the command window inside a Windows VM. It displays the list of supported interfaces with the ovmcmd command, which appears when ovmcmd is entered without additional parameters.

Enter one of these commands to run ovmcmd in shell mode:

32-bit Windows: ovmcmd ovmapishell
64-bit Windows: ovmcmd_x64 ovmapishell

This example shows the ovmcmd shell on a 64-bit Windows:

This figure shows a screenshot of the ovmcmd shell inside a 64-bit Windows VM.

The Commands

In shell mode, ovmcmd sets up a session and connects an event handler. The user can enter commands at the OVMAPIShell shell prompt without having to re-issue ovmcmd. This is optional, as individual commands can be specified on the Windows command line executing ovmcmd. Shell mode can be used to send and receive messages containing parameter values, or to display the contents of the xenstore. Commands for sending and receiving messages are illustrated under Conversation Between Guest and Oracle VM Manager. Command names in ovmcmd are not case sensitive.

The Xenstore commands should only be used by people with substantial knowledge of the internals of Xen. Those commands are:

XenstoreRead: reads the value of a xenstore key. The parameter following the subcommand is the xenstore key to read.
```
OVMAPIShell>XenstoreRead /local/domain/708/device/vif/0/state
4
OVMAPIShell>
```
XenstoreWrite: writes a value to a xenstore key or creates a new xenstore key. The parameters are the xenstore key and the value to be written. If the xenstore key is read-only, an error message appears.
```
OVMAPIShell>XenstoreWrite /local/domain/708/control/test 1
Operation Succeeded
OVMAPIShell>XenstoreWrite /local/domain/708/test 2
Operation Failed
OVMAPIShell>
```

XenstoreDir: lists a xenstore directory. The parameter is the xenstore directory to display.

OVMAPIShell>XenstoreDir /local/domain/0
vm
device
control
error
memory
guest
hvmpv
data
cpu
  1
    availability
  2
    availability
[...]
OVMAPIShell>

The SendMessage command is used to send messages. However, messages sent this way are not saved.

OVMAPIShell>SendMessage value 1
Operation Succeeded
OVMAPIShell>

To send a message and at the same time save the parameter key/value pair, use the ParamSetValue command.

OVMAPIShell>ParamSetValue guestparam1 guestval 1
ParamSetValue returned 0
OVMAPIShell>OVMCmdEventHandler: Received Event type 64, size 12, ID 6
ParamSetValue returned 0

To retrieve the value of a specified parameter, use the ParamGetValue command.

OVMAPIShell>ParamGetValue guestparam1 guestval
ParamGetValue returned 0, guestparam1 = guestval (len = 9)

Conversation Between Guest and Oracle VM Manager

Conversations between the guest VM and Oracle VM Manager are based on sending and receiving messages.

From the Windows VM side of the conversation: use the ovmcmd command ParamSetValue to set a parameter and send a message from the guest VM to Oracle VM Manager. For example ParamSetValue mykey myval sets the value of key "mykey" to "myval", and sends a message to Oracle VM Manager.

C:\Program Files (x86)\Oracle Corporation\Oracle VM Windows PV Drivers>OVMCmd_64 ParamSetValue mykey myval
ParamSetValue returned 0

The SendMessage command can also be used.

C:\Program Files (x86)\Oracle Corporation\Oracle VM Windows PV Drivers>OVMCmd_64 SendMessage foo bar
Operation Succeeded

Use the ReadParameter command as shown below to read messages from Oracle VM Manager. Output can optionally be piped to a file for later processing.

C:\Program Files (x86)\Oracle Corporation\Oracle VM Windows PV Drivers>OVMCmd_64 ReadParameter sesame
Success: sesame = street (7)

For the Oracle VM Manager side of the conversation: to display the message from the Oracle VM Manager user interface, select the VM in the Servers and VMs tab, right click, and select Display Events.

See View Virtual Machine Events in the Oracle VM Manager User's Guide for more information.

Alternatively, send a message to the guest with the Oracle VM CLI sendVmMessage command.

OVM> sendvmmessage vm name=VMNAME key=managerparam message=managerval log=no

See sendVmMessage in the Oracle VM Manager Command Line Interface User's Guide for more information.