8 Image Description #

A simple tar archive image. The tbz type packs the contents of the image root tree into a xz compressed tarball.

A filesystem image. The image root tree data is packed into a filesystem image of the given type. An image of that type can be loop mounted and accessed according to the capabiities of the selected filesystem.

An iso image which can be dumped on a CD/DVD or USB stick and boots off from this media without interfering with other system storage components. A useful pocket system for testing and demo and debugging purposes.

An image representing an expandable system disk. This means after deployment the system can resize itself to the new disk geometry. The resize operation is configurable as part of the image description and an installation image for CD/DVD, USB stick and Network deployment can be created in addition. For use in cloud frameworks like Amazon EC2, Google Compute Engine or Microsoft Azure this disk type also supports the common virtual disk formats.

An archive image suitable for the docker container engine. The image can be loaded via the docker load command and works within the scope of the container engine

An archive image that builds a container matching the OCI (Open Container Interface) standard. The container should be able to run with any oci compliant container engine.

An archive image suitable for the Windows Subsystem For Linux container engine. The image can be loaded From a Windows System that has support for WSL activated.

An optional root filesystem image associated with a kernel and initrd. The use case for this component image type is highly customizable. Many different deployment strategies are possible.

Boolean parameter notifying KIWI NG whether an extra boot partition should be used or not (the default depends on the current layout). This will override KIWI NG’s default layout.

For images with a separate boot partition this attribute specifies the size in MB. If not set the boot partition size is set to 200 MB

For images with an EFI layout, specify if the legacy CSM (BIOS) mode should be supported or not. By default CSM mode is enabled.

For images with an EFI fat partition this attribute specifies the size in MB. If not set the EFI partition size is set to 20 MB

For ISO images (live and install) the EFI boot requires an embedded FAT image. This attribute specifies the size in MB. If not set the FAT image size is set to 20 MB

For images with an EFI firmware specifies the partition table type to use. If not set defaults to the GPT partition table type

For oem disk images, specifies to make use of logical partitions inside of an extended one. If set to true and if the msdos table type is active, this will cause the fourth partition to be an extended partition and all following partitions will be placed as logical partitions inside of that extended partition. This setting is useful if more than 4 primary partitions needs to be created in an msdos table

Boolean parameter to activate filesystem quotas if the filesystem is btrfs. By default quotas are inactive.

For oem disk images using the btrfs filesystem, requests to set a default volume for the rootfs which is used when the filesystem gets mounted. In case a true value is provided or the attribute is not specified at all, kiwi will make a volume the default volume. This can be either / or the configured root subvolume or the configured root snapshot. Consequently the entry created for the rootfs in the /etc/fstab file will not contain any specific volume definition. In case a false value is provided, kiwi will not set any default volume which also means that the entry for the rootfs in the /etc/fstab file requires a volume definition which is placed by kiwi as a subvol= parameter in the respective fstab field entry. In addition the parameter rootflags=subvol= is added to the kernel commandline such that early initrd code has a chance to know about the rootfs volume.

Tell kiwi to create a root volume to host (/) inside. The name of this subvolume is by default set to: @. The name of the subvolume can be changed via a volume entry of the form:

<systemdisk>
  <volume name="@root=TOPLEVEL_NAME"/>
</systemdisk>

By default the creation of a toplevel volume is set to: true

Boolean parameter that tells KIWI NG to install the system into a btrfs snapshot. The snapshot layout is compatible with snapper. By default snapshots are turned off.

Boolean parameter notifying KIWI NG that the btrfs root filesystem snapshot has to made read-only. if this option is set to true, the root filesystem snapshot it will be turned into read-only mode, once all data has been placed to it. The option is only effective if btrfs_root_is_snapshot is also set to true. By default the root filesystem snapshot is writable.

For use with the apt packagemanager only. Specifies the name of a bootstrap package which provides a bootstrap tarball in /var/lib/bootstrap/PACKAGE_NAME.ARCH.tar.xz. The tarball will be unpacked and used as the bootstrap rootfs to begin with. This allows for an alternative bootstrap method. For further details see Section 11.22, “Circumvent Debian Bootstrap”.

