13 Python API #

Extract selected command name

Extract argument dict for selected command

Extract argument dict for global arguments

Extract service name from argument parse result

Loads task class plugin according to service and command name

Execute man to show the selected manual page

Execute a program and return an io file handle pair back. stdout and stderr are both on different channels. The caller must read from the output file handles in order to actually run the command. This can be done using the CommandIterator from command_process

Example:

process = Command.call(['ls', '-l'])

Execute a program and block the caller. The return value is a CommandT namedtuple containing the stdout, stderr and return code information. Unless raise_on_error is set to False an exception is thrown if the command exits with an error code not equal to zero. If raise_on_command_not_found is False and the command is not found, then None is returned.

Example:

result = Command.run(['ls', '-l'])

Alias for field number 2

Alias for field number 3

Alias for field number 0

Alias for field number 1

Alias for field number 4

Alias for field number 1

Alias for field number 0

Alias for field number 2

command () – instance of subprocess

Provide return value from processed command

Provide data which was sent to the stderr channel

Provide process ID of command while running

Send kill signal SIGTERM to command process

create a matcher function pointer which calls the given method as method(item_to_match, data) on dereference

Iterate over process, raise on error and log output

Iterate over process don’t raise on error and log stdout and stderr

Iterate over process and show progress in percent raise on error and log output

Implements get method for profile elements

Provides list of supported archive image types

Provides bios core boot binary name

Provides BIOS directory name which stores the pc binaries

Provide default loader entries directory for BLS loaders

Provides the path to find custom kiwi boot descriptions

Provides the file path to bootloader strip metadata. This file contains information about the files and directories automatically striped out from the kiwi initrd

Provides the base name of the environment file in a buildservice worker

Provides the file path to config functions metadata.

This file contains bash functions used for system configuration or in the boot code from the kiwi initrd

Provides the tag used to identify base layers during the build of derived images.

Provides default container compression

Provides list of supported container image types

Returns the rpm bootstrap macro file name created in the custom rpm macros path

Returns the rpm image macro file name created in the custom rpm macros path

Returns the custom macros directory for the rpm database.

Provides default boot partition size in mbytes

Provides default boot timeout in seconds

Return default bootloader name which is grub2

Provides the default ‘created by’ history entry for containers.

Provides the default container name.

Provides the default container subcommand.

Provides the default container tag.

Provides the default initial disk sector for the first disk partition.

Provides default EFI partition size in mbytes

Provides the default partition table type for efi firmwares.

Provides default firmware for specified architecture

Provides default size of inodes in bytes. This is only relevant for inode based filesystems

Provides default size of bios_grub partition in mbytes

Provides default live iso root filesystem type

Provides default live iso union type

Returns the default package manager name if none is configured in the image description

Provides the packager tool according to the package manager

Provides default size of prep partition in mbytes

Provides default URI type

Absolute path specifications used in the context of an URI will apply the specified default mime type

Uses auto mode for default video. See get_video_mode_map for details on the value depending which bootloader is used

Provides default LVM volume group name

Provides arch specific partition UUIDs as defined by the UAPI group

Provides supported disk format types

Provides supported disk image types

Provides file path of dracut config file to be used with KIWI

Provides list of EC2 capable firmware names. These are those for which kiwi supports the creation of disk images bootable within the Amazon EC2 public cloud

Provides list of EFI capable firmware names. These are those for which kiwi supports the creation of an EFI bootable disk image

Provides architecture specific EFI boot binary name

Provides architecture specific EFI directory name which stores the EFI binaries for the desired architecture.

Provides EFI vendor directory if present

Looks up distribution specific EFI vendor directory

Provides supported enclave(initrd-only) image types

Provides the list of folders that are not associated with a physical device. KIWI returns the basename of the folders typically used as mountpoint for those devices.

Provides list of files/dirs to exclude from the removed files detection in a delta root build

Provides the list of files or folders that are created by KIWI for its own purposes. Those files should be not be included in the resulting image.

Provides the list of folders that are excluded by the optional metadata file image/exclude_files.yaml

Provides failsafe boot kernel options

Provides list of supported filesystem image types

Provides supported architecture specific firmware types

Provides list of basic grub modules

Provides grub bios image

Searches distribution specific locations to find the core bios image below the given root path

Provides list of grub bios modules

