Home > Blogs > VMware vApp Developer Blog


Virtual Hardware in OVF – Part 1

In the blog post Inside the OVF Package, we talked about the structure of an OVF package, including the different sections (XML elements). One of the more important sections is the one describing the virtual hardware configuration for a VM. The operating system and applications installed in a virtual machine (commonly referred to as just the guest) are highly depended on the virtual hardware that is provided by the deployed virtualization platform. For example, if the hypervisor is exposing the virtual disks through an IDE controller to a guest that is expecting to use a SCSI controller, it is likely that the software will not boot or even worse it might even misbehave. A key objective of the OVF format is to ensure robust and well-behaved deployments. This is achieved by the OVF package author describe the requirements to the virtual hardware in the OVF descriptor, and the OVF deployment can check whether it can fullfill those requirements at deployment time.

In this first blog entry, we will introduce the hardware description model along with a simple examples. This is probably all that you need to know for most daily use. We will follow up with another post with some more examples, and finally with a post with some more advanced examples using deployment-time configurations and multiple hardware profiles.

Ok, lets, get started.

The OVF specification version 1.0 defines a VirtualHardwareSection. This is based on the ResourceAllocationSettingData (RASD) elements from the DMTF CIM standard. For users not familiar with the CIM model this may appear slightly complex at first, but there are many advantages to leveraging an already existing standard, and as we will see once you get used to it, it is pretty straight forward.

The 'System' Element:

We start with the System element found as <System> in the OVF descriptor. The System element is optional but is generally used to specify the “virtual hardware family type”. For VMware products we use the form ‘vmx-X’ where X is VMware's virtual hardware version number. The import process will convert the virtual hardware to use this version number. Several hardware versions may be defined by using space as a delimiter e.g. “vmx-04 vmx-07”. The list of hardware versions are unordered, meaning that the import process is free to pick a hardware version satisfying the remaining of the hardware requirements. VMware products will always pick the recommended hardware version of the host if multiple acceptable versions exists.

The remaining fields are not necessary for import but required by the CIM standard. A system element could look like:

<System>
        <vssd:ElementName>Virtual Hardware Family</vssd:ElementName>
        <vssd:InstanceID>0</vssd:InstanceID>
        <vssd:VirtualSystemIdentifier>MyVm</vssd:VirtualSystemIdentifier>
        <vssd:VirtualSystemType>vmx-07 vmx-4 myHardwareVersion someOtherHardwareVersion</vssd:VirtualSystemType>
</System>

The following table show which hardware versions are supported on various VMware platforms.

Hardware Family Supported by (and later versions of the same products)
vmx-04 WS 5.0, Fusion 1.1, Server 1.0, ESX 3.0
vmx-06 WS 6.0, Fusion 1.1, Server 1.0
vmx-07 WS 6.5, Fusion 2.0, Server 2.0, ESX 4.0

The 'item' Elements

Virtual hardware is modeled as a set of devices, such as ethernet card or disk controllers, memory. Each of those devices are described by an element. The  DMTF RASD specifies a set of fields that can be set. We only a subset of those fields in an OVF descriptor. The fields in a RASD must be ordered alphabetically. The following table lists the RASD fields that are used:

ElementName Required field that contains a display-friendly message about the content of the RASD
Description Human-readable description
InstanceID Required field that contains unique ID within this <VirtualHardwareSection>
ResourceType Required field that indicates the kind of resource
ResourceSubType A vendor-specific identifier for specific devices
VirtualQuantity Specifies the amount (used for memory and CPU)
AllocationUnits Specifies the unit of resource (used for memory and CPU)
Reservation Specifies resource allocation policy (CPU and memory)
Limit Specifies resource allocation policy (CPU and memory)
Weight Specifies resource allocation policy (CPU and memory)
Address Typically used as the unit number of a controller
Parent Instance ID of parent controller (for devices on a controller)
AddressOnParent Used to specify the order for devices on a controller
AutomaticAllocation Used to specify whether a device should be connected on power-on (e.g., for a CDROM)
Connection Reference to a network for an ethernet adaptor
HostResource Reference to a virtual disk for a disk drive

The minimum Item element looks like this:

<Item>
<rasd:ElementName>SomeName</rasd:ElementName>
<rasd:InstanceID>1</rasd:InstanceID>
<rasd:ResourceType>0</rasd:ResourceType>
</Item>