Specifies whether the image output file should be compressed or not. This option is only used for filesystem only images or for the pxe or cpio types.

Specifies the path to a script which is called right before the bootloader is installed. The script runs relative to the directory which contains the image structure.

Specifies the path to a script which is called right after the bootloader is installed. The script runs relative to the directory which contains the image structure.

The root filesystem

Specifies the boot firmware of the appliance. This attribute is used to differentiate the image according to the firmware which boots up the system. It mostly impacts the disk layout and the partition table type. By default bios is used on x86, ofw on PowerPC and efi on ARM.

Boolean parameter to force the usage of a MBR partition table even if the system would default to GPT. This is occasionally required on ARM systems that use a EFI partition layout but which must not be stored in a GPT. Note that forcing a MBR partition table incurs limitations with respect to the number of available partitions and their sizes.

Specifies the filesystem mount options which are passed via the -o flag to mount and are included in /etc/fstab.

Specifies the filesystem options used to create the filesystem. In KIWI NG the filesystem utility to create a filesystem is called without any custom options. The default options are filesystem specific and are provided along with the package that provides the filesystem utility. For the Linux ext[234] filesystem, the default options can be found in the /etc/mke2fs.conf file. Other filesystems provides this differently and documents information about options and their defaults in the respective manual page, e.g man mke2fs. With the fscreateoptions attribute it’s possible to directly influence how the filesystem will be created. The options provided as a string are passed to the command that creates the filesystem without any further validation by KIWI NG. For example, to turn off the journal on creation of an ext4 filesystem the following option would be required:

<preferences>
  <type fscreateoptions="-O ^has_journal"/>
</preferences>

Additional kernel parameters passed to the kernel by the bootloader.

For oem disk images, this attribute allows to create number clone(s) of the root partition, with number >= 1. A clone partition is content wise an exact byte for byte copy of the origin root partition. However, to avoid conflicts at boot time the UUID of any cloned partition will be made unique. In the sequence of partitions, the clone(s) will always be created first followed by the partition considered the origin. The origin partition is the one that will be referenced and used by the system. Also see Section 11.12, “Partition Clones”

Same as root_clone but applied to the boot partition if present

Supplying a value will trigger the encryption of the partition serving the root filesystem using the LUKS extension. The supplied value represents either the passphrase string or the location of a key file if specified as file://... resource or the reserved name random. When using a passphrase the system will interactively ask for that passphrase on first boot unless it is set empty. In case of an empty passphrase the system cannot be considered secure. When using a key file the information from the file is read and used as a passphrase. The given key file is not automatically placed into the system or added to the etc/crypttab which means the passphrase in the key file is by default requested from an interactive dialog at boot time. When using the reserved word random, kiwi will create a key file with a random passphrase and place this information into etc/crypttab. This allows the system to boot without user interaction but also requires the initrd to be protected in some way because it will contain the keyfile. The use of random is therefore only secure if the image adds additional security that encrypts the initrd like it is e.g. done in the IBM secure execution process. If the encryption of the system is combined with the attribute bootpartition="false" it’s important to understand that this will place /boot into the encrypted area of the system and leaves reading boot data from it as a responsibility to the bootloader. Not every bootloader can cope with that and those that can e.g. grub will then open an interactive dialog at the bootloader level asking for the credentials to decrypt the root filesystem.

Specify which LUKS version should be used. If not set and by default luks is used. The interpretation of the default depends on the distribution and could result in either ‘luks1’ or ‘luks2’. The specification of the LUKS version allows using a different set of luksformat options. To investigate the differences between the two please consult the cryptsetup manual page.

Specifies the image blocksize in bytes which has to match the logical blocksize of the target storage device. By default 512 Bytes is used, which works on many disks. You can obtain the blocksize from the SSZ column in the output of the following command:

blockdev --report $DEVICE

Indicate if the target disk for oem images is deployed to a removable device e.g a USB stick or not. This only affects the EFI setup if requested and in the end avoids the creation of a custom boot menu entry in the firmware of the target machine. By default the target disk is expected to be non-removable

