Image Description Elements

Note

This document provides a reference for the elements and attributes of the KIWI NG XML document in version 10.2.41.

<image>

The top level of any KIWI NG image description.

<image schemaversion="8.0" name="{exc_image_base_name}">
    <!-- descendants -->
</image>

The image definition starts with an image tag and requires the schema format at version 8.0. The attribute name specifies the name of the image, which is also used for the filenames created by KIWI. Because we don’t want spaces in filenames, the name attribute must not have any spaces in its name.

The following optional attributes can be inserted in the image tag:

displayname

Allows setting up the boot menu title for the selected boot loader. So you can have suse-SLED-foo as the image name but a different name as the boot display name. Spaces are not allowed in the display name because it causes problems for some boot loaders, and kiwi did not take the effort to separate the ones that can display them correctly from the ones that can’t.

id

sets an identification number that appears as file /etc/ImageID within the image.

<include>

Optional include of XML file content from a file.

<image schemaversion="8.0" name="{exc_image_base_name}">
    <include from="file://description.xml"/>
</image>

with file description.xml as follows:

<image>
    <description type="system">
        <author>name</author>
        <contact>contact</contact>
        <specification>text</specification>
    </description>
</image>

This will replace the include statement with the contents of description.xml. The validation of the result happens after the inclusion of all include references. The value for the from attribute is interpreted as a URI. As of now, only local URI types are supported, as well as the this:// resource locator, which translates into the path to the KIWI image description.

Note

The include information must be embedded into an <image> root node. Only the inner elements of the root node will be included. The processing of XML data via XSLT always requires a root node, which is the reason why this is required to be specified for include files as well.

Note

Nesting of include statements in other include files is not supported. This will lead to unresolved include statements in the final document and will cause the runtime checker to complain about it.

Note

The include is implemented via an XSLT stylesheet and therefore expects an XML document. Other markup formats are not supported as an include reference.

<description>

Provide an image identity.

<description type="system">
  <author>name</author>
  <contact>contact</contact>
  <specification>text</specification>
</description>

The mandatory description section contains information about the creator of this image description. The attribute type could be either of the value system, which indicates this is a system image description, or a value boot for custom kiwi boot image descriptions.

The following optional subsections can be inserted below the description tag:

license

Specifies the license name that applies to this image description.

<certificates>

Add a cert-file to the directory storing additional local CA certificates. The import will occur immediately after the bootstrap process, where the required CA update tooling is expected to be installed. This setting is useful for situations where certificates are not packaged, or the certificates are required during the build process, e.g., due to proxy servers in the build environment that need certificates in chroot. The required target_distribution attribute must be set to allow kiwi a correct matching for the CA store path and the update tool with regard to the image’s target distribution. The following settings apply:

Distributor

CA Store

Update Tool

SUSE

/etc/pki/trust/anchors

update-ca-certificates

Red Hat

/etc/pki/ca-trust/source/anchors

update-ca-certificates

Debian Based

/usr/local/share/ca-certificates

update-ca-certificates

Arch Linux

/etc/ca-certificates/trust-source/anchors

update-ca-trust

 
<certificates target_distribution="suse|redhat|debian|archlinux">
  <certificate name="/some/ca/filename1"/>
  <certificate name="/some/ca/filename2"/>
</certificates>

<preferences>

Set up image type and layout.

<preferences arch="arch">
  <version>1.2.3</version>
  <packagemanager name="zypper"/>
  <type image="tbz"/>
</preferences>

The mandatory preferences section contains information about the supported image type(s), the used package manager, the version of this image, and further optional elements. The preferences section can be configured to apply only for a certain architecture. In this case, specify the arch attribute with a value as it is reported by uname -m.

<preferences><version>

The mandatory image version must be a three-part version number of the format: Major.Minor.Release. In case of changes to the image description, the following rules should apply:

  • For smaller image modifications that do not add or remove any new packages, only the release number is incremented. The XML description file(config.xml) remains unchanged.

  • For image changes that involve the addition or removal of packages, the minor number is incremented, and the release number is reset.

  • For image changes that change the behavior or geometry of the image file, the major number is incremented.

<preferences><packagemanager>

The mandatory packagemanager element specifies which package manager should be used to handle software packages. The packagemanager setup is connected to the distribution used to build the image. The following table shows which package manager is connected to which distributor:

Distributor

Package Manager

SUSE

zypper

Red Hat

dnf4 / dnf5

Debian Based

apt

Arch Linux

pacman

Alpine Linux

apk

In general, the specification of one preferences section is sufficient. However, it’s possible to specify multiple preferences sections and distinguish between the sections via the profiles attribute.

In combination with the above, the preferences element supports the following optional elements:

<preferences><rpm-locale-filtering>

locale-filtering can be set to “true” or “false”. If set to “true”, it sets the install_lang macro for RPM-based installations to the RPM- configured locale list. This results in language-specific files being filtered out by rpm if they don’t match the configured list.

<preferences>
  <rpm-locale-filtering>true</rpm-locale-filtering>
</preferences>

Note

It depends on the individual package design if the install_lang macro contents apply to the package or not.

<preferences><rpm-check-signatures>

Specifies whether package signatures should be checked or not.

