OVF Reference

OVF Files and Abiquo

An OVF descriptor is designed to be read by a hypervisor directly. Abiquo can read OVF files that were created automatically and exported from hypervisors. However, Abiquo uses the OVF descriptor to create the VM by calling the hypervisor API (or libvirt). Thus Abiquo will send a command to the hypervisor API to create the VM resources required. As this example shows, some elements of a typical OVF descriptor created by a hypervisor will be ignored by Abiquo.

Abiquo recommends that you do not develop your own OVF envelope documents. This OVF Reference section is to provide information about OVF for Abiquo for reference and troubleshooting purposes.

Introduction to OVF

The OVF standard is widely used in virtualization. Abiquo's VM templates and template definitions are based on OVF.

This is an excerpt from the OVF specification.

Open Virtualization Format (OVF) is a hypervisor-neutral, efficient, extensible, and open specification for the packaging and distribution of virtual appliances composed of one or more virtual computer systems.

The rapid adoption of virtual infrastructure has highlighted the need for a standard, portable meta-data model for the distribution of virtual machines to and between virtualization platforms. Packaging an application together with the operating system on which it is certified, into a virtual machine that can be easily transferred from an ISV, through test and development and into production as a pre-configured, pre-packaged unit with no external dependencies, is extremely attractive. Such pre-deployed, ready to run applications packaged as virtual machines (VMs) are called virtual appliances. In order to make this concept practical on a large scale it is important that the industry adopts a vendor-neutral standard for the packaging of such VMs and the meta-data that are required to automatically and securely install, configure, and run the virtual appliance on any virtualization platform.

Whereas current virtual appliances contain a single VM only, modern enterprise applications model service oriented architectures (SOA) with multiple tiers, where each tier contains one or more machines. A single VM model is thus not sufficient to distribute a multi-tier service. In addition, complex applications require install-time customization of networks and other customer specific properties. Furthermore, a virtual appliance is packaged in a run-time format with hard disk images and configuration data suitable for a particular hypervisor. Run-time formats are optimized for execution and not for distribution. For efficient software distribution, a number of additional features become critical, including portability, platform independence, verification, signing, versioning, and licensing terms.

The Open Virtualization Format (OVF) specification is a hypervisor-neutral, efficient, extensible, and open specification for the packaging and distribution of virtual appliances composed of one or more VMs. It aims to facilitate the automated, secure management not only of virtual machines but the appliance as a functional unit. For the OVF format to succeed it must be developed and endorsed by ISVs, virtual appliance vendors, operating system vendors, as well as virtual platform vendors, and must be developed within a standards-based framework.

OVF for Abiquo

OVF is a packaging format for distributing solutions based on VM templates. To deploy a VM packaged using the OVF standard, add it to the Abiquo Apps library as a VM template.

Abiquo currently only supports OVFs with a single virtual system.

An OVF package contains:

• The OVF envelope descriptor document (.ovf) with the configuration metadata.
• Virtual disk files. Abiquo can work with various disk formats but streamOptimized is the default distribution format.

Abiquo only uses the elements of the OVF package described on this page.

Envelope

The OVF description file (.ovf) contains metadata of the virtual appliance template.
Envelope is the root element for this XML document.

The mandatory sections are:

• References
• DiskSection
• VirtualSystem
  • ProductSection (required by Abiquo)
  • VirtualHardwareSection

References

This section contains references to external resources used by the virtual appliance. References can point to files such as virtual disks or icons.

Reference information for completing the References section:

• ovf:id: Internal ID for this reference used within the OVF descriptor .
• ovf:href : Reference to the file location. This is the relative path from the location of the OVF descriptor document on disk.
• ovf:size : Size of the file in bytes.

In the example below, there are two disk files, 0 and 1, inside the OVF descriptor, and it is located in the same directory on the disk as the OVF descriptor. An icon is also included for this file.

	<ovf:References>
    	<ovf:File ovf:id="0" ovf:href="grml-sync.qcow2" ovf:size="1073741824"/>
    	<ovf:File ovf:id="1" ovf:href="otherdisk.vmdk" ovf:size="209715200"/>
	</ovf:References>

