Building Images for Supported Types

10.1 Build an ISO Hybrid Live Image #

how to build an ISO image
how to run it with QEMU

A Live ISO image is a system on a removable media, e.g CD/DVD or USB stick. Once built and deployed it boots off from this media without interfering with other system storage components making it a useful pocket system for testing and demo- and debugging-purposes.

To add a live ISO build to your appliance, create a type element with image set to iso in your config.xml as shown below:

<image schemaversion="7.4" name="Tumbleweed_appliance">
  <!-- snip -->
  <preferences>
    <type image="iso" primary="true" flags="overlay" hybridpersistent_filesystem="ext4" hybridpersistent="true"/>
    <!-- additional preferences -->
  </preferences>
  <!-- snip -->
</image>

The following attributes of the type element are relevant when building live ISO images:

flags: Specifies the live ISO technology and dracut module to use, can be set to overlay or to dmsquash.
If set to overlay, the kiwi-live dracut module will be used to support a live ISO system based on squashfs and overlayfs. If set to dmsquash, the dracut standard dmsquash-live module will be used to support a live ISO system based on squashfs and the device mapper. Note, both modules support a different set of live features. For details see Decision for a live ISO technology
hybridpersistent: Accepts true or false, if set to true then the resulting image will be created with a COW file to keep data persistent over a reboot
hybridpersistent_filesystem: The filesystem used for the COW file. Possible values are ext4 or xfs, with ext4 being the default.

With the appropriate settings present in config.xml KIWI NG can now build the image:

$ sudo kiwi-ng system build \
      --description kiwi/build-tests/x86/leap/test-image-live \
      --set-repo obs://openSUSE:Leap:15.3/standard \
      --target-dir /tmp/myimage

The resulting image is saved in the folder /tmp/myimage and can be tested with QEMU:

$ sudo qemu -cdrom \
      kiwi-test-image-live.x86_64-1.15.3.iso \
      -m 4096 -serial stdio

The image is now complete and ready to use. See Section 11.1, “Deploy ISO Image on an USB Stick” and Section 11.2, “Deploy ISO Image as File on a FAT32 Formated USB Stick” for further information concerning deployment.

10.1.1 Decision for a live ISO technology #

The decision for the overlay vs. dmsquash dracut module depends on the features one wants to use. From a design perspective the overlay module is conceived for live ISO deployments on disk devices which allows the creation of a write partition or cow file. The dmsquash module is conceived as a generic mapping technology using device-mapper snapshots. The following list describes important live ISO features and their support status compared to the overlay and dmsquash modules.

ISO scan: Usable in the same way with both dracut modules. This feature allows to boot the live ISO as a file from a grub loopback configured bootloader. The live-grub-stick tool is just one example that uses this feature. For details how to setup ISO scan with the overlay module see Section 11.2, “Deploy ISO Image as File on a FAT32 Formated USB Stick”
ISO in RAM completely: Usable with the dmsquash module through rd.live.ram. The overlay module does not support this mode but KIWI NG supports RAM only systems as OEM deployment into RAM from an install ISO media. For details how to setup RAM only deployments in KIWI NG see: Section 11.9, “Deploy and Run System in a RamDisk”
Overlay based on overlayfs: Usable with the overlay module. A squashfs compressed readonly root gets overlayed with a readwrite filesystem using the kernel overlayfs filesystem.
Overlay based on device mapper snapshots: Usable with the dmsquash module. A squashfs compressed readonly root gets overlayed with a readwrite filesystem using a device mapper snapshot. This method was the preferred one before overlayfs existed in the Linux kernel.
Media Checksum Verification: Boot the live iso only for ISO checksum verification. This is possible with both modules but the overlay module uses the checkmedia tool whereas the upstream dmsquash module uses checkisomd5. The activation of the verification process is done by passing the kernel option mediacheck for the overlay module and rd.live.check for the dmsquash module.
Live ISO through PXE boot: Boot the live image via the network. This is possible with both modules but uses different technologies. The overlay module supports network boot only in combination with the AoE (Ata Over Ethernet) protocol. For details see Section 11.16, “Booting a Live ISO Image from Network”. The dmsquash module supports network boot by fetching the ISO image into memory from root=live: using the livenet module.
Persistent Data: Keep new data persistent on a writable storage device. This can be done with both modules but in different ways. The overlay module activates persistency with the kernel boot parameter rd.live.overlay.persistent. If the persistent setup cannot be created the fallback to the non persistent mode applies automatically. The overlay module auto detects if it is used on a disk or ISO scan loop booted from a file. If booted as disk, persistency is setup on a new partition of that disk. If loop booted from file, persistency is setup on a new cow file. The cow file/partition setup can be influenced with the kernel boot parameters: rd.live.overlay.cowfs and rd.live.cowfile.mbsize. The dmsquash module configures persistency through the rd.live.overlay option exclusively and does not support the automatic creation of a write partition in disk mode.