<preferences>
  <rpm-check-signatures>true</rpm-check-signatures>
</preferences>

<preferences><rpm-excludedocs>

Specifies whether files marked as documentation should be skipped during installation.

<preferences>
  <rpm-excludedocs>true</rpm-excludedocs>
</preferences>

<preferences><keytable>

Specifies the name of the console keymap to use. The value corresponds to a map file in /usr/share/kbd/keymaps/xkb.

<preferences>
  <keytable>us</keytable>
</preferences>

<preferences><timezone>

Specifies the time zone. Available time zones are located in the /usr/share/zoneinfo directory. Specify the attribute value relative to /usr/share/zoneinfo. For example, specify Europe/Berlin for /usr/share/zoneinfo/Europe/Berlin.

<preferences>
  <timezone>Europe/Berlin</timezone>
</preferences>

<preferences><locale>

Specifies the name of the UTF-8 locale to use, which defines the contents of the RC_LANG system environment variable used in the image and to run the custom scripts specified as part of the KIWI NG image description. Please note, only UTF-8 locales are supported here, which also means that the encoding must not be part of the locale information. This means you need to specify the locale using the 4-digit name, like the following example: en_US or en_US,de_DE.

<preferences>
  <locale>en_US</locale>
</preferences>

<preferences><bootsplash-theme>

Specifies the name of the plymouth bootsplash theme to use.

<preferences>
  <bootsplash-theme>bgrt</bootsplash-theme>
</preferences>

<preferences><bootloader-theme>

Specifies the name of the bootloader theme to use if that used bootloader has theme support.

<preferences>
  <bootloader-theme>openSUSE</bootloader-theme>
</preferences>

Along with the version and the packagemanager, at least one image type element must be specified to indicate which image type should be built.

<preferences><release-version>

Specifies the distribution’s global release version as consumed by package managers. Currently, the release version is not set or set to 0 for package managers that require a value to operate. With the optional release-version section, users have an opportunity to specify a custom value which is passed along the package manager to define the distribution release.

Note

The release version information is currently used in dnf/dnf5 and microdnf package managers only. It might happen that it gets applied to the other package manager backends as well. This will happen on demand, though.

<preferences><type>

At least one type element must be configured. It is possible to specify multiple type elements in a preferences block. To set a given type description as the default image, use the boolean attribute primary and set its value to true:

<preferences>
  <type image="typename" primary="true"/>
</preferences>

The image type to be created is determined by the value of the image attribute. The following list describes the supported types and possible values of the image attribute:

image=”tbz”

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

image=”btrfs|ext2|ext3|ext4|squashfs|xfs”

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 capabilities of the selected filesystem.

image=”iso”

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

image=”oem”

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.

image=”docker”

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.

image=”oci”

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.

image=”appx”

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.

image=”wsl”

An archive image suitable for the Windows Subsystem for Linux container engine >= v2.4.4. The image represents a gzip-compressed tar file as described in https://learn.microsoft.com/en-us/windows/wsl/build-custom-distro and can be loaded from a Windows System that has support for WSL in that version activated.

image=”kis”

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.

For completion of a type description, there could be several other optional attributes and child elements. The type element supports a plethora of optional attributes; some of these are only relevant for certain build types and will be covered in extra chapters that describe the individual image types in more detail. Certain attributes are, however, useful for nearly all build types and will be covered next:

bootpartition=”true|false”:

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

bootpartsize=”nonNegativeInteger”:

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.

eficsm=”true|false”:

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

efipartsize=”nonNegativeInteger”:

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.

efifatimagesize=”nonNegativeInteger”:

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.

efiparttable=”msdos|gpt”:

For images with an EFI firmware, specifies the partition table type to use. If not set, it defaults to the GPT partition table type for disk images and MBR (msdos) for ISO images.

dosparttable_extended_layout=”true|false”:

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 need to be created in an msdos table.

btrfs_quota_groups=”true|false”:

A boolean parameter to activate filesystem quotas if the filesystem is btrfs. By default, quotas are inactive.

btrfs_set_default_volume=”true|false”:

For OEM disk images using the btrfs filesystem, this 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.

btrfs_root_is_subvolume=”true|false”:

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 top-level volume is set to true.

btrfs_root_is_snapper_snapshot=”true|false”:

A boolean parameter that tells KIWI NG to install the system into a btrfs snapshot. The snapshot layout is compatible with the snapper management toolkit and follows a concept by SUSE. By default, snapshots are turned off.

btrfs_root_is_readonly_snapshot=”true|false”:

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

bootstrap_package=”package_name”:

For use with the apt package manager only. Specifies the name of a bootstrap package that 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 Circumvent Debian Bootstrap.

compressed=”true|false”:

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.

editbootconfig=”file_path”:

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

editbootinstall=”file_path”:

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

filesystem=”btrfs|ext2|ext3|ext4|squashfs|xfs”:

The root filesystem.

firmware=”efi|uefi|bios|ec2|ofw|opal”:

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.

  • efi Standard EFI layout.

  • uefi Standard EFI layout for secure boot.

  • bios Standard BIOS layout for x86.

  • ec2 Standard BIOS layout for x86 using Xen grub modules for old- style Xen boot in Amazon EC2.

  • ofw Standard PPC layout.

  • opal Standard openPOWER PPC64 layout. kexec-based boot process.

