kiwi.system Package

Submodules

kiwi.system.identifier Module

class kiwi.system.identifier.SystemIdentifier

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_id() → None

Calculate random hex id

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

get_id() → str

Current hex identifier

Returns:

hex id

Return type:

str

write(filename: str) → None

Write current hex identifier to file

Parameters:

filename (str) – file path name

write_to_disk(device_provider: DeviceProvider) → None

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: str)

Bases: object

Implementes kernel lookup and extraction from given root tree

Parameters:

• root_dir (str) – root directory path name

• kernel_names (list) – list of kernel names to search for functions.sh::suseStripKernel() provides a normalized file so that we do not have to search for many different names in this code

copy_kernel(target_dir: str, file_name: str | None = None) → None

Copy kernel to specified target

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

Parameters:

• target_dir (str) – target path name

• filename (str) – base filename in target

copy_xen_hypervisor(target_dir: str, file_name: str | None = None) → None

Copy xen hypervisor to specified target

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

Parameters:

• target_dir (str) – target path name

• filename (str) – base filename in target

get_kernel(raise_on_not_found: bool = False) → kernel_type | None

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:

tuple|None

get_xen_hypervisor() → xen_hypervisor_type | None

Lookup xen hypervisor and provide filename and hypervisor name

Returns:

tuple with filename and hypervisor name

Return type:

tuple|None

class kiwi.system.kernel.kernel_type(name, filename, version)

Bases: tuple

filename: str

Alias for field number 1

name: str

Alias for field number 0

version: str

Alias for field number 2

class kiwi.system.kernel.xen_hypervisor_type(filename, name)

Bases: tuple

filename: str

Alias for field number 0

name: str

Alias for field number 1

kiwi.system.prepare Module

class kiwi.system.prepare.SystemPrepare(xml_state: XMLState, root_dir: str, allow_existing: bool = False)

Bases: object

Implements preparation and installation of a new root system

Parameters:

• xml_state (object) – instance of XMLState

• root_dir (str) – Path to new root directory

• allow_existing (bool) – Allow using an existing root_dir

clean_package_manager_leftovers() → None

This methods cleans some package manager artifacts created at run time such as macros

delete_packages(manager: PackageManagerBase, packages: List, force: bool = False) → None

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.

Parameters:

• manager (object) – instance of a PackageManager subclass

• packages (list) – package list

• force (bool) – force deletion true|false

Raises:

KiwiSystemDeletePackagesFailed – if installation process fails

install_bootstrap(manager: PackageManagerBase, plus_packages: List | None = None) → None

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

Parameters:

• manager (object) – instance of a PackageManager subclass

• plus_packages (list) – list of additional packages

Raises:

KiwiBootStrapPhaseFailed – if the bootstrapping process fails either installing packages or including bootstrap archives

install_packages(manager: PackageManagerBase, packages: List) → None

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

Parameters:

• manager (object) – instance of a PackageManager subclass

• packages (list) – package list

Raises:

KiwiSystemInstallPackagesFailed – if installation process fails

install_system(manager: PackageManagerBase) → None

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: PackageManagerBase | None = None, force: bool = False) → None

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.

Parameters:

• manager (object) – instance of PackageManager subclass

• force (bool) – Forced deletion True|False

Raises:

KiwiPackagesDeletePhaseFailed – if the deletion packages process fails

setup_repositories(clear_cache: bool = False, signing_keys: List[str] | None = None, target_arch: str | None = None) → PackageManagerBase

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

Parameters:

• clear_cache (bool) – Flag the clear cache before configure anything

• signing_keys (list) – Keys imported to the package manager

• target_arch (str) – Target architecture name

Returns:

instance of PackageManager subclass

Return type:

PackageManager

update_system(manager: PackageManagerBase) → None

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

uri_list: List[Uri]

A list of Uri references

kiwi.system.profile Module

class kiwi.system.profile.Profile(xml_state: XMLState)

Bases: object

Create bash readable .profile environment from the XML description

Parameters:

xml_state (object) – instance of :class`XMLState`

add(key: str, value: str) → None

Add key/value pair to profile dictionary

Parameters:

• key (str) – profile key

• value (str) – profile value

create(filename: str) → None

Create bash quoted profile

Parameters:

filename (str) – file path name

delete(key: str) → None

get_settings() → Dict

Return all profile elements that has a value

kiwi.system.result Module

class kiwi.system.result.Result(xml_state: XMLState)

Bases: object

Collect image building results

Parameters:

• result_files (dict) – dict of result files

• class_version (object) – Result class version

• xml_state (object) – instance of XMLState

add(key: str, filename: str, use_for_bundle: bool = True, compress: bool = False, shasum: bool = True) → None

Add result tuple to result_files list

Parameters:

• 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

add_bundle_format(pattern: str)

dump(filename: str, portable: bool = True) → None

Picke dump this instance to a file

Parameters:

• filename (str) – file path name

• portable (bool) – If set to true also create a .json formatted variant of the dump file which contains the elements of this instance that could be expressed in a portable json document. Default is set to: True