10.2 Build a Virtual Disk Image #

define a simple disk image in the image description
build a simple disk image
run it with QEMU

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 image="oem" in config.xml that has the oem-resize feature 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 below:

<image schemaversion="7.4" 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: 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 NG will forward the settings from this attribute as a parameter to the -o option in the qemu-img call.

The bootloader, size and 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 Section 2.4, “Example Appliance Descriptions” and use one of them) build the image with KIWI NG:

$ sudo kiwi-ng system build \
     --description kiwi/build-tests/x86/leap/test-image-disk-simple \
     --set-repo obs://openSUSE:Leap:15.3/standard \
     --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:

$ sudo qemu \
    -drive file=kiwi-test-image-disk-simple.x86_64-1.15.3.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: Section 11.7, “Image Description for Vagrant”.

10.2.1 Setting up the Bootloader of the Image #

<preferences>
  <type>
     <bootloader name="grub2"/>
  </type>
</preferences>

The bootloader element defines which bootloader will be used in the image and offers several options for customizing its configuration.

For details, see: Section 8.1.4.14, “<preferences><type><bootloader>”

10.2.2 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:

<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 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.

10.2.3 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.

10.2.3.1 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 NG does not check the entries for correctness. KIWI NG only forwards them.

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>

10.2.3.2 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:

<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>

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 NG will not verify the values that are passed to these attributes, it will only paste them into the appropriate configuration files.

10.2.3.3 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:

<preferences>
  <type image="oem" filesystem="ext4" format="vmdk">
    <machine memory="512" guestOS="suse" HWversion="4">
      <vmdisk id="0" controller="ide"/>
    </machine>
  </type>
</preferences>

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).

10.2.3.4 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 IDE controller:

<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>

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.

10.3 Build an Expandable Disk Image #

build an expandable disk image
deploy an expandable disk image
run the deployed system

An expandable disk represents the system disk with the capability to auto expand the disk and its filesystem to a custom disk geometry. This allows deploying the same disk image on target systems with different hardware setup.

The following example shows how to build and deploy such a disk image based on openSUSE Leap using a QEMU virtual machine as the target system:

Make sure you have checked out the example image descriptions, see Section 2.4, “Example Appliance Descriptions”.
Build the image with KIWI NG:
```
$ sudo kiwi-ng --type oem system build \
    --description kiwi/build-tests/x86/leap/test-image-disk \
    --set-repo obs://openSUSE:Leap:15.3/standard \
    --target-dir /tmp/myimage
```
Find the following result images below /tmp/myimage.
- The disk image with the suffix .raw is an expandable virtual disk. It can expand itself to a custom disk geometry.
- The installation image with the suffix install.iso is a hybrid installation system which contains the disk image and is capable to install this image on any target disk.

10.3.1 Deployment Methods #

The basic idea behind an expandable disk image is to provide the virtual disk data for OEM vendors to support easy deployment of the system to physical storage media.

There are the following basic deployment strategies:

Manual Deployment
Manually deploy the disk image onto the target disk.
CD/DVD Deployment
Boot the installation image and let KIWI NG’s installer deploy the disk image from CD/DVD or USB stick onto the target disk.
Network Deployment
PXE boot the target system and let KIWI NG’s installer deploy the disk image from the network onto the target disk.

10.3.2 Manual Deployment #

The manual deployment method can be tested using virtualization software such as QEMU, and an additional virtual target disk of a larger size. The following steps shows how to do it:

Create a target disk
```
$ qemu-img create target_disk 20g
```
Note
Retaining the Disk Geometry
If the target disk geometry is less or equal to the geometry of the disk image itself, the disk expansion performed for a physical disk install during the boot workflow will be skipped and the original disk geometry stays untouched.

