Build a Virtual Disk Image¶
A simple Virtual Disk Image is a compressed system disk with additional metadata useful for cloud frameworks like Amazon EC2, Google Compute Engine, or Microsoft Azure. It is used as the native disk of a system and does not require an extra installation workflow or a complex first boot setup procedure which is why we call it a simple disk image.
To instruct KIWI NG to build a simple disk image add a
type element with
config.xml that has the
disabled. An example configuration for a 42 GB large VMDK image with
512 MB RAM, an IDE controller and a bridged network interface is shown
<image schemaversion="7.2" name="Tumbleweed_appliance"> <!-- snip --> <preferences> <type image="oem" filesystem="ext4" format="vmdk"> <bootloader name="grub2" timeout="0"/> <size unit="G">42</size> <oemconfig> <oem-resize>false</oem-resize> </oemconfig> <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 simple disk images:
format: Specifies the format of the virtual disk, possible values are:
formatoptions: Specifies additional format options passed to qemu-img.
formatoptionsis a comma separated list of format specific options in a
name=valueformat like qemu-img expects it. KIWI NG will forward the settings from this attribute as a parameter to the
-ooption in the qemu-img call.
machine child-elements of
type can be
used to customize the virtual machine image further. We describe them in
the following sections: Setting up the Bootloader of the Image, 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 NG:
$ sudo kiwi-ng --type oem system build \ --description kiwi-descriptions/suse/x86_64/suse-leap-15.1 \ --target-dir /tmp/myimage
The created image will be in the target directory
the file extension
The live image can then be tested with QEMU:
$ qemu \ -drive file=Leap-15.1_appliance.x86_64-1.15.1.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: Image Description for Vagrant.
Setting up the Bootloader of the Image¶
<preferences> <bootloader name="grub2"/> </preferences>
bootloader element is used to select the bootloader. At the moment
grub2_s390x_emu (a combination of zipl
and a userspace GRUB2) are supported. The special
custom entry allows
to skip the bootloader configuration and installation and leaves this up
to the user which can be done by using the
editbootconfig custom scripts.
In addition to the mandatory name attribute the following optional attributes are supported:
Specifies the bootloader console. The attribute is available for the grub and isolinux bootloader types. By default a graphics console setup is used
Specifies the bootloader serial line setup. The setup is effective if the bootloader console is set to use the serial line. The attribute is available for the grub bootloader only
Specifies the boot timeout in seconds prior to launching the default boot option. By default the timeout is set to 10 seconds. It makes sense to set this value to
0for images intended to be started non-interactively (e.g. virtual machines).
Specifies the boot timeout style to control the way in which the timeout interacts with displaying the menu. If set the display of the bootloader menu is delayed after the timeout expired. In countdown mode an indication of the remaining time is displayed. The attribute is available for the grub loader only
Specifies the device type of the disk zipl should boot. On zFCP devices use
SCSI, on DASD devices use
LDLon emulated DASD devices use
FBA. The attribute is available for the zipl loader only
Modifying the Size of the Image¶
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:
<preferences> <type image="oem" format="vmdk"> <size unit="G" additive="true" unpartitioned="5">20</size> <oemconfig> <oem-resize>false</oem-resize> </oemconfig> </type> </preferences>
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
Mfor megabytes and
Gfor 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
unpartitioned: Specifies the image space in the image that will not be partitioned. This value uses the same unit as defined in the attribute
unitor the default.
Customizing the Virtual Machine¶
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
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
HWversion: The virtual machine’s hardware version (
ovaformats only), see https://kb.vmware.com/s/article/1003746 for further details which value to choose.
arch: the VM architecture (
vmdkformat only), possible values are:
xen_loader: the Xen target loader which is expected to load this guest, supported values are:
guestOS: The virtual guest OS’ identification string for the VM (only applicable for
ovaformats, note that the name designation is different for the two formats).
min_memory: The virtual machine’s minimum memory in MB (
max_memory: The virtual machine’s maximum memory in MB (
min_cpu: The virtual machine’s minimum CPU count (
max_cpu: The virtual machine’s maximum CPU count (
memory: The virtual machine’s memory in MB (all formats).
ncpus: The umber of virtual CPUs available to the virtual machine (all formats).
machine supports additional child elements that are covered
in the following subsections.
Modifying the VM Configuration Directly¶
vmconfig-entry element is used to add entries directly into the
virtual machine’s configuration file. This is currently only supported for
vmdk format where the provided strings are directly pasted into 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 NG does not check the entries for correctness. KIWI NG only
The following example adds the two entries
numvcpus = "4" and
cpuid.coresPerSocket = "2" into the VM configuration file:
<preferences> <type image="oem" filesystem="ext4" format="vmdk"> <machine memory="512" guestOS="suse" HWversion="4"> <vmconfig-entry>numvcpus = "4"</vmconfig-entry> <vmconfig-entry>cpuid.coresPerSocket = "2"</vmconfig-entry> </machine> </type> </preferences>
Adding Network Interfaces to the VM¶
Network interfaces can be explicitly specified for the VM when required via
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
<preferences> <type image="oem" filesystem="ext4" format="vmdk"> <machine memory="4096" guestOS="suse" HWversion="4"> <vmnic driver="e1000" interface="0" mode="bridged"/> </machine> </type> </preferences>
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 NG 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¶
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
ova image formats.
The following example adds a disk with the ID 0 using an IDE controller:
<preferences> <type image="oem" filesystem="ext4" format="vmdk"> <machine memory="512" guestOS="suse" HWversion="4"> <vmdisk id="0" controller="ide"/> </machine> </type> </preferences>
vmdisk element can be further customized via the following optional
controller: The disk controller used for the VM guest (
vmdkformat only). Supported values are:
device: The disk device to appear in the guest (
diskmode: The disk mode (
vmdkformat only), possible values are:
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 (
ovaformat only). This attribute is currently unused.
id: The disk ID of the VM disk (
Adding CD/DVD Drives¶
KIWI NG 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
<preferences> <type image="oem" filesystem="ext4"> <machine memory="512" xen_loader="hvmloader"> <vmdvd id="0" controller="scsi"/> <vmdvd id="1" controller="ide"/> </machine> </type> </preferences>
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