Raises:

KiwiResultError – if pickle fails to dump Result instance

get_results() → Dict[str, result_file_type]

Current list of result tuples

static load(filename: str) → result_type

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() → None

Print results human readable

static verify_image_size(size_limit: int, filename: str) → None

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.

Parameters:

• size_limit (int) – The size limit for filename in bytes.

• filename (str) – File to verify.

Raises:

KiwiResultError – if filename exceeds the size limit

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

Bases: tuple

compress: bool

Alias for field number 2

filename: str

Alias for field number 0

shasum: bool

Alias for field number 3

use_for_bundle: bool

Alias for field number 1

class kiwi.system.result.result_name_tags(N, P, A, I, T, M, m, p, v)

Bases: tuple

A: str

Alias for field number 2

I: str

Alias for field number 3

M: str

Alias for field number 5

N: str

Alias for field number 0

P: str

Alias for field number 1

T: str

Alias for field number 4

m: str

Alias for field number 6

p: str

Alias for field number 7

v: str

Alias for field number 8

kiwi.system.root_bind Module

class kiwi.system.root_bind.RootBind(root_init: RootInit)

Bases: object

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

Parameters:

• 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() → None

Cleanup mounted locations, directories and intermediate config files

mount_kernel_file_systems(delta_root: bool = False) → None

Bind mount kernel filesystems

Raises:

KiwiMountKernelFileSystemsError – if some kernel filesystem fails to mount

mount_shared_directory(host_dir: str | None = None) → None

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

setup_intermediate_config() → None

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

umount_kernel_file_systems() → None

Umount kernel filesystems

Raises:

KiwiMountKernelFileSystemsError – if some kernel filesystem fails to mount

kiwi.system.root_init Module

class kiwi.system.root_init.RootInit(root_dir: str, allow_existing: bool = False)

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() → None

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 core system paths

• create static core device nodes

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

delete() → None

Force delete root directory and its contents

kiwi.system.setup Module

class kiwi.system.setup.SystemSetup(xml_state: XMLState, root_dir: str)

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.

Parameters:

• xml_state (object) – instance of XMLState

• root_dir (str) – root directory path name

call_config_host_overlay_script(working_directory: str | None = None) → None

Call config-host-overlay.sh script _NON_ chrooted

call_config_overlay_script() → None

Call config-overlay.sh script chrooted

call_config_script() → None

Call config.sh script chrooted

call_disk_script() → None

Call disk.sh script chrooted

call_edit_boot_config_script(filesystem: str, boot_part_id: int, working_directory: str | None = None) → None

Call configured editbootconfig script _NON_ chrooted

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

Parameters:

• filesystem (str) – boot filesystem name

• boot_part_id (int) – boot partition number

• working_directory (str) – directory name

call_edit_boot_install_script(diskname: str, boot_device_node: str, working_directory: str | None = None) → None

Call configured editbootinstall script _NON_ chrooted

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

Parameters:

• diskname (str) – file path name

• boot_device_node (str) – boot device node name

• working_directory (str) – directory name

call_image_script() → None

Call images.sh script chrooted

call_post_bootstrap_script() → None

Call post_bootstrap.sh script chrooted

call_pre_disk_script() → None

Call pre_disk_sync.sh script chrooted

cleanup() → None

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

create_fstab(fstab: Fstab) → None

Create etc/fstab from given Fstab object

Custom fstab modifications are possible and handled in the following order:

1. Look 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

2. Look for an optional fstab.patch file which allows to patch the current contents of the fstab file with a given patch file. Once patched the fstab.patch file will be deleted

3. Look for an optional fstab.script file which is called chrooted for the purpose of updating the fstab file as appropriate. Note: There is no validation in place that checks if the script actually handles fstab or any other file in the image rootfs. Once called the fstab.script file will be deleted

Parameters:

fstab (object) – instance of Fstab

create_init_link_from_linuxrc() → None

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_recovery_archive() → None

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_modprobe_setup(target_root_dir: str) → None

Export etc/modprobe.d to given root_dir

Parameters:

target_root_dir (str) – path name

export_package_changes(target_dir: str) → str

Export image package changelog for comparision of actual changes of the installed packages

Parameters:

target_dir (str) – path name

export_package_list(target_dir: str) → str

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

Parameters:

target_dir (str) – path name

export_package_verification(target_dir: str) → str

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

Parameters:

target_dir (str) – path name

import_cdroot_files(target_dir: str) → None

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_description() → None

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

import_files() → None

import_image_identifier() → None

Create etc/ImageID identifier file

import_overlay_files(follow_links: bool = False, preserve_owner_group: bool = False) → None

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.

In addition the method also supports profile specific overlay files which are searched in a directory of the same name as the profile name.

The overall order for including overlay files is as follows:

1. root/ dir or root.tar.gz

2. PROFILE_NAME/ dir(s) in the order of the selected profiles

Parameters:

• follow_links (bool) – follow symlinks true|false