Dump disk image on target disk.

$ dd if=kiwi-test-image-disk.x86_64-1.15.3.raw of=target_disk conv=notrunc

Boot the target disk
```
$ sudo qemu -hda target_disk -m 4096 -serial stdio
```
At first boot of the target_disk the system is expanded to the configured storage layout. By default the system root partition and filesystem is resized to the maximum free space available.

10.3.3 CD/DVD Deployment #

The deployment from CD/DVD via the installation image can also be tested using virtualization software such as QEMU. The following steps shows how to do it:

Create a target disk
Follow the steps above to create a virtual target disk
Boot the installation image as CD/DVD with the target disk attached.
```
$ sudo qemu -cdrom \
      kiwi-test-image-disk.x86_64-1.15.3.install.iso -hda target_disk \
      -boot d -m 4096 -serial stdio
```
Note
USB Stick Deployment
Like any other ISO image built with KIWI NG, also the installation image is a hybrid image. Thus it can also be used on USB stick and serve as installation stick image like it is explained in Section 10.1, “Build an ISO Hybrid Live Image”

10.3.4 Network Deployment #

The deployment from the network downloads the disk image from a PXE boot server. This requires a PXE network boot server to be setup as explained in Section 11.13, “Setting Up a Network Boot Server”

If the PXE server is running the following steps shows how to test the deployment process over the network using a QEMU virtual machine as target system:

Make sure to create an installation PXE TAR archive along with your disk image by replacing the following setup in kiwi/build-tests/x86/leap/test-image-disk/appliance.kiwi
Instead of
```
<type image="oem" installiso="true"/>
```
setup
```
<type image="oem" installpxe="true"/>
```

Rebuild the image, unpack the resulting kiwi-test-image-disk.x86_64-1.15.3.install.tar.xz file to a temporary directory and copy the initrd and kernel images to the PXE server:

Unpack installation tarball

mkdir /tmp/pxe && cd /tmp/pxe
tar -xf kiwi-test-image-disk.x86_64-1.15.3.install.tar.xz

Copy kernel and initrd used for pxe boot

scp pxeboot.kiwi-test-image-disk.x86_64-1.15.3.initrd PXE_SERVER_IP:/srv/tftpboot/boot/initrd
scp pxeboot.kiwi-test-image-disk.x86_64-1.15.3.kernel PXE_SERVER_IP:/srv/tftpboot/boot/linux

Copy the disk image, MD5 file, system kernel, initrd and bootoptions to the PXE boot server:
Activation of the deployed system is done via kexec of the kernel and initrd provided here.
1. Copy system image and MD5 checksum
  scp kiwi-test-image-disk.x86_64-1.15.3.xz PXE_SERVER_IP:/srv/tftpboot/image/ scp kiwi-test-image-disk.x86_64-1.15.3.md5 PXE_SERVER_IP:/srv/tftpboot/image/
2. Copy kernel, initrd and bootoptions used for booting the system via kexec
  scp kiwi-test-image-disk.x86_64-1.15.3.initrd PXE_SERVER_IP:/srv/tftpboot/image/ scp kiwi-test-image-disk.x86_64-1.15.3.kernel PXE_SERVER_IP:/srv/tftpboot/image/ scp kiwi-test-image-disk.x86_64-1.15.3.config.bootoptions PXE_SERVER_IP:/srv/tftpboot/image/
  Note
  The config.bootoptions file is used together with kexec to boot the previously dumped image. The information in that file references the root of the dumped image and can also include any other type of boot options. The file provided with the KIWI NG built image is by default connected to the image present in the PXE TAR archive. If other images got deployed the contents of this file must be adapted to match the correct root reference.