DiskSection

You can use multiple physical disks to create a virtual machine. The disk at sequence 0 on the disk controller must be a boot disk.

Reference information for completing the DiskSection:

• ovf:diskId : Internal ID of this disk used in the 'VirtualSection' to mount the disk.
• ovf:fileRef : Use the 'ovf:id' for the File in the 'References' section above.
• ovf:capacity : Size in bytes of the FULL logical size of the virtual disk. See Determine the size of a VM disk file
• ovf:CapacityAllocationUnits:, default bytes.
  
  • "KB", "KILOBYTE" or "byte * 2^10".
  • "MB", "MEGABYTE" or "byte * 2^20".
  • "GB", "GIGABYTE" or "byte * 2^30".
  • "TB", "TERABYTE" or "byte * 2^40".
• ovf:format  : The format of the virtual disk as a URL. For the URLs of the formats supported by Abiquo, see Template Compatibility Table#Supported Disk Format Types.

	<ovf:Section xsi:type="ovf:DiskSection_Type">
    	<ovf:Disk ovf:diskId="0" ovf:fileRef="0" ovf:capacity="1024" ovf:capacityAllocationUnits="MegaBytes" ovf:format="http://people.gnome.org/~markmc/qcow-image-format.html#monolithic_sparse"/>
    	<ovf:Disk ovf:diskId="1" ovf:fileRef="1" ovf:capacity="1" ovf:capacityAllocationUnits="MegaBytes" ovf:format="http://unknown"/>
	</ovf:Section>

Empty disks

Abiquo enables you to define empty disks in the OVF file. These disks have no file reference. The system disk cannot be an empty disk.

 <Disk  diskId="disk1"  capacity="4294967296" format="http://raw" />

VirtualSystem

The VirtualSystem describes the template configuration for a virtual machine. In Abiquo, the OVF descriptor can only contain one VirtualSystem but you can use a virtual appliance to hold multiple virtual machines.

Abiquo uses the following elements of the virtual system that are mandatory:

• ovf:id: If the optional Name attribute is not supplied, this is the Name of the VM template
• Info: Description of the VM for the appliance library
• Icon: As described below
• ProductSection: As described below
• OperatingSystemSection: As described below
• VirtualHardwareSection: As described below
• Name: Optional - Abiquo uses this Name attribute as the VM template Name; otherwise, it falls back to the id.

The VirtualSystem section is structured as follows.

<ovf:VirtualSystem ovf:id="promm">
	<ovf:Info>GRML Small with sync to disk. Used for the functional tests.</ovf:Info>
  	<ovf:Name>promm</ovf:Name>
    <ovf:ProductSection>
        ...
    </ovf:ProductSection>
	<ovf:VirtualHardwareSection>
		...
    </ovf:VirtualHardwareSection>
	...
</ovf:VirtualSystem>

ProductSection

The ProductSection is required by Abiquo. Enter information about the VM that is displayed for users.

The ProductSection must contain:

• Info
• Product
• Icon
  • ovf:fileRef: URL of the icon file
  • ovf:mimeType: jpeg, png or gif
  • ovf:width: pixels
  • ovf:height: pixels

The Icon URL must include a public IP address or domain name (not 127.0.0.1 or localhost).

The ProductSection can also contain the following optional elements:

• Vendor
• Version
• ProductUrl
• VendorUrl
• Property 
  
  • ovf:key="user"
  • ovf:key="password"

    <ProductSection>
    	<Info>Abiquo - Flex machine</Info>
        <Product>Abiquo - Flex machine</Product>
        <Icon ovf:fileRef="http://rs.bcn.abiquo.com:9000/public/icons/q.png" ovf:mimeType="image/jpeg" ovf:width="32" ovf:height="32" />        
        <Property ovf:key="user" ovf:type="string" ovf:value="myUser">
             <Description>Default login username</Description>
        </Property>
        <Property ovf:key="password" ovf:type="string" ovf:value="myPassword">
             <Description>Default login password</Description>
        </Property>
  </ProductSection>

