Build a Virtual Disk Image

A Virtual Disk Image is a compressed system disk with additional metadata useful for cloud frameworks like Amazon EC2, Google Compute Engine, or Microsoft Azure.

To instruct KIWI to build a VMX image add a type element with image="vmx" in config.xml. An example configuration for a 42 GB large VMDK image with 512 MB RAM, an IDE controller and a bridged network interface is shown below:

<image schemaversion="7.1" name="JeOS-Tumbleweed">
  <!-- snip -->
  <preferences>
    <type image="vmx" filesystem="ext4"
          format="vmdk" boottimeout="0"
          bootloader="grub2">
      <size unit="G">42</size>
      <machine memory="512" guestOS="suse" HWversion="4">
        <vmdisk id="0" controller="ide"/>
        <vmnic driver="e1000" interface="0" mode="bridged"/>
      </machine>
    </type>
    <!-- additional preferences -->
  </preferences>
  <!-- snip -->
</image>

The following attributes of the type element are of special interest when building VMX images:

  • format: Specifies the format of the virtual disk, possible values are: gce, ova, qcow2, vagrant, vmdk, vdi, vhd, vhdx and vhd-fixed.

  • formatoptions: Specifies additional format options passed to qemu-img. formatoptions is a comma separated list of format specific options in a name=value format like qemu-img expects it. KIWI will forward the settings from this attribute as a parameter to the -o option in the qemu-img call.

The size and machine child-elements of type can be used to customize the virtual machine image further. We describe them in the following sections (see Modifying the Size of the Image and Customizing the Virtual Machine).

Once your image description is finished (or you are content with a image from the example descriptions and use one of them) build the image with KIWI:

$ sudo kiwi-ng --type vmx system build \
    --description path/to/the/vmx-image-description/ \
    --target-dir /tmp/myimage

The created image will be in the target directory /tmp/myimage with the file extension .raw.

The live image can then be tested with QEMU:

$ qemu \
    -drive file=$IMAGE_NAME.raw,format=raw,if=virtio \
    -m 4096

For further information how to setup the image to work within a cloud framework see:

For information how to setup a Vagrant box, see: KIWI Image Description for Vagrant.

Modifying the Size of the Image

The size child element of type specifies the size of the resulting disk image. The following example shows a image description where 20 GB are added to the virtual machine image of which 5 GB are left unpartitioned:

<image schemaversion="7.1" name="JeOS-Tumbleweed">
  <!-- snip -->
  <preferences>
    <type image="vmx" format="vmdk">
      <size unit="G" additive="true" unpartitioned="5">20</size>
    </type>
    <!-- additional preferences -->
  </preferences>
  <!-- snip -->
</image>

The following optional attributes can be used to customize the image size further:

  • unit: Defines the unit used for the provided numerical value, possible settings are M for megabytes and G for gigabytes. The default unit are megabytes.

  • additive: boolean value that determines whether the provided value will be added to the current image’s size (additive="true") or whether it is the total size (additive="false"). The default is false.

  • unpartitioned: Specifies the image space in the image that will not be partitioned. This value uses the same unit as defined in the attribute unit or the default.

Customizing the Virtual Machine

The machine child element of type can be used to customize the virtual machine configuration which is used when the image is run, like the number of CPUs or the connected network interfaces.

The following attributes are supported by the machine element:

  • ovftype: The OVF configuration type. The Open Virtualization Format is a standard for describing virtual appliances and distribute them in an archive called Open Virtual Appliance (OVA). The standard describes the major components associated with a disk image. The exact specification depends on the product using the format.

    Supported values are zvm, powervm, xen and vmware.

  • HWversion: The virtual machine’s hardware version (vmdk and ova formats only), see https://kb.vmware.com/s/article/1003746 for further details which value to choose.

  • arch: the VM architecture (vmdk format only), possible values are: ix86 (= i585 and i686) and x86_64.

  • xen_loader: the Xen target loader which is expected to load this guest, supported values are: hvmloader, pygrub and pvgrub.

  • guestOS: The virtual guest OS’ identification string for the VM (only applicable for vmdk and ova formats, note that the name designation is different for the two formats).

  • min_memory: The virtual machine’s minimum memory in MB (ova format only).

  • max_memory: The virtual machine’s maximum memory in MB (ova format only).

  • min_cpu: The virtual machine’s minimum CPU count (ova format only).

  • max_cpu: The virtual machine’s maximum CPU count (ova format only).

  • memory: The virtual machine’s memory in MB (all formats).

  • ncpus: The umber of virtual CPUs available to the virtual machine (all formats).