The selinux_policy attribute sets the SELinux policy to use. targeted policy is the default policy. Only change this option if you want to use the mls or minimum policy.

Request a spare partition right before the root partition of the requested size. The attribute takes a size value and allows a unit in MB or GB, e.g 200M. If no unit is given the value is considered to be mbytes. A spare partition can only be configured for the disk image type oem

Specify mount point for spare partition in the system. Can only be configured for the disk image type oem

Specify filesystem for spare partition in the system. Can only be configured for the disk image type oem

Specify filesystem attributes for the spare partition. Attributes can be specified as comma separated list. Currently the attributes no-copy-on-write and synchronous-updates are available. Can only be configured for the disk image type oem

Specify if the spare partition should be the last one in the partition table. Can only be configured for the oem type with oem-resize switched off. By default the root partition is the last one and the spare partition lives before it. With this attribute that setup can be toggled. However, if the root partition is no longer the last one the oem repart/resize code can no longer work because the spare part would block it. Because of that moving the spare part at the end of the disk is only applied if oem-resize is switched off. There is a runtime check in the KIWI NG code to check this condition

Specifies which method to use for persistent device names. This will affect all files written by kiwi that includes device references for example etc/fstab or the root= parameter in the kernel commandline. By default by-uuid is used

Specifies the compression type for mksquashfs

Specifies the compression type and level for erofs. The attribute is a free form text because erofs allows paramters for the different compression types. Please consult the erofs man page for details how to specify a value for the -z option on mkfs.erofs and pass a proper value as erofscompression

For the oem type only, specifies to create a standalone dm_integrity layer on top of the root filesystem

For the oem type only and in combination with the standalone_integrity attribute, Allow to use old flawed HMAC calculation (does not protect superblock).

Warning

Do not use this attribute unless compatibility with a specific old kernel is required!

For the oem type only and in combination with the standalone_integrity attribute, protects access to the integrity map using the given keyfile.

For the oem type only and in combination with the embed_integrity_metadata attribute, specifies a custom description of an integrity key as it is expected to be present in the kernel keyring. The information is placed in the integrity metadata block. If not specified kiwi creates a key argument string instead which is based on the given integrity_keyfile filename. The format of this key argument is:

:BASENAME_OF_integrity_keyfile_WITHOUT_FILE_EXTENSION

For the oem type only, and in combination with the standalone_integrity attribute, specifies to write a binary block at the end of the partition serving the root filesystem, containing information to create the dm_integrity device map in the following format:

|header|0xFF|dm_integrity_meta|0xFF|0x0|

For the oem type only, specifies to create a dm verity hash from the number of given blocks (or all) placed at the end of the root filesystem For later verification of the device, the credentials information produced by veritysetup from the cryptsetup tools are needed. This data as of now is only printed as debugging information to the build log file. A concept to persistently store the verification metadata as part of the partition(s) will be a next step.

For the oem type only, and in combination with the verity_blocks attribute, specifies to write a binary block at the end of the partition serving the root filesystem, containing information for dm_verity verification in the following format:

|header|0xFF|dm_verity_credentials|0xFF|0x0|

For the oem type only, specifies to use an overlayfs based root filesystem consisting out of a squashfs compressed read-only root filesystem combined with an optional write-partition or tmpfs. The optional kernel boot parameter rd.root.overlay.temporary can be used to point the write area into a tmpfs instead of a persistent write-partition. In this mode all written data is temporary until reboot of the system. The kernel boot parameter rd.root.overlay.size can be used to configure the size for the tmpfs that is used for the overlayfs mount process if rd.root.overlay.temporary is requested. That size configures the amount of space available for writing new data during the runtime of the system. The default value is set to 50% which means one half of the available RAM space can be used for writing new data. By default the persistent write-partition is used. The size of that partition can be influenced via the optional <size> element in the <type> section or via the optional <oem-resize> element in the <oemconfig> section of the XML description. Setting a fixed <size> value will set the size of the image disk to that value and results in an image file of that size. The available space for the write partition is that size reduced by the size the squashfs read-only system needs. If the <oem-resize> element is set to true an eventually given <size> element will not have any effect because the write partition will be resized on first boot to the available disk space. To disable the use of any overlay the kernel boot parameter rd.root.overlay.readonly can be used. It takes precedence over all other overlay kernel parameters because it leads to the deactivation of any overlayfs based action and just boots up with the squashfs root filesystem. In fact this mode is the same as not installing the kiwi-overlay dracut module.

