JavaScript must be enabled to correctly display this content

Chapter 9 Using the Oracle VM Utilities

The Oracle VM Utilities are a collection of command line scripts that allow you to perform certain tasks in an Oracle VM environment, such as collecting metrics about the Oracle VM Server host on which virtual machines run and configuring CPU pinning, which is also referred to as hard partitioning.

The Oracle VM Utilities communicate directly with Oracle VM Manager using a Oracle VM API. The Oracle VM Utilities connect to the Oracle VM API with an Oracle VM Manager administrative user name and password. Oracle VM Manager listens for the Oracle VM Utilities on port 7002 (HTTPS).

Note

The Oracle VM Utilities version 2.1 and later work with Oracle VM Manager Release 3.4. Additionally, only the ovm_vmdisks, ovm_vmhostd, vm_dump_metrics, and ovm_vmcontrol scripts are intended for use with Oracle VM Manager Release 3.4. All other scripts are either obsolete or deprecated by the Oracle VM Manager Command Line Interface. See the Oracle VM Manager Command Line Interface User's Guide for details on how you can perform management tasks in an Oracle VM environment.
The Oracle VM Utilities are provided as-is and are not supported by Oracle. However, Oracle provides support for the Oracle VM Utilities in the following cases:
- The ovm_vmhostd and vm_dump_metrics scripts are supported when running SAP applications on Oracle Linux guests in an Oracle VM environment.
- The ovm_vmcontrol script is supported only when configuring hard partitioning, which is also referred to as CPU pinning. For more information, see the Setting Hard Partitioning for Virtual Machines CPUs section in the Oracle VM Concepts Guide .

Downloading and Installing the Oracle VM Utilities

To install the Oracle VM Utilities, do the following:

Download the Oracle VM Utilities as a .zip file from the Oracle VM downloads page:

https://www.oracle.com/technetwork/server-storage/vm/downloads/index.html
Extract the contents of the .zip file to the system. Refer to the readme file for specific instructions.

9.1 Oracle VM Virtual Machine Control (ovm_vmcontrol)

The ovm_vmcontrol script lets you configure CPU pinning, which is also referred to as hard partitioning, on virtual machines.

Note

The ovm_vmcontrol script supports CPU pinning for virtual machines running on x86-based Oracle VM Servers only. You cannot configure CPU pinning for virtual machines running on Oracle VM Server for SPARC.
If you are using Oracle VM Release 3.4.1 or Release 3.4.2, after you configure CPU pinning for a virtual machine, you must stop and then start the virtual machine for the configuration to take effect. Restarting the virtual machine does not load the configuration changes for CPU pinning.
As of Oracle VM Release 3.4.3, support for dynamic CPU pinning is available. As a result, after you configure CPU pinning for a virtual machine, there is no longer a requirement to stop and then start the virtual machine for the configuration to take effect.

Syntax

ovm_vmcontrol { -u username } [ -p password | -E ] { -h hostname } { -c command } { -v vm_name | -U vm_uuid } [ -s cpu_thread_list ... ]

Where command is:

{ setvcpu | getvcpu | rmvcpu }

Options

The following table shows the available options for this command.

