Debian Codegraph @

doc/source/building_images/build_expandable_disk.rst

raw
1 .. _expandable_disk:
2
3 Build an Expandable Disk Image
4 ==============================
5
6 .. sidebar:: Abstract
7
8 This page explains how to build an expandable disk image.
9 It covers the following topics:
10
11 * builds an expandable disk image
12 * deploys an expandable disk image
13 * runs the deployed system
14
15 An expandable disk represents the system disk with the capability to automatically
16 expand the disk and its filesystem to a custom disk geometry. This
17 allows deploying the same disk image on target systems with different
18 hardware setups.
19
20 The following example shows how to build and deploy an expandable disk image
21 based on openSUSE Leap using a QEMU virtual machine as a target
22 system:
23
24 1. Make sure you have checked out the example image descriptions (see :ref:`example-descriptions`).
25
26 2. Build an image with {kiwi}:
27
28 .. code:: bash
29
30 $ sudo kiwi-ng --type oem system build \
31 --description kiwi/build-tests/{exc_description_disk} \
32 --set-repo {exc_repo_leap} \
33 --target-dir /tmp/myimage
34
35 The resulting image is saved in :file:`/tmp/myimage`.
36
37 * The disk image with the suffix :file:`.raw` is an expandable
38 virtual disk. It can expand itself to a custom disk geometry.
39
40 * The installation image with the suffix :file:`install.iso` is a
41 hybrid installation system that contains the disk image and is
42 capable of installing this image on any target disk.
43
44 .. _deployment_methods:
45
46 Deployment Methods
47 ------------------
48
49 The goal of an expandable disk image is to provide the virtual
50 disk data for OEM vendors to support easy deployment of the system to
51 physical storage media.
52
53 Basic deployment strategies are as follows:
54
55 1. :ref:`deploy_manually`
56
57 Manually deploy the disk image onto the target disk.
58
59 2. :ref:`deploy_from_iso`
60
61 Boot the installation image and let {kiwi}'s installer
62 deploy the disk image from a CD/DVD or USB stick onto the target disk.
63
64 3. :ref:`deploy_from_network`
65
66 PXE boot the target system and let {kiwi}'s installer
67 deploy the disk image from the network onto the target disk.
68
69 .. _deploy_manually:
70
71 Manual Deployment
72 -----------------
73
74 The manual deployment method can be tested using virtualization software
75 like QEMU and an additional virtual large-size target disk.
76 To do this, follow the steps below.
77
78 1. Create a target disk:
79
80 .. code:: bash
81
82 $ qemu-img create target_disk 20g
83
84 .. note:: Retaining the Disk Geometry
85
86 If the target disk geometry is less than or equal to the geometry of
87 the disk image itself, the disk expansion that is performed on a physical
88 disk install during the boot workflow is skipped, and the
89 original disk geometry stays unchanged.
90
91 2. Dump the disk image on the target disk:
92
93 .. code:: bash
94
95 $ dd if={exc_image_base_name_disk}.x86_64-{exc_image_version}.raw of=target_disk conv=notrunc
96
97 3. Boot the target disk:
98
99 .. code:: bash
100
101 $ sudo qemu -hda target_disk -m 4096 -serial stdio
102
103
104 On the first boot of the `target_disk`, the system is expanded to the
105 configured storage layout. By default, the system root partition
106 and filesystem are resized to the maximum free space available.
107
108 .. _deploy_from_iso:
109
110 CD/DVD Deployment
111 -----------------
112
113 The deployment from a CD/DVD via an installation image can
114 also be tested using virtualization software such as QEMU.
115 To do this, follow the steps below.
116
117 1. Create a target disk:
118
119 Follow the steps above to create a virtual target disk.
120
121 2. Boot the installation image as a CD/DVD with the
122 target disk attached.
123
124 .. code:: bash
125
126 $ sudo qemu -cdrom \
127 {exc_image_base_name_disk}.x86_64-{exc_image_version}.install.iso -hda target_disk \
128 -boot d -m 4096 -serial stdio
129
130 .. note:: USB Stick Deployment
131
132 Like any other ISO image built with {kiwi}, the installation
133 image is also a hybrid image. Thus, it can also be used on a USB stick and
134 serve as installation media, as explained in
135 :ref:`hybrid_iso`.
136
137 .. _deploy_from_network:
138
139 Network Deployment
140 ------------------
141
142 The process of deployment from the network downloads the disk image from a
143 PXE boot server. This requires a PXE network boot server to be set up
144 as described in :ref:`network-boot-server`.
145
146 If the PXE server is running, the following steps show how to test the
147 deployment process over the network using a QEMU virtual machine as
148 a target system:
149
150 1. Create an installation PXE TAR archive along with your
151 disk image by replacing the following configuration in
152 `kiwi/build-tests/{exc_description_disk}/appliance.kiwi`:
153
154 Find the line below:
155
156 .. code:: xml
157
158 <type image="oem" installiso="true"/>
159
160 Modify the line as follows:
161
162 .. code:: xml
163
164 <type image="oem" installpxe="true"/>
165
166
167 2. Rebuild the image, unpack the resulting
168 :file:`{exc_image_base_name_disk}.x86_64-{exc_image_version}.install.tar.xz`
169 file to a temporary directory, and copy the initrd and kernel images to
170 the PXE server.
171
172 a) Unpack the installation tarball:
173
174 .. code:: bash
175
176 mkdir /tmp/pxe && cd /tmp/pxe
177 tar -xf {exc_image_base_name_disk}.x86_64-{exc_image_version}.install.tar.xz
178
179 b) Copy the kernel and initrd used for PXE boot:
180
181 .. code:: bash
182
183 scp pxeboot.{exc_image_base_name_disk}.x86_64-{exc_image_version}.initrd PXE_SERVER_IP:/srv/tftpboot/boot/initrd
184 scp pxeboot.{exc_image_base_name_disk}.x86_64-{exc_image_version}.kernel PXE_SERVER_IP:/srv/tftpboot/boot/linux
185
186 3. Copy the disk image, SHA256 file, system kernel, initrd, and bootoptions to
187 the PXE boot server.
188
189 Activation of the deployed system is done via `kexec` of the kernel
190 and initrd provided here.
191
192 a) Copy the system image and SHA256 checksum:
193
194 .. code:: bash
195
196 scp {exc_image_base_name_disk}.x86_64-{exc_image_version}.xz PXE_SERVER_IP:/srv/tftpboot/image/
197 scp {exc_image_base_name_disk}.x86_64-{exc_image_version}.sha256 PXE_SERVER_IP:/srv/tftpboot/image/
198
199 b) Copy the kernel, initrd, and bootoptions used for booting the system via kexec:
200
201 .. code:: bash
202
203 scp {exc_image_base_name_disk}.x86_64-{exc_image_version}.initrd PXE_SERVER_IP:/srv/tftpboot/image/
204 scp {exc_image_base_name_disk}.x86_64-{exc_image_version}.kernel PXE_SERVER_IP:/srv/tftpboot/image/
205 scp {exc_image_base_name_disk}.x86_64-{exc_image_version}.config.bootoptions PXE_SERVER_IP:/srv/tftpboot/image/
206
207 .. note::
208
209 The `config.bootoptions` file is used with `kexec` to boot the previously
210 dumped image. This file specifies the root of the dumped image, and the
211 file can include other boot options. The file provided with the {kiwi}-
212 built image is connected to the image present in the PXE TAR archive. If
213 other images are deployed, the file must be modified to match the
214 correct root reference.
215
216 .. note::
217
218 If the image is deployed into a ramdisk that is configured
219 by passing `rd.kiwi.ramdisk` as part of the append setup below,
220 it is not required to copy the above-mentioned kernel and initrd
221 file to boot the system because for ramdisk deployments, the
222 currently active kernel and initrd will be used, as kexec cannot
223 be called with a system in memory.
224
225 4. Add/Update the kernel command-line parameters.
226
227 Edit your PXE configuration (for example, :file:`pxelinux.cfg/default`) on
228 the PXE server and add the following parameters to the append line similar to that shown below:
229
230 .. code:: bash
231
232 append initrd=boot/initrd rd.kiwi.install.pxe rd.kiwi.install.image=tftp://192.168.100.16/image/{exc_image_base_name_disk}.x86_64-{exc_image_version}.xz
233
234 The location of the image is specified as a source URI that can point
235 to any location supported by the `curl` command. {kiwi} uses `curl` to fetch
236 the data from this URI. This means that the image, checksum file, system kernel,
237 and initrd can be fetched from any server and do not need to be stored
238 on the `PXE_SERVER`.
239
240 By default, {kiwi} does not use specific `curl` options or flags. But it is
241 possible to specify desired options by adding the
242 `rd.kiwi.install.pxe.curl_options` flag to the kernel command line (`curl`
243 options are passed as comma-separated values), for example:
244
245 .. code:: bash
246
247 rd.kiwi.install.pxe.curl_options=--retry,3,--retry-delay,3,--speed-limit,2048
248
249 The above instructs {kiwi} to run `curl` as follows:
250
251 .. code:: bash
252
253 curl --retry 3 --retry-delay 3 --speed-limit 2048 -f <url>
254
255 This can be particularly useful when the deployment infrastructure requires a
256 specific download configuration. For example, setting more robust retries
257 over an unstable network connection.
258
259 .. note::
260
261 {kiwi} replaces commas with spaces and appends the result to the `curl`
262 command. Keep that in mind, because command-line options that include
263 commas break the command.
264
265 .. note::
266
267 The initrd and Linux Kernel for PXE boot are always loaded via TFTP
268 from the `PXE_SERVER`.
269
270 4. Create a target disk.
271
272 Follow the steps above to create a virtual target disk.
273
274 5. Connect the client to the network and boot QEMU with the target disk
275 attached to the virtual machine:
276
277 .. code:: bash
278
279 $ sudo qemu -boot n -hda target_disk -m 4096
280
281 .. note:: QEMU bridged networking
282
283 To connect QEMU to the network, we recommend setting up
284 a network bridge on the host system and connecting QEMU
285 to it via a custom `/etc/qemu-ifup` configuration. For details, see
286 https://en.wikibooks.org/wiki/QEMU/Networking.
287
288 .. _oem_customize:
289
290 OEM Customization
291 -----------------
292
293 The deployment process of an OEM image can be customized using
294 the `oemconfig` element. This element is a child section of the `type`
295 element, for example:
296
297 .. code:: xml
298
299 <oemconfig>
300 <oem-swapsize>512</oem-swapsize>
301 </oemconfig>
302
303
304 Below is a list of optional `oem` element settings.
305
306 oemconfig.oem-resize
307 Determines if the disk has the capability to expand itself to
308 a new disk geometry or not. By default, this feature is activated.
309 The implementation of the resize capability is done in a dracut
310 module packaged as `dracut-kiwi-oem-repart`. If `oem-resize` is
311 set to `false`, the installation of the corresponding dracut package
312 can be skipped as well.
313
314 oemconfig.oem-boot-title
315 By default, the string `OEM` is used as the boot manager menu
316 entry when KIWI creates the GRUB configuration during deployment.
317 The `oem-boot-title` element allows you to set a custom name for the
318 grub menu entry. This value is represented by the
319 `kiwi_oemtitle` variable in the initrd.
320
321 oemconfig.oem-bootwait
322 Determines if the system waits for user interaction before
323 continuing the boot process after the disk image has been dumped to
324 the designated storage device (the default value is `false`). This value
325 is represented by the `kiwi_oembootwait` variable in the initrd.
326
327 oemconfig.oem-reboot
328 When enabled, the system is rebooted after the disk image has
329 been deployed to the designated storage device (the default value is
330 `false`). This value is represented by the `kiwi_oemreboot`
331 variable in the initrd.
332
333 oemconfig.oem-reboot-interactive
334 When enabled, the system is rebooted after the disk image has
335 been deployed to the designated storage device (the default value is
336 `false`). Before the reboot, a message is displayed, and it must be
337 acknowledged by the user for the system to reboot. This
338 value is represented by the `kiwi_oemrebootinteractive` variable
339 in the initrd.
340
341 oemconfig.oem-silent-boot
342 Determines if the system boots in silent mode after the disk
343 image has been deployed to the designated storage device (the default
344 value is `false`). This value is represented by the
345 `kiwi_oemsilentboot` variable in the initrd.
346
347 oemconfig.oem-shutdown
348 Determines if the system is powered down after the disk image
349 has been deployed to the designated storage device (the default value
350 is `false`). This value is represented by the `kiwi_oemshutdown`
351 variable in the initrd.
352
353 oemconfig.oem-shutdown-interactive
354 Determines if the system is powered down after the disk image
355 has been deployed to the designated storage device (the default value
356 is `false`). Before the shutdown, a message is displayed, and it must be
357 acknowledged by the user for the system to power off.
358 This value is represented by the `kiwi_oemshutdowninteractive`
359 variable in the initrd.
360
361 oemconfig.oem-swap
362 Determines if a swap partition is created. By default, no
363 swap partition is created. This value is represented
364 by the `kiwi_oemswap` variable in the initrd.
365
366 oemconfig.oem-swapname
367 Specifies the name of the swap space. By default, the name is set to
368 `LVSwap`. The default indicates that this setting is only useful in
369 combination with the LVM volume manager. In this case, the swapspace is
370 configured as a volume in the volume group, and every volume requires a name.
371 The name specified in `oemconfig.oem-swapname` here is used as the name of the
372 swap volume.
373
374 oemconfig.oem-swapsize
375 Specifies the size of the swap partition. If a swap partition is created while
376 the size of the swap partition is not specified, KIWI calculates the size of
377 the swap partition and creates a swap partition at initial boot time. In this
378 case, the swap partition size equals double the amount of RAM of the system.
379 This value is represented by the `kiwi_oemswapMB` variable in the initrd.
380
381 oemconfig.oem-systemsize
382 Specifies the MB size the operating system is allowed to occupy on the target
383 disk. The size limit does not include any swap space or recovery partition
384 considerations. In a setup *without* the `systemdisk` element, this value
385 specifies the size of the root partition. In a setup that *includes* the
386 `systemdisk` element when using LVM, this value specifies the size of the LVM
387 partition that contains all specified volumes. This means that the sum of all
388 specified volume sizes plus the sum of the specified freespace for each volume
389 must be smaller than or equal to the size specified with the `oem-systemsize`
390 element. This value is represented by the variable `kiwi_oemrootMB` in the
391 initrd. The specified value can be dynamically overwritten via the
392 `rd.kiwi.install.systemsize` kernel boot option. If `rd.kiwi.install.systemsize`
393 is set to `all`, this will unset the size limit, and the maximum possible
394 size will apply.
395
396 oemconfig.oem-unattended
397 The installation of the image to the target system occurs
398 automatically without requiring user interaction. If multiple
399 possible target devices are discovered, the image is deployed to
400 the first device. `kiwi_oemunattended` in the initrd.
401
402 oemconfig.oem-unattended-id
403 Selects a target disk device for the installation according to the
404 specified device ID. The device ID corresponds to the name of the device for
405 the configured `devicepersistency`. By default, it is the `by-uuid` device
406 name. If no representation exists, for example, for ramdisk devices, the UNIX
407 device node can be used to select one. The given name must be present in the
408 device list detected by KIWI.
409
410 oemconfig.oem-skip-verify
411 Disables the checksum verification process after installing the image on
412 the target disk. The verification process computes the checksum of the image
413 installed on the target. This value is then compared to the initrd-embedded
414 checksum generated at the build time of the image. Depending on the size of the
415 image and machine power, computing the checksum may take time.
416
417 .. _installmedia_customize:
418
419 Installation Media Customization
420 --------------------------------
421
422 The installation media created for OEM network or CD/DVD deployments can
423 be customized with the `installmedia` section. It is a child section of the `type`
424 element, for example:
425
426 .. code:: xml
427
428 <installmedia>
429 <initrd action="omit">
430 <dracut module="network-legacy"/>
431 </initrd>
432 </installmedia>
433
434 The `installmedia` is only available for OEM image types that include the
435 request to create an installation media.
436
437 The `initrd` child element of `installmedia` lists dracut modules. The element's
438 `action` attribute determines whether the dracut module is omitted
439 (`action="omit"`) or added (`action="add"`). Use `action="set"` to use only the
440 listed modules and nothing else (that is, none of the dracut modules included by
441 default).