kiwi.system Package


kiwi.system.identifier Module

class kiwi.system.identifier.SystemIdentifier[source]

Bases: object

Create a random ID to identify the system

The information is used to create the mbrid file as an example

Parameters:image_id (str) – hex identifier string

Calculate random hex id

Using 4 tuples of rand in range from 1..0xfe


Current hex identifier

Returns:hex id
Return type:str

Write current hex identifier to file

Parameters:filename (str) – file path name

Write current hex identifier to MBR at offset 0x1b8 on disk

Parameters:device_provider (object) – Instance based on DeviceProvider

kiwi.system.kernel Module

class kiwi.system.kernel.Kernel(root_dir)[source]

Bases: object

Implementes kernel lookup and extraction from given root tree

  • root_dir (str) – root directory path name
  • kernel_names (list) – list of kernel names to search for provides a normalized file so that we do not have to search for many different names in this code
copy_kernel(target_dir, file_name=None)[source]

Copy kernel to specified target

If no file_name is given the target filename is set as kernel-<kernel.version>.kernel

  • target_dir (str) – target path name
  • filename (str) – base filename in target
copy_xen_hypervisor(target_dir, file_name=None)[source]

Copy xen hypervisor to specified target

If no file_name is given the target filename is set as hypervisor-<>

  • target_dir (str) – target path name
  • filename (str) – base filename in target

Lookup kernel files and provide filename and version

Parameters:raise_on_not_found (bool) – sets the method to raise an exception if the kernel is not found
Raises:KiwiKernelLookupError – if raise_on_not_found flag is active and kernel is not found
Returns:tuple with filename, kernelname and version
Return type:namedtuple

Lookup xen hypervisor and provide filename and hypervisor name

Returns:tuple with filename and hypervisor name
Return type:namedtuple

kiwi.system.prepare Module

class kiwi.system.prepare.SystemPrepare(xml_state, root_dir, allow_existing=False)[source]

Bases: object

Implements preparation and installation of a new root system

  • xml_state (object) – instance of XMLState
  • profiles (list) – list of configured profiles
  • root_bind (object) – instance of RootBind
  • uri_list (list) – a list of Uri references
delete_packages(manager, packages, force=False)[source]

Delete one or more packages using the package manager inside of the new root directory. If the removal is set with force flag only listed packages are deleted and any dependency break or leftover is ignored.

  • manager (object) – instance of a PackageManager subclass
  • packages (list) – package list
  • force (bool) – force deletion true|false

KiwiSystemDeletePackagesFailed – if installation process fails


Install system software using the package manager from the host, also known as bootstrapping

Parameters:manager (object) – instance of a PackageManager subclass
Raises:KiwiBootStrapPhaseFailed – if the bootstrapping process fails either installing packages or including bootstrap archives
install_packages(manager, packages)[source]

Install one or more packages using the package manager inside of the new root directory

  • manager (object) – instance of a PackageManager subclass
  • packages (list) – package list

KiwiSystemInstallPackagesFailed – if installation process fails


Install system software using the package manager inside of the new root directory. This is done via a chroot operation and requires the desired package manager to became installed via the bootstrap phase

Parameters:manager (object) – instance of a PackageManager subclass
Raises:KiwiInstallPhaseFailed – if the install process fails either installing packages or including any archive
pinch_system(manager=None, force=False)[source]

Delete packages marked for deletion in the XML description. If force param is set to False uninstalls packages marked with type="uninstall" if any; if force is set to True deletes packages marked with type="delete" if any.

  • manager (object) – instance of PackageManager
  • force (bool) – Forced deletion True|False

KiwiPackagesDeletePhaseFailed – if the deletion packages process fails

setup_repositories(clear_cache=False, signing_keys=None)[source]

Set up repositories for software installation and return a package manager for performing software installation tasks

  • clear_cache (bool) – flag the clear cache before configure anything
  • signing_keys (list) – keys imported to the package manager

instance of PackageManager

Return type:



Install package updates from the used repositories. the process uses the package manager from inside of the new root directory

Parameters:manager (object) – instance of a PackageManager subclass
Raises:KiwiSystemUpdateFailed – if packages update fails