Option	Description
`-u username`	Username of an Oracle VM Manager admin user. This option is required.
[ `-p password` \| `-E` ]	Corresponding password for the Oracle VM Manager admin user. You can specify the password as follows: Do not set an option for the password in the command line. The Oracle VM Utilities then prompt you to specify it. You should use this method to set the password. Set the password as an environment variable and then use the `-E` option. It is best practice to remove the environment variable when it is no longer required. You must use the `OVMUTIL_PASS` environment variable with the `-E` option. Set this variable for a single session as follows: # export OVMUTIL_PASS=`password` Specify the password on the command line with the `-p` option. This option is deprecated as of Oracle VM Release 3.4.
{ `-h hostname` }	Hostname of the server running Oracle VM Manager.
`-c` { `setvcpu` \| `getvcpu` \| `rmvcpu` }	Command to execute. This option is required. The `setvcpu` command hard-binds or pins virtual CPUs to threads. For example, `-c setvcpu -s 0,1,2` physically binds vcpu0 to thread0, vcpu1 to thread1, vcpu2 to thread2. Use the `getvcpu` command to retrieve information about pinned virtual CPUs for the selected virtual machine. CPU binding immediately takes effect, and will continue on subsequent start ups of the virtual machine.
`-v vm_name`	Virtual machine name.
`-U vm_uuid`	Virtual machine UUID. If you do not specify the virtual machine name with the `-v vm_name` option, you must specify the UUID of the virtual machine.
`-s` `cpu_thread_list` ...	List of physical thread numbers to which you can bind virtual CPUs. You can set the value as follows: One or more numbers separated by a comma. For example, `0,1,2,3,4`. A range of numbers. For example, `0-4` is equal to `0,1,2,3,4`. A range of numbers that excludes one number. For example, `0-4,^2` is equal to `0,1,3,4`. A combination of comma-separated numbers and ranges. For example, `0-2,4,6-8` is equal to `0,1,2,4,6,7,8`. Note You must not set a number as the value for the `-s` option that is greater than the physical CPU count for the server. For example, if a server has 8 physical CPUs then you can set 0 to 7. Setting 8 or higher is not valid. You must use this command in combination with: `-c` `setvcpu`

Examples

Example 9.1 Setting CPU pinning for a virtual machine

This example binds the virtual CPUs of the virtual machine to threads 0, 1, 3, 5, and 7.

# ./ovm_vmcontrol -u admin -h localhost -v MyVM01 -c setvcpu -s 0-3,^2,5-7,^6
Oracle VM VM Control utility 2.1.
Connecting to OVM Manager using Web Service.
Connected.
OVM Manager version: version
Command : setvcpu
Pinning vCPU '0-3,^2,5-7,^6' to VM 'MyVM01'
Pin vCPU succeed.

Example 9.2 Checking CPU pinning for a virtual machine

This example shows the virtual CPUs of the virtual machine are bound to threads 0, 1, 3, 5, and 7.

# ./ovm_vmcontrol -u admin -h localhost -v MyVM01 -c getvcpu
Oracle VM VM Control utility 2.1.
Connecting to OVM Manager using Web Service.
Connected.
OVM Manager version: version
Command : getvcpu
Getting pinned CPU list...
Current pinned CPU:0-3,^2,5-7,^6

9.2 Oracle VM Retrieve Disk (ovm_vmdisks)

The ovm_vmdisks script retrieves details about virtual disks. This script lists every virtual disk for a given virtual machine, as well as the virtual machine configuration (vm.cfg) file. If the virtual disks are physical devices directly attached to the virtual machine, this script lists the device mapper entry on the Oracle VM Server to which the virtual machine is assigned. If the virtual disks are files on an NFS server, the utility lists the NFS server name, mount point, and file name and location.

Syntax

ovm_vmdisks { -u username } { -p password | -E } { -h hostname } { -v vm_name | -U vm_uuid }

Options

The following table shows the available options for this command.

Option	Description
`-u username`	Username of an Oracle VM Manager admin user. This option is required.
[ `-p password` \| `-E` ]	Corresponding password for the Oracle VM Manager admin user. You can specify the password as follows: Do not set an option for the password in the command line. The Oracle VM Utilities then prompt you to specify it. You should use this method to set the password. Set the password as an environment variable and then use the `-E` option. It is best practice to remove the environment variable when it is no longer required. You must use the `OVMUTIL_PASS` environment variable with the `-E` option. Set this variable for a single session as follows: # export OVMUTIL_PASS=`password` Specify the password on the command line with the `-p` option. This option is deprecated as of Oracle VM Release 3.4.
{ `-h hostname` }	Hostname of the server running Oracle VM Manager.
`-v vm_name`	Virtual machine name.
`-U vm_uuid`	Virtual machine UUID. If you do not specify the virtual machine name with the `-v vm_name` option, you must specify the UUID of the virtual machine.

Examples

Example 9.3 Listing virtual disks for a virtual machine