Provides grub2 data directory name in boot/ directory

Depending on the distribution the grub2 boot path could be either boot/grub2 or boot/grub. The method will decide for the correct base directory name according to the name pattern of the installed grub2 tools

Provides distribution specific EFI font directory used with grub.

Provides list of grub efi modules

Provides list of grub ofw modules (ppc)

Provides grub path to given search file

Depending on the distribution grub could be installed below a grub2 or grub directory. grub could also reside in /usr/lib as well as in /usr/share. Therefore this information needs to be dynamically looked up

The method returns the path to the given grub search file. By default it raises a KiwiBootLoaderGrubDataError exception if the file could not be found in any of the search locations. If raise_on_error is set to False and no file could be found the function returns None

Provides list of grub ofw modules (s390)

Provides the path to an imported root system image

If the image description specified a derived_from attribute the file from this attribute is copied into the root_dir using the name as provided by this method

Provides default value for ISO volume ID for install media

Provides arch specific relative path to boot files on kiwi iso filesystems

Return name of eltorito grub image used as ISO loader

Return name of hybrid MBR image used as ISO boot record

Provides default iso media tag tool

Provides default iso tool category

Provides supported kis image types

Provides flag_name to dracut modules name map

Depending on the value of the flag attribute in the KIWI image description specific dracut modules need to be selected

Provides supported live image types

Provides list of boot options passed to the dracut kiwi-live module to setup persistent writing

Provides key length to use for random luks keys

Provides empiric LVM overhead size in mbytes

Provides default minimum partition size in mbytes

Provides default minimum LVM volume size in mbytes per filesystem

Provides Mok Manager file path

Searches distribution specific locations to find the Mok Manager EFI binary

Provides the default API server url to access the public open buildservice API

Provides the default download server url hosting the public open buildservice repositories

Provides the default OCI archive tool name.

Provides the default partition mapper tool name.

Provides the machine architecture name as used by KIWI

This is the architecture name as it is returned by ‘uname -m’ with one exception for the 32bit x86 architecture which is handled as ‘ix86’ in general

Provides ISO preparer name

Return name of profile file for given root directory

Provides ISO publisher name

Provides spare size of recovery partition in mbytes

Provides base file name to store removed files in a delta root build

Provides file path to kiwi RelaxNG schema

Provides module name for XML SchemaTron validations

Provides the shared cache location

This is a directory which shares data from the image buildsystem host with the image root system. The location is returned as an absolute path stripped off by the leading ‘/’. This is because the path is transparently used on the host /<cache-dir> and inside of the image imageroot/<cache-dir>

Provides shim loader file path

Searches distribution specific locations to find shim.efi below the given root path

Provides shim vendor directory

Searches distribution specific locations to find shim.efi below the given root path and return the directory name to the file found

Provides shim signed grub loader file path

Searches distribution specific locations to find a grub EFI binary within the given root path

Provides the default configuration template file for snapper. The location in etc/ are preferred over files in usr/

Provides the directory to store SAT solvables for repositories. The solvable files are used to perform package dependency and metadata resolution

Provides swapsize in MB

Provides list of default data sync options

Provides base file name to store system files in a container build

Provides the base temp directory location

This is the directory used to store any temporary files and directories created by kiwi during runtime

Provides unsigned grub efi loader file path

Searches distribution specific locations to find a distro grub EFI binary within the given root path

Provides the default value for vagrantconfig.virtualbox_guest_additions_present

Provides video mode map

Assign a tuple to each kernel vesa hex id for each of the supported bootloaders

Provides default value for ISO volume ID

Provides the file path to the KIWI XSLT style sheets

Provides compression options for the xz compressor

Checks if build host is an open buildservice machine

The presence of /.buildenv on the build host indicates we are building inside of the open buildservice

Checks if machine architecture is ppc64 based

Any arch that matches little endian or big endian ppc64 architecture causes the method to return True. Anything else will cause the method to return False

Checks if machine architecture is x86 based

Any arch that matches 32bit and 64bit x86 architecture causes the method to return True. Anything else will cause the method to return False

Provides the python module base directory search path

The method uses the importlib.resources.path method to identify files and directories from the application

Sets the runtime config file once

Sets the platform architecture once

Sets the runtime checker metadata filename

Sets the shared cache location once

Sets the temp directory location once