force_mbr=”true|false”:

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

fsmountoptions=”option_string”:

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

fscreateoptions=”option_string”:

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 provide this differently and document 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 the creation of an ext4 filesystem, the following option would be required:

<preferences>
  <type fscreateoptions="-O ^has_journal"/>
</preferences>
kernelcmdline=”string”:

Additional kernel parameters passed to the kernel by the bootloader.

root_clone=”number”

For OEM disk images, this attribute allows you 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 Partition Clones.

boot_clone=”number”

Same as root_clone but applied to the boot partition if present.

luks=”passphrase|file:///path/to/keyfile|random”:

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 a 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 /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 key file. The use of random is therefore only secure if the image adds additional security that encrypts the initrd, as 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 leave 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.

luks_version=”luks|luks1|luks2”:

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.

target_blocksize=”number”:

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
target_removable=”true|false”:

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.

selinux_policy.attribute=”targeted|mls|minimum”:

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

spare_part=”number”:

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.

spare_part_mountpoint=”dir_path”:

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

spare_part_fs=”btrfs|ext2|ext3|ext4|xfs”:

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

spare_part_fs_attributes=”attribute_list”:

Specify filesystem attributes for the spare partition. Attributes can be specified as a 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.

spare_part_is_last=”true|false”:

Specify if the spare partition should be the last one in the partition table. It 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.

devicepersistency=”by-uuid|by-label”:

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

squashfscompression=”uncompressed|gzip|lzo|lz4|xz|zstd”:

Specifies the compression type for mksquashfs.

erofscompression=”text”

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

standalone_integrity=”true|false”:

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

integrity_legacy_hmac=”true|false”:

For the oem type only and in combination with the standalone_integrity attribute, this allows the use of old, flawed HMAC calculations (does not protect the superblock).

Warning

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

integrity_keyfile=”filepath”:

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

integrity_metadata_key_description=”string”:

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
embed_integrity_metadata=”true|false”:

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|
header:

Is a string of the following information separated by spaces:

  • version: currently set to 1

  • fstype: name of the filesystem attribute

  • access: either ro or rw, depending on the filesystem capabilities

  • integrity: fixed identifier value

dm_integrity_meta:

Is a string of the following information separated by spaces:

  • provided_data_sectors: number of data sectors

  • sector_size: sector size in bytes; defaults to 512

  • parameter_count: number of parameters needed to construct the integrity device map. After the parameter_count, a list of space-separated parameters follows, and the parameter_count specifies the quantity of these parameters.

  • parameters: The first element of the parameter list contains information about the used hash algorithm, which is not part of the superblock and is provided according to the parameters passed along when KIWI NG calls integritysetup. As of now, this defaults to:

    • internal_hash:sha256

    All subsequent parameters are taken from the flags field of the dm-integrity superblock. see the dm-integrity documentation on the web for possible flag values.

verity_blocks=”number|all”:

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.

embed_verity_metadata=”true|false”:

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|
header:

Is a string of the following information separated by spaces:

  • version: currently set to 1

  • fstype: name of filesystem attribute

  • access: either ro or rw depending on the filesystem capabilities

  • verity: fixed identifier value

dm_verity_credentials:

Is a string of the following information separated by spaces:

  • hash_type: hash type name as returned by veritysetup

  • data_blksize: data blocksize as returned by veritysetup

  • hash_blksize: hash blocksize as returned by veritysetup

  • data_blocks: number of data blocks as returned by veritysetup

  • hash_start_block: hash start block as required by the kernel to construct the device map

  • algorithm: hash algorithm as returned by veritysetup

  • root_hash: root hash as returned by veritysetup

  • salt: salt hash as returned by veritysetup

Note

dm-verity Runtime Options

Additional veritysetup options can be provided at boot time using the kernel parameter rd.kiwi.verity_options=option1,option2. This allows runtime customization.

KIWI automatically provides hash-offset and hash-block-size parameters based on the image configuration. These should not be specified manually via rd.kiwi.verity_options=.

Common Options:

  • panic-on-corruption: System panics on corruption detection.

  • restart-on-corruption: System restarts on corruption (often default).

  • ignore-corruption: Ignore corruption (debugging only).

  • ignore-zero-blocks: Skip verification of zero blocks.

  • check-at-most-once: Verify each block only once.

For complete options, see veritysetup(8).

overlayroot=”true|false”:

For the oem type only, specifies to use an overlayfs-based root filesystem consisting 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 the system is rebooted. 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.

overlayroot_readonly_filesystem=”squashfs|erofs”:

For the oem type only, specifies the filesystem type to use as a read-only filesystem in an overlayroot setup. By default, squashfs is used.

overlayroot_write_partition=”true|false”:

For the oem type only, this allows you 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 expects 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 whether the partition table should contain the read-write partition or not.

overlayroot_readonly_partsize=”mbsize”:

Specifies the size in MB of the partition that 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 happen after this calculation, which cannot be guaranteed as there is at least one optional script hook that 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.

bootfilesystem=”btrfs|ext2|ext3|ext4|xfs|fat32|fat16”:

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