Add/Update the kernel command line parameters
Edit your PXE configuration (for example pxelinux.cfg/default) on the PXE server and add these parameters to the append line, typically looking like this:
```
append initrd=boot/initrd rd.kiwi.install.pxe rd.kiwi.install.image=tftp://192.168.100.16/image/kiwi-test-image-disk.x86_64-1.15.3.xz
```
The location of the image is specified as a source URI which can point to any location supported by the curl command. KIWI NG calls curl to fetch the data from this URI. This also means your image, MD5 file, system kernel and initrd could be fetched from any server and doesn’t have to be stored on the PXE_SERVER.
By default KIWI NG does not use specific curl options or flags. However it is possible to add custom ones by adding the rd.kiwi.install.pxe.curl_options flag into the kernel command line. curl options are passed as comma separated values. Consider the following example:
```
rd.kiwi.install.pxe.curl_options=--retry,3,--retry-delay,3,--speed-limit,2048
```
The above tells KIWI NG to call curl with:
```
curl --retry 3 --retry-delay 3 --speed-limit 2048 -f <url>
```
This is specially handy when the deployment infraestructure requires some fine tuned download behavior. For example, setting retries to be more robust over flaky network connections.
Note
KIWI NG just replaces commas with spaces and appends it to the curl call. This is relevant since command line options including commas will always fail.
Note
The initrd and Linux Kernel for pxe boot are always loaded via tftp from the PXE_SERVER.

Create a target disk
Follow the steps above to create a virtual target disk
Connect the client to the network and boot QEMU with the target disk attached to the virtual machine.
```
$ sudo qemu -boot n -hda target_disk -m 4096
```
Note
QEMU bridged networking
In order to let qemu connect to the network we recommend to setup a network bridge on the host system and let qemu connect to it via a custom /etc/qemu-ifup. For details see https://en.wikibooks.org/wiki/QEMU/Networking

10.3.5 OEM Customization #

The deployment process of an oem image can be customized through the oemconfig element which is a child section of the type element like the following example shows:

<oemconfig>
  <oem-swapsize>512</oem-swapsize>
</oemconfig>

The following list of optional oem element settings exists:

oemconfig.oem-resize Element: Specify if the disk has the capability to expand itself to a new disk geometry or not. By default, this feature is activated. The implementation of the resize capability is done in a dracut module packaged as dracut-kiwi-oem-repart. If oem-resize is set to false, the installation of the corresponding dracut package can be skipped as well.
oemconfig.oem-boot-title Element: By default, the string OEM will be used as the boot manager menu entry when KIWI creates the GRUB configuration during deployment. The oem-boot-title element allows you to set a custom name for the grub menu entry. This value is represented by the kiwi_oemtitle variable in the initrd
oemconfig.oem-bootwait Element: Specify if the system should wait for user interaction prior to continuing the boot process after the disk image has been dumped to the designated storage device (default value is false). This value is represented by the kiwi_oembootwait variable in the initrd
oemconfig.oem-reboot Element: Specify if the system is to be rebooted after the disk image has been deployed to the designated storage device (default value is false). This value is represented by the kiwi_oemreboot variable in the initrd
oemconfig.oem-reboot-interactive Element: Specify if the system is to be rebooted after the disk image has been deployed to the designated storage device (default value is false). Prior to reboot a message is posted and must be acknowledged by the user in order for the system to reboot. This value is represented by the kiwi_oemrebootinteractive variable in the initrd
oemconfig.oem-silent-boot Element: Specify if the system should boot in silent mode after the disk image has been deployed to the designated storage device (default value is false). This value is represented by the kiwi_oemsilentboot variable in the initrd
oemconfig.oem-shutdown Element: Specify if the system is to be powered down after the disk image has been deployed to the designated storage device (default value is false). This value is represented by the kiwi_oemshutdown variable in the initrd
oemconfig.oem-shutdown-interactive Element: Specify if the system is to be powered down after the disk image has been deployed to the designated storage device (default value is false). Prior to shutdown a message is posted and must be acknowledged by the user in order for the system to power off. This value is represented by the kiwi_oemshutdowninteractive variable in the initrd
oemconfig.oem-swap Element: Specify if a swap partition should be created. By default no swap partition will be created. This value is represented by the kiwi_oemswap variable in the initrd
oemconfig.oem-swapname Element: Specify the name of the swap space. By default the name is set to LVSwap. The default already indicates that this setting is only useful in combination with the LVM volume manager. In this case the swapspace is setup as a volume in the volume group and any volume needs a name. The name set here is used to give the swap volume a name.
oemconfig.oem-swapsize Element: Set the size of the swap partition. If a swap partition is to be created and the size of the swap partition is not specified with this optional element, KIWI will calculate the size of the swap partition and create a swap partition equal to two times the RAM installed on the system at initial boot time. This value is represented by the kiwi_oemswapMB variable in the initrd
oemconfig.oem-systemsize Element: Set the size the operating system is allowed to consume on the target disk. The size limit does not include any consideration for swap space or a recovery partition. In a setup without a systemdisk element this value specifies the size of the root partition. In a setup including a systemdisk element this value specifies the size of the LVM partition which contains all specified volumes. Thus, the sum of all specified volume sizes plus the sum of the specified freespace for each volume must be smaller or equal to the size specified with the oem-systemsize element. This value is represented by the variable kiwi_oemrootMB in the initrd
oemconfig.oem-unattended Element: The installation of the image to the target system occurs automatically without requiring user interaction. If multiple possible target devices are discovered the image is deployed to the first device. kiwi_oemunattended in the initrd
oemconfig.oem-skip-verify Element: Do not perform the checksum verification process after install of the image to the target disk. The verification process computes the checksum of the image byte size installed to the target and compares this value with the initrd embedded checksum information at build time of the image. Depending on the size of the image and machine power the computation can take some time.