Additionally, machine supports additional child elements that are covered in the following subsections.

Modifying the VM Configuration Directly

The vmconfig-entry element is used to add entries directly into the virtual machine’s configuration file. This is currently only supported for the vmdk format where the provided strings are directly pasted into the .vmx file.

The vmconfig-entry element has no attributes and can appear multiple times, the entries are added to the configuration file in the provided order. Note, that KIWI does not check the entries for correctness. KIWI only forwards them.

The following example adds the two entries numvcpus = "4" and cpuid.coresPerSocket = "2" into the VM configuration file:

<image schemaversion="7.1" name="openSUSE-15.1" displayname="Bob">
  <preferences>
    <type image="vmx" filesystem="ext4" format="vmdk"
          bootloader="grub2" kernelcmdline="splash"
          bootpartition="false">
      <machine memory="512" guestOS="suse" HWversion="4">
        <vmconfig-entry>numvcpus = "4"</vmconfig-entry>
        <vmconfig-entry>cpuid.coresPerSocket = "2"</vmconfig-entry>
      </machine>
    </type>
  </preferences>
</image>

Adding Network Interfaces to the VM

Network interfaces can be explicitly specified for the VM when required via the vmnic element. This can be used to add another bridged interface or to specify the driver which is being used.

Note, that this element is only used for the vmdk image format.

In the following example we add a bridged network interface using the e1000 driver:

<image schemaversion="7.1" name="openSUSE-15.1" displayname="Bob">
  <preferences>
    <type image="vmx" filesystem="btrfs"
          bootloader="grub2" kernelcmdline="splash">
      <machine memory="4096" guestOS="suse" HWversion="4">
        <vmnic driver="e1000" interface="0" mode="bridged"/>
      </machine>
    </type>
  </preferences>
</image>

The vmnic element supports the following attributes:

  • interface: mandatory interface ID for the VM’s network interface.

  • driver: optionally the driver which will be used can be specified

  • mac: this interfaces’ MAC address

  • mode: this interfaces’ mode.

Note that KIWI will not verify the values that are passed to these attributes, it will only paste them into the appropriate configuration files.

Specifying Disks and Disk Controllers

The vmdisk element can be used to customize the disks and disk controllers for the virtual machine. This element can be specified multiple times, each time for each disk or disk controller present.

Note that this element is only used for vmdk and ova image formats.

The following example adds a disk with the ID 0 using an IDE controller:

<image schemaversion="7.1" name="openSUSE-15.1" displayname="Bob">
  <preferences>
    <type image="vmx" filesystem="ext4" format="vmdk"
          bootloader="grub2" kernelcmdline="splash"
          bootpartition="false">
      <machine memory="512" guestOS="suse" HWversion="4">
        <vmdisk id="0" controller="ide"/>
      </machine>
    </type>
  </preferences>
</image>

Each vmdisk element can be further customized via the following optional attributes:

  • controller: The disk controller used for the VM guest (vmdk format only). Supported values are: ide, buslogic, lsilogic, lsisas1068, legacyESX and pvscsi.

  • device: The disk device to appear in the guest (xen format only).

  • diskmode: The disk mode (vmdk format only), possible values are: monolithicSparse, monolithicFlat, twoGbMaxExtentSparse, twoGbMaxExtentFlat and streamOptimized (see also https://www.vmware.com/support/developer/converter-sdk/conv60_apireference/vim.OvfManager.CreateImportSpecParams.DiskProvisioningType.html).

  • disktype: The type of the disk as it is internally handled by the VM (ova format only). This attribute is currently unused.

  • id: The disk ID of the VM disk (vmdk format only).

Adding CD/DVD Drives

KIWI supports the addition of IDE and SCSCI CD/DVD drives to the virtual machine using the vmdvd element for the vmdk image format. In the following example we add two drives: one with a SCSCI and another with a IDE controller:

<image schemaversion="7.1" name="openSUSE-15.1" displayname="Bob">
  <preferences>
    <type bootloader="grub2" filesystem="ext4"
          image="vmx" kernelcmdline="splash">
      <machine memory="512" xen_loader="hvmloader">
        <vmdvd id="0" controller="scsi"/>
        <vmdvd id="1" controller="ide"/>
      </machine>
    </type>
  </preferences>
</image>

The vmdvd element features just these two mandatory attributes:

  • id: The CD/DVD ID of the drive

  • controller: The CD/DVD controller used for the VM guest, supported values are ide and scsi.