kiwi.system.profile Module

class kiwi.system.profile.Profile(xml_state)[source]

Bases: object

Create bash readable .profile environment from the XML description

The information is used by the kiwi first boot code.

  • xml_state (object) – instance of :class`XMLState`
  • dot_profile (dict) – profile dictionary
add(key, value)[source]

Add key/value pair to profile dictionary

  • key (str) – profile key
  • value (str) – profile value

Create bash quoted profile

Returns:profile dump for bash
Return type:str

kiwi.system.result Module

class kiwi.system.result.Result(xml_state)[source]

Bases: object

Collect image building results

  • result_files (list) – list of result files
  • class_version (object) – Result class version
  • xml_state (object) – instance of XMLState
add(key, filename, use_for_bundle=True, compress=False, shasum=True)[source]

Add result tuple to result_files list

  • key (str) – name
  • filename (str) – file path name
  • use_for_bundle (bool) – use when bundling results true|false
  • compress (bool) – compress when bundling true|false
  • shasum (bool) – create shasum when bundling true|false

Picke dump this instance to a file

Parameters:filename (str) – file path name
Raises:KiwiResultError – if pickle fails to dump Result instance

Current list of result tuples

classmethod load(filename)[source]

Load pickle dumped filename into a Result instance

Parameters:filename (str) – file path name
Raises:KiwiResultError – if filename does not exist or pickle fails to load filename

Print results human readable

verify_image_size(size_limit, filename)[source]

Verifies the given image file does not exceed the size limit. Throws an exception if the limit is exceeded. If the size limit is set to None no verification is done.

  • size_limit (int) – The size limit for filename in bytes.
  • filename (str) – File to verify.

KiwiResultError – if filename exceeds the size limit

class kiwi.system.result.result_file_type(filename, use_for_bundle, compress, shasum)

Bases: tuple


Alias for field number 2


Alias for field number 0


Alias for field number 3


Alias for field number 1

kiwi.system.root_bind Module

class kiwi.system.root_bind.RootBind(root_init)[source]

Bases: object

Implements binding/copying of host system paths into the new root directory

  • root_dir (str) – root directory path name
  • cleanup_files (list) – list of files to cleanup, delete
  • mount_stack (list) – list of mounted directories for cleanup
  • dir_stack (list) – list of directories for cleanup
  • config_files (list) – list of initial config files
  • bind_locations (list) – list of kernel filesystems to bind mount
  • shared_location (str) – shared directory between image root and build system root

Cleanup mounted locations, directories and intermediate config files


Bind mount kernel filesystems

Raises:KiwiMountKernelFileSystemsError – if some kernel filesystem fails to mount

Bind mount shared location

The shared location is a directory which shares data from the image buildsystem host with the image root system. It is used for the repository setup and the package manager cache to allow chroot operations without being forced to duplicate this data

Parameters:host_dir (str) – directory to share between image root and build system root
Raises:KiwiMountSharedDirectoryError – if mount fails

Change the given path elements to a new root directory

Parameters:elements (list) – list of path names
Returns:changed elements
Return type:list

Create intermediate config files

Some config files e.g etc/hosts needs to be temporarly copied from the buildsystem host to the image root system in order to allow e.g DNS resolution in the way as it is configured on the buildsystem host. These config files only exists during the image build process and are not part of the final image

Raises:KiwiSetupIntermediateConfigError – if the management of intermediate configuration files fails

kiwi.system.root_init Module

class kiwi.system.root_init.RootInit(root_dir, allow_existing=False)[source]

Bases: object

Implements creation of new root directory for a linux system

Host system independent static default files and device nodes are created to initialize a new base system

Parameters:root_dir (str) – root directory path name

Create new system root directory

The method creates a temporary directory and initializes it for the purpose of building a system image from it. This includes the following setup:

  • create static core device nodes
  • create core system paths

On success the contents of the temporary location are synced to the specified root_dir and the temporary location will be deleted. That way we never work on an incomplete initial setup

Raises:KiwiRootInitCreationError – if the init creation fails at some point

Force delete root directory and its contents

kiwi.system.setup Module

