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

Abiquo's VM templates and template definitions are based on the OVF standard.

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.

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 Catalogue as a VM template.

Abiquo currently only supports OVFs with one virtual system.

An OVF package contains:

• The OVF envelope descriptor document (.ovf) with the configuration metadata.

• Virtual disk files. Abiquo can work with various https://abiquo.atlassian.net/wiki/spaces/doc/pages/311371267/Template+compatibility+table#Supported-disk-format-types  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 (This is 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.

Example references section

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, which means the size when the disk is deployed. 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.

Example DiskSection

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.

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 will use the id.

The VirtualSystem section is structured as follows.

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"

VirtualSystem

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.

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, and it 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.

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

VirtualHardwareSection

Contains all the information about the hardware resources needed to run the virtual appliance. The System section includes various Items:

• System

• Item (virtual device)

VirtualHardwareSection

System

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.

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.

System virtual CPU 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.

System virtual memory item

Hard disk

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

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

System Harddisk item

Disk controller

Abiquo can support DiskControllers of type IDE or SCSI that you supply in the .ovf definition. And a 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 disk 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:

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 ESXi, Abiquo can support three types of Ethernet adapters. The supported adapters are: E1000, PCNet32, and VMXNET3. The default is E1000, and if there are problems with other adapters, Abiquo will use E1000.

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.

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.

It should give detailed information about the validation process.

Here is the output from a successful validation test:

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

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 Catalogue. 
However, you can check these points before uploading a VM template to the Catalogue.

OVF Validation checklist table