# ./ovm_vmdisks -u admin -p Welcome1 -h localhost -v MyVM01
Oracle VM Retrieve Disk utility 2.1.
Connecting to OVM Manager using Web Service.
Connected.
Virtual Machine : 'MyVM01'
Assigned Server : OVS_01
Virtual Disk : '0004fb00001200003a3384c82332cce4.img' size : 50GB
    repository='MyRepo'
    Mounted Path=/OVS/Repositories/ \
    0004fb0000030000c96714fda5ef202f/ \
    VirtualDisks/0004fb00001200003a3384c82332cce4.img
    Absolute Path=IP_address:/ \
    nfs/mypath/sp1/VirtualDisks/0004fb00001200003a3384c82332cce4.img
Config File :
   Mounted Path=/OVS/Repositories/ \
   0004fb0000030000c96714fda5ef202f/ \
   VirtualMachines/0004fb000006000097e4d197a07005d9/vm.cfg
   Absolute Path=IP_address:/ \
   nfs/mypath/sp1/VirtualMachines/0004fb000006000097e4d197a07005d9/vm.cfg

9.3 Oracle VM Hostd For Metrics Messaging (ovm_vmhostd)

The ovm_vmhostd script collects metrics about the Oracle VM Server host on which a virtual machine is running. Every 60 seconds, the script checks that the virtual machine is running and then sends the metrics about the host to the virtual machine itself. In other words, the same virtual machine sends and receives the metrics about the Oracle VM Server host.

The virtual machine message that the ovm_vmhostd script sends has a key of vmhost. The metrics about the Oracle VM Server host are defined as the value of the virtual machine message.

To retrieve the host metrics from the virtual machine, you can use either the Oracle VM Guest Additions daemon, ovmd, or the vm-dump-metrics script. See Section 9.4, “Retrieving Host Metrics from Virtual Machines (vm-dump-metrics)”.

Note

The ovm_vmhostd script uses the Oracle VM Guest Additions to send and receive the metrics as virtual machine messages. For this reason, the guest virtual machine must be running Oracle Linux with the Oracle VM Guest Additions installed. See Chapter 8, Installing and Using the Oracle VM Guest Additions.

Syntax

ovm_vmhostd { -u username } [ -p password | -E ] { -h hostname } { -v vm_name | -U vm_uuid }

Options

The following table shows the available options for this command.

Option	Description
`-u username`	Username of an Oracle VM Manager admin user. This option is required.
[ `-p password` \| `-E` ]	Corresponding password for the Oracle VM Manager admin user. You can specify the password as follows: Do not set an option for the password in the command line. The Oracle VM Utilities then prompt you to specify it. You should use this method to set the password. Set the password as an environment variable and then use the `-E` option. It is best practice to remove the environment variable when it is no longer required. You must use the `OVMUTIL_PASS` environment variable with the `-E` option. Set this variable for a single session as follows: # export OVMUTIL_PASS=`password` Specify the password on the command line with the `-p` option. This option is deprecated as of Oracle VM Release 3.4.
{ `-h hostname` }	Hostname of the server running Oracle VM Manager.
`-v vm_name`	Virtual machine name. The virtual machine name is the name you assign during the creation of the virtual machine.
`-U vm_uuid`	Virtual machine UUID. If you do not specify the virtual machine name with the `-v vm_name` option, you must specify the UUID of the virtual machine.

Examples

Example 9.4 Sending Oracle VM Server details to a virtual machine

# ./ovm_vmhostd -u admin -h localhost -v MyVM01
Oracle VM Hostd 2.1.
Connecting to OVM Manager using Web Service.
Connected.
Processing VM : 'MyVM01'

VM : 'MyVM01' has status :  Running.
Message sent.
Sleeping 60 seconds.
Sleeping 60 seconds.
Sleeping 60 seconds.

9.4 Retrieving Host Metrics from Virtual Machines (vm-dump-metrics)

The vm-dump-metrics script outputs the metrics about the Oracle VM Server host in XML format that an SAP application running on a virtual machine guest can consume.

To collect the host metrics, do the following:

Run the ovm_vmhostd script to send metrics about the Oracle VM Server host as a virtual machine message.
Copy the vm-dump-metrics script to the guest virtual machine that received the virtual machine message.
Run the vm-dump-metrics script. The vm-dump-metrics script does not take any commands or options.

The vm-dump-metrics script queries ovmd to retrieve a message with the vmhost key. The script then does one of the following:

Parses the message and outputs the XML to standard output (stdout).
Exits with status 1 if a message with the vmhost key does not exist.

The following is an example of XML output from the vm-dump-metrics script:

<metrics>
  <metric type='real64' context='host'>
    <name>TotalCPUTime</name>
    <value>2694.3596</value>
  </metric>
  <metric type='uint64' context='host'>
    <name>PagedOutMemory</name>
    <value>0</value>
  </metric>
  <metric type='uint64' context='host'>
    <name>PagedInMemory</name>
    <value>0</value>
  </metric>
  <metric type='uint64' context='host'>
    <name>UsedVirtualMemory</name>
    <value>6747</value>
  </metric>
  <metric type='uint64' context='host'>
    <name>FreeVirtualMemory</name>
    <value>9817</value>
  </metric>
  <metric type='uint64' context='host'>
    <name>FreePhysicalMemory</name>
    <value>9817</value>
  </metric>
  <metric type='uint64' context='host'>
    <name>MemoryAllocatedToVirtualServers</name>
    <value>6747</value>
  </metric>
  <metric type='uint32' context='host'>
    <name>NumberOfPhysicalCPUs</name>
    <value>4</value>
  </metric>
  <metric type='string' context='host'>
    <name>HostSystemInfo</name>
    <value>ovm3</value>
  </metric>
  <metric type='string' context='host'>
    <name>VirtProductInfo</name>
    <value>Oracle VM 3</value>
  </metric>
  <metric type='string' context='host'>
    <name>VirtualizationVendor</name>
    <value>Oracle Corporation</value>
  </metric>
  <metric type='uint64' context='host'>
    <name>Time</name>
    <value>1360606566774</value>
  </metric>
  <metric type='string' context='host'>
    <name>HostName</name>
    <value>ovm3</value>
  </metric>
  <metric type='uint64' context='vm' id='0' uuid='0004fb00-0006-0000-d72b-647e20a85939'>
    <name>PhysicalMemoryAllocatedToVirtualSystem</name>
    <value>1024</value>
  </metric>
  <metric type='uint64' context='vm' id='0' uuid='0004fb00-0006-0000-d72b-647e20a85939'>
    <name>ResourceMemoryLimit</name>
    <value>1024</value>
  </metric>
  <metric type='uint32' context='vm' id='0' uuid='0004fb00-0006-0000-d72b-647e20a85939'>
    <name>ResourceProcessorLimit</name>
    <value>1</value>
  </metric>
  <metric type='real64' context='vm' id='0' uuid='0004fb00-0006-0000-d72b-647e20a85939'>
    <name>TotalCPUTime</name>
    <value>2694.3596</value>
  </metric>
</metrics>

Querying the Oracle VM Guest Additions Daemon Directly

As an alternative to using the vm-dump-metrics script, you can query ovmd to view the message that contains the metrics about the Oracle VM Server host, as follows:

# ovmd -g vmhost
com.sap.host.VirtualizationVendor=Oracle Corporation;com.sap.host.VirtProductInfo=Oracle VM 3;
com.sap.host.PagedInMemory=0;com.sap.host.PagedOutMemory=0;com.sap.host.PageRates=0;
com.sap.vm.uuid=0004fb0000060000d72b647e20a85939;com.sap.host.HostName=ovm3;
com.sap.host.HostSystemInfo=ovm3;com.sap.host.NumberOfPhysicalCPUs=4;com.sap.host.NumCPUs=4;
com.sap.host.TotalPhyMem=16383;com.sap.host.UsedVirtualMemory=6747;
com.sap.host.MemoryAllocatedToVirtualServers=6747;com.sap.host.FreeVirtualMemory=9817;
com.sap.host.FreePhysicalMemory=9817;com.sap.host.TotalCPUTime=381175.97;
com.sap.host.Time=1360606887997;com.sap.vm.PhysicalMemoryAllocatedToVirtualSystem=1024;
com.sap.vm.ResourceMemoryLimit=1024;com.sap.vm.TotalCPUTime=2696.2214;
com.sap.vm.ResourceProcessorLimit=1;

For more information about the Oracle VM Guest Additions daemon, ovmd, see Chapter 8, Installing and Using the Oracle VM Guest Additions.