• preserve_owner_group (bool) – preserve permissions true|false

import_repositories_marked_as_imageinclude() → None

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

script_exists(name: str) → bool

Check if provided script base name exists in the image description

Parameters:

name (str) – script base name

set_selinux_file_contexts(security_context_file: str) → None

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

Parameters:

security_context_file (str) – path file name

setup_groups() → None

Add groups for configured users

setup_keyboard_map() → None

Setup console keyboard

setup_locale() → None

Setup UTF8 system wide locale

setup_machine_id() → None

Setup systemd machine id

There are various states of /etc/machine-id:

1. Does not exist: Triggers ConditionFirstBoot, but does not work if the filesystem is initially read-only (booted without “rw”).

2. Exists, is empty: Does not trigger ConditionFirstBoot, but works with read-only mounts.

3. Exists, contains the string “uninitialized”: Same as b), but triggers ConditionFirstBoot. Supported by systemd v247+ only.

4. Exists, contains a valid ID.

See the machine-id(5) man page for details.

In images, d) is not desirable, so truncate the file. This is the previous behaviour and what existing images expect. If the image has one of the other states, keep it as-is.

setup_permissions() → None

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_plymouth_splash() → None

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_registry_import() → None

Fetch container(s) and activate systemd unit to load containers from local oci-archive file during boot

setup_selinux_file_contexts() → None

Set SELinux file security contexts if the default context file is found

setup_timezone() → None

Setup timezone symlink

setup_users() → None

Add/Modify configured users

kiwi.system.shell Module

class kiwi.system.shell.Shell

Bases: object

Special character handling for shell evaluated code

static format_to_variable_value(value: Any | None) → str

Format given variable value to return a string value representation that can be sourced by shell scripts. If the provided value is not representable as a string (list, dict, tuple etc) an exception is raised

Parameters:

value (any) – a python variable

Raises:

KiwiShellVariableValueError – if value is an iterable

Returns:

string value representation

Return type:

str

static quote(message: str) → str

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

static quote_key_value_file(filename: str) → List[str]

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:

list of quoted text

Return type:

List[str]

static run_common_function(name: str, parameters: List[str]) → None

Run a function implemented in config/functions.sh

Parameters:

• name (str) – function name

• parameters (list) – function arguments

kiwi.system.size Module

class kiwi.system.size.SystemSize(source_dir: str)

Bases: object

Provide source tree size information

Parameters:

source_dir (str) – source directory path name

accumulate_files() → int

Calculate sum of all files in the source tree

Returns:

number of files

Return type:

int

accumulate_mbyte_file_sizes(exclude: List[str] | None = None) → int

Calculate data size of all data in the source tree

Parameters:

exclude (list) – list of paths to exclude

Returns:

mbytes

Return type:

int

customize(size: float, requested_filesystem: str) → int

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

Parameters:

• size (float) – mbsize to update

• requested_filesystem (str) – filesystem name

Returns:

mbytes

Return type:

int

kiwi.system.uri Module

class kiwi.system.uri.Uri(uri: str, repo_type: str = 'rpm-md', source_type: str = '')

Bases: object

Normalize and manage URI types

alias() → str

Create hex representation of uuid4

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 hex representation of uuid4

Return type:

str

credentials_file_name() → str

Filename to store repository credentials

Returns:

credentials file name

Return type:

str

get_fragment() → str

Returns the fragment part of the URI.

Returns:

fragment part of the URI if any, empty string otherwise

Return type:

str

is_public() → bool

Check if URI is considered to be publicly reachable

Returns:

True|False

Return type:

bool

is_remote() → bool

Check if URI is a remote or local location

Returns:

True|False

Return type:

bool

static print_sensitive(location: str) → str

translate(check_build_environment: bool = True) → str

Translate repository location according to their URI type

Depending on the URI type the provided location needs to be adapted e.g 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

Returns:

translated repository location

Return type:

str

kiwi.system.users Module

class kiwi.system.users.Users(root_dir: str)

Bases: object

Operations on users and groups in a root directory

Parameters:

root_dir (str) – root directory path name

group_add(group_name: str, options: List[str]) → None

Add group with options

Parameters:

• group_name (str) – group name

• options (list) – groupadd options

group_exists(group_name: str) → bool

Check if group exists

Parameters:

group_name (str) – group name

Returns:

True|False

Return type:

bool

setup_home_for_user(user_name: str, group_name: str, home_path: str) → None

Setup user home directory

Parameters:

• user_name (str) – user name

• group_name (str) – group name

• home_path (str) – path name

user_add(user_name: str, options: List[str]) → None

Add user with options

Parameters:

• user_name (str) – user name

• options (list) – useradd options

user_exists(user_name: str) → bool

Check if user exists

Parameters:

user_name (str) – user name

Returns:

True|False

Return type:

bool

user_modify(user_name: str, options: List[str]) → None

Modify user with options

Parameters:

• user_name (str) – user name

• options (list) – usermod options

Module Contents