ElementName is a general description of the Item element. InstanceID is a unique identifier for the Item element and is used to refer to other hardware elements. The ResourceType describes the type of hardware. The resource types used in OVF are described in CIM_ResourceAllocationSettingData.mof, which describes the mapping from the ResourceType number to hardware element type. For instance, ResourceType=2 maps to “Processor” (CPU) and ResourceType=10 maps to “Ethernet Adapter”. See the following table for the typical used ResourceTypes: 

Kind ResourceType
Other 0
Processor 3
Memory 4
IDE Controller 5
SCSI Controller 6
Ethernet Adapter 10
Floppy Drive 14
CD/DVD Drive 15/16
Disk Drive 17
USB Controller 23

For some ResourceTypes it is necessary to define a more specific subtype. ResourceSubType is vendor specific, meaning that VMware supports one set of subtypes while other vendors may support other types. ResourceSubType with ResourceType=0 (Other) is also used to define Virtual Hardware that is not described in the CIM schema, for instance a soundcard. The complete list of ResourceTypes with supported ResourceSubTypes for VMware products is shown below:

Kind ResourceType ResourceSubType Other Fields
Other 0 vmware.soundcard.sb16, vmware.soundcard.ensoniq1371, vmware.pcicontroller,vmware.ps2controller, vmware.siocontroller, vmware.keyboard, vmware.pointingdevice Depend on hardware type
Processor 3 AllocationUnit, VirtualQuantity, Reservation, Limit, Weight
Memory 4 AllocationUnit, VirtualQuantity, Reservation, Limit, Weight
IDE Controller 5 Address
SCSI Controller 6 lsilogic, buslogic, lsilogicsas, virtualscsi Address
Ethernet Adapter 10 E1000, PCNet32, VmxNet, VmxNet2, VmxNet3 AddressOnParent, AutomaticAllocation, Connection
Floppy Drive 14 AddressOnParent, AutomaticAllocation
CD/DVD Drive 15 Parent, AddressOnParent, AutomaticAllocation
Disk Drive 17 Parent, AddressOnParent, HostResource
USB Controller 23

Example

We will now look at a sample OVF descriptor that describe a small VM, that are using a single CPU, 512 MB of memory and the use of a disk on a SCSI controller. In this example we will look at the virtual hardware description and will disregard the the other metadata information present in the OVF descriptor. We will look at each of the Item elements in the virtual hardware section and explain what they do and how they reference each other.

The System element specifies that this hardware description is designed for vmx-07 or vmx-04: 

<Info>Virtual hardware requirements</Info>
<System>
        <vssd:ElementName>Virtual Hardware Family</vssd:ElementName>
        <vssd:InstanceID>0</vssd:InstanceID>
        <vssd:VirtualSystemIdentifier>My Small VM</vssd:VirtualSystemIdentifier>
        <vssd:VirtualSystemType>vmx-07 vmx-04</vssd:VirtualSystemType>
</System>

If we look at the two first Item elements we first see a definition of how many CPUs we want the VM to have. The amount is in the VirtualQuantity element and for this VM we want 1 CPU. In AllocationUnits we are using the Programmatic Units as defined in http://www.dmtf.org/standards/published_documents/DSP0004_2.5.0.pdf. The next Item element we are defining the amount of memory.

<Item>
        <rasd:AllocationUnits>hertz * 10^6</rasd:AllocationUnits>
        <rasd:Description>Number of Virtual CPUs</rasd:Description>
        <rasd:ElementName>1 virtual CPU(s)</rasd:ElementName>
        <rasd:InstanceID>1</rasd:InstanceID>
        <rasd:ResourceType>3</rasd:ResourceType>
        <rasd:VirtualQuantity>1</rasd:VirtualQuantity>
</Item>
<Item>
        <rasd:AllocationUnits>byte * 2^20</rasd:AllocationUnits>
        <rasd:Description>Memory Size</rasd:Description>
        <rasd:ElementName>512MB of memory</rasd:ElementName>
        <rasd:InstanceID>2</rasd:InstanceID>
        <rasd:ResourceType>4</rasd:ResourceType>
        <rasd:VirtualQuantity>512</rasd:VirtualQuantity>
</Item>

We now define a SCSI controller of subtype ‘lsilogic’ and with an InstanceID=3. We will later use the InstanceID to bind a disk to this controller. As can be seen we have not defined a PCI controller to bind the SCSI controller to. For VMware products PCI controller is a default device so there it is optional to add it as an Item element. The next two Item elements are defining IDE controllers.

