Debian Codegraph @

doc/source/building_images/build_live_iso.rst

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