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

Calculate random hex id

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

get_id()

Current hex identifier

Returns

hex id

Return type

str

write(filename)

Write current hex identifier to file

Parameters

filename (str) – file path name

write_to_disk(device_provider)

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)

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, file_name=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, file_name=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=False)

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

get_xen_hypervisor()

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)

Bases: object

Implements preparation and installation of a new root system

Parameters

• 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

clean_package_manager_leftovers()

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

delete_packages(manager, packages, force=False)

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, plus_packages=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, packages)

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)

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)

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

• force (bool) – Forced deletion True|False

Raises

KiwiPackagesDeletePhaseFailed – if the deletion packages process fails

setup_repositories(clear_cache=False, signing_keys=None)

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

Returns

instance of PackageManager

Return type

PackageManager

update_system(manager)

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)

Bases: object

Create bash readable .profile environment from the XML description

The information is used by the kiwi first boot code.

Parameters

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

• dot_profile (dict) – profile dictionary

add(key, value)

Add key/value pair to profile dictionary

Parameters

• key (str) – profile key

• value (str) – profile value

create(filename)

Create bash quoted profile

Parameters

filename (str) – file path name

delete(key)

get_settings()

Return all profile elements that has a value

kiwi.system.result Module

class kiwi.system.result.Result(xml_state)

Bases: object

Collect image building results

Parameters

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

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

dump(filename)

Picke dump this instance to a file

Parameters

filename (str) – file path name

Raises

KiwiResultError – if pickle fails to dump Result instance

get_results()

Current list of result tuples

static load(filename)

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

Print results human readable

verify_image_size(size_limit, filename)

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

Alias for field number 2

filename

Alias for field number 0

shasum

Alias for field number 3

use_for_bundle

Alias for field number 1

kiwi.system.root_bind Module

class kiwi.system.root_bind.RootBind(root_init)

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

Cleanup mounted locations, directories and intermediate config files

mount_kernel_file_systems()

Bind mount kernel filesystems

Raises

KiwiMountKernelFileSystemsError – if some kernel filesystem fails to mount

mount_shared_directory(host_dir=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()

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

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, allow_existing=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()

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

Force delete root directory and its contents

kiwi.system.setup Module

class kiwi.system.setup.SystemSetup(xml_state, root_dir)

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

• arch (str) – Defaults.get_platform_name

• 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_config_script()

Call config.sh script chrooted

call_disk_script()

Call disk.sh script chrooted

call_edit_boot_config_script(filesystem, boot_part_id, working_directory=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, boot_device_node, working_directory=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()

Call images.sh script chrooted

cleanup()

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

create_fstab(fstab)

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 (list) – instance of Fstab

create_init_link_from_linuxrc()

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

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)

Export etc/modprobe.d to given root_dir

Parameters

target_root_dir (str) – path name

export_package_changes(target_dir)

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

Parameters

target_dir (str) – path name

export_package_list(target_dir)

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

Parameters

target_dir (str) – path name

export_package_verification(target_dir)

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

Parameters

target_dir (str) – path name

import_cdroot_files(target_dir)

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

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

import_image_identifier()

Create etc/ImageID identifier file

import_overlay_files(follow_links=False, preserve_owner_group=False)

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

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

script_exists(name)

Check if provided script base name exists in the image description

set_selinux_file_contexts(security_context_file)

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

Add groups for configured users

setup_keyboard_map()

Setup console keyboard

setup_locale()

Setup UTF8 system wide locale

setup_machine_id()

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

setup_permissions()

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

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

Setup timezone symlink

setup_users()

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: Optional[Any]) → 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)

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)

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

static run_common_function(name, parameters)

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)

Bases: object

Provide source tree size information

Parameters

source_dir (str) – source directory path name

accumulate_files()

Calculate sum of all files in the source tree

Returns

number of files

Return type

int

accumulate_mbyte_file_sizes(exclude=None)

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, requested_filesystem)

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 (int) – mbsize to update

• requested_filesystem (str) – filesystem name

Returns

mbytes

Return type

int

kiwi.system.uri Module

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

Bases: object

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

Parameters

• 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

alias()

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

credentials_file_name()

Filename to store repository credentials

Returns

credentials file name

Return type

str

get_fragment()

Returns the fragment part of the URI.

Returns

fragment part of the URI if any, empty string otherwise

Return type

str

is_public()

Check if URI is considered to be publicly reachable

Returns

True or False

Return type

bool

is_remote()

Check if URI is a remote or local location

Returns

True or False

Return type

bool

translate(check_build_environment=True)

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)

Bases: object

Operations on users and groups in a root directory

Parameters

root_dir (str) – root directory path name

group_add(group_name, options)

Add group with options

Parameters

• group_name (str) – group name

• options (list) – groupadd options

group_exists(group_name)

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)

Setup user home directory

Parameters

• user_name (str) – user name

• group_name (str) – group name

• home_path (str) – path name

user_add(user_name, options)

Add user with options

Parameters

• user_name (str) – user name

• options (list) – useradd options

user_exists(user_name)

Check if user exists

Parameters

user_name (str) – user name

Return type

bool

user_modify(user_name, options)

Modify user with options

Parameters

• user_name (str) – user name

• options (list) – usermod options

Module Contents