10.3.6 Installation Media Customization #

The installation media created for OEM network or CD/DVD deployments can be customized with the installmedia section which is a child section of the type element as it appears in the following example:

<installmedia>
  <initrd action="omit">
    <dracut module="network-legacy"/>
  </initrd>
</installmedia>

The installmedia is only available for OEM image types that includes the request to create an installation media.

The initrd child element of installmedia lists dracut modules, they can be omitted, added or staticaly set the list of included ones. This is specified with the action attribute and can take action="omit", action="add" or action="set" values.

10.4 Build a Container Image #

basic configuration explanation
how to build a Container Image
how to run it with a Container Runtime

KIWI NG is capable of building native Container Images from scratch and derived ones. KIWI NG Container images are considered to be native since the KIWI NG tarball image is ready to be loaded into a Container Runtime like Podman, Docker or Containerd, including common container configurations.

The Container configuration metadata is provided to KIWI NG as part of the Section 1.1.1, “Components of an Image Description” using the <containerconfig> tag. The following configuration metadata can be specified:

containerconfig attributes:

name: Specifies the repository name of the Container Image.
tag: Sets the tag of the Container Image.
maintainer: Specifies the author field of the container, this is equivalent to the MAINTAINER directive in a Dockerfile.
user: Sets the user name or user id (UID) to be used when running entrypoint and subcommand. Equivalent of the USER directive of a Dockerfile.
workingdir: Sets the working directory to be used when running cmd and entrypoint. Equivalent of the WORKDIR directive in a Dockerfile.

containerconfig child tags:

subcommand: Provides the default execution parameters of the container. Equivalent of the CMD directive in a Dockerfile.
labels: Adds custom metadata to an image using key-value pairs. Equivalent to one or more LABEL directives in a Dockerfile.
expose: Define which ports can be exposed to the outside when running this container image. Equivalent to one or more EXPOSE directives in a Dockerfile.
environment: Sets environment variables using key-value pairs. Equivalent to one or multiple ENV directives in a Dockerfile.
entrypoint: Sets the binary via which all commands inside the container will be executed. Equivalent of the ENTRYPOINT directive in a Dockerfile.
volumes: Create mountpoints with the given name and mark them to hold external volumes from the host or from other containers. Equivalent to one or more VOLUME directives in a Dockerfile.

Other Dockerfile directives such as RUN, COPY or ADD, can be mapped to KIWI NG using the Section 1.1.1, “Components of an Image Description” script file to run bash commands or the Section 1.1.1, “Components of an Image Description” to include additional files.

The following example illustrates how to build a Container Image based on openSUSE Leap:

Make sure you have checked out the example image descriptions, see Section 2.4, “Example Appliance Descriptions”.
Include the Virtualization/containers repository to your list:
```
$ zypper addrepo http://download.opensuse.org/repositories/Virtualization:/containers/<DIST> container-tools
```
where the placeholder <DIST> is the preferred distribution.
Install umoci and skopeo tools
```
$ zypper in umoci skopeo
```

Build the image with KIWI NG:

$ sudo kiwi-ng system build \
    --description kiwi/build-tests/x86/leap/test-image-docker \
    --set-repo obs://openSUSE:Leap:15.3/standard \
    --target-dir /tmp/myimage

