| 1 |
.. _hybrid_iso: |
| 2 |
|
| 3 |
Build an ISO Hybrid Live Image |
| 4 |
============================== |
| 5 |
|
| 6 |
.. sidebar:: Abstract |
| 7 |
|
| 8 |
This page explains how to build a live image. It covers the following topics: |
| 9 |
|
| 10 |
* how to build an ISO image |
| 11 |
* how to run the image with QEMU |
| 12 |
|
| 13 |
A Live ISO image is a system on removable media, for example, a CD/DVD or a USB |
| 14 |
stick. Booting a Live ISO image does not interfere |
| 15 |
with other system storage components, making it a useful portable system for |
| 16 |
demonstration, testing, and debugging. |
| 17 |
|
| 18 |
To add a Live ISO build to your appliance, create a `type` element with |
| 19 |
`image` set to `iso` in the :file:`config.xml` file, as shown below: |
| 20 |
|
| 21 |
.. code:: xml |
| 22 |
|
| 23 |
<image schemaversion="{schema_version}" name="Tumbleweed_appliance"> |
| 24 |
<!-- snip --> |
| 25 |
<preferences> |
| 26 |
<type image="iso" primary="true" flags="overlay" hybridpersistent_filesystem="ext4" hybridpersistent="true"/> |
| 27 |
<!-- additional preferences --> |
| 28 |
</preferences> |
| 29 |
<!-- snip --> |
| 30 |
</image> |
| 31 |
|
| 32 |
The following attributes of the `type` element are relevant when building |
| 33 |
Live ISO images: |
| 34 |
|
| 35 |
- `flags`: Specifies the dracut module to use. |
| 36 |
|
| 37 |
If set to `overlay`, the kiwi-live dracut module supplied by {kiwi} is used |
| 38 |
for booting. |
| 39 |
|
| 40 |
If set to `dmsquash`, the dracut-supplied `dmsquash-live` module is |
| 41 |
used for booting. |
| 42 |
|
| 43 |
Both modules support a different set of live features. |
| 44 |
For details, see :ref:`live_features`. |
| 45 |
|
| 46 |
- `filesystem`: Specifies the root filesystem for the live system. |
| 47 |
|
| 48 |
If set to `squashfs`, the root filesystem is written into a squashfs image. |
| 49 |
This option is not compatible with device-mapper-specific features of the |
| 50 |
`dmsquash-live` dracut module. In that case, use `overlayfs`. |
| 51 |
|
| 52 |
If set to a value different from `squashfs`, the root filesystem is written |
| 53 |
into a filesystem image of the specified type, and the filesystem image is |
| 54 |
written into a squashfs image for compression. |
| 55 |
|
| 56 |
The default value of this option is `ext4`. |
| 57 |
|
| 58 |
- `hybridpersistent`: Accepts `true` or `false`; if set to `true`, the |
| 59 |
resulting image is created with a COW file to keep data persistent |
| 60 |
over a reboot. |
| 61 |
|
| 62 |
- `hybridpersistent_filesystem`: The filesystem used for the COW |
| 63 |
file. Valid values are `ext4` or `xfs`, with `ext4` being the default. |
| 64 |
|
| 65 |
|
| 66 |
With the appropriate settings specified in :file:`config.xml`, you can build an |
| 67 |
image using {kiwi}: |
| 68 |
|
| 69 |
.. code:: bash |
| 70 |
|
| 71 |
$ sudo kiwi-ng system build \ |
| 72 |
--description kiwi/build-tests/{exc_description_live} \ |
| 73 |
--set-repo {exc_repo_leap} \ |
| 74 |
--target-dir /tmp/myimage |
| 75 |
|
| 76 |
The resulting image is saved in :file:`/tmp/myimage`, and the image can |
| 77 |
be tested with QEMU: |
| 78 |
|
| 79 |
.. code:: bash |
| 80 |
|
| 81 |
$ sudo qemu -cdrom \ |
| 82 |
{exc_image_base_name_live}.x86_64-{exc_image_version}.iso \ |
| 83 |
-m 4096 -serial stdio |
| 84 |
|
| 85 |
The image is now complete and ready to use. See :ref:`iso_to_usb_stick` and |
| 86 |
:ref:`iso_as_file_to_usb_stick` for further information concerning |
| 87 |
deployment. |
| 88 |
|
| 89 |
.. _live_features: |
| 90 |
|
| 91 |
`overlay` or `dmsquash` |
| 92 |
---------------------------------- |
| 93 |
|
| 94 |
Whether you choose the `overlay` or `dmsquash` dracut module depends on the |
| 95 |
features you intend to use. The `overlay` module supports only `overlayfs`-based |
| 96 |
overlays but with automatic creation of a writable layer for |
| 97 |
persistence. The `dmsquash` module supports `overlayfs` as well as |
| 98 |
device-mapper-based overlays. |
| 99 |
|
| 100 |
The following list describes important Live ISO features and their support |
| 101 |
status in the `overlay` and `dmsquash` modules. |
| 102 |
|
| 103 |
ISO scan |
| 104 |
Usable in the same way with both dracut modules. This feature allows |
| 105 |
you to boot the Live ISO as a file from a grub loopback-configured bootloader. |
| 106 |
The `live-grub-stick` tool is one example that uses this feature. |
| 107 |
For details on how to set up ISO scan with the `overlay` module, see |
| 108 |
:ref:`iso_as_file_to_usb_stick`. |
| 109 |
|
| 110 |
ISO in RAM completely |
| 111 |
Usable with the `dmsquash` module through `rd.live.ram`. The `overlay` |
| 112 |
module does not support this mode, while {kiwi} supports RAM-only systems |
| 113 |
as OEM deployment into RAM from an install ISO media. For details on |
| 114 |
how to set up RAM-only deployments in {kiwi}, see :ref:`ramdisk_deployment`. |
| 115 |
|
| 116 |
Overlay based on overlayfs |
| 117 |
Usable with both dracut modules. The read-only root filesystem is |
| 118 |
overlaid with a read-write filesystem using the kernel's `overlayfs` |
| 119 |
filesystem. |
| 120 |
|
| 121 |
Overlay based on device-mapper snapshots |
| 122 |
Usable with the `dmsquash` module. A squashfs-compressed read-only root |
| 123 |
is overlaid with a read-write filesystem using a device-mapper |
| 124 |
snapshot. |
| 125 |
|
| 126 |
Media Checksum Verification |
| 127 |
Boot the Live ISO only for ISO checksum verification. This is possible with |
| 128 |
both modules, but the `overlay` module uses the `checkmedia` tool, whereas the |
| 129 |
upstream `dmsquash` module uses `checkisomd5`. The verification process is |
| 130 |
triggered by passing the kernel option `mediacheck` for the `overlay` module |
| 131 |
and `rd.live.check` for the `dmsquash` module. |
| 132 |
|
| 133 |
Live ISO through PXE boot |
| 134 |
Boot the Live image via the network. This is possible with both |
| 135 |
modules, but it uses different technologies. The `overlay` module supports |
| 136 |
network boot only in combination with the AoE (Ata Over Ethernet) protocol. |
| 137 |
For details, see :ref:`network_live_boot`. The `dmsquash` module supports |
| 138 |
network boot by fetching the ISO image into memory from `root=live:<url>` |
| 139 |
using the `livenet` module. |
| 140 |
|
| 141 |
Persistent Data |
| 142 |
Keep new data persistent on a writable storage device. This can be done |
| 143 |
with both modules but in different ways. The `overlay` module activates |
| 144 |
persistency with the kernel boot parameter `rd.live.overlay.persistent`. |
| 145 |
If the persistent setup cannot be created, the fallback to the non-persistent |
| 146 |
mode applies automatically. The `overlay` module autodetects if it is |
| 147 |
used on a disk or ISO scan loop booted from a file. If booted as a disk, |
| 148 |
persistency is set up on a new partition of that disk. If loop-booted |
| 149 |
from a file, persistency is set up on a new COW file. The COW file/partition |
| 150 |
setup can be influenced by the kernel boot parameters: |
| 151 |
`rd.live.overlay.cowfs` and `rd.live.cowfile.mbsize`. The `dmsquash` |
| 152 |
module configures persistency through the `rd.live.overlay` option |
| 153 |
exclusively and does not support the automatic creation of a write |
| 154 |
partition in disk mode. |
| 155 |
|
| 156 |
.. admonition:: dmsquash documentation |
| 157 |
|
| 158 |
Documentation for the upstream `dmsquash` module can be found |
| 159 |
`here <http://man7.org/linux/man-pages/man7/dracut.cmdline.7.html>`_. |
| 160 |
Options to set up `dmsquash` are marked with `rd.live`. |