For the oem type only, allows to specify if the extra read-write partition in an overlayroot setup should be created or not. By default the partition is created and the kiwi-overlay dracut module also expect it to be present. However, the overlayroot feature can also be used without dracut (initrd_system="none") and under certain circumstances it is handy to configure if the partition table should contain the read-write partition or not.

Specifies the size in MB of the partition which stores the squashfs compressed read-only root filesystem in an overlayroot setup. If not specified kiwi calculates the needed size by a preliminary creation of the squashfs compressed file. However this is only accurate if no changes to the root filesystem data happens after this calculation, which cannot be guaranteed as there is at least one optional script hook which is allowed and applied after the calculation. In addition the pre-calculation requires some time in the build process. If the value can be provided beforehand this also speeds up the build process significantly

If an extra boot partition is required this attribute specify which filesystem should be used for it. The type of the selected bootloader might overwrite this setting if there is no alternative possible though.

For the iso image type specifies the live iso technology and dracut module to use. If set to overlay the kiwi-live dracut module will be used to support a live iso system based on squashfs+overlayfs. If set to dmsquash the dracut standard dmsquash-live module will be used to support a live iso system based on the capabilities of the upstream dracut module.

For disk image type oem, specifies the format of the virtual disk such that it can run on the desired target virtualization platform.

Specifies additional format options passed on to qemu-img formatoptions is a comma separated list of format specific options in a name=value format like qemu-img expects it. kiwi will take the information and pass it as parameter to the -o option in the qemu-img call

Specifies the filesystem mount options which also ends up in fstab The string given here is passed as value to the -o option of mount

Specifies options to use at creation time of the filesystem

Force use of MBR (msdos table) partition table even if the use of the GPT would be the natural choice. On e.g some arm systems an EFI partition layout is required but must not be stored in a GPT. For those rare cases this attribute allows to force the use of the msdos table including all its restrictions in max partition size and amount of partitions

For GPT disk types only: Create a hybrid GPT/MBR partition table

For the live ISO type, triggers the creation of a partition for a COW file to keep data persistent over a reboot

For the live ISO type, set the filesystem to use for persistent writing if a hybrid image is used as disk on e.g a USB Stick. By default the ext4 filesystem is used.

Specify which initrd builder to use, default is set to dracut. If set to none the image is build without an initrd. Depending on the image type this can lead to a non bootable system as its now a kernel responsibility if the given root device can be mounted or not.

Specifies a path to additional metadata required for the selected image type or its tools used to create that image type.

Note

Currently this is only effective for the appx container image type.

Specifies the bootloader default boot entry for the initial boot of a KIWI NG install image.

Note

This value is only evaluated for grub

Specifies the boot timeout handling for the KIWI NG install image. If set to “true” the configured timeout or its default value applies. If set to “false” no timeout applies in the boot menu of the install image.

Specifies if the bootloader menu should provide an failsafe entry with special kernel parameters or not

Specifies if an install iso image should be created. This attribute is only available for the oem type. The generated ISO image is an hybrid ISO which can be used as disk on e.g a USB stick or as ISO.

Specifies if a tarball that contains all data for a pxe network installation should be created. This attribute is only available for the oem type.

For ISO images, specifies if the bootloader menu should provide an mediacheck entry to verify ISO integrity or not. Disabled by default and only available for the x86 arch family.

Setup software raid in degraded mode with one disk Thus only mirroring and striping is possible

Specifies this type to be the primary type. If no type option is given on the commandline, KIWI NG will build this type

