Build an ISO Hybrid Live Image

Abstract

This page explains how to build a live image. It covers the following topics:

• how to build an ISO image

• how to run the image with QEMU

A Live ISO image is a system on a removable media, for example a CD/DVD or a USB stick. Booting a Live ISO image does not interfere with other system storage components, making it a useful portable system for demonstration, testing, and debugging.

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

<image schemaversion="8.0" 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 dracut module to use.

  If set to overlay, the kiwi-live dracut module supplied by KIWI NG is used for booting.

  If set to dmsquash, the dracut-supplied dmsquash-live module is used for booting.

  Both modules support a different set of live features. For details see overlay or dmsquash

• filesystem: Specifies the root filesystem for the live system.

  If set to squashfs, the root filesystem is written into a squashfs image. This option is not compatible with device-mapper specific features of the dmsquash-live dracut module. In that case, use overayfs.

  If set to a value different from squashfs, the root filesystem is written into a filesystem image of the specified type, and the filesystem image written into a squashfs image for compression.

  The default value of this option is ext4.

• hybridpersistent: Accepts true or false, if set to true, the resulting image is created with a COW file to keep data persistent over a reboot.

• hybridpersistent_filesystem: The filesystem used for the COW file. Valid values are ext4 or xfs, with ext4 being the default.

With the appropriate settings specified in config.xml, you can build an image using KIWI NG:

$ sudo kiwi-ng system build \
      --description kiwi/build-tests/x86/leap/test-image-live \
      --set-repo https://download.opensuse.org/distribution/leap/15.6/repo/oss \
      --target-dir /tmp/myimage

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

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

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

overlay or dmsquash

Whether you choose the overlay or dmsquash dracut module depends on the features you intend to use. The overlay module supports only overlayfs based overlays, but with automatic creation of a writable layer for persistence. The dmsquash module supports overlayfs as well as device-mapper based overlays.

The following list describes important Live ISO features and their support status in 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 one example that uses this feature. For details how to setup ISO scan with the overlay module see 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, while 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: Deploy and Run System in a RamDisk

Overlay based on overlayfs

Usable with both dracut modules. The readonly root filesystem is overlaid 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 is overlaid with a readwrite filesystem using a device mapper snapshot.

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 verification process is triggered 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 it uses different technologies. The overlay module supports network boot only in combination with the AoE (Ata Over Ethernet) protocol. For details see 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.

dmsquash documentation

Documentation for the upstream dmsquash module can be found here. Options to setup dmsquash are marked with rd.live