The user and password are stored as <loginUser> and <loginPassword> in the Abiquo VM template definition. If they are not supplied, the default value is null.

OperatingSystemSection

This optional section contains the operating system ID and version.

The operating system ID must be one of the official codes described in the OVF documentation for the CIM Schema version supported by Abiquo.

Please note that the code usually includes the number of bits. For example, the code for Ubuntu 32 bit is not the same as the code for Ubuntu 64 bit. The operating system version is a free text field. There are no restrictions on the values you can enter. 

For example, for Windows 7 Server the OperatingSystemSection should be as follows.

   <OperatingSystemSection 
    ovf:id="105"
    ovf:version="Server">
        <Info>The kind of guest operating system installed</Info>
        <Description>Windows 7 Server 64 bit</Description>
</OperatingSystemSection>

To create the template definition, Abiquo will interpret the OperatingSystemSection ovf:id according to the Guest OS Interpretation Table on the Extended OVF Support and Template Definition page. This means that the CIM code will be converted to the name of the OS and the version field will be stored directly in Abiquo without any changes. Note that you can modify the template definition in Abiquo using the API or in the Abiquo database.

...
   <osType>WINDOWS_7</osType>
   <osVersion>Server</osVersion>
...

When you deploy a virtual machine from this template in ESXi 5.1, Abiquo will set the guest operating system based on the table.

windows7Server64Guest

VirtualHardwareSection

Contains all the information about the hardware resources needed to run the virtual appliance. The System section is followed by various Items.

• System
• Item (virtual device)

<ovf:Section xsi:type="ovf:VirtualHardwareSection_Type">
        	<ovf:System>
            	<vssd:VirtualSystemType>abiquo</vssd:VirtualSystemType>
        	</ovf:System>
        <ovf:Item>...</ovf:Item>
        ...
        <ovf:Item>...</ovf:Item>
    </ovf:VirtualHardwareSection>

System

Previously this field was used to describe the disk format. However, now Abiquo uses the Template Compatibility Table to determine if the target hypervisor can run the source disk format. Abiquo V2V functionality can convert a disk from one format to another. Enter "abiquo" as the VirtualSystemType.

    <ovf:System>
		<vssd:VirtualSystemType>abiquo</vssd:VirtualSystemType>
    </ovf:System>

Items

In the System section, an Item specifies a virtual device by describing the resources to allocate on the virtual system. Resources are described using Resource Allocation Setting Data (RASD) elements.

Required Items:

• Virtual CPU
• Virtual Memory
• SCSI Disk

Optional Items (Abiquo will automatically create these if they are not included):

• SCSI Adapter
• Ethernet Adapter 1
• Ethernet Adapter 2

Common Item RASD Fields found in all items

• rasd:Caption: Brief description to make the OVF more readable.
• rasd:InstanceID: A unique ID for the Item.

Virtual CPU

Reference information for completing the Virtual CPU Item:

• rasd:ResourceType: Set to "3" to indicate this is a CPU.
• rasd:VirtualQuantity: The number of virtual CPUs allocated.

			<Item>
				<rasd:Caption>1 virtual CPUs</rasd:Caption>
				<rasd:Description>Number of virtual CPUs</rasd:Description>
				<rasd:InstanceId>1</rasd:InstanceId>
				<rasd:ResourceType>3</rasd:ResourceType>
				<rasd:VirtualQuantity>1</rasd:VirtualQuantity>
			</Item>

Virtual Memory

Reference information for completing the RAM Item:

• rasd:ResourceType: Set to "4" to indicate this is RAM.
• rasd:AllocationUnits: Default is "bytes". Other options are:
  • "KB", "KILOBYTE" or "byte * 2^10".
  • "MB", "MEGABYTE" or "byte * 2^20".
  • "GB", "GIGABYTE" or "byte * 2^30".
  • "TB", "TERABYTE" or "byte * 2^40".