flags=”overlay|dmsquash”:

For the ISO image type, this 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.

format=”gce|ova|qcow2|vagrant|vmdk|vdi|vhd|vhdx|vhd-fixed”:

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

formatoptions=”string”:

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

fsmountoptions=”string”:

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

fscreateoptions=”string”:

Specifies options to use at the creation time of the filesystem.

force_mbr=”true|false”:

Force the use of an 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 you to force the use of the msdos table, including all its restrictions in max partition size and amount of partitions.

gpt_hybrid_mbr=”true|false”:

For disk types, create a hybrid GPT/MBR partition table with an ‘accurate’ MBR table that will have no ‘bootable’ flagged partition. For ISO types, create a hybrid GPT/MBR partition table where the MBR partition table contains a whole-disk ‘protective’ partition and a second bootable-flagged partition (intended to make the image bootable in both UEFI and BIOS modes on as much hardware as possible). In both cases, it only has an effect if the EFI partition table type is GPT.

hybridpersistent=”true|false”:

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

hybridpersistent_filesystem=”ext4|xfs”:

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

initrd_system=”kiwi|dracut|none”:

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

metadata_path=”dir_path”:

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.

installboot=”failsafe-install|harddisk|install”:

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

Note

This value is only evaluated for grub.

install_continue_on_timeout=”true|false”:

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.

installprovidefailsafe=”true|false”:

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

installiso=”true|false”

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

installpxe=”true|false”:

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.

mediacheck=”true|false”:

For ISO images, specifies whether the bootloader menu should provide a mediacheck entry to verify ISO integrity or not. It is disabled by default and only available for the x86 arch family.

mdraid=”mirroring|striping”:

Set up software RAID in degraded mode with one disk. Thus, only mirroring and striping are possible.

primary=”true|false”:

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

ramonly=”true|false”:

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

rootfs_label=”string”:

A label name to set for the root filesystem. By default, ROOT is used.

volid=”string”:

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

application_id=”string”:

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.

vhdfixedtag=”GUID_string”:

For the VHD disk format, this specifies the GUID.

derived_from=”string”:

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.

delta_root=”true|false”:

For container images and in combination with the derived_from attribute. If delta_root is set to true, {kiwi-ng} creates a container image that 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 that 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 you to manage applications as containers that feel like native applications on the host system.

ensure_empty_tmpdirs=”true|false”:

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

publisher=”string”:

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

eficsmpart_id=”number”:

For OEM images, this specifies the partition number for the EFI CSM (legacy BIOS) partition. For details about the evaluation and impact of custom partition ids, please see: Custom Disk Partitions.

efipart_id=”number”:

For OEM images, specifies the partition number for the EFI partition. For details about the evaluation and impact of custom partition ids, please see: Custom Disk Partitions.

rootpart_id=”number”:

For OEM images, this specifies the partition number for the ROOT partition. For details about the evaluation and impact of custom partition ids, please see: Custom Disk Partitions.

bootpart_id=”number”:

For OEM images, specifies the partition number for the BOOT partition. For details about the evaluation and impact of custom partition ids, please see: Custom Disk Partitions.

The following sections show the supported child elements of the type element, including references to their usage in a detailed type setup:

<preferences><type><luksformat>

The luksformat element is used to specify additional luks options passed on to the cryptsetup luksFormat call. The element requires the attribute luks to be set in the <type> section referring to luksformat. Several custom settings related to the LUKS and LUKS2 format features can be set up. For example, the setup of the dm_integrity feature:

<luksformat>
  <option name="--cipher" value="aes-gcm-random"/>
  <option name="--integrity" value="aead"/>
</luksformat>

<preferences><type><bootloader>

The bootloader element is used to select the bootloader. At the moment, grub2, systemd_boot, and the combination of zipl plus userspace grub2, grub2_s390x_emu, are supported. The special custom entry allows you to skip the bootloader configuration and installation and leaves this up to the user, which can be done by using the editbootinstall and editbootconfig custom scripts.

Note

Bootloaders provide a very different set of features and only work within their individual implementation priorities. KIWI NG provides an API for bootloaders, but not all API methods can be implemented for all bootloaders due to the fact that some features only exist in one but not in another bootloader. If a bootloader setting is used that is not understood by the selected bootloader, the image build process will fail with an exception message.

name=”grub2|systemd_boot|grub2_s390x_emu|zipl”:

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 providing alternative EFI filesystem drivers, e.g., efifs, and also needs adaptations 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.

In addition to the mandatory name attribute, the following optional attributes are supported:

bls=”true|false”:

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.

output_console=”none|console|gfxterm|serial|vga_text|mda_text|morse|spkmodem”:

Specifies the bootloader output console. The attribute is available for the grub bootloader type. Multiple console types can be provided, separated by a space.

input_console=”none|console|serial|at_keyboard|usb_keyboard”:

Specifies the bootloader input console. The attribute is available for the grub bootloader type. Multiple console types can be provided, separated by a space. If no input_console is provided, the value for the output_console is used if specified.

grub_template=”filename”:

Specifies a custom grub bootloader template file that 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:

Variable

Description

search_params

parameters needed for grub’s search command to locate the root volume

default_boot

number of the default menu item to boot

kernel_file