class kiwi.system.setup.SystemSetup(xml_state, root_dir)[source]

Bases: object

Implementation of system setup steps supported by kiwi

Kiwi is not responsible for the system configuration, however some setup steps needs to be performed in order to provide a minimal work environment inside of the image according to the desired image type.

  • arch (str) – platform.machine. The 32bit x86 platform is handled as ‘ix86’
  • xml_state (object) – instance of XMLState
  • description_dir (str) – path to image description directory
  • derived_description_dir – path to derived_description_dir boot image descriptions inherits data from the system image description, thus they are derived from another image description directory which is needed to e.g find system image archives, overlay files
  • root_dir (str) – root directory path name

Call script chrooted

call_edit_boot_config_script(filesystem, boot_part_id, working_directory=None)[source]

Call configured editbootconfig script _NON_ chrooted

Pass the boot filesystem name and the partition number of the boot partition as parameters to the call

  • filesystem (str) – boot filesystem name
  • boot_part_id (int) – boot partition number
  • working_directory (str) – directory name
call_edit_boot_install_script(diskname, boot_device_node, working_directory=None)[source]

Call configured editbootinstall script _NON_ chrooted

Pass the disk file name and the device node of the boot partition as parameters to the call

  • diskname (str) – file path name
  • boot_device_node (str) – boot device node name
  • working_directory (str) – directory name

Call script chrooted


Delete all traces of a kiwi description which are not required in the later image


Create etc/fstab from given list of entries

Also lookup for an optional fstab.append file which allows to append custom fstab entries to the final fstab. Once embedded the fstab.append file will be deleted

Parameters:entries (list) – list of line entries for fstab

kiwi boot images provides the linuxrc script, however the kernel also expects an init executable to be present. This method creates a hard link to the linuxrc file


Create a compressed recovery archive from the root tree for use with kiwi’s recvoery system. The method creates additional data into the image root filesystem which is deleted prior to the creation of a new recovery data set


Export etc/modprobe.d to given root_dir

Parameters:target_root_dir (str) – path name

Export image package list as metadata reference used by the open buildservice

Parameters:target_dir (str) – path name

Export package verification result as metadata reference used by the open buildservice

Parameters:target_dir (str) – path name

Copy cdroot files from the image description to the specified target directory. Supported is a tar archive named config-cdroot.tar[.compression-postfix]

Parameters:target_dir (str) – directory to unpack archive to

Import XML descriptions, custom scripts, archives and script helper methods


Create etc/ImageID identifier file

import_overlay_files(follow_links=False, preserve_owner_group=False)[source]

Copy overlay files from the image description to the image root tree. Supported are a root/ directory or a root.tar.gz tarball. The root/ directory takes precedence over the tarball

  • follow_links (bool) – follow symlinks true|false
  • preserve_owner_group (bool) – preserve permissions true|false

Those <repository> sections which are marked with the imageinclude attribute should be permanently added to the image repository configuration


Create profile environment to let scripts consume information from the XML description.

Parameters:profile (object) – instance of Profile

Initialize the security context fields (extended attributes) on the files matching the security_context_file

Parameters:security_context_file (str) – path file name

Add groups for configured users


Setup console keyboard


Setup UTF8 system wide locale


Setup systemd machine id

Empty out the machine id which was provided by the package installation process. This will instruct the dracut initrd code to create a new machine id. This way a golden image produces unique machine id’s on first deployment and boot of the image.

Note: Requires dracut connected image type

This method must only be called if the image is of a type which gets booted via a dracut created initrd. Deleting the machine-id without the dracut initrd creating a new one produces an inconsistent system


Check and Fix permissions using chkstat

Call chkstat in system mode which reads /etc/sysconfig/security to determine the configured security level and applies the appropriate permission definitions from the /etc/permissions* files. It’s possible to provide those files as overlay files in the image description to apply a certain permission setup when needed. Otherwise the default setup as provided on the package level applies.

It’s required that the image root system has chkstat installed. If not present KIWI skips this step and continuous with a warning.


Setup the KIWI configured splash theme as default