• rasd:VirtualQuantity: The number of units of RAM allocated.

			<Item>
				<rasd:Caption>2048 MB of memory RAM</rasd:Caption>
				<rasd:Description>Memory Size</rasd:Description>
				<rasd:InstanceId>2</rasd:InstanceId>
				<rasd:ResourceType>4</rasd:ResourceType>
				<rasd:AllocationUnits>MB</rasd:AllocationUnits>
				<rasd:VirtualQuantity>2048</rasd:VirtualQuantity>
			</Item>

Hard Disk

Abiquo requires a hard disk that is appropriate for your hypervisor and virtual machine.

Reference information for completing the Hard Disk Item:

• rasd:HostResource: Reference to the disk ID of a disk defined in the DiskSection above.
• rasd:ResourceType: Set ResourceType to 17 to indicate a hard disk

• rasd:AddressOnParent: Set AddressOnParent to the disk sequence number and file/disk number

        	<ovf:Item>
            	<rasd:AddressOnParent>0</rasd:AddressOnParent>
            	<rasd:AllocationUnits>MB</rasd:AllocationUnits>
            	<rasd:ElementName>Hd</rasd:ElementName>
            	<rasd:HostResource>ovf:/disk/0</rasd:HostResource>
            	<rasd:InstanceID>1000</rasd:InstanceID>
            	<rasd:Parent>SCSI.lsilogic</rasd:Parent>
            	<rasd:ResourceType>17</rasd:ResourceType>
            	<rasd:VirtualQuantity>1024</rasd:VirtualQuantity>
        	</ovf:Item>
        	<ovf:Item>
            	<rasd:AddressOnParent>1</rasd:AddressOnParent>
            	<rasd:AllocationUnits>MB</rasd:AllocationUnits>
            	<rasd:ElementName>Hd</rasd:ElementName>
            	<rasd:HostResource>ovf:/disk/1</rasd:HostResource>
            	<rasd:InstanceID>1001</rasd:InstanceID>
            	<rasd:Parent>SCSI.lsilogic</rasd:Parent>
            	<rasd:ResourceType>17</rasd:ResourceType>
            	<rasd:VirtualQuantity>1</rasd:VirtualQuantity>
        	</ovf:Item>

Disk Controller

Abiquo can support DiskControllers of type IDE or SCSI supplied in the .ovf definition. And the specific controller can be set. You can add multiple SCSI controllers. You can change the SCSI controller before or after you deploy the VM.

For example, when you create a volume in an ESXi virtual datacenter, if you don’t enter a value for the disk controller, the platform will use the value set in the Abiquo Configuration Properties or the default VirtualLsiLogicController.

For example:

			<ovf:Item>
            	<rasd:ElementName>SCSI Controller</rasd:ElementName>
            	<rasd:InstanceID>SCSI.lsilogic</rasd:InstanceID>
            	<rasd:ResourceSubType>lsilogic</rasd:ResourceSubType>
            	<rasd:ResourceType>6</rasd:ResourceType>
        	</ovf:Item>

or  
			<ovf:Item>
                <rasd:Description>IDE Controller</rasd:Description>
                <rasd:ElementName>IDE controller 0</rasd:ElementName>
                <rasd:ResourceType>5</rasd:ResourceType>
           </ovf:Item>

This element is known as the diskControllerType in the Abiquo template definition. For example, <diskControllerType>IDE</diskControllerType>.

Ethernet Adapter

By default, Abiquo supports the E1000 ethernet adapter.

On ESX, Abiquo can support three types of Ethernet adapters. The supported adapters are: E1000, PCNet32, and VMXNET3. The default is E1000 and in case of problems with other adapters, E1000 will be used.

			<Item>
				<rasd:Caption>vNic Driver</rasd:Caption>
				<rasd:Description>Ethernet Adapter</rasd:Description>

				<rasd:InstanceId>4</rasd:InstanceId>
				<rasd:ResourceType>10</rasd:ResourceType>

				<rasd:Connection>bridged</rasd:Connection>
				<rasd:ResourceSubType>{E1000, PCNet32, VMXNET3}</rasd:ResourceSubType>
			</Item>

On KVM, Abiquo can support the VIRTIO ethernet adapter in addition to the E1000 ethernet adapter.