Implements method to add list of profile keys and their values to the specified instance of a Profile class

Alias for field number 1

Alias for field number 0

Alias for field number 1

Alias for field number 0

Alias for field number 0

Alias for field number 3

Alias for field number 1

Alias for field number 2

message () – Exception message text

Check if BIOS mode is requested

Check if EC2 mode is requested

Check if EFI mode is requested

Size of EFI partition. Returns 0 if no such partition is needed

Size of legacy bios_grub partition if legacy BIOS mode is required. Returns 0 if no such partition is needed

Provides partition table type according to architecture and firmware

Size of Prep partition if OFW mode is requested. Returns 0 if no such partition is needed

Check if the legacy boot from BIOS systems should be activated

Check if OFW mode is requested

Check if Opal mode is requested

Call man to show the command specific manual page

All kiwi commands store their manual page in the section ‘8’ of the man system. The calling process is replaced by the man process

doc () – docopt doc string

command_usage () – usage data

name () – name of the logger

Return logging flags

Return currently used log level

Return file path name of logfile

Custom progress log information. progress information is intentionally only logged to stdout and will bypass any handlers. We don’t want this information to show up in the log file

Set logging flag for further properties of the logging facility Available flags are:

Set custom log level for all console handlers

if both except_for and only_for handlers are specified, the except_for list will be ignored

Set color format for all console handlers

Set log socket handler

Set logfile handler

Creates a logging Formatter with support for color messages

Message formatter with support for embedded color sequences

The Message is allowed to contain the following color metadata:

The color of the message depends on the level and is defined in the ColorMessage constructor

Only messages with record level DEBUG can pass for messages with another level an extra handler is used

Only messages with record level DEBUG can pass for messages with another level an extra handler is used

Only messages with record level INFO can pass for messages with another level an extra handler is used

Messages from apscheduler scheduler instances are filtered out They conflict with console progress information

Only messages with record level WARNING can pass for messages with another level an extra handler is used

Bind mount the device to the mountpoint

Return attributes dict for this mount manager

Check if mounted

Standard mount the device to the mountpoint

tmpfs mount the device to the mountpoint

Umount by the mountpoint directory

Wait up to 10sec trying to umount. If the resource stays busy the call will raise an exception unless raise_on_busy is set to False. In case the umount failed and raise_on_busy is set to False, the method returns False to indicate the error condition.

Umount by the mountpoint directory in lazy mode

Release the mount in any case, however the time when the mounted resource is released by the kernel depends on when the resource enters the non busy state

Check whether path can be accessed with the given mode.

Create path and all sub directories to target

Change the given path elements to a new root directory

Include the root prefix for the given paths elements

Recursively remove an empty path and its sub directories starting at a given root directory. Ignore non empty or protected paths and leave them untouched

Sort given list of path names by their hierachy in the tree

Example:

result = Path.sort_by_hierarchy(['/var/lib', '/var'])

Lookup file name in PATH

Delete path and all contents

Check if we are effectively root on the system. If not an exception is thrown

When building wsl images there are some naming conventions that must be fulfilled to run the container on Microsoft Windows

If a kiwi initrd is used, a lookup to the specified boot description is done and fails early if it does not exist

If a kiwi initrd is used, the kernel used to build the kiwi initrd and the kernel used in the system image must be the same in order to avoid an inconsistent boot setup

When creating container images the specific tools are used in order to import and export OCI or Docker compatible images. This check searches for those tools to be installed in the build system and fails if it can’t find them

OEM images if configured to use dracut as initrd system requires the KIWI provided dracut-kiwi-oem-repart module to be installed at the time dracut is called. Thus this runtime check examines if the required package is part of the package list in the image description.

Disk images configured to use a root filesystem overlay requires the KIWI provided kiwi-overlay dracut module to be installed at the time dracut is called. Thus this runtime check examines if the required package is part of the package list in the image description.

Live ISO images uses a dracut initrd to boot and requires the KIWI provided kiwi-live dracut module to be installed at the time dracut is called. Thus this runtime check examines if the required package is part of the package list in the image description.

OEM images if configured to use dracut as initrd system and configured with one of the installiso, installstick or installpxe attributes requires the KIWI provided dracut-kiwi-oem-dump module to be installed at the time dracut is called. Thus this runtime check examines if the required package is part of the package list in the image description.