the name of the kernel file

initrd_file

the name of the initial ramdisk file

boot_options

kernel command-line options for booting normally

failsafe_boot_options

kernel command-line options for booting in failsafe mode

gfxmode

the resolution to use for the bootloader; passed to grub’s gfxmode command

theme

the name of a graphical theme to use

boot_timeout

the boot menu timeout, set by the timeout attribute

boot_timeout_style

the boot timeout style, set by the timeout_style attribute

serial_line_setup

directives used to initialize the serial port, set by the serial_line attribute

title

a title for the image: this will be the <image> tag’s displayname attribute or its name attribute if displayname is not set; see: <image>

bootpath

the bootloader lookup path

boot_directory_name

the name of the grub directory

efi_image_name

architecture-specific EFI boot binary name

terminal_setup

the bootloader console mode, set by the console attribute
serial_line=”string”:

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.

timeout=”number”:

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

timeout_style=”countdown|hidden”:

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 has expired. In countdown mode, an indication of the remaining time is displayed. The attribute is available for the grub loader only.

targettype=”CDL|LDL|FBA|SCSI|GPT”:

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

<preferences><type><bootloader><securelinux>

Used to specify data required to set up secure Linux execution. Secure Linux execution reads the kernel, initrd, and boot parameters from an encrypted data blob and couples the image to the machine it gets executed on. Typically, the private key is protected in hardware on the machine itself. KIWI NG supports secure execution for the IBM secure Linux target on the s390 platform, along with the bootloaders zipl and grub2-s390x-emu.

<securelinux>
    <hkd_cert name="some1-host.crt"/>
    <hkd_cert name="some2-host.crt"/>
    <hkd_ca_cert name="some-ca.crt"/>
    <hkd_sign_cert name="some1-signing.crt"/>
    <hkd_sign_cert name="some2-signing.crt"/>
    <hkd_revocation_list name="some1-revocation.crl"/>
    <hkd_revocation_list name="some2-revocation.crl"/>
</securelinux>

Except for the hkd_ca_cert, all other certificates can be specified multiple times.

hkd_cert:

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

hkd_ca_cert:

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.

hkd_sign_cert:

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.

hkd_revocation_list:

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

<preferences><type><bootloader><bootloadersettings>

Used to specify custom arguments for the tools called to set up the bootloader: * secure boot via <shimoption>, e.g., shiminstall * installation of the bootloader via <installoption>, e.g., grub-install * configuration of the bootloader via <configoption>, e.g., grub-mkconfig * setup of bootloader environment variables via <environment>, e.g., grub2-editenv

<bootloadersettings>
    <shimoption name="--suse-enable-tpm"/>
    <shimoption name="--bootloader-id" value="some-id"/>
    <installoption name="--suse-enable-tpm"/>
    <configoption name="--debug"/>
    <environment>
        <env name="menu_auto_hide" value="1"/>
    </environment>
</bootloadersettings>

Note

{kiwi-ng} does not judge the given parameters, and if the provided data is effectively used depends on the individual bootloader implementation.

<preferences><type><containerconfig>

Used to describe the container configuration metadata in docker or wsl image types. For details, see: Build a Container Image and: Build a WSL Container Image.

<preferences><type><vagrantconfig>

Used to describe vagrant configuration metadata in a disk image that is being used as a vagrant box. For details, see: Image Description for Vagrant.

<preferences><type><systemdisk>

Used to describe the volumes of the disk area, which contains the root filesystem. Volumes are either a feature of the used filesystem, or LVM is used for this purpose. For details, see: Custom Disk Volumes.

Note

When both <partitions> and <systemdisk> are used, <partitions> are evaluated first, and mount points defined in <partitions> cannot be redefined as <systemdisk> volumes. The two types define a complete disk setup, so there cannot be any overlapping volumes or mount points. As a result, whatever is written in <partitions> cannot be expressed in the same way in <volumes>.

<preferences><type><partitions>

Used to describe the geometry of the disk on the level of the partition table. For details, see: Custom Disk Partitions.

<preferences><type><oemconfig>

Used to customize the deployment process in an OEM disk image. For details, see: OEM Customization.

<preferences><type><size>

Used to customize the size of the resulting disk image in an OEM image. For details, see: Modifying the Size of the Image.

<preferences><type><machine>

Used to customize the virtual machine configuration, which describes the components of an emulated hardware. For details, see: Customizing the Virtual Machine.

<preferences><type><installmedia>

Used to customize the installation media images created for OEM images deployment. For details, see: Installation Media Customization.

<preferences><type><initrd>

Used to specify custom arguments for the initrd tooling, e.g., dracut.

<initrd action="setup">
    <dracut uefi="true"/>
</initrd>
<initrd action="add|omit">
    <dracut module="some_a"/>
    <dracut module="some_b"/>
    <dracut driver="driver_name"/>
</initrd>
dracut.uefi.true:

As part of the setup action, this enables creating a UKI EFI binary.

dracut.module.NAME:

As part of the add or omit action, this adds or omits the given module name. The element can be specified multiple times.

dracut.driver.NAME:

As part of the add or omit action, this adds or omits the given kernel driver. The element can be specified multiple times and accepts kernel driver names without the ko extension.