This element is referred to as <ethernetDriverType> in the Abiquo template definition. For example <ethernetDriverType>E1000</ethernetDriverType>.

Example OVF Descriptor

This is an example of the OVF descriptor created by Abiquo. It contains only the essential elements. Follow the instructions above to update the OVF descriptor for your virtual disk files.

Right click and use Save As to download the following desc.ovf sample descriptor file which is also attached to this page.

<Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:vssd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_VirtualSystemSettingData"
    xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ResourceAllocationSettingData"
    xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"
    xmlns="http://schemas.dmtf.org/ovf/envelope/1"
    xsi:schemaLocation="http://schemas.dmtf.org/ovf/envelope/1">
    

	<References>
	
	<!--
		<File ovf:href="AbiquoCIB.qcow2" ovf:id="file1" ovf:size="4913673728" />
		<File ovf:href="25/file" ovf:id="file1" ovf:size="4913673728" />
	-->
	
		<File ovf:href="file-AbiquoCIB.qcow2" ovf:id="file1" ovf:size="4913673728" />
	</References>
	
	<DiskSection>
		<Info>List of Virtual Disks</Info>
		<Disk 
			ovf:fileRef="file1"
			ovf:diskId="disk1" 
			ovf:capacity="4294967296"
			ovf:format="http://people.gnome.org/~markmc/qcow-image-format.html#monolithic_sparse" />
	</DiskSection>
	
	
	<VirtualSystem ovf:id="Abiquo - Flex machine">
		<Info>A virtual machine</Info>
		
	  	<ProductSection>
	    	<Info>Abiquo - Flex machine</Info>
            <Product>Abiquo - Flex machine</Product>
            <Icon ovf:fileRef="http://rs.bcn.abiquo.com:9000/public/icons/q.png" ovf:mimeType="image/jpeg" ovf:width="32" ovf:height="32" /> 
            <Property ovf:key="user" ovf:type="string" ovf:value="myUser">
                 <Description>Default login username</Description>
            </Property>
            <Property ovf:key="password" ovf:type="string" ovf:value="myPassword">
                 <Description>Default login password</Description>
            </Property>       
       	</ProductSection>

	    <OperatingSystemSection 
          ovf:id="107"
          ovf:version="5">
            <Info>The kind of guest operating system installed</Info>
      		<Description>CentOS 5 64-bit</Description>
    	</OperatingSystemSection>
		<VirtualHardwareSection>
			<System>
				<vssd:VirtualSystemType>abiquo</vssd:VirtualSystemType>
			</System>
			<Item>
				<rasd:Caption>1 virtual CPUs</rasd:Caption>
				<rasd:Description>Number of virtual CPUs</rasd:Description>
				<rasd:InstanceId>1</rasd:InstanceId>
				<rasd:ResourceType>3</rasd:ResourceType>
				<rasd:VirtualQuantity>1</rasd:VirtualQuantity>
			</Item>
			<Item>
				<rasd:Caption>2048 MB of memory RAM</rasd:Caption>
				<rasd:Description>Memory Size</rasd:Description>
				<rasd:InstanceId>2</rasd:InstanceId>
				<rasd:ResourceType>4</rasd:ResourceType>
				<rasd:AllocationUnits>MB</rasd:AllocationUnits>
				<rasd:VirtualQuantity>2048</rasd:VirtualQuantity>
			</Item>
			<Item>
				<rasd:Caption>Harddisk 0</rasd:Caption>
				<rasd:InstanceId>11</rasd:InstanceId>
				<rasd:ResourceType>17</rasd:ResourceType>
				<rasd:HostResource>ovf:/disk/disk1</rasd:HostResource>
			</Item>
			<Item>
                <rasd:Description>SCSI Controller</rasd:Description>
                <rasd:ElementName>SCSI controller 0</rasd:ElementName>
                <rasd:ResourceType>6</rasd:ResourceType>
                <rasd:ResourceSubType>lsilogic</rasd:ResourceSubType>
           </Item>
			<Item>
				<rasd:Caption>vNic Driver</rasd:Caption>
				<rasd:Description>Ethernet Adapter</rasd:Description>

				<rasd:InstanceId>4</rasd:InstanceId>
				<rasd:ResourceType>10</rasd:ResourceType>

				<rasd:Connection>bridged</rasd:Connection>
				<rasd:ResourceSubType>PCNet32</rasd:ResourceSubType>
			</Item>
		</VirtualHardwareSection>
	</VirtualSystem>
	
	<Section xsi:type="ovf:NetworkSection_Type">
		<Info>List of networks</Info>
		<Network ovf:name="Network 1">
			<Description>The "Network 1" network</Description>
		</Network>
	</Section>
