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