<containers>

Set up containers to fetch from a registry assigned to one of the supported container backends.

<containers source="registry.opensuse.org" backend="podman">
    <container name="some"/>
</containers>

<containers source="registry.opensuse.org" backend="container-snap">
    <container name="opensuse/bootable" tag="slowroll"/>
</containers>

The optional containers element specifies the location of one or more containers on a registry source server. KIWI NG will take this information and fetch the containers as OCI archives to the image. On first boot, these container archives will be loaded into the local container backend store for the selected backend, and the archive files will be deleted.

Supported backend values are docker, podman, and container-snap. The backend attribute is mandatory and specifies for which container backend the image should be available in the system. The containers element has the following optional attributes:

arch=”arch”

The containers section can be configured to apply only for a certain architecture. In this case, specify the arch attribute with a value as it is reported by uname -m.

profiles=”name[,name]”

A list of profiles to which this containers selection applies (see Image Profiles).

<containers><container>

Details about the container.

<containers source="registry.opensuse.org" backend="podman">
    <container name="some"/>
</containers>

The name attributes are mandatory and specify the name of the container as it exists in the registry. The container element has the following optional attributes:

path=”some/path”

The path to the container in the registry. If not specified, the value defaults to /.

fetch_only=”true|false”

If set to true, kiwi will only fetch the container but will not set up the systemd unit for loading the container into the local registry. In this mode, the container archive file stays in the system and can be handled in a custom way. By default, fetch_only is set to false.

tag=”tagname”

Specifies the container tag to fetch. If not set, the tag name defaults to latest.

arch=”arch”

The container section can be configured to apply only for a certain architecture. In this case, specify the arch attribute with a value as it is reported by uname -m.

<repository>

Set up software sources for the image.

<repository arch="arch">
  <source path="uri"/>
</repository>

The mandatory repository element specifies the location and type of a repository to be used by the package manager as a package installation source. KIWI NG supports apk, apt, dnf4, dnf5, pacman, and zypper as package managers, specified with the packagemanager element. The repository element has the following optional attributes:

alias=”name”

Specifies an alternative name for the configured repository. If the attribute is not specified, KIWI NG will generate a random alias name for the repository. The specified name must match the pattern: [a-zA-Z0-9_-.]+.

components=”name”

Used for Debian (apt) based repositories only. Specifies the component name that should be used from the repository. By default, the main component is used.

distribution=”name”

Used for Debian (apt) based repositories only. Specifies the distribution name used in the repository data structure.

imageonly=”true|false”

Specifies whether or not this repository should be configured in the resulting image without using it at build time. By default, the value is set to false.

repository_gpgcheck=”true|false”

Specifies whether or not this specific repository values the result of the repository signature validation. If not set, the default is false. If set, the relevant key information needs to be provided on the KIWI NG commandline using the --signing-key option or via the <signing> element as part of the <repository> setting in the image description.

package_gpgcheck=”true|false”

Specify whether or not this specific repository values the result of the package signature validation for each package taken from this repository. If not set, the default value is false. If set, the same key information requirements as for the repository_gpgcheck attribute apply.

customize=”/path/to/custom_script”

A custom script hook that is invoked with the repo file as a parameter for each file created by KIWI NG.

Note

If the script is provided as a relative path, it will be searched in the image description directory.

imageinclude=”true|false”

Specifies whether the given repository should be configured as a repository in the image or not. The default behavior is that repositories used to build an image are not configured as a repository inside the image. This feature allows you to change the behavior by setting the value to true.

Note

Scope of repository uri’s

The repository is configured in the image according to the source path as specified with the path attribute of the source element. Therefore, if the path is not a fully qualified URL, you may need to adjust the repository file in the image to accommodate the expected location. It is recommended that you use the alias attribute in combination with the imageinclude attribute to avoid having unpredictable random names assigned to the repository you wish to include in the image.

password=”string”

Specifies a password for the given repository. The password attribute must be used in combination with the username attribute. Dependent on the repository location, this information may not be used.

username=”name”

Specifies a user name for the given repository. The username attribute must be used in combination with the password attribute. Dependent on the repository location, this information may not be used.

prefer-license=”true|false”

The repository providing this attribute will be used primarily to install the license tarball if found on that repository. If no repository with a preferred license attribute exists, the search happens over all repositories. It’s not guaranteed in that case that the search order follows the repository order as they are written into the XML description.

priority=”number”

Specifies the repository priority for this given repository. Priority values are treated differently by different package managers. Repository priorities allow the package management system to disambiguate packages that may be contained in more than one of the configured repositories. The zypper package manager, for example, prefers packages from a repository with a lower priority over packages from a repository with higher priority values. The value 99 means “no priority is set”. For other package managers, please refer to the individual documentation about repository priorities.

sourcetype=”baseurl|metalink|mirrorlist”

Specifies the source type of the repository path. Depending on whether the source path is a simple URL or a pointer to a metadata file or mirror list, the configured package manager needs to be set up appropriately. By default, the source is expected to be a simple repository baseurl.

use_for_bootstrap=”true|false”

Used for Debian (apt) based repositories only. It specifies whether this repository should be the one used for bootstrapping or not. It is set to ‘false’ by default. Only a single repository is allowed to be used for bootstrapping. If no repository is set for the bootstrap, the last one in the description XML is used.