</Envelope>

OVF Validation

Checking OVF files using an API call

Administrators can validate OVF files for Abiquo by calling the Abiquo appliance manager API.

The .ovf file should contain the fields as described in #OVF for Abiquo above. Replace the text in red with appropriate values for your system, where the "Remote Services Server" is the address of the server with the Appliance Manager.

You can use the fix query parameter to resolve a missing product section and/or disk-format type URI. By default, the fix parameter is set to false. Here is an example query with the fix query parameter.

curl --verbose -u admin:xabiquo -X POST http://localhost/am/validate?fix=true -d @zeus.ovf -H 'Content-Type:application/xml'

It should give detailed information about the validation process.

Here is the output from a successful validation test:

> POST /am/validate HTTP/1.1
> User-Agent: curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
> Host: abiquo.example.com
> Accept: */*
> Content-Type: application/xml
> Content-Length: 11987
> Expect: 100-continue
> 
< HTTP/1.1 100 Continue
} [data not shown]
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Content-Type: application/atom+xml
< Content-Length: 580
< Date: Fri, 13 Jul 2012 13:38:35 GMT
< 
{ [data not shown]
100 12567  100   580  100 11987  29291   591k --:--:-- --:--:-- --:--:--  616k
* Connection #0 to host abiquo.example.com left intact
* Closing connection #0
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<template>
  <description>Windows2003 machine</description>
  <diskFileSize>818991104</diskFileSize>
  <diskFormatType>UNKNOWN</diskFormatType>
  <ethernetDriverType>PCNet32</ethernetDriverType>
  <name>Windows2003</name>
  <url>http://am/validation/OK.ovf</url>
  <cpu>1</cpu>
  <diskFileFormat>UNKNOWN</diskFileFormat>
  <diskFilePath>windows2003-disk1.vmdk</diskFilePath>
  <hd>10737418240</hd>
  <hdSizeUnit>BYTE</hdSizeUnit>
  <iconPath>http://rs.bcn.abiquo.com:9000/public/icons.q.png</iconPath>
  <ram>701</ram>
  <ramSizeUnit>MEGABYTE</ramSizeUnit>
</template>

And here is an example of the output when checking an incorrect .ovf file.

> POST /am/validate HTTP/1.1
> User-Agent: curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
> Host: abiquo.example.com
> Accept: */*
> Content-Type: application/xml
> Content-Length: 11729
> Expect: 100-continue
> 
< HTTP/1.1 100 Continue
} [data not shown]
< HTTP/1.1 500 Internal Server Error
< Server: Apache-Coyote/1.1
< Content-Type: application/atom+xml
< Content-Length: 219
< Date: Fri, 13 Jul 2012 13:39:49 GMT
< Connection: close
< 
{ [data not shown]
100 11948  100   219  100 11729   4928   257k --:--:-- --:--:-- --:--:--  266k
* Closing connection #0
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
  <code>TEMPLATE-INVALID</code>
  <message>Invalid OVF Document
Caused by: Section org.dmtf.schemas.ovf.envelope._1.ProductSectionType not found</message>
</error>

Manual OVF Validation

This section is based on the automatic OVF validation process prior to downloading a VM template from the remote repository to the appliance library. 
However, you can check these points before uploading a VM to the appliance library.

Checklist:

All these errors are reported on the appliance library screen and directly on the repository filesystem (''deploy.error'' file inside the package folder).