<Item>
        <rasd:Address>0</rasd:Address>
        <rasd:Description>SCSI Controller</rasd:Description>
        <rasd:ElementName>SCSI Controller 0</rasd:ElementName>
        <rasd:InstanceID>3</rasd:InstanceID>
        <rasd:ResourceSubType>lsilogic</rasd:ResourceSubType>
        <rasd:ResourceType>6</rasd:ResourceType>
</Item>
<Item>
        <rasd:Address>1</rasd:Address>
        <rasd:Description>IDE Controller</rasd:Description>
        <rasd:ElementName>IDE 1</rasd:ElementName>
        <rasd:InstanceID>4</rasd:InstanceID>
        <rasd:ResourceType>5</rasd:ResourceType>
</Item>
<Item>
        <rasd:Address>0</rasd:Address>
        <rasd:Description>IDE Controller</rasd:Description>
        <rasd:ElementName>IDE 0</rasd:ElementName>
        <rasd:InstanceID>5</rasd:InstanceID>
        <rasd:ResourceType>5</rasd:ResourceType>
</Item>

We now want to add a CDROM drive to one of the IDE controllers. If we look at the Parent element we can see we want to bind it to a device with InstanceID=5. If we look for an Item element with InstanceID=5 we can see that this is IDE 0. We use AddressOnParent to tell where on the IDE controller we want to place the CDROM. If no AddressOnParent element is specified devices are attached to their “parent” in the order they are found in the OVF. Here we see that the AddressOnParent=0, so we set it to device 0 on the IDE controller. On the Item element we are defining a ovf:required=”false” this tells the import process that if we are unable to add this hardware device the import process is allowed to continue.

<Item ovf:required="false">
        <rasd:AddressOnParent>0</rasd:AddressOnParent>
        <rasd:AutomaticAllocation>false</rasd:AutomaticAllocation>
        <rasd:ElementName>CD/DVD Drive 1</rasd:ElementName>
        <rasd:InstanceID>7</rasd:InstanceID>
        <rasd:Parent>5</rasd:Parent>
        <rasd:ResourceType>15</rasd:ResourceType>
</Item>

The last item element found in this VirtualHardwareSection is a disk. If we look at the Parent element we can see that we must attach this device to a controller. By looking for InstanceID we can see that this disk's parent is the SCSI controller. Again we specify the AddressOnParent=0 to tell that we want this disk to first on the controller. The HostResource tells what disk defined in the DiskSection we want to use. 'ovf:/disk/vmdisk1' points to an 'ovf:diskId' attribute in the Disk section element. This will tell import process basic information about the disk like capacity and disk format.

<Item>
        <rasd:AddressOnParent>0</rasd:AddressOnParent>
        <rasd:ElementName>Hard Disk 1</rasd:ElementName>
        <rasd:HostResource>ovf:/disk/vmdisk1</rasd:HostResource>
        <rasd:InstanceID>9</rasd:InstanceID>
        <rasd:Parent>3</rasd:Parent>
        <rasd:ResourceType>17</rasd:ResourceType>
</Item>

We have now defined a small working VM with a SCSI controller, a virtual disk, and a CDROM if supported. Click to download the complete OVF descriptor.

In the next part of this blog post on virtual hardware we will describe more detailed examples of how to create virtual hardware sections.

4 thoughts on “Virtual Hardware in OVF – Part 1

  1. Carl Skow

    Are any of these passable to the VM? Lets say I want to change the amount of memory via OVF property pulldown during deployment, or have the user select whether they want 1 or 2 vCPU based on environment. Is that possible?

  2. Eske Christiansen

    You should see properties as information that are parsed to the VM. To solve your problem I would take a look at DeploymentOptionSection in the standard. Here you can define a preset configuration e.g small = 1 cpu, medium = 2 cpu etc. that the user get to choose when he deploy the OVF. Im not sure VMware studio supports that but adding it by hand should not be hard.

  3. definition

    Thank you for this post, after searching google for definition site I found this useful site ” http://nicedefinition.com ” it free online site for English definitions,
    they try to collect all definitions and meanings from all world dictionaries and open sources,
    and everyday they try to add and update more and more, they planning to be the world largest free online definitions site.
    Thank you again for this post.

Comments are closed.