<repository><source>

The location of a repository is specified by the path attribute of the mandatory source child element:

<repository alias="kiwi">
  <source path="obs://Virtualization:Appliances:Builder/openSUSE_Leap_15.6"/>
</repository>

The location specification may include the %arch macro, which will expand to the architecture of the image building host. The value for the path attribute may begin with any of the following location indicators:

  • file:///local/path/to/file An absolute path to a file accessible through the local filesystem.

  • ftp://<ftp://> A ftp-protocol-based network location.

  • http://<http://> A http-protocol-based network location.

  • https://<https://> A https-protocol-based network location.

    Note

    https repositories

    When specifying a https location for a repository, it is generally necessary to include the openssl certificates and a cracklib word dictionary as package entries in the bootstrap section of the image configuration. The names of the packages to include are individual to the used distribution. On SUSE systems, as one example, this would be openssl-certs and cracklib-dict-full.

  • obs://Open:Build:Service:Project:Name A reference to a project in the Open Build Service (OBS). KIWI NG translates the given project path into a remote URL at which the given project hosts the packages.

  • obsrepositories:/ A placeholder for the Open Build Service (OBS) to indicate that all repositories are taken from the project configuration in OBS.

A repository <source> element can optionally contain one or more signing keys for the packages from this repository, as shown in the following example:

<repository alias="kiwi">
  <source path="obs://Virtualization:Appliances:Builder/openSUSE_Leap_15.6">
    <signing key="file:///path/to/sign_key_a"/>
    <signing key="file:///path/to/sign_key_b"/>
  </source>
</repository>

All signing keys from all repositories will be collected and incorporated into the keyring as used by the selected package manager.

<packages>

Set up software components to be installed in the image.

<packages type="type"/>

The mandatory packages element specifies the setup of a packages group for the given type. The value of the type attribute specifies at which state in the build process the packages group is handled. Supported values are as follows:

type=”bootstrap”

Bootstrap packages, a list of packages to be installed first into a new (empty) root tree. The packages list the required components to support a chroot environment from which further software components can be installed.

type=”image”

Image packages, a list of packages to be installed as part of a chroot operation inside the new root tree.

type=”uninstall|delete”

Packages to be uninstalled or deleted. For further details, see Uninstall System Packages.

type=”image_type_name”

Packages to be installed for the given image type name. For example, if set to type="iso", the packages in this group will only be installed if the ISO image type is built.

The packages element must contain at least one child element of the following list to provide specific configuration information for the specified packages group:

<packages><package>

<packages type="image"/>
  <package name="name" arch="arch"/>
</packages>

The package element installs the given package name. The optional arch attribute can be used to limit the installation of the package to the host architecture from which KIWI NG is called. The arch attribute is also available in all of the following elements.

<packages><namedCollection>

<packages type="image" patternType="onlyRequired">
  <namedCollection name="base"/>
</packages>

The namedCollection element is used to install a number of packages grouped together under a name. This is a feature of the individual distribution and is used in the implementation of the KIWI NG package manager backend. At the moment, collections are only supported for SUSE- and Red Hat-based distributions. The optional patternType attribute is used to control the behavior of the dependency resolution of the package collection. onlyRequired installs only the collection and its required packages. plusRecommended installs the collection, any of its required packages, and any recommended packages.

Note

Collections on SUSE

On SUSE-based distributions, collections are called patterns and are just simple packages. To get the names of the patterns such that they can be used in a namedCollection type, use the following command: $ zypper patterns. If for some reason the collection name cannot be used, it is also possible to add the name of the package that provides the collection as part of a package element. To get the names of the pattern packages, type the following command: $ zypper search patterns. By convention, all packages that start with the name “patterns-” represent a pattern package.

Note

Collections on Red Hat

On Red Hat-based distributions, collections are called groups and are extra metadata. To get the names of these groups, type the following command: $ dnf group list -v. Please note that since KIWI NG v9.23.39, group IDs are allowed only, e.g.: <namedCollection name="minimal-environment"/>.

<packages><collectionModule>

<packages type="bootstrap">
    <collectionModule name="module" stream="stream" enable="true|false"/>
</packages>

In CentOS Stream >= 8 and Red Hat Enterprise Linux >= 8, there are Application Streams that are offered in the form of modules (using Fedora Modularity technology). To build images that use this content, KIWI NG offers to enable/disable modules when using the dnf or microdnf package manager backend. Modules are set up prior to the bootstrap phase, and their setup persists as part of the image.

There are the following constraints when adding collectionModule elements:

  • collectionModule elements can only be specified as part of the <packages type="bootstrap"> section. This is because the setup of modules must be done once and as early as possible in the process of installing the image root tree.

  • Disabling a module can only be done as a whole, and therefore, the stream attribute is not allowed for disabling modules. For enabling modules, the stream attribute is optional.

  • The enable attribute is mandatory because it should be an explicit setting if a module is effectively used or not.

<packages><file>

<packages type="image"/>
  <file name="name"/>
</packages>

The file element takes the name attribute and looks up the given name as a file on the system. If specified as a relative path, KIWI NG looks up the name in the image description directory. The file is installed using the rsync program. The file element has the following optional attributes:

owner=”user:group”

The owner attribute can be specified to make the file belong 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.

permissions=”perms”

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.

target=”some/path”

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.

<packages><archive>

<packages type="image"/>
  <archive name="name" target_dir="some/path"/>
</packages>

The archive element takes the name attribute and looks up the given name as a file on the system. If specified as a relative path, KIWI NG looks up the name in the image description directory. The archive is installed using the tar program. Thus, the file name is expected to be a tar archive. The compression of the archive is detected automatically by the tar program. The optional target_dir attribute can be used to specify a target directory to unpack the archive inside the image root tree.

<packages><ignore>

<packages type="image"/>
  <ignore name="name"/>
</packages>

The ignore element instructs the used package manager to ignore the given package name at installation time. Please note whether or not the package can be ignored is up to the package manager. Packages that are hard-required by other packages in the install procedure cannot be ignored, and the package manager will simply ignore the request.

<packages><product>

<packages type="image">
  <product name="name"/>
</packages>

The product element instructs the used package manager to install the given product. What the installation of a product means is up to the package manager and is also distribution-specific. This feature currently only works on SUSE-based distributions.

<users>

Set up image users.

<users arch="arch">
  <user
    name="user"
    groups="group_list"
    home="dir"
    id="number"
    password="text"
    pwdformat="encrypted|plain"
    realname="name"
    shell="path"
  />
</users>

The optional users element contains the user setup KIWI NG should create in the system. The optional arch attribute can be used to limit the user’s setup to the host architecture from which KIWI NG is called. At least one user child element must be specified as part of the users element. Multiple user elements may be specified.

Each user element represents a specific user that is added or modified. The following attributes are mandatory:

name=”name”:

the UNIX username.

password=”string”

The password for this user account. It can be provided either in cleartext form or encrypted. An encrypted password can be created using openssl as follows:

$ openssl passwd -1 -salt xyz PASSWORD

It is also possible to specify the password as a non-encrypted string by using the pwdformat attribute and setting its value to plain. KIWI NG will then encrypt the password prior to the user being added to the system.

Warning

plain text passwords

We do not recommend plain passwords, as they will be readable in the image configuration in plain text.

All specified users and groups will be created if they do not already exist. The defined users will be part of the group(s) specified with the groups attribute or belong to the default group as configured in the system. If specified, the first entry in the groups list is used as the login group.

Additionally, the following optional attributes can be specified:

home=”path”:

The path to the user’s home directory.

groups=”group_a,group_b,group_c:id”:

A comma-separated list of UNIX groups. The first element of the list is used as the user’s primary group. The remaining elements are appended to the user’s supplementary groups. When no groups are assigned, then the system’s default primary group will be used. If a group should be of a specific group ID, it can be appended to the name, separated by a colon.

Note

Group IDs can only be set for groups that do not yet exist at the time when KIWI NG creates them. A check is made if the desired group is already present, and if it exists, the user will become a member of that group, but any given group ID from the KIWI NG configuration will not be taken into account. Usually, all standard system groups are affected by this behavior because they are provided by the OS itself. Thus, it’s by intention not possible to overwrite the group ID of an existing group.

id=”number”:

The numeric user ID of this account.

pwdformat=”plain|encrypted”:

The format in which password is provided. The default, if not specified, is encrypted.

<profiles>

Manage image namespace(s).

<profiles>
  <profile name="name" description="text"/>
</profiles>

The optional profiles section lets you maintain one image description while allowing for variation of other sections that are included. A separate profile element must be specified for each variation. The profile child element, which has name and description attributes, specifies an alias name used to mark sections as belonging to a profile and a short description explaining what this profile does.

For example, to mark a set of packages as belonging to a profile, simply annotate them with the profiles attribute, as shown below:

<packages type="image" profiles="profile_name">
  <package name="name"/>
</packages>

It is also possible to mark sections as belonging to multiple profiles by separating the names in the profiles attribute with a comma:

<packages type="image" profiles="profile_A,profile_B">
  <package name="name"/>
</packages>

If a section tag does not have a profiles attribute, it is globally present in the configuration. If global sections and profiled sections contains the same sub-sections, the profiled sections will overwrite the global sections in the order of the provided profiles. For a better overview of the result configuration when profiles are used we recommend to put data that applies in any case to non profiled (global) sections and only extend those global sections with profiled data. For example:

<preferences>
  <version>1.2.3</version>
  <packagemanager name="zypper"/>
</preferences>

<preferences profiles="oem_qcow_format">
  <type image="oem" filesystem="ext4" format="qcow2"/>
</preferences>

<preferences profiles="oem_vmdk_format">
  <type image="oem" filesystem="ext4" format="vmdk"/>
</preferences>

The above example configures two version of the same oem type. One builds a disk in qcow2 format the other builds a disk in vmdk format. The global preferences section without a profile assigned will be used in any case and defines those preferences settings that are common to any build process. A user can select both profiles at a time but that will result in building the disk format that is specified last because one is overwriting the other.

Use of one or more profile(s) during image generation is triggered by the use of the --profile command line argument. multiple profiles can be selected by passing this option multiple times.