KIWI images which makes use of kiwi dracut modules has to use module versions compatible with the version of this KIWI builder code base. This is important to avoid inconsistencies between the way how kiwi includes its own dracut modules and former version of those dracut modules which could be no longer compatible with the builder. Therefore this runtime check maintains a min_version constraint for which we know this KIWI builder to be compatible with.

Verify that the efifatimagesize does not exceed the max El Torito load size of 65535 * 512 bytes

Disk images configured to use a root filesystem overlay only supports the standard EFI mode and not secure boot. That’s because the shim setup performs changes to the root filesystem which can not be applied during the bootloader setup at build time because at that point the root filesystem is a read-only squashfs source.

Verify that all repos marked with the imageinclude attribute can be resolved into a http based web URL

Verify that the selected image type is unique within the range of the configured types and profiles.

Kiwi requires a <version> element to be specified as part of at least one <preferences> section.

Raise for still included <include> statements as not resolvable. The KIWI XSLT processing replaces the specified include directive(s) with the given file reference(s). If this action did not happen for example on nested includes, it can happen that they stay in the document as sort of waste.

If the boot attribute is used without selecting kiwi as the initrd_system, the setting of the boot attribute will not have any effect. We assume that configurations which explicitly specify the boot attribute wants to use the custom kiwi initrd system and not dracut.

Options set via the luksformat element are passed along to the cryptsetup tool. Only options that are known to the tool should be allowed. Thus this runtime check looks up the provided option names if they exist in the cryptsetup version used on the build host

If the image description enables the mediacheck attribute the required tools to run this check must be installed on the image build host

The devicepersistency setting by-partuuid can only be used in combination with a partition table type that supports UUIDs. In any other case Linux creates artificial values for PTUUID and PARTUUID from the disk signature which can change without touching the actual partition table. We consider this unsafe and only allow the use of by-partuuid in combination with partition tables that actually supports it properly.

Verify that there are repositories configured

The optional oem-swapname is only effective if used together with the LVM volume manager. A name for the swap space can only be set if it is created as a LVM volume. In any other case the name does not apply to the system

The target directory must be outside of the kiwi shared cache directory in order to avoid busy mounts because kiwi bind mounts the cache directory into the image root tree to access host caching information

The optional volume label in a systemdisk setup is only effective if the LVM, logical volume manager system is used. In any other case where the filesystem itself offers volume management capabilities there are no extra filesystem labels which can be applied per volume

The volume size specification ‘all’ makes this volume to take the rest space available on the system. It’s only allowed to specify one all size volume

The root volume in a systemdisk setup is handled in a special way. It is not allowed to setup a custom name or mountpoint for the root volume. Therefore the size of the root volume can be setup via the @root volume name. This check looks up the volume setup and searches if there is a configuration for the ‘/’ mountpoint which would cause the image build to fail

If the image is classified to be used as Xen image, it can be either a Xen Server(dom0) or a Xen guest. The image configuration is checked if the information uniquely identifies the image as such

Alias for field number 1

Alias for field number 0

reread () – reread runtime config

Return boolean value to express if the image bundle should contain XZ compressed image results or not.

If compression of image build results is activated the size of the bundle is smaller and the download speed increases. However the image must be uncompressed before use

If no compression is explicitly configured, the provided default value applies

Return compression for container images

if no or invalid configuration data is provided, the default compression from the Defaults class is returned

Return verification metadata signing key file, used for signature creation of rootfs verification metadata:

There is no default value for this setting available

Returns disabled runtime checks. Checks can be disabled with:

if the provided string does not match any RuntimeChecker method it is just ignored.

Return media tag tool used to checksum iso images

if no or invalid configuration exists the default media tagger from the Defaults class is returned

Return tool category which should be used to build iso images

if no or invalid configuration exists the default tool category from the Defaults class is returned

Return partition mapper tool

if no configuration exists the default tool from the Defaults class is returned

Returns the maximum allowed size of the built image. The value is returned in bytes and it is specified in build_constraints element with the max_size attribute. The value can be specified in bytes or it can be specified with m=MB or g=GB.

if no configuration exists None is returned

Return OBS API credentials if configured:

Return URL of buildservice API server in:

if no configuration exists the API server from the Defaults class is returned

Return URL of buildservice download server in:

if no configuration exists the downloadserver from the Defaults class is returned

Return OCI archive tool which should be used on creation of container archives for OCI compliant images, e.g docker

if no configuration exists the default tool from the Defaults class is returned

Return boolean value to express if the image build and bundle should contain a .changes file. The .changes file contains the package changelog information from all packages installed into the image.

By default the creation is switched on. When building in the Open Build Service the default is switched off because obs provides a .report file containing the same information.

Return list of XZ compression options in:

if no configuration exists None is returned

Check if the buildservice configuration is public or private in:

if no configuration exists we assume to be public

Return the xml etree parse result for the specified extension namespace

Read XML description, validate it against the schema and the schematron rules and pass it to the autogenerated(generateDS) parser.

Alias for field number 1

Alias for field number 2

Alias for field number 4

Alias for field number 3

Alias for field number 5

Alias for field number 0

Alias for field number 1

Alias for field number 2

Alias for field number 0

Adds a new label in the containerconfig section, if a label with the same name is already defined in containerconfig it gets overwritten by this method.

Add a new repository section at the end of the list

Check if setting a default volume for btrfs is requested

Tests if the given namedcollection section is applicable for the current host architecture. If no architecture is specified within the section it is considered as a match returning True.

Note: The XML section pointer must provide an arch attribute

Tests if the given container section is applicable for the current host architecture. If no arch attribute is provided in the section it is considered as a match and returns: True.

Tests if the given containers section is applicable for the current host architecture. If no arch attribute is provided in the section it is considered as a match and returns: True.

Copy packages marked as bootdelete to the packages type=delete section in the target xml state

Copy archives marked as bootinclude to the packages type=bootstrap section in the target xml state

Copy packages marked as bootinclude to the packages type=bootstrap section in the target xml state. The package will also be removed from the packages type=delete section in the target xml state if present there

Copy bootloader section from this xml state to the target xml state

Copy specified attributes from this build type section to the target xml state build type section

Copy image displayname from this xml state to the target xml state

Copy drivers sections from this xml state to the target xml state

Copy machine sections from this xml state to the target xml state

Copy image name from this xml state to the target xml state

Copy oemconfig sections from this xml state to the target xml state

Copy subsections of the preferences sections, matching given section names, from this xml state to the target xml state

Copy repository sections from this xml state to the target xml state

Copy strip sections from this xml state to the target xml state

Copy systemdisk sections from this xml state to the target xml state

Delete all repository sections matching configured profiles

Delete all repository sections used to build the image matching configured profiles

Dict of archive names and target dirs for packages section(s), if any :return: archive names and its target dir :rtype: dict

List of custom options used in the bootloader configuration

List of custom options used in the bootloader installation

List of custom options used in the process to run bootloader setup workloads

List of custom options used in the process to setup secure boot

List of archive names from the type=”bootstrap” packages section(s)

Dict of archive names and target dirs from the type=”bootstrap” packages section(s) :return: archive names and its target dir :rtype: dict

Collection type for packages sections matching type=”bootstrap”

List of collection names from the packages sections matching type=”bootstrap”

List of file names from the type=”bootstrap” packages section(s)

List of ignore package names from the packages sections matching type=”image” and type=build_type

bootstrap_package name from type=”bootstrap” packages section

List of package names from the type=”bootstrap” packages section(s)

The list gets the selected package manager appended if there is a request to install packages inside of the image via a chroot operation

List of packages sections matching type=”bootstrap”

List of product names from the packages sections matching type=”bootstrap”

Return bootloader bls setting for selected build type

Return bootloader console setting for selected build type

Return bootloader name for selected build type

First bootloader section from the build type section

First securelinux section from the build type bootloader section

Return bootloader serial line setup parameters for the selected build type

First bootloadersettings section from the build type bootloader section

Return bootloader target type setting. Only relevant for the zipl bootloader because zipl is installed differently depending on the storage target it runs later

Return bootloader timeout setting for selected build type

Return bootloader timeout style setting for selected build type

Indicate whether the bootloader configuration should use the password protecting the encrypted root volume.

Return bundle_format for build type

The bundle_format string is validated against the available name tags from kiwi.system.result::result_name_tags.

First containerconfig section from the build type section

Disk format options returned as a dictionary

First machine section from the build type section

Default build type name

First oemconfig section from the build type section