The method uses the plymouth-set-default-theme tool to setup the theme for the plymouth splash system. Only in case the tool could be found in the image root, it is assumed plymouth splash is in use and the tool is called in a chroot operation


Setup timezone symlink


Add/Modify configured users Module


Bases: object

Special character handling for shell evaluated code

classmethod quote(message)[source]

Quote characters which have a special meaning for bash but should be used as normal characters. actually I had planned to use pipes.quote but it does not quote as I had expected it. e.g ‘name_wit_a_$’ does not quote the $ so we do it on our own for the scope of kiwi

Parameters:message (str) – message text
Returns:quoted text
Return type:str
classmethod quote_key_value_file(filename)[source]

Quote given input file which has to be of the form key=value to be able to become sourced by the shell

Parameters:filename (str) – file path name
Returns:quoted text
Return type:str
classmethod run_common_function(name, parameters)[source]

Run a function implemented in config/

  • name (str) – function name
  • parameters (list) – function arguments

kiwi.system.size Module

class kiwi.system.size.SystemSize(source_dir)[source]

Bases: object

Provide source tree size information

Parameters:source_dir (str) – source directory path name

Calculate sum of all files in the source tree

Returns:number of files
Return type:int

Calculate data size of all data in the source tree

Parameters:exclude (list) – list of paths to exclude
Return type:int
customize(size, requested_filesystem)[source]

Increase the sum of all file sizes by an empiric factor

Each filesystem has some overhead it needs to manage itself. Thus the plain data size is always smaller as the size of the container which embeds it. This method increases the given size by a filesystem specific empiric factor to ensure the given data size can be stored in a filesystem of the customized size

  • size (int) – mbsize to update
  • requested_filesystem (str) – filesystem name


Return type:


kiwi.system.uri Module

class kiwi.system.uri.Uri(uri, repo_type=None)[source]

Bases: object

Normalize url types available in a kiwi configuration into standard mime types

  • repo_type (str) – repository type name. Only needed if the uri is not enough to determine the repository type e.g for yast2 vs. rpm-md obs repositories
  • uri (str) – URI, repository location, file
  • mount_stack (list) – list of mounted locations
  • remote_uri_types (dict) – dictionary of remote uri type names
  • local_uri_type (dict) – dictionary of local uri type names

Create hexdigest from URI as alias

If the repository definition from the XML description does not provide an alias, kiwi creates one for you. However it’s better to assign a human readable alias in the XML configuration

Returns:alias name as hexdigest
Return type:str

Filename to store repository credentials

Returns:credentials file name
Return type:str

Returns the fragment part of the URI.

Returns:fragment part of the URI if any, None otherwise
Return type:str, None

Check if URI is considered to be publicly reachable

Returns:True or False
Return type:bool

Check if URI is a remote or local location

Returns:True or False
Return type:bool

Translate repository location according to their URI type

Depending on the URI type the provided location needs to be adapted e.g loop mounted in case of an ISO or updated by the service URL in case of an open buildservice project name

Raises:KiwiUriStyleUnknown – if the uri scheme can’t be detected, is unknown or it is inconsistent with the build environment
Parameters:check_build_environment (bool) – specify if the uri translation should depend on the environment the build is called in. As of today this only effects the translation result if the image build happens inside of the Open Build Service
Return type:str

kiwi.system.users Module

class kiwi.system.users.Users(root_dir)[source]

Bases: object

Operations on users and groups in a root directory

Parameters:root_dir (str) – root directory path name
group_add(group_name, options)[source]

Add group with options

  • group_name (str) – group name
  • options (list) – groupadd options

Check if group exists

Parameters:group_name (str) – group name
Returns:True or False
Return type:bool
setup_home_for_user(user_name, group_name, home_path)[source]

Setup user home directory

  • user_name (str) – user name
  • group_name (str) – group name
  • home_path (str) – path name
user_add(user_name, options)[source]

Add user with options

  • user_name (str) – user name
  • options (list) – useradd options

Check if user exists

Parameters:user_name (str) – user name
Return type:bool
user_modify(user_name, options)[source]

Modify user with options

  • user_name (str) – user name
  • options (list) – usermod options

Module Contents