Use escape sequences to print different types of information in colored output. for this option to work, the underlying terminal must support those escape characters. Error messages appear in red, warning messages in yellow, and debugging information is printed in light grey.

Use specified runtime configuration file. If not specified, the runtime configuration is expected to be in the ~/.config/kiwi/config.yml or /etc/kiwi.yml files.

Print debug information on the command line. Same as: --loglevel 10.

Run scripts called by KIWI NG in a screen session.

Specify log file. The logfile contains detailed information about the process. The special call: --logfile stdout sends all information to standard out instead of writing to a file.

Send log data to the specified Unix Domain socket in the same format as with --logfile.

Specify logging level as a number. Further info about the available log levels can be found at: https://docs.python.org/3/library/logging.html#logging-levels Setting a log level displays all messages above the specified level.

----------------------------
| Level    | Numeric value |
----------------------------
| CRITICAL | 50            |
| ERROR    | 40            |
| WARNING  | 30            |
| INFO     | 20            |
| DEBUG    | 10            |
| NOTSET   | 0             |
----------------------------

Select profile to use. The specified profile must be part of the XML description. The option can be specified multiple times to allow a combination of profiles.

Specify an alternative shared cache directory. The directory is shared via bind mount between the build host and image root system, and it contains information about package repositories and their cache and meta data. The default location is /var/cache/kiwi.

Specify an alternative base temporary directory. The provided path is used as base directory to store temporary files and directories. Default is /var/tmp.

Specify an image architecture. By default, the host architecture is used as the image architecture. If the specified architecture name does not match the host architecture (thus requesting a cross architecture image build), you must configure the support for the image architecture and binary format on the building host. This must be done during the preparation stage, and it is beyond the scope of KIWI NG.

Select an image build type. The specified build type must be configured as part of the XML description.

Basename of kiwi file that contains the main image configuration elements. If not specified, kiwi uses a file named config.xml or a file matching *.kiwi

Show program version

Directory containing the KIWI NG build results.

Directory containing the bundle results, compressed versions of image results, and SHA checksum files.

Specify the bundle format to create the bundle. If provided, this setting will overwrite an eventually provided bundle_format attribute from the main image description. The format string can contain placeholders for the following elements:

Bundle ID. It is a free-form text appended to the image version information as part of the result image filename.

Directory containing the KIWI NG build results.

Download location of the bundle file or files. Only relevant if zsync is used to sync the bundle.

Create an RPM package containing the result files.

Specify a package to install as part of the early KIWI NG bootstrap phase. The option can be specified multiple times.

Add a container label to the container configuration metadata. It overwrites the label with the provided key-value pair if it was already defined in the XML description.

Specify a package to add (install). The option can be specified multiple times.

Add a new repository to the existing repository setup in the XML description. This option can be specified multiple times. For details about the supported option values, see the –set-repo information below

For uri://user:pass@location type repositories, set the user and password connected with an add-repo specification. If the provided value is a filename in the filesystem, the first line of the file is used as credentials.

Allow to re-use an existing image root directory.

Delete repository cache for each of the used repositories before installing any package. This is useful if an image build validates the signature of the package from the original repository source for any build. Some package managers unconditionally trust the contents of the cache, which works for cache data dedicated to one build. In case of KIWI NG, the cache is shared between multiple image builds on the host for performance reasons.

Specify a package to delete. The option can be specified multiple times.

Path to the KIWI NG XML description. The directory must contain at least a config.xml of *.kiwi XML description.

Ignore all repository configurations in the XML description. This option is normally used in combination with the --add-repo` option. Otherwise, an image build operation results in an error.

Works the same way as --ignore-repos,` but the repository configurations that have the imageonly attribute set to true are not ignored.

Path to the new root system.

Overwrite the first repository entry in the XML description with the provided information:

For uri://user:pass@location type repositories, set the user and password connected to the set-repo specification. If the provided value is a filename in the filesystem, the first line of that file is used as credentials.

Overwrite the source location of the base container for the selected image type. The setting is only effective if the configured image type is setup with an initial derived_from reference

Overwrite the container tag in the container configuration. The setting applies only if the container configuration provides an initial tag value.

Overwrite/set the attribute with the provided value in the selected build type section. Example: --set-type-attr volid=some

Overwrite/set the release-version element in the selected build type preferences section

Set the key file to be trusted and imported into the package manager database before performing any operation. This is useful if an image build validates repository and package signatures during build time. This option can be specified multiple times.

Specify a package to add (install). The option can be specified multiple times.

Specify a package to delete. The option can be specified multiple times.