First partitions section from the build type section

Size information from the build type section. If no unit is set the value is treated as mbytes

Build type specific list of filesystem attributes applied to the spare partition.

Size information for the spare_part size from the build type. If no unit is set the value is treated as mbytes

First system disk section from the build type section

Size of the unpartitioned area for image in megabytes

First vagrantconfig section from the build type section

List of vmconfig-entry section values from the first machine section in the build type section

First vmdisk section from the first machine section in the build type section

First vmdvd section from the first machine section in the build type section

vmnic section(s) from the first machine section in the build type section

Dict of collection modules to enable and/or disable

Collection type from packages sections matching given section type.

If no collection type is specified the default collection type is set to: onlyRequired

List of collection names from the packages sections matching type=section_type and type=build_type

Dictionary of containerconfig information

Takes attributes and subsection data from the selected <containerconfig> section and stores it in a dictionary

List of all containers sections for the selected profiles that matches the host architecture

Uri object(s) of derived image if configured

Specific image types can be based on one ore more derived images. This method returns the location of this image(s) when configured in the XML description

The description section

First disk sector number to be used by the first disk partition.

Extract the distribution name from the boot attribute of the build type section.

If no boot attribute is configured or the contents does not match the kiwi defined naming schema for boot image descriptions, an exception is thrown

List of driver names from all drivers sections matching configured profiles

List of root filesystem creation options

The list contains elements with the information from the fscreateoptions attribute string that got split into its substring components

List of root filesystem mount options

The list contains one element with the information from the fsmountoptions attribute. The value there is passed along to the -o mount option

List of ignore package names from the packages sections matching section_type and type=build_type

List of packages sections matching type=”image”

Image version from preferences section.

Multiple occurences of version in preferences sections are not forbidden, however only the first version found defines the final image version

List of all <include> section file name references

Name of initrd system to use

Depending on the image type a specific initrd system is either pre selected or free of choice according to the XML type setup.

Gets the list of modules to append in installation initrds

Gets list of locale names if configured. Takes the first locale setup from the existing preferences sections into account.

Return key or passphrase credentials to open the luks pool

Return list of luks format options

State value to activate multipath maps. Returns a boolean value if specified or False

State value to activate/deactivate disk resize. Returns a boolean value if specified or True to set resize on by default

State value to retrieve root partition size

Return swapsize in MB if requested or None

Operates on the value of oem-swap and if set to true returns the given size or the default value.

Return the swap space name

Operates on the value of oem-swapname and if set returns the configured name or the default name: LVSwap

The name of the swap space is used only if the image is configured to use the LVM volume manager. In this case swap is a volume and the volume takes a name. In any other case the given name will have no effect.

Get configured package manager from selected preferences section

List of package sections from the given packages sections. Each list element contains a tuple with the <package> section reference and the <packages> section this package belongs to

If a package entry specfies an architecture, it is only taken if the host architecture matches the configured architecture

List of packages sections matching given section type(s)

Dictionary of configured partitions.

Each entry in the dict references a ptable_entry_type Each key in the dict references the name of the partition entry as handled by KIWI

All preferences sections for the selected profiles that match the host architecture

List of product names from the packages sections matching type=section_type and type=build_type

Get configured release version from selected preferences section

Get list of signing keys specified on the repositories

List of all repository sections for the selected profiles that matches the host architecture

List of all repositorys sections used to build the image and matching configured profiles.

List of all repositorys sections to be configured in the resulting image matching configured profiles.

Return preserved UUID

Return preserved PARTUUID

Gets the rpm-check-signatures configuration flag. Returns False if not present.

Gets the rpm-excludedocs configuration flag. Returns False if not present.

Gets list of locale names to filter out by rpm if rpm-locale-filtering is switched on the the list always contains: [POSIX, C, C.UTF-8] and is extended by the optionaly configured locale

Gets the rpm-locale-filtering configuration flag. Returns False if not present.

Items to delete from strip section

Libraries to keep from strip section

List of strip names matching the given section type and profiles

Tools to keep from strip section

List of archive names from the packages sections matching type=”image” and type=build_type

Dict of archive names and its target dir from the packages sections matching type=”image” and type=build_type :return: archive names and its target dir :rtype: dict

Collection type for packages sections matching type=”image”

List of collection names from the packages sections matching type=”image”