For all images that are configured to use the overlay filesystem this setting forces any COW(Copy-On-Write) action to happen in RAM.

Label name to set for the root filesystem. By default ROOT is used

For the ISO type only, specifies the volume ID (volume name or label) to be written into the master block. There is space for 32 characters.

For the ISO/(oem install ISO) type only, specifies the Application ID to be written into the master block. There is space for 128 characters.

For the VHD disk format, specifies the GUID

For container images, specifies the image URI of the container image. The image created by KIWI NG will use the specified container as the base root to work on.

For container images and in combination with the derived_from attribute. If delta_root is set to true, {kiwi-ng} creates a container image which only contains the differences compared to the given derived_from container. Such a container is on its own no longer functional and requires a tool which is able to provision a container instance from the derived_from container combined with the delta_root application container. Such a tool exists with the oci-pilot project and allows to manage applications as containers that feels like native applications on the host system.

For OCI container images, specifies whether to ensure /run and /tmp directories are empty in the container image created by Kiwi. Default is true.

For ISO images, specifies the publisher name of the ISO.

Specifies the bootloader to use for this image.

Note

systemd_boot ESP size

The implementation to support systemd-boot reads all data from the ESP (EFI Standard Partition). This also includes the kernel and initrd which requires the size of the ESP to be configured appropriately. By default KIWI NG configures the ESP with 20MB. For systemd_boot this is usually too small and can be changed with the efipartsize attribute. Reading boot relevant files from another filesystem requires to provide alternative EFI filesystem drivers e.g efifs and also needs adaptions on the setup of bootctl.

Note

systemd_boot and shim

At the moment the EFI image provided along with systemd-boot is not compatible with the shim signed loader provided in an extra effort by the distributions.

Specifies whether to use Bootloader Spec-style configuration if grub in the image supports it. It is a no-op if the blscfg module is not available. This option is only available for grub and defaults to true if not set.

Specifies the bootloader console. The attribute is available for the grub bootloader type. The behavior for setting up the console is different per bootloader:

For grub the console setting is split into the setting for the output and the input console:

Specifies a custom grub bootloader template file which will be used instead of the one provided with Kiwi. A static bootloader template to create the grub config file is only used in Kiwi if the native method via the grub mkconfig toolchain does not work properly. As of today, this is only the case for live and install ISO images. Thus, this setting only affects the oem and iso image types.

The template file should contain a Template string and can use the following variables:

Specifies the bootloader serial line setup. The setup is effective if the bootloader console is set to use the serial line. The attribute is available for the grub bootloader only.

Specifies the boot timeout in seconds prior to launching the default boot option. By default, the timeout is set to 10 seconds. It makes sense to set this value to 0 for images intended to be started non-interactively (e.g. virtual machines).

Specifies the boot timeout style to control the way in which the timeout interacts with displaying the menu. If set, the display of the bootloader menu is delayed after the timeout expired. In countdown mode, an indication of the remaining time is displayed. The attribute is available for the grub loader only.

Specifies the device type of the disk zipl should boot. On zFCP devices, use SCSI; on DASD devices, use CDL or LDL; on emulated DASD devices, use FBA. The attribute is available for the zipl loader only.

The file specified in hkd_cert defines the Host Key Document and tightly couples the image to the host matching the document

Required in combination with hkd_cert, providing the Common Authority certificate (signed by the root CA) that is used to establish a chain of trust for the verification of the Host Key Document.

Required in combination with hkd_cert, providing the Signing certificate that is used to establish a chain of trust for the verification of the Host Key Document.

Optional in combination with hkd_cert, providing the the revocation list to check on use of expired certificates in the chain of trust.

The owner attribute can be specified to make the file belonging to the specified owner and group. The ownership of the original file is meaningless in this case. The provided value is passed along to the chown program.

The permissions attribute can be specified to store the file with the provided permission. The permission bits of the original file are meaningless in this case. The provided value is passed along to the chmod program.

The target attribute can be used to specify a target path to install the file to the specified directory and name. Eventually missing parent directories will be created.