Test the Container image.

First load the new image into your Container Runtime:

$ podman load -i kiwi-test-image-docker.x86_64-1.15.3.docker.tar.xz

and then run the image:

$ podman run --rm -it buildsystem /bin/bash

10.5 Build a WSL Container Image #

KIWI NG is capable of building WSL images using the appx utility. Make sure you have installed a package that provides this command on your build host.

Once the build host has the appx installed, the following image type setup is required in the XML description config.xml:

<type image="appx" metadata_path="/meta/data"/>

The /meta/data path specifies a path that provides additional information required for the WSL-DistroLauncher. This component consists out of a Windows(exe) executable file and an AppxManifest.xml file which references other files like icons and resource configurations for the startup of the container under Windows.

Note

/meta/data

Except for the root filesystem tarball KIWI NG is not responsible for providing the meta data required for the WSL-DistroLauncher. It is expected that the given metadata path contains all the needed information. Typically this information is delivered in a package provided by the Distribution and installed on the build host

10.5.1 Setup of the WSL-DistroLauncher #

The contents of the AppxManifest.xml will be changed by KIWI NG if a containerconfig section is provided in the XML description. In the context of a WSL image the following container configuration parameters are taken into account:

<containerconfig name="my-wsl-container">
    <history
        created_by="Organisation"
        author="Name"
        application_id="AppIdentification"
        package_version="https://docs.microsoft.com/en-us/windows/uwp/publish/package-version-numbering"
        launcher="WSL-DistroLauncher-exe-file"
    >Container Description Text</history>
</containerconfig>

All information provided here including the entire section is optional. If not provided the existing AppxManifest.xml stays untouched.

created_by: Provides the name of a publisher organisation. An appx container needs to be signed off with a digital signature. If the image is build in the Open Build Service (OBS) this happens automatically. Outside of OBS one needs to make sure the given publisher organisation name matches the certificate used for signing.
author: Provides the name of the author and maintainer of this container
application_id: Provides an ID name for the container. The name must start with a letter and only allows alphanumeric characters. KIWI NG will not validate the given name string because there is no common criteria between the container architectures. KIWI NG just accepts any text.
package_version: Provides the version identification for the container. KIWI NG validates this against the Microsoft Package Version Numbering rules.
launcher: Provides the binary file name of the launcher .exe file.

Warning

There is no validation by KIWI NG if the contents of AppxManifest.xml are valid or complete to run the container. Users will find out at call time, not before

The following example shows how to build a WSL image based on openSUSE TW:

Make sure you have checked out the example image descriptions, see Section 2.4, “Example Appliance Descriptions”.
Include the Virtualization/WSL repository to your list:
```
$ zypper addrepo http://download.opensuse.org/repositories/Virtualization:/WSL/<DIST> WSL
```
where the placeholder <DIST> is the preferred distribution.
Install fb-util-for-appx utility and a package that provides the WSL-DistroLauncher metadata. See the above note about /meta/data
```
$ zypper in fb-util-for-appx DISTRO_APPX_METADATA_PACKAGE
```
Note
If you are building in the Open Build Service make sure to add the packages from the zypper call above to your project config via osc meta -e prjconf and a line of the form support: PACKAGE_NAME for each package that needs to be installed on the Open Build Service worker that runs the KIWI NG build process.
Setup the image type:
Edit the XML description file: kiwi/build-tests/x86/tumbleweed/test-image-wsl/appliance.kiwi and add the following type and containerconfig:
```
<type image="appx" metadata_path="/meta/data">
    <containerconfig name="Tumbleweed">
        <history
            created_by="SUSE"
            author="KIWI-Team"
            application_id="tumbleweed"
            package_version="2003.12.0.0"
            launcher="openSUSE-Tumbleweed.exe"
        >Tumbleweed Appliance text based</history>
    </containerconfig>
</type>
```
Warning
If the configured metadata path does not exist the build will fail. Furthermore there is no validation by KIWI NG that the contents of the metadata path are valid or complete with respect to the requirements of the WSL-DistroLauncher

Build the image with KIWI NG:

$ sudo kiwi-ng system build \
    --description kiwi/build-tests/x86/tumbleweed/test-image-wsl \
    --set-repo http://download.opensuse.org/tumbleweed/repo/oss \
    --target-dir /tmp/myimage

