kiwi.system Package¶
Submodules¶
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
- write(filename: str) None [source]¶
Write current hex identifier to file
- Parameters
filename (str) – file path name
- write_to_disk(device_provider: DeviceProvider) None [source]¶
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)[source]¶
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: Optional[str] = None) None [source]¶
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: Optional[str] = None) None [source]¶
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) Optional[kernel_type] [source]¶
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() Optional[xen_hypervisor_type] [source]¶
Lookup xen hypervisor and provide filename and hypervisor name
- Returns
tuple with filename and hypervisor name
- Return type
tuple|None
kiwi.system.prepare
Module¶
- class kiwi.system.prepare.SystemPrepare(xml_state: XMLState, root_dir: str, allow_existing: bool = False)[source]¶
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 [source]¶
This methods cleans some package manager artifacts created at run time such as macros
- delete_packages(manager: PackageManagerBase, packages: List, force: bool = False) None [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.- Parameters
manager (object) – instance of a
PackageManager
subclasspackages (list) – package list
force (bool) – force deletion true|false
- Raises
KiwiSystemDeletePackagesFailed – if installation process fails
- install_bootstrap(manager: PackageManagerBase, plus_packages: Optional[List] = None) None [source]¶
Install system software using the package manager from the host, also known as bootstrapping
- Parameters
manager (object) – instance of a
PackageManager
subclassplus_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 [source]¶
Install one or more packages using the package manager inside of the new root directory
- Parameters
manager (object) – instance of a
PackageManager
subclasspackages (list) – package list
- Raises
KiwiSystemInstallPackagesFailed – if installation process fails
- install_system(manager: PackageManagerBase) None [source]¶
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: Optional[PackageManagerBase] = None, force: bool = False) None [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 withtype="delete"
if any.- Parameters
manager (object) – instance of
PackageManager
subclassforce (bool) – Forced deletion True|False
- Raises
KiwiPackagesDeletePhaseFailed – if the deletion packages process fails
- setup_repositories(clear_cache: bool = False, signing_keys: Optional[List[str]] = None, target_arch: Optional[str] = None) PackageManagerBase [source]¶
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
- update_system(manager: PackageManagerBase) None [source]¶
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: XMLState)[source]¶
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 [source]¶
Add key/value pair to profile dictionary
- Parameters
key (str) – profile key
value (str) – profile value
kiwi.system.result
Module¶
- class kiwi.system.result.Result(xml_state: XMLState)[source]¶
Bases:
object
Collect image building results
- Parameters
result_files (dict) – dict of result files
class_version (object) –
Result
class versionxml_state (object) – instance of
XMLState
- add(key: str, filename: str, use_for_bundle: bool = True, compress: bool = False, shasum: bool = True) None [source]¶
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: str, portable: bool = True) None [source]¶
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] [source]¶
Current list of result tuples
- static load(filename: str) result_type [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
- static verify_image_size(size_limit: int, filename: str) None [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.
- 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
- property compress¶
Alias for field number 2
- property filename¶
Alias for field number 0
- property shasum¶
Alias for field number 3
- property use_for_bundle¶
Alias for field number 1
- class kiwi.system.result.result_name_tags(N, P, A, I, T, M, m, p)¶
Bases:
tuple
- property A¶
Alias for field number 2
- property I¶
Alias for field number 3
- property M¶
Alias for field number 5
- property N¶
Alias for field number 0
- property P¶
Alias for field number 1
- property T¶
Alias for field number 4
- property m¶
Alias for field number 6
- property p¶
Alias for field number 7
kiwi.system.root_bind
Module¶
- class kiwi.system.root_bind.RootBind(root_init: RootInit)[source]¶
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
- mount_kernel_file_systems() None [source]¶
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
- setup_intermediate_config() None [source]¶
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 [source]¶
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)[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() None [source]¶
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
kiwi.system.setup
Module¶
- class kiwi.system.setup.SystemSetup(xml_state: XMLState, root_dir: str)[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.
- Parameters
xml_state (object) – instance of
XMLState
root_dir (str) – root directory path name
- call_edit_boot_config_script(filesystem: str, boot_part_id: int, working_directory: Optional[str] = None) 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
- 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: Optional[str] = None) 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
- Parameters
diskname (str) – file path name
boot_device_node (str) – boot device node name
working_directory (str) – directory name
- cleanup() None [source]¶
Delete all traces of a kiwi description which are not required in the later image
- create_fstab(fstab: Fstab) None [source]¶
Create etc/fstab from given Fstab object
Custom fstab modifications are possible and handled in the following order:
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
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
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 [source]¶
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 [source]¶
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 [source]¶
Export etc/modprobe.d to given root_dir
- Parameters
target_root_dir (str) – path name
- export_package_changes(target_dir: str) str [source]¶
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 [source]¶
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 [source]¶
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 [source]¶
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 [source]¶
Import XML descriptions, custom scripts, archives and script helper methods
- import_overlay_files(follow_links: bool = False, preserve_owner_group: bool = False) None [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.
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:
root/ dir or root.tar.gz
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 [source]¶
Those <repository> sections which are marked with the imageinclude attribute should be permanently added to the image repository configuration
- script_exists(name: str) bool [source]¶
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 [source]¶
Initialize the security context fields (extended attributes) on the files matching the security_context_file
- Parameters
security_context_file (str) – path file name
- setup_machine_id() None [source]¶
Setup systemd machine id
There are various states of /etc/machine-id:
Does not exist: Triggers ConditionFirstBoot, but does not work if the filesystem is initially read-only (booted without “rw”).
Exists, is empty: Does not trigger ConditionFirstBoot, but works with read-only mounts.
Exists, contains the string “uninitialized”: Same as b), but triggers ConditionFirstBoot. Supported by systemd v247+ only.
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 [source]¶
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 [source]¶
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
kiwi.system.shell
Module¶
- class kiwi.system.shell.Shell[source]¶
Bases:
object
Special character handling for shell evaluated code
- static format_to_variable_value(value: Optional[Any]) str [source]¶
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 [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
kiwi.system.size
Module¶
- class kiwi.system.size.SystemSize(source_dir: str)[source]¶
Bases:
object
Provide source tree size information
- Parameters
source_dir (str) – source directory path name
- accumulate_files() int [source]¶
Calculate sum of all files in the source tree
- Returns
number of files
- Return type
int
- accumulate_mbyte_file_sizes(exclude: Optional[List[str]] = None) int [source]¶
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 [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
- 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 = '')[source]¶
Bases:
object
Normalize and manage URI types
- alias() str [source]¶
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() str [source]¶
Filename to store repository credentials
- Returns
credentials file name
- Return type
str
- get_fragment() str [source]¶
Returns the fragment part of the URI.
- Returns
fragment part of the URI if any, empty string otherwise
- Return type
str
- is_public() bool [source]¶
Check if URI is considered to be publicly reachable
- Returns
True|False
- Return type
bool
- is_remote() bool [source]¶
Check if URI is a remote or local location
- Returns
True|False
- Return type
bool
- translate(check_build_environment: bool = True) str [source]¶
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)[source]¶
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 [source]¶
Add group with options
- Parameters
group_name (str) – group name
options (list) – groupadd options
- group_exists(group_name: str) bool [source]¶
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 [source]¶
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 [source]¶
Add user with options
- Parameters
user_name (str) – user name
options (list) – useradd options