### KIWI NG: PXE Client Setup Configuration - Setup Client with System on Local Disk Source: https://osinside.github.io/kiwi/_modules/kiwi/solver/repository/rpm_md Instructions for configuring a PXE client to install or run the system from its local disk after booting over the network. This allows for a persistent local installation. ```bash # Example kernel command line parameters root=/dev/sda1 ``` -------------------------------- ### Installing and Configuring DHCP and TFTP with dnsmasq Source: https://osinside.github.io/kiwi/_modules/kiwi/iso_tools/xorriso This describes the setup for a network boot server, specifically focusing on installing and configuring 'dnsmasq' to provide DHCP and TFTP services. This is crucial for PXE booting. ```bash # Example dnsmasq configuration snippet # interface=eth0 # dhcp-range=192.168.1.100,192.168.1.200,12h # enable-tftp # tftp-root=/srv/tftp # dhcp-boot=pxelinux.0 ``` -------------------------------- ### Abstract Method: Setup Install Image Configuration Source: https://osinside.github.io/kiwi/_modules/kiwi/bootloader/config/base Abstract method for creating boot configuration files to boot from install media in EFI mode. Requires MBRID, hypervisor, kernel, and initrd. ```python @abstractmethod def setup_install_image_config( self, mbrid, hypervisor, kernel, initrd ): """ Create boot config file to boot from install media in EFI mode. :param string mbrid: mbrid file name on boot device :param string hypervisor: hypervisor name :param string kernel: kernel name :param string initrd: initrd name Implementation in specialized bootloader class required """ pass ``` -------------------------------- ### Run a system disk image with QEMU Source: https://osinside.github.io/kiwi/_sources/quickstart.rst Boots a previously built system disk image using QEMU. This command attaches the raw disk image to a virtual machine and configures basic settings like boot order and memory. ```bash $ sudo qemu -boot c \ -drive file={exc_image_base_name_disk}.x86_64-{exc_image_version}.raw,format=raw,if=virtio \ -m 4096 -serial stdio ``` -------------------------------- ### Setup Repositories and Get PackageManager Source: https://osinside.github.io/kiwi/api/kiwi.system Configures software installation repositories, optionally clearing the cache and importing signing keys. Returns a package manager instance for subsequent installation tasks. ```python def setup_repositories(self, clear_cache: bool = False, signing_keys: List[str] = None, target_arch: str | None = None) -> PackageManagerBase: pass ``` -------------------------------- ### Add User and Setup Home Directory (Python) Source: https://osinside.github.io/kiwi/_modules/kiwi/system/setup This snippet demonstrates adding a user to the system and setting up their home directory with appropriate permissions. It logs informational messages and uses a helper function `system_users.user_add` and `system_users.setup_home_for_user`. It handles cases where group messages or home paths might be absent. ```python log.info('--> Adding user: {0}'.format(user_name)) if group_msg: log.info(group_msg) system_users.user_add(user_name, options) if home_path: log.info( '--> Setting permissions for {0}'.format(home_path) ) # Emtpy group string assumes the login or default group system_users.setup_home_for_user( user_name, user_groups[0] if len(user_groups) else '', home_path ) ``` -------------------------------- ### Clone Kiwi repository Source: https://osinside.github.io/kiwi/_sources/quickstart.rst Clones the official Kiwi repository from GitHub. This repository contains example appliance descriptions and build tests necessary for getting started. ```bash $ git clone https://github.com/OSInside/kiwi ``` -------------------------------- ### Get Bootloader Custom Options Source: https://osinside.github.io/kiwi/_modules/kiwi/xml_state Fetches a list of custom options for bootloader setup based on the specified option type ('shim', 'install', or 'config'). It iterates through the relevant options and extracts their names and values. ```python def get_bootloader_options(self, option_type: str) -> List[str]: """ List of custom options used in the process to run bootloader setup workloads """ result: List[str] = [] bootloader_settings = self.get_build_type_bootloader_settings_section() if bootloader_settings: options = [] if option_type == 'shim': options = bootloader_settings.get_shimoption() elif option_type == 'install': options = bootloader_settings.get_installoption() elif option_type == 'config': options = bootloader_settings.get_configoption() for option in options: result.append(option.get_name()) if option.get_value(): result.append(option.get_value()) return result ``` -------------------------------- ### Post Initialization Setup (Python) Source: https://osinside.github.io/kiwi/_modules/kiwi/boot/image/builtin_kiwi The `post_init` method in BootImageKiwi sets up the necessary environment for creating a custom initrd. It initializes an empty `boot_root_directory` and a list for temporary directories, then loads the boot XML description. ```python def post_init(self) -> None: """ Post initialization method Creates custom directory to prepare the boot image root filesystem which is a separate image to create the initrd from """ # builtin kiwi initrd builds its own root tree to create # an initrd from. Thus there is no pre defined boot root # directory self.boot_root_directory = '' self.temp_directories: List[str] = [] self.load_boot_xml_description() ``` -------------------------------- ### List example appliance build tests Source: https://osinside.github.io/kiwi/_sources/quickstart.rst Lists the directory structure of the example appliance build tests within the cloned Kiwi repository. This helps in identifying available image descriptions. ```bash $ tree -L 3 kiwi/build-tests ``` -------------------------------- ### Clone Kiwi Build Tests Repository Source: https://osinside.github.io/kiwi/_sources/installation.rst This command clones the official Kiwi GitHub repository, which contains build tests and example appliance descriptions. These are useful for understanding how Kiwi works and for testing purposes. ```shell-session $ git clone https://github.com/OSInside/kiwi $ tree -L 3 kiwi/build-tests ``` -------------------------------- ### Prepare Boot System for Initrd (Python) Source: https://osinside.github.io/kiwi/_modules/kiwi/boot/image/builtin_kiwi The `prepare` method sets up a new root system suitable for creating a kiwi initrd. It creates a temporary directory for the boot root, imports system description elements, installs bootstrap and system packages, configures the profile, and imports overlay files. ```python def prepare(self) -> None: """ Prepare new root system suitable to create a kiwi initrd from it """ if self.boot_xml_state: self.boot_root_directory_temporary = Temporary( prefix='kiwi_boot_root.', path=self.target_dir ).new_dir() self.boot_root_directory = self.boot_root_directory_temporary.name self.temp_directories.append( self.boot_root_directory ) boot_image_name = self.boot_xml_state.xml_data.get_name() self.import_system_description_elements() log.info('Preparing boot image') with SystemPrepare( xml_state=self.boot_xml_state, root_dir=self.boot_root_directory, allow_existing=True ) as system: with system.setup_repositories( signing_keys=self.signing_keys, target_arch=self.target_arch ) as manager: system.install_bootstrap( manager ) system.install_system( manager ) profile = Profile(self.boot_xml_state) profile.add('kiwi_initrdname', boot_image_name) defaults = Defaults() defaults.to_profile(profile) self.setup = SystemSetup( self.boot_xml_state, self.boot_root_directory ) profile.create( Defaults.get_profile_file(self.boot_root_directory) ) self.setup.import_description() self.setup.import_overlay_files( follow_links=True ) self.setup.call_config_script() system.pinch_system( manager=manager, force=True ) self.setup.call_image_script() self.setup.create_init_link_from_linuxrc() ``` -------------------------------- ### Bootloader Installation API Source: https://osinside.github.io/kiwi/_modules/kiwi/bootloader/template/grub2 Handles the installation process for various bootloaders, ensuring proper setup on the target image. ```APIDOC ## Bootloader Installation ### Description This section covers the components responsible for installing bootloaders into the constructed images. ### Modules - `kiwi.bootloader.install.base`: Base class for bootloader installation logic. - `kiwi.bootloader.install.grub2`: Handles GRUB2 installation. - `kiwi.bootloader.install.systemd_boot`: Manages systemd-boot installation. - `kiwi.bootloader.install.zipl`: Provides functionality for Zipl installation. ### Key Classes - `BootLoaderInstallBase`: Abstract base class for bootloader installation. - `BootLoaderInstallGrub2`: Implementation for GRUB2 installation. - `BootLoaderInstallSystemdBoot`: Implementation for systemd-boot installation. - `BootLoaderInstallZipl`: Implementation for Zipl installation. - `BootLoaderInstall`: A central class orchestrating bootloader installations. ``` -------------------------------- ### Setting Up a Network Boot Server Source: https://osinside.github.io/kiwi/_modules/kiwi/solver/sat This outlines the general steps for setting up a network boot server, typically involving DHCP, TFTP, and NFS services to serve boot files and root filesystems. ```shell # 1. Install necessary packages (e.g., dnsmasq, nfs-kernel-server) # sudo apt update && sudo apt install dnsmasq nfs-kernel-server # 2. Configure DHCP server (e.g., dnsmasq.conf) # See dnsmasq configuration example for PXE. # 3. Configure TFTP server (e.g., tftpd-hpa or dnsmasq's TFTP) # Ensure boot files (pxelinux.0, kernel, initrd) are in the TFTP root. # 4. Configure NFS server to export the root filesystem. # Edit /etc/exports and add: # /srv/nfs/rootfs *(rw,sync,no_subtree_check,no_root_squash) # sudo exportfs -ra ``` -------------------------------- ### Setup Client with System on Local Disk Source: https://osinside.github.io/kiwi/working_with_images/legacy_netboot_root_filesystem Provides the configuration for deploying a KIWI NG image onto a client's local disk. This involves specifying the image source and defining the disk partitioning scheme. The example shows how to set up a swap partition and a root partition on `/dev/sda`. ```shell IMAGE="/dev/sda2;kiwi-test-image-pxe.x86_64;1.15.6;192.168.100.2;4096" DISK="/dev/sda" PART="5;S;X,X;L;/ ``` -------------------------------- ### Get Bootloader Installation Options Source: https://osinside.github.io/kiwi/api/kiwi Lists all custom options that can be used during the bootloader installation process. ```APIDOC ## GET /get_bootloader_install_options ### Description Lists all custom options that can be used during the bootloader installation process. ### Method GET ### Endpoint /get_bootloader_install_options ### Response #### Success Response (200) - **options** (list[str]) - A list of available bootloader installation options. #### Response Example ```json { "options": ["install_option1", "install_option2"] } ``` ``` -------------------------------- ### Install Kiwi from Fedora/Rawhide Repositories Source: https://osinside.github.io/kiwi/_sources/installation.rst This command installs the Kiwi CLI tool from the official repositories for Fedora and Rawhide distributions using the dnf package manager. ```shell-session $ sudo dnf install kiwi-cli ``` -------------------------------- ### Initialize FileSystemSetup Class (Python) Source: https://osinside.github.io/kiwi/_modules/kiwi/filesystem/setup Initializes the FileSystemSetup class, which prepares filesystem setup methods. It takes an XMLState object and a root directory path, configuring the build type size and determining the requested filesystem type. ```python from kiwi.system.size import SystemSize from kiwi.defaults import Defaults from kiwi.xml_state import XMLState log = logging.getLogger('kiwi') class FileSystemSetup: """ **Implement filesystem setup methods** Methods from this class provides information from the root directory required before building a filesystem image :param object xml_state: Instance of XMLState :param string root_dir: root directory path """ def __init__(self, xml_state: XMLState, root_dir: str): self.configured_size = xml_state.get_build_type_size( include_unpartitioned=True ) if xml_state.get_build_type_unpartitioned_bytes() > 0: log.warning( 'Unpartitoned size attribute is ignored for filesystem images' ) self.size = SystemSize(root_dir) self.requested_image_type = xml_state.get_build_type_name() if self.requested_image_type in Defaults.get_filesystem_image_types(): self.requested_filesystem = self.requested_image_type else: self.requested_filesystem = xml_state.build_type.get_filesystem() ``` -------------------------------- ### Create Live ISO Filesystem and Add Metadata Source: https://osinside.github.io/kiwi/_modules/kiwi/builder/live This snippet demonstrates the creation of a live ISO filesystem from a specified directory and includes steps for adding media tags for the checkmedia tool. It also handles image size verification and adds bundle formats and checksums to the build results. Dependencies include FileSystemIsoFs, Iso, and Result classes. ```python # create iso filesystem from media_dir log.info('Creating live ISO image') with FileSystemIsoFs( device_provider=DeviceProvider(), root_dir=self.media_dir.name, custom_args=custom_iso_args ) as iso_image: iso_image.create_on_file(self.isoname) # include metadata for checkmedia tool if self.xml_state.build_type.get_mediacheck() is True: Iso.set_media_tag(self.isoname) Result.verify_image_size( self.runtime_config.get_max_size_constraint(), self.isoname ) if self.bundle_format: self.result.add_bundle_format(self.bundle_format) self.result.add( key='live_image', filename=self.isoname, use_for_bundle=True, compress=False, shasum=True ) self.result.add( key='image_packages', filename=self.system_setup.export_package_list( self.target_dir ), use_for_bundle=True, compress=False, shasum=False ) self.result.add( key='image_changes', filename=self.system_setup.export_package_changes( self.target_dir ), use_for_bundle=True, compress=True, shasum=False ) self.result.add( key='image_verified', filename=self.system_setup.export_package_verification( self.target_dir ), use_for_bundle=True, compress=False, shasum=False ) return self.result ``` -------------------------------- ### Zipl Secure Boot Installation Source: https://osinside.github.io/kiwi/_modules/kiwi/bootloader/install/zipl Handles the shim installation for secure boot setup for Zipl. This is currently a no-operation. ```APIDOC ## POST /bootloader/zipl/secure_boot_install ### Description Attempts to run the shim installation process for secure boot setup with Zipl. Currently, this operation is skipped as the specific details for secure boot with Zipl are not yet finalized or clear. ### Method POST ### Endpoint /bootloader/zipl/secure_boot_install ### Parameters #### Request Body None ### Response #### Success Response (200) - **status** (string) - Indicates that the operation was skipped. #### Response Example ```json { "status": "Secure boot installation skipped for Zipl" } ``` ``` -------------------------------- ### KiwiInstallBootImageError: Installation Boot Files Missing Source: https://osinside.github.io/kiwi/_modules/kiwi/exceptions Raised if essential files required for booting an installation image, such as the kernel or hypervisor, are not found. This prevents the installation process from starting correctly. ```python class KiwiInstallBootImageError(KiwiError): """ Exception raised if the required files to boot an installation image could not be found, e.g kernel or hypervisor. """ pass ``` -------------------------------- ### System Preparation and Repository Setup Source: https://osinside.github.io/kiwi/_modules/kiwi/tasks/system_build Prepares the system environment for image building. It sets up repositories, optionally clearing the cache and including signing keys. This block utilizes context managers for managing the system preparation and repository setup phases. ```python log.info('Preparing new root system') with SystemPrepare( self.xml_state, image_root, self.command_args['--allow-existing-root'] ) as system: with system.setup_repositories( self.command_args['--clear-cache'], self.command_args[ '--signing-key' ] + self.xml_state.get_repositories_signing_keys(), self.global_args['--target-arch'] ) as manager: ``` -------------------------------- ### Install Kiwi from openSUSE Leap/Tumbleweed Repositories Source: https://osinside.github.io/kiwi/_sources/installation.rst This command installs the Kiwi appliance builder directly from the official repositories for openSUSE Leap and Tumbleweed distributions using the zypper package manager. ```shell-session $ sudo zypper install python3-kiwi ``` -------------------------------- ### Create and Attach Persistent Storage Disk (Bash) Source: https://osinside.github.io/kiwi/_sources/working_with_images/network_live_iso_boot.rst This snippet demonstrates how to create a 3GB raw disk image using `qemu-img` and then attach it to a QEMU instance for booting. The created disk serves as persistent storage for the live system. ```bash $ qemu-img create mydisk.raw 3G $ qemu -boot n -hda mydisk.raw ``` -------------------------------- ### PXE Client Setup Configuration - Custom Kernel Boot Options Source: https://osinside.github.io/kiwi/_modules/kiwi/solver/sat This example illustrates how to pass custom kernel boot options to a PXE client. This allows for specific hardware configurations or troubleshooting parameters. ```shell # Example pxelinux.cfg/default entry with custom kernel options DEFAULT custom_options LABEL custom_options KERNEL vmlinuz APPEND initrd=initrd root=/dev/sda1 console=ttyS0,115200 selinux=0 ``` -------------------------------- ### Zipl Bootloader Installation Class (Python) Source: https://osinside.github.io/kiwi/_modules/kiwi/bootloader/install/zipl Defines the `BootLoaderInstallZipl` class for Zipl bootloader installations. It includes methods for post-initialization, checking installation requirements (always returning false as installation is handled by BLS), and skipping secure boot setup. ```python from kiwi.bootloader.install.base import BootLoaderInstallBase log = logging.getLogger('kiwi') class BootLoaderInstallZipl(BootLoaderInstallBase): """ **zipl bootloader installation** """ def post_init(self, custom_args: Dict): """ zipl post initialization method :param dict custom_args: unused """ self.custom_args = custom_args def install_required(self) -> bool: """ Check if zipl needs to install boot code zipl requires boot code installation, but it is done as part of the BLS implementation in bootloader/config/zipl.py Thus this method always returns: False :return: False :rtype: bool """ return False def secure_boot_install(self): """ Run shim installation for secure boot setup For zipl this is skipped since details for secure boot are not yet clear. """ pass ``` -------------------------------- ### Create Installation Media (ISO, PXE) - Python Source: https://osinside.github.io/kiwi/_modules/kiwi/builder/disk Builds an installation image, which can be a bootable hybrid ISO or a PXE archive. It uses InstallImageBuilder and adds the created media to the result instance with relevant metadata. Dependencies include 'log', 'Result', 'InstallImageBuilder'. ```python def create_install_media(self, result_instance: Result) -> Result: """ Build an installation image. The installation image is a bootable hybrid ISO image which embeds the raw disk image and an image installer :param object result_instance: instance of :class:`Result` :return: updated result_instance with installation media :rtype: instance of :class:`Result` """ if self.install_media: boot_image = None if self.initrd_system == 'kiwi': boot_image = self.boot_image install_image = InstallImageBuilder( self.xml_state, self.root_dir, self.target_dir, boot_image, self.custom_args ) if self.install_iso or self.install_stick: log.info('Creating hybrid ISO installation image') install_image.create_install_iso() result_instance.add( key='installation_image', filename=install_image.isoname, use_for_bundle=True, compress=False, shasum=True ) if self.install_pxe: log.info('Creating PXE installation archive') install_image.create_install_pxe_archive() result_instance.add( key='installation_pxe_archive', filename=install_image.pxetarball, use_for_bundle=True, compress=False, shasum=True ) return result_instance ``` -------------------------------- ### Start dnsmasq Service Source: https://osinside.github.io/kiwi/working_with_images/setup_network_bootserver This command starts the dnsmasq service on the system. Ensure that the dnsmasq package is installed and its configuration file is correctly set up before running this command. ```bash systemctl start dnsmasq ``` -------------------------------- ### Install Kiwi using pip Source: https://osinside.github.io/kiwi/_sources/quickstart.rst Installs the Kiwi OS appliance builder using pip. This is a prerequisite for using Kiwi and assumes pip is already installed and configured. ```bash $ sudo pip install kiwi ``` -------------------------------- ### Get Shim Install Tool Name (Python) Source: https://osinside.github.io/kiwi/_modules/kiwi/bootloader/install/grub2 Retrieves the name of the shim installation tool within a chroot environment. It specifically looks for 'shim-install'. If not found, it does not provide a fallback, indicating that shim installation might not be supported or configured. ```python def _get_shim_install_tool_name(self, root_path): return self._get_tool_name( root_path, lookup_list=['shim-install'], fallback_on_not_found=False ) ``` -------------------------------- ### Using SUSE Product ISO To Build Source: https://osinside.github.io/kiwi/_modules/kiwi/solver/sat No description -------------------------------- ### KiwiInstallPhaseFailed: Installation Phase Error Source: https://osinside.github.io/kiwi/_modules/kiwi/exceptions Raised if any installation phase during the system preparation command fails. This indicates a critical error during the setup process. ```python class KiwiInstallPhaseFailed(KiwiError): """ Exception raised if the install phase of a system prepare command has failed. """ pass ``` -------------------------------- ### Get Installmedia Initrd Drivers Source: https://osinside.github.io/kiwi/api/kiwi Retrieves a list of drivers to be appended to installation initrds. This function is useful for customizing the drivers loaded during the installation process. ```python def get_installmedia_initrd_drivers(_action : str_) -> List[str]: """ Gets the list of drivers to append in installation initrds Returns: a list of dracut driver names """ pass ```