10.5.2 Testing the WSL image #

For testing the image a Windows 10 system is required. As a first step the optional feature named Microsoft-Windows-Subsystem-Linux must be enabled. For further details on how to setup the Windows machine see the following documentation: Windows Subsystem for Linux

10.6 Build KIS Image (Kernel, Initrd, System) #

A KIS image is a collection of image components that are not associated with a dedicated use case. This means from a KIWI NG perspective we don’t know in which environment these components are later used. The predecessor of this image type was called pxe under the assumption that the components will be used in a pxe boot environment. However this assumption is not neccessarily true and the image components are used in a different way. Because there are so many possible deployment strategies for a kernel plus initrd and optional system root filesystem, KIWI NG provides this as generic KIS type that is generically usable.

The former pxe image type will continue to exist but is expected to be used only in combination with the legacy netboot infrastructure as described in Section 11.14, “Build PXE Root File System Image for the legacy netboot infrastructure”.

To add a KIS build to your appliance, create a type element with image set to kis in your config.xml as shown below:

<preferences>
    <type image="kis"/>
</preferences>

With this image type setup KIWI NG will just build a kernel and initrd not associated to any system root file system. Usually such an image is only useful with some custom dracut extensions as part of the image description.

The following attributes of the type element are often used when building KIS images:

filesystem: Specifies the root filesystem and triggers the build of an additional filesystem image of that filesystem. The generated kernel command line options file (append file) will then also include a root= parameter that references this filesystem image UUID. If the information from the append file should be used or not is optional.
kernelcmdline: Specifies kernel command line options that will be part of the generated kernel command line options file (append file). By default the append file contains no information or the reference to the root UUID if the filesystem attribute is used.

All other attributes of the type element that applies to an optional root filesystem image will be effective in the system image of a KIS image as well.

With the appropriate settings present in config.xml KIWI NG can now build the image:

$ sudo kiwi-ng --type kis system build \
    --description kiwi/build-tests/x86/tumbleweed/test-image-pxe \
    --set-repo http://download.opensuse.org/tumbleweed/repo/oss \
    --target-dir /tmp/myimage

The resulting image components are saved in the folder /tmp/myimage. Outside of a deployment infrastructure the example KIS image can be tested with QEMU as follows:

$ sudo qemu
    -kernel /tmp/myimage/*.kernel \
    -initrd /tmp/myimage/*.initrd \
    -append $(cat /tmp/myimage/*.append) \
    -hda /tmp/myimage/kiwi-test-image-pxe.*-1.15.3 \
    -serial stdio

Note

For testing the components of a KIS image a deployment infrastructure and also a deployment process is usually needed. One example of a deployment infrastructure using PXE is provided by KIWI NG with the netboot infrastructure. However that netboot infrastructure is no longer developed and only kept for compatibiliy reasons. For details see Section 11.14, “Build PXE Root File System Image for the legacy netboot infrastructure”

Building Linux System Appliances with KIWI Next Generation (KIWI NG) 9.25.12

10 Building Images for Supported Types #

Note

10.1 Build an ISO Hybrid Live Image #

10.1.1 Decision for a live ISO technology #

10.2 Build a Virtual Disk Image #

10.2.1 Setting up the Bootloader of the Image #

10.2.2 Modifying the Size of the Image #

10.2.3 Customizing the Virtual Machine #

10.2.3.1 Modifying the VM Configuration Directly #

10.2.3.2 Adding Network Interfaces to the VM #

10.2.3.3 Specifying Disks and Disk Controllers #

10.2.3.4 Adding CD/DVD Drives #

10.3 Build an Expandable Disk Image #

10.3.1 Deployment Methods #

10.3.2 Manual Deployment #

Note

10.3.3 CD/DVD Deployment #

Note

10.3.4 Network Deployment #

Note

Note

Note

Note

10.3.5 OEM Customization #

10.3.6 Installation Media Customization #

10.4 Build a Container Image #

10.5 Build a WSL Container Image #

Note

10.5.1 Setup of the WSL-DistroLauncher #

Warning

Note

Warning

10.5.2 Testing the WSL image #

10.6 Build KIS Image (Kernel, Initrd, System) #

Note