Path to the root directory of the image.

Specify package to install as part of the early KIWI NG bootstrap phase. The option can be specified multiple times.

Add a container label in the container configuration metadata. It overwrites the label with the provided key-value pair if it is already defined in the XML description.

Specify package to add (install). The option can be specified multiple times.

Add a new repository to the existing repository setup in the XML description. This option can be specified multiple times. For details about the possible option values see the –set-repo information below.

For uri://user:pass@location repositories, set the user and password associated with an add-repo specification. If the provided value describes a filename in the filesystem, the first line of that file is used as credentials.

Use an existing root directory from a previous build attempt. Use with caution, because this can cause an inconsistent root tree if the existing contents does not fit to the previous image type setup.

Delete repository cache for each of the used repositories before installing any package. This is useful when an image build validates the signature of the package from the original repository source for any build. Some package managers unconditionally trust the contents of the cache, which works for cache data dedicated to one build. In case of KIWI NG, the cache is shared between multiple image builds on that host for performance reasons.

Specify package to delete. The option can be specified multiple times.

Path to an XML description. This is a directory containing at least one _config.xml_ or _*.kiwi_ XML file.

Ignore all repository configurations from the XML description. This option is used in combination with the --add-repo` option. Otherwise, there are no repositories available for an image build, which leads to an error.

Works the same way as --ignore-repos, except that repository configuration with the imageonly attribute set to true is not ignored.

Overwrite the first repository entry in the XML description with the provided information:

For uri://user:pass@location type repositories, set the user and password connected to the set-repo specification. If the provided value describes a filename in the filesystem, the first line of that file is used as credentials.

Overwrite the source location of the base container for the selected image type. The setting applies only if the configured image type is setup with an initial derived_from reference.

Overwrite the container tag in the container configuration. The setting is only effective if the container configuration provides the initial tag value.

Overwrite/set the attribute with the provided value in the selected build type section. Example: --set-type-attr volid=some

Overwrite/set the release-version element in the selected build type preferences section

Set the key file to be trusted and imported into the package manager database before performing any operation. This is useful when an image build validates repository and package signatures during build time. This option can be specified multiple times.

Path to store the build results.

Path to the image root directory. This directory is normally created by the kiwi prepare command. Keep in mind that if the specified directory is not created using the kiwi prepare command, KIWI NG stores image build metadata in the image/ directory. This directory must exist for the kiwi create command to work correctly.

Path to store the build results.

Trusted key file to be imported into the package manager database before performing any operation. This is useful if an image build validates repository and package signatures during build time. In the create step, this option only affects the boot image. This option can be specified multiple times.

The path to the root directory. If not specified, kiwi searches the root directory in build/image-root under the specified target directory.

New size of the image. The value is either a size in bytes, or it can be specified with m (MB) or g (GB). Example: 20g

Directory containing the kiwi build results.

Add repository with given source, type, alias and priority.

The description must be a directory containing a kiwi XML description and optional metadata files.

Ignore all repository configurations from the XML description. This option is usually used together with the –add-repo option. Otherwise there are no repositories available for the processing the requested image information, which could lead to an error.

list profiles available for the selected/default type.

NOTE: If the image description is designed in a way that there is no default build type configured and/or the main build type is also profiled, it’s required to provide this information to kiwi to list further profiles for this type. For example: kiwi-ng –profile top_level_entry_profile image info …

print kiwi profile environment variables. The listed variables are available in the shell environment of the kiwi hook scripts.

NOTE: The kiwi profile environment grows during the build process. When used in early stages e.g. in a post_bootstrap.sh script it can happen that not all variables have a value. The setup of the kiwi profile environment in the image info output can therefore also only list the static configuration values which are known at the beginning of a build process.

Solve package dependencies and return a list of all packages including their attributes, for example size, shasum, and more.

Print image description in the XML format. The specified image description is converted to XML and sent to the XSLT stylesheet processor. The result is then validated using the RelaxNG schema and the schematron rules. The command is normally used to convert an old image description to the latest schema.

Behaves similar to --print-xml, but after validation, the result is converted to the YAML format. The command can be used for different operations:

With QEMU’s 9pfs you can create virtual filesystem devices (virtio-9p-device) and expose them to the box. For more information see 9pfs. Using this sharing backend does not require any setup procedure from the user and is also the default for boxbuild

SSHFS is a FUSE-based filesystem client for mounting remote directories over a Secure Shell connection (SSH). In boxbuild this is used to mount directories from the host into the box. Because this runs through an SSH connection the host must allow connections from the box. If you plan to use sshfs add the following SSH public key to the ~/.ssh/authorized_keys file of the user which is expected to call boxbuild

echo "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCtiqDaYgEMkr7za7qc4iPXftgu/j3sodPOtpoG8PinwRX6/3xZteOJzCH2qCZjEgA5zsP9lxy/119cWXvdxFUvyEINjH77unzRnaHj/yTXPhHuhHgAiEubuHer2gZoOs+UH4cGJLKCrabjTjZdeK9KvL+hoAgJaWxDUvGsXYDQTBHXlKjniOL1MGbltDBHnYhu4k+PjjJ+UEBN+8+F74Y5fYgIovXXY88WQrybuEr1eAYjhvk/ln6TKw1P6uvVMuIbAGUgnZFntDCI91Qw8ps1j+lX3vNc8ZBoOwM6nHZqq4FAqbXuH+NvQFS/xDM6wwZQhAe+14dTQBA5F1mgCVf+fSbteb0/CraSGmgKIM8aPnK8rfF+BY6Jar3AJFKVRPshRzrQj6CWYu3BfmOLupCpqOK2XFyoU2lEpaZDejgPSJq/IBGZdjKplWJFF8ZRQ01a8eX8K2fjrQt/4k9c7Pjlg1aDH8Sf+5+vcehlSNs1d50wnFoaIPrgDdy04omiaJ8= kiwi@boxbuild" >> ~/.ssh/authorized_keys

The public key mentioned here is associated with an SSH key pair we provide in the pre-built box images.

Warning

If the sshfs backend is used without the host trusting the box, the boxbuild call will become interactive at the time of the sshfs mount. In this case the user might be asked for a passphrase or depending on the host sshd setup the request will be declined and the boxbuild fails.

QEMU virtio-fs shared file system daemon. Share a host directory tree with a box through a virtio-fs device. For more information see virtiofs. Using this sharing backend does not require any setup procedure from the user

Warning

virtiofs support was added but considered experimental and not yet stable across the distributions. Feedback welcome.

Exports the TERM variable into the initrd environment. If the default value for the terminal emulation is not correct, rd.kiwi.term can be used to overwrite the default. The environment is also passed to the systemd unit that calls dialog based programs in KIWI NG dracut code, which means that the TERM setting applies there too.

Activates the debug log file for the KIWI NG part of the boot process in /run/initramfs/log/boot.kiwi.

Instructs an OEM installation image to lookup the system image on a remote location specified in rd.kiwi.install.image.

Specifies the remote location of the system image in a PXE based OEM installation.

Instructs an OEM installation image to pass an additional boot parameters to the kernel used to boot the installed image. This can be used, for example, to pass on first boot configuration for a PXE image. Note that options starting with rd.kiwi are not passed to avoid side effects.

Specifies the maximum disk size an unattended OEM installation uses for image deployment. Unattended OEM deployments default to deploying on /dev/sda (or more precisely, the first device that is not filtered out by oem-device-filter). With RAID controllers, you may have big JBOD disks along with a 480G RAID1 configured for OS deployment. With rd.kiwi.oem.maxdisk=500G, the deployment is performed on the RAID disk.

Forces the disk resize process on an OEM disk image. If set, no sanity check for unpartitioned/free space is performed and also an eventually configured <oem-resize-once> configuration from the image description will not be taken into account. The disk resize will be started which includes re-partition as well as all steps to resize the block layers up to the filesystem holding the data. As rd.kiwi.oem.force_resize bypasses all sanity checks to detect if such a resize process is needed or not, it can happen that all program calls of the resize process ends without any effect if the disk is already properly resized. It’s also important to understand that the partition UUIDs will change on every resize which might be an unwanted side effect of a forced resize.

Configures the disk device to use in an OEM installation. This overwrites or resets any other OEM device-specific settings, such as oem-device-filter, oem-unattended-id or rd.kiwi.oem.maxdisk, and continues the installation on the given device. The device must exist and must be a block special.

Specifies the size for the tmpfs filesystem of a live ISO image that is used for the overlayfs mount process. If the write area of the overlayfs mount uses this tmpfs, any new data written during the runtime of the system is written in this space. The default value is 50%, meaning half of the available RAM space can be used for writing new data.

Instructs a live ISO image to prepare a persistent write partition.

Specifies which filesystem of a live ISO image to use for storing data on the persistent write partition.

Specifies the size of the COW file in MB. When using tools like live-grub-stick, the live ISO image is copied as a file on the target device, and a GRUB loopback setup is created there to boot the live system from the file. In this case, the persistent write setup that normally creates an extra write partition on the target will fail in most situations, because the target has no free and unpartitioned space available. To prevent this from happening, a COW file (live_system.cow) of a partition is created alongside the live ISO image file. The default size of the COW file is 500MB.

Effectively used in isoscan loop mounted live systems. For details on this type of live system refer to Section 11.2, “Deploy ISO Image as File on a FAT32 Formated USB Stick”. Specifies the path of the COW file below the /run/initramfs/isoscan loop mount point. If not specified the cowfile is placed at /run/initramfs/isoscan/live_system.cow.

Specifies a directory that contains the live OS root directory. Default is LiveOS.

Specifies the name of the squashfs image file which contains the OS root. Default is squashfs.img.

By default kiwi stops plymouth if present and active in the initrd. Setting rd.kiwi.allow_plymouth will keep plymouth active in the initrd including all effects that might have to the available consoles.

Allows setup of 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 which can display them correctly from the ones which can’t

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

Specifies the license name which applies to this image description.

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.

A list of profiles to which this containers selection applies (see Section 7.4, “Image Profiles”).

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

If set to true kiwi will only fetch the container but does not setup 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.

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

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.

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_-.]+

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

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

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

Specifies whether or not this specific repository is configured to to run repository signature validation. If not set, no value is appended into the repository configuration file. 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.

Custom script hook which is invoked with the repo file as parameter for each file created by KIWI NG.

Note

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

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.

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.

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.

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 like they are written into the XML description.

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.

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

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.

Bootstrap packages, 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

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

Packages to be uninstalled or deleted. For further details see Section 7.3.3, “Uninstall System Packages”

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

the UNIX username

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 it’s 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.

The path to the user’s home directory

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 ID’s can only be set for groups that does 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.

The numeric user id of this account.

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

Usable in the same way with both dracut modules. This feature allows to boot the Live ISO as a file from a grub loopback configured bootloader. The live-grub-stick tool is one example that uses this feature. For details how to setup ISO scan with the overlay module see Section 11.2, “Deploy ISO Image as File on a FAT32 Formated USB Stick”

Usable with the dmsquash module through rd.live.ram. The overlay module does not support this mode, while KIWI NG supports RAM only systems as OEM deployment into RAM from an install ISO media. For details how to setup RAM only deployments in KIWI NG see: Section 11.9, “Deploy and Run System in a RamDisk”

Usable with both dracut modules. The readonly root filesystem is overlaid with a readwrite filesystem using the kernel overlayfs filesystem.

Usable with the dmsquash module. A squashfs compressed readonly root is overlaid with a readwrite filesystem using a device mapper snapshot.

Boot the Live iso only for ISO checksum verification. This is possible with both modules but the overlay module uses the checkmedia tool, whereas the upstream dmsquash module uses checkisomd5. The verification process is triggered by passing the kernel option mediacheck for the overlay module and rd.live.check for the dmsquash module.

Boot the Live image via the network. This is possible with both modules, but it uses different technologies. The overlay module supports network boot only in combination with the AoE (Ata Over Ethernet) protocol. For details see Section 11.16, “Booting a Live ISO Image from Network”. The dmsquash module supports network boot by fetching the ISO image into memory from root=live: using the livenet module.

Keep new data persistent on a writable storage device. This can be done with both modules but in different ways. The overlay module activates persistency with the kernel boot parameter rd.live.overlay.persistent. If the persistent setup cannot be created the fallback to the non persistent mode applies automatically. The overlay module auto detects if it is used on a disk or ISO scan loop booted from a file. If booted as disk, persistency is setup on a new partition of that disk. If loop booted from file, persistency is setup on a new cow file. The cow file/partition setup can be influenced with the kernel boot parameters: rd.live.overlay.cowfs and rd.live.cowfile.mbsize. The dmsquash module configures persistency through the rd.live.overlay option exclusively and does not support the automatic creation of a write partition in disk mode.

Determines if the disk has the capability to expand itself to a new disk geometry or not. By default, this feature is activated. The implementation of the resize capability is done in a dracut module packaged as dracut-kiwi-oem-repart. If oem-resize is set to false, the installation of the corresponding dracut package can be skipped as well.

By default, the string OEM is used as the boot manager menu entry when KIWI creates the GRUB configuration during deployment. The oem-boot-title element allows you to set a custom name for the grub menu entry. This value is represented by the kiwi_oemtitle variable in the initrd.

Determines if the system waits for user interaction before continuing the boot process after the disk image has been dumped to the designated storage device (default value is false). This value is represented by the kiwi_oembootwait variable in the initrd.