From 29c52aad9d53d31fe49f72d6d00a94ba65a5b488 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcus=20Sch=C3=A4fer?= Date: Sat, 31 Jan 2026 18:42:45 +0100 Subject: [PATCH] Fix documentation for language errors and wording --- doc/source/building_images.rst | 6 +- .../building_images/build_container_image.rst | 34 +- doc/source/building_images/build_enclave.rst | 24 +- .../building_images/build_expandable_disk.rst | 160 +-- doc/source/building_images/build_kis.rst | 28 +- doc/source/building_images/build_live_iso.rst | 66 +- .../building_images/build_simple_disk.rst | 80 +- .../building_images/build_wsl_container.rst | 60 +- doc/source/commands/image_info.rst | 34 +- doc/source/commands/image_resize.rst | 8 +- doc/source/commands/kiwi.rst | 54 +- doc/source/commands/result_bundle.rst | 14 +- doc/source/commands/result_list.rst | 2 +- doc/source/commands/system_build.rst | 98 +- doc/source/commands/system_create.rst | 10 +- doc/source/commands/system_prepare.rst | 80 +- doc/source/commands/system_update.rst | 2 +- doc/source/concept_and_workflow.rst | 84 +- .../customize_the_boot_process.rst | 154 +-- doc/source/concept_and_workflow/packages.rst | 64 +- doc/source/concept_and_workflow/profiles.rst | 6 +- .../concept_and_workflow/repository_setup.rst | 42 +- .../runtime_configuration.rst | 6 +- .../concept_and_workflow/shell_scripts.rst | 112 +- .../concept_and_workflow/systemdeps.rst | 50 +- doc/source/concept_and_workflow/users.rst | 8 +- doc/source/contributing.rst | 92 +- doc/source/contributing/kiwi_from_python.rst | 14 +- .../contributing/kiwi_plugin_architecture.rst | 30 +- doc/source/contributing/schema_extensions.rst | 34 +- doc/source/contributing/scripts_testing.rst | 26 +- doc/source/image_description.rst | 34 +- doc/source/image_description/elements.rst | 1040 ++++++++--------- doc/source/image_types_and_results.rst | 152 +-- doc/source/index.rst | 44 +- doc/source/installation.rst | 42 +- doc/source/integration_testing.rst | 34 +- doc/source/overview.rst | 42 +- doc/source/overview/workflow.rst | 38 +- doc/source/plugins.rst | 2 +- doc/source/plugins/self_contained.rst | 98 +- doc/source/plugins/stackbuild.rst | 66 +- doc/source/quickstart.rst | 14 +- doc/source/troubleshooting.rst | 6 +- doc/source/troubleshooting/architectures.rst | 26 +- .../troubleshooting/boxbuild_tweaks.rst | 27 +- .../troubleshooting/buildhost_constraints.rst | 66 +- doc/source/troubleshooting/filesystems.rst | 44 +- doc/source/troubleshooting/security.rst | 28 +- doc/source/working_with_images.rst | 2 +- .../build_in_buildservice.rst | 102 +- .../build_with_profiles.rst | 6 +- .../build_without_debianbootstrap.rst | 50 +- .../working_with_images/clone_partitions.rst | 68 +- .../working_with_images/custom_partitions.rst | 113 +- .../working_with_images/custom_volumes.rst | 40 +- .../disk_ramdisk_deployment.rst | 48 +- .../disk_setup_for_azure.rst | 26 +- .../disk_setup_for_ec2.rst | 42 +- .../disk_setup_for_google.rst | 34 +- .../disk_setup_for_luks.rst | 32 +- .../disk_setup_for_vagrant.rst | 86 +- .../iso_to_usb_stick_deployment.rst | 20 +- ...iso_to_usb_stick_file_based_deployment.rst | 38 +- .../iso_to_usb_stick_grub2_boot_from_iso.rst | 23 +- .../legacy_netboot_root_filesystem.rst | 170 +-- .../network_live_iso_boot.rst | 62 +- .../network_overlay_boot.rst | 50 +- .../setup_network_bootserver.rst | 46 +- .../working_with_images/use_suse_media.rst | 32 +- 70 files changed, 2188 insertions(+), 2187 deletions(-) diff --git a/doc/source/building_images.rst b/doc/source/building_images.rst index 0faf5501..591e808e 100644 --- a/doc/source/building_images.rst +++ b/doc/source/building_images.rst @@ -5,9 +5,9 @@ Building Images for Supported Types .. note:: - This document provides an overview how to build and use - the {kiwi} supported image types. All images that we provide - for testing uses the root password: `linux` + This document provides an overview of how to build and use + the {kiwi}-supported image types. All images that we provide + for testing use the root password: `linux`. .. toctree:: :maxdepth: 1 diff --git a/doc/source/building_images/build_container_image.rst b/doc/source/building_images/build_container_image.rst index 3f51fbfb..bff77036 100644 --- a/doc/source/building_images/build_container_image.rst +++ b/doc/source/building_images/build_container_image.rst @@ -7,18 +7,18 @@ Build a Container Image This page explains how to build a Container Image. It covers the following topics: - * basic configuration explanation + * a basic configuration explanation * how to build a Container Image * how to run it with a Container Runtime {kiwi} can build native container images from scratch or using existing images. -{kiwi} container images are considered to be native, because a {kiwi} tarball -image can be loaded directly into container runtimes like Podman, Docker or +{kiwi} container images are considered native because a {kiwi} tarball +image can be loaded directly into container runtimes like Podman, Docker, or Containerd, including common container configurations. The container configuration metadata is supplied to {kiwi} as part of the :ref:`XML description file ` using the -```` tag. The following configuration metadata can be +`` tag. The following configuration metadata can be specified. `containerconfig` attributes: @@ -28,16 +28,16 @@ specified. * ``maintainer``: Specifies the author of the container. Equivalent to the `MAINTAINER` directive in a :file:`Dockerfile`. * ``user``: Sets the user name or user id (UID) to be used when - running `entrypoint` and `subcommand`. Equivalent of the `USER` + running `entrypoint` and `subcommand`. Equivalent to the `USER` directive of a :file:`Dockerfile`. * ``workingdir``: Sets the working directory to be used when running - `cmd` and `entrypoint`. Equivalent of the `WORKDIR` directive in a + `cmd` and `entrypoint`. Equivalent to the `WORKDIR` directive in a :file:`Dockerfile`. `containerconfig` child tags: * ``subcommand``: Provides the default execution parameters of the - container. Equivalent of the `CMD` directive in a :file:`Dockerfile`. + container. Equivalent to the `CMD` directive in a :file:`Dockerfile`. * ``labels``: Adds custom metadata to an image using key-value pairs. Equivalent to one or more `LABEL` directives in a :file:`Dockerfile`. * ``expose``: Defines which ports can be exposed to the outside when @@ -46,17 +46,17 @@ specified. * ``environment``: Sets environment variables using key-value pairs. Equivalent to one or multiple `ENV` directives in a :file:`Dockerfile`. * ``entrypoint``: Sets the binary to use for executing all commands inside the - container. Equivalent of the `ENTRYPOINT` directive in a :file:`Dockerfile`. + container. Equivalent to the `ENTRYPOINT` directive of a :file:`Dockerfile`. * ``volumes``: Creates mountpoints with the given name and marks them to hold external volumes from the host or from other containers. Equivalent to one or more `VOLUME` directives in a :file:`Dockerfile`. -* ``stopsignal``: The stopsignal element sets the system call signal that +* ``stopsignal``: The `stopsignal` element sets the system call signal that will be sent to the container to exit. This signal can be a signal name - in the format SIG[NAME], for instance SIGKILL, or an unsigned number that - matches a position in the kernel's syscall table, for instance 9. - The default is SIGTERM if not defined + in the format `SIG[NAME]`, for instance, `SIGKILL`, or an unsigned number that + matches a position in the kernel's syscall table, for instance, 9. + The default is `SIGTERM` if not defined. -Other :file:`Dockerfile` directives such as ``RUN``, ``COPY`` or ``ADD``, +Other :file:`Dockerfile` directives such as `RUN`, `COPY`, or `ADD`, can be mapped to {kiwi} using the :ref:`config.sh ` script file to run Bash commands, or the :ref:`overlay tree ` to include @@ -68,13 +68,13 @@ openSUSE Leap: 1. Make sure you have checked out the example image descriptions (see :ref:`example-descriptions`). -#. Include the ``Virtualization/containers`` repository into your list (replace the placeholder `` with the name of the desired distribution): +#. Include the `Virtualization/containers` repository in your list (replace the placeholder `` with the name of the desired distribution): .. code:: bash $ zypper addrepo http://download.opensuse.org/repositories/Virtualization:/containers/ container-tools -#. Install :command:`umoci` and :command:`skopeo` tools +#. Install `umoci` and `skopeo` tools. .. code:: bash @@ -91,13 +91,13 @@ openSUSE Leap: #. Test the container image. - First load the new image into your container runtime: + First, load the new image into your container runtime: .. code:: bash $ podman load -i {exc_image_base_name_docker}.x86_64-{exc_image_version}.docker.tar.xz - Then run the image: + Then, run the image: .. code:: bash diff --git a/doc/source/building_images/build_enclave.rst b/doc/source/building_images/build_enclave.rst index 9e271db4..2fb5c570 100644 --- a/doc/source/building_images/build_enclave.rst +++ b/doc/source/building_images/build_enclave.rst @@ -15,10 +15,10 @@ to further protect and securely process highly sensitive data such as personally identifiable information (PII), healthcare, financial, and intellectual property data within their Amazon EC2 instances. Nitro Enclaves uses the same Nitro Hypervisor technology that provides CPU and memory isolation for EC2 instances. -For further details please visit https://aws.amazon.com/ec2/nitro/nitro-enclaves +For further details, please visit https://aws.amazon.com/ec2/nitro/nitro-enclaves. To add an enclave build to your appliance, create a `type` element with -`image` set to `enclave` in the :file:`config.xml` file as shown below: +`image` set to `enclave` in the :file:`config.xml` file, as shown below: .. code:: xml @@ -41,16 +41,16 @@ To add an enclave build to your appliance, create a `type` element with The following attributes of the `type` element are relevant: -- `enclave_format`: Specifies the enclave target +- `enclave_format`: Specifies the enclave target. - As of today only the `aws-nitro` enclave target is supported + As of today, only the `aws-nitro` enclave target is supported. -- `kernelcmdline`: Specifies the kernel commandline suitable for the enclave +- `kernelcmdline`: Specifies the kernel commandline suitable for the enclave. - An enclave is a system that runs completely in RAM loaded from - an enclave binary format which includes the kernel, initrd and - the kernel commandline suitable for the target system. + An enclave is a system that runs completely in RAM, loaded from + an enclave binary format that includes the kernel, initrd, and + the kernel command line suitable for the target system. With the appropriate settings specified in :file:`config.xml`, you can build an image using {kiwi}: @@ -76,9 +76,9 @@ be tested with QEMU: The image is now complete and ready to use. Access to the system is possible via ssh through a vsock connection into the guest. To establish -a vsock connection it's required to forward the connection through the -guest AF_VSOCK socket. This can be done via a ProxyCommand setup of the -host ssh as follows: +a vsock connection, it's required to forward the connection through the +guest's `AF_VSOCK` socket. This can be done via a `ProxyCommand` setup of the +host's ssh as follows: .. code:: bash @@ -95,7 +95,7 @@ host ssh as follows: host *.vsock ProxyCommand ~/bin/vsock-ssh.sh %h -After the ssh proxy setup login to the enclave with a custom vsock port +After the ssh proxy setup, log in to the enclave with a custom vsock port as follows: .. code:: bash diff --git a/doc/source/building_images/build_expandable_disk.rst b/doc/source/building_images/build_expandable_disk.rst index 06a5e0a9..d45a1be9 100644 --- a/doc/source/building_images/build_expandable_disk.rst +++ b/doc/source/building_images/build_expandable_disk.rst @@ -8,9 +8,9 @@ Build an Expandable Disk Image This page explains how to build an expandable disk image. It covers the following topics: - * build an expandable disk image - * deploy an expandable disk image - * run the deployed system + * builds an expandable disk image + * deploys an expandable disk image + * runs the deployed system An expandable disk represents the system disk with the capability to automatically expand the disk and its filesystem to a custom disk geometry. This @@ -38,8 +38,8 @@ system: virtual disk. It can expand itself to a custom disk geometry. * The installation image with the suffix :file:`install.iso` is a - hybrid installation system which contains the disk image and is - capable to install this image on any target disk. + hybrid installation system that contains the disk image and is + capable of installing this image on any target disk. .. _deployment_methods: @@ -59,7 +59,7 @@ Basic deployment strategies are as follows: 2. :ref:`deploy_from_iso` Boot the installation image and let {kiwi}'s installer - deploy the disk image from CD/DVD or USB stick onto the target disk. + deploy the disk image from a CD/DVD or USB stick onto the target disk. 3. :ref:`deploy_from_network` @@ -72,7 +72,7 @@ Manual Deployment ----------------- The manual deployment method can be tested using virtualization software -like QEMU and an additional virtual a large-size target disk. +like QEMU and an additional virtual large-size target disk. To do this, follow the steps below. 1. Create a target disk: @@ -83,12 +83,12 @@ To do this, follow the steps below. .. note:: Retaining the Disk Geometry - If the target disk geometry is less than or equals to the geometry of + If the target disk geometry is less than or equal to the geometry of the disk image itself, the disk expansion that is performed on a physical - disk install during the boot workflow is skipped and the + disk install during the boot workflow is skipped, and the original disk geometry stays unchanged. -2. Dump disk image on target disk: +2. Dump the disk image on the target disk: .. code:: bash @@ -101,7 +101,7 @@ To do this, follow the steps below. $ sudo qemu -hda target_disk -m 4096 -serial stdio - On first boot of the target_disk, the system is expanded to the + On the first boot of the `target_disk`, the system is expanded to the configured storage layout. By default, the system root partition and filesystem are resized to the maximum free space available. @@ -110,15 +110,15 @@ To do this, follow the steps below. CD/DVD Deployment ----------------- -The deployment from CD/DVD via an installation image can +The deployment from a CD/DVD via an installation image can also be tested using virtualization software such as QEMU. To do this, follow the steps below. 1. Create a target disk: - Follow the steps above to create a virtual target disk + Follow the steps above to create a virtual target disk. -2. Boot the installation image as CD/DVD with the +2. Boot the installation image as a CD/DVD with the target disk attached. .. code:: bash @@ -130,9 +130,9 @@ To do this, follow the steps below. .. note:: USB Stick Deployment Like any other ISO image built with {kiwi}, the installation - image is also a hybrid image. Thus, it can also be used on USB stick and - serve as installation media as explained in - :ref:`hybrid_iso` + image is also a hybrid image. Thus, it can also be used on a USB stick and + serve as installation media, as explained in + :ref:`hybrid_iso`. .. _deploy_from_network: @@ -140,8 +140,8 @@ Network Deployment ------------------ The process of deployment from the network downloads the disk image from a -PXE boot server. This requires a PXE network boot server to be setup -as described in :ref:`network-boot-server` +PXE boot server. This requires a PXE network boot server to be set up +as described in :ref:`network-boot-server`. If the PXE server is running, the following steps show how to test the deployment process over the network using a QEMU virtual machine as @@ -149,7 +149,7 @@ a target system: 1. Create an installation PXE TAR archive along with your disk image by replacing the following configuration in - kiwi/build-tests/{exc_description_disk}/appliance.kiwi + `kiwi/build-tests/{exc_description_disk}/appliance.kiwi`: Find the line below: @@ -169,34 +169,34 @@ a target system: file to a temporary directory, and copy the initrd and kernel images to the PXE server. - a) Unpack installation tarball: + a) Unpack the installation tarball: .. code:: bash mkdir /tmp/pxe && cd /tmp/pxe tar -xf {exc_image_base_name_disk}.x86_64-{exc_image_version}.install.tar.xz - b) Copy kernel and initrd used for PXE boot: + b) Copy the kernel and initrd used for PXE boot: .. code:: bash scp pxeboot.{exc_image_base_name_disk}.x86_64-{exc_image_version}.initrd PXE_SERVER_IP:/srv/tftpboot/boot/initrd scp pxeboot.{exc_image_base_name_disk}.x86_64-{exc_image_version}.kernel PXE_SERVER_IP:/srv/tftpboot/boot/linux -3. Copy the disk image, SHA256 file, system kernel, initrd and bootoptions to +3. Copy the disk image, SHA256 file, system kernel, initrd, and bootoptions to the PXE boot server. Activation of the deployed system is done via `kexec` of the kernel and initrd provided here. - a) Copy system image and SHA256 checksum: + a) Copy the system image and SHA256 checksum: .. code:: bash scp {exc_image_base_name_disk}.x86_64-{exc_image_version}.xz PXE_SERVER_IP:/srv/tftpboot/image/ scp {exc_image_base_name_disk}.x86_64-{exc_image_version}.sha256 PXE_SERVER_IP:/srv/tftpboot/image/ - b) Copy kernel, initrd and bootoptions used for booting the system via kexec: + b) Copy the kernel, initrd, and bootoptions used for booting the system via kexec: .. code:: bash @@ -206,26 +206,26 @@ a target system: .. note:: - The config.bootoptions file is used with kexec to boot the previously + The `config.bootoptions` file is used with `kexec` to boot the previously dumped image. This file specifies the root of the dumped image, and the - file can include other boot options. The file provided with the {kiwi} - built image connected to the image present in the PXE TAR archive. If + file can include other boot options. The file provided with the {kiwi}- + built image is connected to the image present in the PXE TAR archive. If other images are deployed, the file must be modified to match the correct root reference. .. note:: - If the image gets deployed into a ramdisk which is configured + If the image is deployed into a ramdisk that is configured by passing `rd.kiwi.ramdisk` as part of the append setup below, - it is not required to copy the above mentioned kernel and initrd - file to boot the system because for ramdisk deployments the - currently active kernel and initrd will be used as kexec cannot + it is not required to copy the above-mentioned kernel and initrd + file to boot the system because for ramdisk deployments, the + currently active kernel and initrd will be used, as kexec cannot be called with a system in memory. -4. Add/Update the kernel command line parameters. +4. Add/Update the kernel command-line parameters. - Edit your PXE configuration (for example :file:`pxelinux.cfg/default`) on - the PXE server, and add the following parameters to the append line similar to shown below: + Edit your PXE configuration (for example, :file:`pxelinux.cfg/default`) on + the PXE server and add the following parameters to the append line similar to that shown below: .. code:: bash @@ -233,11 +233,11 @@ a target system: The location of the image is specified as a source URI that can point to any location supported by the `curl` command. {kiwi} uses `curl` to fetch - the data from this URI. This means that the image, checksum file, system kernel - and initrd can be fetched from any server, and they do not need to be stored + the data from this URI. This means that the image, checksum file, system kernel, + and initrd can be fetched from any server and do not need to be stored on the `PXE_SERVER`. - By default {kiwi} does not use specific `curl` options or flags. But it is + By default, {kiwi} does not use specific `curl` options or flags. But it is possible to specify desired options by adding the `rd.kiwi.install.pxe.curl_options` flag to the kernel command line (`curl` options are passed as comma-separated values), for example: @@ -252,7 +252,7 @@ a target system: curl --retry 3 --retry-delay 3 --speed-limit 2048 -f - This can be particularly useful when the deployment infrastructure requires + This can be particularly useful when the deployment infrastructure requires a specific download configuration. For example, setting more robust retries over an unstable network connection. @@ -280,10 +280,10 @@ a target system: .. note:: QEMU bridged networking - To connect QEMU to the network, we recommend to - setup a network bridge on the host system and connect QEMU - to it via a custom /etc/qemu-ifup configuration. For details, see - https://en.wikibooks.org/wiki/QEMU/Networking + To connect QEMU to the network, we recommend setting up + a network bridge on the host system and connecting QEMU + to it via a custom `/etc/qemu-ifup` configuration. For details, see + https://en.wikibooks.org/wiki/QEMU/Networking. .. _oem_customize: @@ -301,117 +301,117 @@ element, for example: -Below is a losr list of optional `oem` element settings. +Below is a list of optional `oem` element settings. oemconfig.oem-resize Determines if the disk has the capability to expand itself to a new disk geometry or not. By default, this feature is activated. The implementation of the resize capability is done in a dracut module packaged as `dracut-kiwi-oem-repart`. If `oem-resize` is - set to false, the installation of the corresponding dracut package + set to `false`, the installation of the corresponding dracut package can be skipped as well. oemconfig.oem-boot-title - By default, the string OEM is used as the boot manager menu + By default, the string `OEM` is used as the boot manager menu entry when KIWI creates the GRUB configuration during deployment. The `oem-boot-title` element allows you to set a custom name for the grub menu entry. This value is represented by the - ``kiwi_oemtitle`` variable in the initrd. + `kiwi_oemtitle` variable in the initrd. oemconfig.oem-bootwait Determines if the system waits for user interaction before continuing the boot process after the disk image has been dumped to - the designated storage device (default value is false). This value - is represented by the ``kiwi_oembootwait`` variable in the initrd. + the designated storage device (the default value is `false`). This value + is represented by the `kiwi_oembootwait` variable in the initrd. oemconfig.oem-reboot When enabled, the system is rebooted after the disk image has - been deployed to the designated storage device (default value is - false). This value is represented by the ``kiwi_oemreboot`` + been deployed to the designated storage device (the default value is + `false`). This value is represented by the `kiwi_oemreboot` variable in the initrd. oemconfig.oem-reboot-interactive When enabled, the system is rebooted after the disk image has - been deployed to the designated storage device (default value is - false). Before the reboot, a message is displayed, and it and must be + been deployed to the designated storage device (the default value is + `false`). Before the reboot, a message is displayed, and it must be acknowledged by the user for the system to reboot. This - value is represented by the ``kiwi_oemrebootinteractive`` variable + value is represented by the `kiwi_oemrebootinteractive` variable in the initrd. oemconfig.oem-silent-boot Determines if the system boots in silent mode after the disk - image has been deployed to the designated storage device (default - value is false). This value is represented by the - ``kiwi_oemsilentboot`` variable in the initrd. + image has been deployed to the designated storage device (the default + value is `false`). This value is represented by the + `kiwi_oemsilentboot` variable in the initrd. oemconfig.oem-shutdown Determines if the system is powered down after the disk image - has been deployed to the designated storage device (default value - is false). This value is represented by the ``kiwi_oemshutdown`` + has been deployed to the designated storage device (the default value + is `false`). This value is represented by the `kiwi_oemshutdown` variable in the initrd. oemconfig.oem-shutdown-interactive Determines if the system is powered down after the disk image - has been deployed to the designated storage device (default value - is false). Before the shutdown a message is displayed, and it must be + has been deployed to the designated storage device (the default value + is `false`). Before the shutdown, a message is displayed, and it must be acknowledged by the user for the system to power off. - This value is represented by the ``kiwi_oemshutdowninteractive`` - variable in the initrd + This value is represented by the `kiwi_oemshutdowninteractive` + variable in the initrd. oemconfig.oem-swap - Determines if a swap partition is be created. By default, no + Determines if a swap partition is created. By default, no swap partition is created. This value is represented - by the ``kiwi_oemswap`` variable in the initrd. + by the `kiwi_oemswap` variable in the initrd. oemconfig.oem-swapname Specifies the name of the swap space. By default, the name is set to - ``LVSwap``. The default indicates that this setting is only useful in + `LVSwap`. The default indicates that this setting is only useful in combination with the LVM volume manager. In this case, the swapspace is configured as a volume in the volume group, and every volume requires a name. - The name specified in `oemconfig.oem-swapname` here is used as a name of the + The name specified in `oemconfig.oem-swapname` here is used as the name of the swap volume. oemconfig.oem-swapsize Specifies the size of the swap partition. If a swap partition is created while the size of the swap partition is not specified, KIWI calculates the size of - the swap partition, and creates a swap partition at initial boot time. In this - case, the swap partition size equals the double amount of RAM of the system. - This value is represented by the ``kiwi_oemswapMB`` variable in the initrd. + the swap partition and creates a swap partition at initial boot time. In this + case, the swap partition size equals double the amount of RAM of the system. + This value is represented by the `kiwi_oemswapMB` variable in the initrd. oemconfig.oem-systemsize Specifies the MB size the operating system is allowed to occupy on the target disk. The size limit does not include any swap space or recovery partition - considerations. In a setup *without* the systemdisk element, this value + considerations. In a setup *without* the `systemdisk` element, this value specifies the size of the root partition. In a setup that *includes* the - systemdisk element when using LVM, this value specifies the size of the LVM + `systemdisk` element when using LVM, this value specifies the size of the LVM partition that contains all specified volumes. This means that the sum of all specified volume sizes plus the sum of the specified freespace for each volume must be smaller than or equal to the size specified with the `oem-systemsize` - element. This value is represented by the variable ``kiwi_oemrootMB`` in the + element. This value is represented by the variable `kiwi_oemrootMB` in the initrd. The specified value can be dynamically overwritten via the `rd.kiwi.install.systemsize` kernel boot option. If `rd.kiwi.install.systemsize` - is set to `all` this will unset the size limit and the maximum possible - size applies. + is set to `all`, this will unset the size limit, and the maximum possible + size will apply. oemconfig.oem-unattended The installation of the image to the target system occurs automatically without requiring user interaction. If multiple possible target devices are discovered, the image is deployed to - the first device. ``kiwi_oemunattended`` in the initrd. + the first device. `kiwi_oemunattended` in the initrd. oemconfig.oem-unattended-id Selects a target disk device for the installation according to the specified device ID. The device ID corresponds to the name of the device for the configured `devicepersistency`. By default, it is the `by-uuid` device - name. If no representation exists, for example for ramdisk devices, the UNIX + name. If no representation exists, for example, for ramdisk devices, the UNIX device node can be used to select one. The given name must be present in the device list detected by KIWI. oemconfig.oem-skip-verify - Disables the checksum verification process after installing of the image to + Disables the checksum verification process after installing the image on the target disk. The verification process computes the checksum of the image - installed to the target. This value is then compared to the initrd embedded - checksum generated at build time of the image. Depending on the size of the + installed on the target. This value is then compared to the initrd-embedded + checksum generated at the build time of the image. Depending on the size of the image and machine power, computing the checksum may take time. .. _installmedia_customize: diff --git a/doc/source/building_images/build_kis.rst b/doc/source/building_images/build_kis.rst index 7cb375f4..ff50d804 100644 --- a/doc/source/building_images/build_kis.rst +++ b/doc/source/building_images/build_kis.rst @@ -6,7 +6,7 @@ Build KIS Image (Kernel, Initrd, System) .. sidebar:: Abstract This page explains how to build an image that consists - out of three components: the kernel an initrd, and an + of three components: the kernel, an initrd, and an optional root filesystem image. In {kiwi} terminology, this type of image is called KIS. @@ -18,15 +18,15 @@ are expected to be used. The predecessor of this image type was called in a PXE boot environment. However, this assumption is not always true, and the image components may be used in different ways. Because there are so many possible deployment strategies -for a `kernel` plus `initrd` and optional `system root filesystem`, +for a `kernel` plus `initrd` and an optional `system root filesystem`, {kiwi} provides this as the universal `KIS` type. -The former `pxe` image type still exist, but it is expected +The former `pxe` image type still exists, but it is expected to be used only in combination with the legacy `netboot` infrastructure, as described in :ref:`build_legacy_pxe`. To add a KIS build to an appliance, create a `type` element with -`image` set to `kis` in the :file:`config.xml` as shown below: +`image` set to `kis` in :file:`config.xml`, as shown below: .. code:: xml @@ -35,7 +35,7 @@ To add a KIS build to an appliance, create a `type` element with With this image type setup, {kiwi} builds a kernel and initrd -not associated with any system root file system. Normally, such +not associated with any system root filesystem. Normally, such an image is only useful with certain custom dracut extensions as part of the image description. @@ -44,17 +44,17 @@ building KIS images: - `filesystem`: Specifies the root filesystem and triggers the build of an additional filesystem image of that filesystem. The generated - kernel command-line options file (append file) then also - include a `root=` parameter that references this filesystem image UUID. - Whther the information from the append file should be used or not is + kernel command-line options file (append file) will then also + include a `root=` parameter that references this filesystem image's UUID. + Whether the information from the append file should be used or not is optional. - `kernelcmdline`: Specifies kernel command-line options that are part of the generated kernel command-line options file (append file). - By default, the append file contains neither information nor the reference - to the root UUID, if the `filesystem` attribute is used. + By default, the append file contains neither information nor a reference + to the root UUID if the `filesystem` attribute is used. -All other attributes of the `type` element that applies to an optional +All other attributes of the `type` element that apply to an optional root filesystem image remain in effect in the system image of a KIS image as well. @@ -83,9 +83,9 @@ tested with QEMU as follows: .. note:: - For testing the components of a KIS image normally requires a deployment + Testing the components of a KIS image normally requires a deployment infrastructure and a deployment process. An example of a deployment infrastructure using PXE is provided by {kiwi} with the `netboot` infrastructure. However, that netboot infrastructure is no longer developed - and only kept for compatibility reasons. For details, see - :ref:`build_legacy_pxe` + and is only kept for compatibility reasons. For details, see + :ref:`build_legacy_pxe`. diff --git a/doc/source/building_images/build_live_iso.rst b/doc/source/building_images/build_live_iso.rst index fe84889d..f73aeb72 100644 --- a/doc/source/building_images/build_live_iso.rst +++ b/doc/source/building_images/build_live_iso.rst @@ -10,13 +10,13 @@ Build an ISO Hybrid Live Image * how to build an ISO image * how to run the image with QEMU -A Live ISO image is a system on a removable media, for example a CD/DVD or a USB +A Live ISO image is a system on removable media, for example, a CD/DVD or a USB stick. Booting a Live ISO image does not interfere with other system storage components, making it a useful portable system for demonstration, testing, and debugging. To add a Live ISO build to your appliance, create a `type` element with -`image` set to `iso` in the :file:`config.xml` file as shown below: +`image` set to `iso` in the :file:`config.xml` file, as shown below: .. code:: xml @@ -37,25 +37,25 @@ Live ISO images: If set to `overlay`, the kiwi-live dracut module supplied by {kiwi} is used for booting. - If set to `dmsquash`, the dracut-supplied dmsquash-live module is + If set to `dmsquash`, the dracut-supplied `dmsquash-live` module is used for booting. Both modules support a different set of live features. - For details see :ref:`live_features` + For details, see :ref:`live_features`. - `filesystem`: Specifies the root filesystem for the live system. If set to `squashfs`, the root filesystem is written into a squashfs image. - This option is not compatible with device-mapper specific features of the - dmsquash-live dracut module. In that case, use overayfs. + This option is not compatible with device-mapper-specific features of the + `dmsquash-live` dracut module. In that case, use `overlayfs`. If set to a value different from `squashfs`, the root filesystem is written - into a filesystem image of the specified type, and the filesystem image + into a filesystem image of the specified type, and the filesystem image is written into a squashfs image for compression. The default value of this option is `ext4`. -- `hybridpersistent`: Accepts `true` or `false`, if set to `true`, the +- `hybridpersistent`: Accepts `true` or `false`; if set to `true`, the resulting image is created with a COW file to keep data persistent over a reboot. @@ -92,40 +92,40 @@ deployment. ---------------------------------- Whether you choose the `overlay` or `dmsquash` dracut module depends on the -features you intend to use. The `overlay` module supports only overlayfs -based overlays, but with automatic creation of a writable layer for -persistence. The `dmsquash` module supports overlayfs as well as -device-mapper based overlays. +features you intend to use. The `overlay` module supports only `overlayfs`-based +overlays but with automatic creation of a writable layer for +persistence. The `dmsquash` module supports `overlayfs` as well as +device-mapper-based overlays. The following list describes important Live ISO features and their support status in the `overlay` and `dmsquash` modules. ISO scan Usable in the same way with both dracut modules. This feature allows - to boot the Live ISO as a file from a grub loopback configured bootloader. + you to boot the Live ISO as a file from a grub loopback-configured bootloader. The `live-grub-stick` tool is one example that uses this feature. - For details how to setup ISO scan with the `overlay` module see - :ref:`iso_as_file_to_usb_stick` + For details on how to set up ISO scan with the `overlay` module, see + :ref:`iso_as_file_to_usb_stick`. ISO in RAM completely Usable with the `dmsquash` module through `rd.live.ram`. The `overlay` - module does not support this mode, while {kiwi} supports RAM only systems - as OEM deployment into RAM from an install ISO media. For details how - to setup RAM only deployments in {kiwi} see: :ref:`ramdisk_deployment` + module does not support this mode, while {kiwi} supports RAM-only systems + as OEM deployment into RAM from an install ISO media. For details on + how to set up RAM-only deployments in {kiwi}, see :ref:`ramdisk_deployment`. Overlay based on overlayfs - Usable with both dracut modules. The readonly root filesystem is - overlaid with a readwrite filesystem using the kernel overlayfs + Usable with both dracut modules. The read-only root filesystem is + overlaid with a read-write filesystem using the kernel's `overlayfs` filesystem. -Overlay based on device mapper snapshots - Usable with the `dmsquash` module. A squashfs compressed readonly root - is overlaid with a readwrite filesystem using a device mapper +Overlay based on device-mapper snapshots + Usable with the `dmsquash` module. A squashfs-compressed read-only root + is overlaid with a read-write filesystem using a device-mapper snapshot. Media Checksum Verification - Boot the Live iso only for ISO checksum verification. This is possible with - both modules but the `overlay` module uses the `checkmedia` tool, whereas the + Boot the Live ISO only for ISO checksum verification. This is possible with + both modules, but the `overlay` module uses the `checkmedia` tool, whereas the upstream `dmsquash` module uses `checkisomd5`. The verification process is triggered by passing the kernel option `mediacheck` for the `overlay` module and `rd.live.check` for the `dmsquash` module. @@ -134,7 +134,7 @@ Live ISO through PXE boot Boot the Live image via the network. This is possible with both modules, but it uses different technologies. The `overlay` module supports network boot only in combination with the AoE (Ata Over Ethernet) protocol. - For details see :ref:`network_live_boot`. The `dmsquash` module supports + For details, see :ref:`network_live_boot`. The `dmsquash` module supports network boot by fetching the ISO image into memory from `root=live:` using the `livenet` module. @@ -142,12 +142,12 @@ Persistent Data Keep new data persistent on a writable storage device. This can be done with both modules but in different ways. The `overlay` module activates persistency with the kernel boot parameter `rd.live.overlay.persistent`. - If the persistent setup cannot be created the fallback to the non persistent - mode applies automatically. The `overlay` module auto detects if it is - used on a disk or ISO scan loop booted from a file. If booted as disk, - persistency is setup on a new partition of that disk. If loop booted - from file, persistency is setup on a new cow file. The cow file/partition - setup can be influenced with the kernel boot parameters: + If the persistent setup cannot be created, the fallback to the non-persistent + mode applies automatically. The `overlay` module autodetects if it is + used on a disk or ISO scan loop booted from a file. If booted as a disk, + persistency is set up on a new partition of that disk. If loop-booted + from a file, persistency is set up on a new COW file. The COW file/partition + setup can be influenced by the kernel boot parameters: `rd.live.overlay.cowfs` and `rd.live.cowfile.mbsize`. The `dmsquash` module configures persistency through the `rd.live.overlay` option exclusively and does not support the automatic creation of a write @@ -157,4 +157,4 @@ Persistent Data Documentation for the upstream `dmsquash` module can be found `here `_. - Options to setup `dmsquash` are marked with `rd.live` + Options to set up `dmsquash` are marked with `rd.live`. diff --git a/doc/source/building_images/build_simple_disk.rst b/doc/source/building_images/build_simple_disk.rst index fb600c63..64db8d39 100644 --- a/doc/source/building_images/build_simple_disk.rst +++ b/doc/source/building_images/build_simple_disk.rst @@ -8,20 +8,20 @@ Build a Virtual Disk Image This page explains how to build a simple disk image. It covers the following topics: - - define a simple disk image in the image description - - build a simple disk image - - run it with QEMU + - defines a simple disk image in the image description + - builds a simple disk image + - runs it with QEMU A simple virtual disk image is a compressed system disk with additional metadata useful for cloud frameworks like Amazon EC2, Google Compute Engine, or Microsoft Azure. It is used as the native disk of a system, and it does -not require an additional installation workflow or a complex first boot setup +not require an additional installation workflow or a complex first-boot setup procedure. To enable {kiwi} to build a simple disk image, add a `type` element with -`image="oem"` in :file:`config.xml`, where the `oem-resize` option -disabled. An example configuration for a 42 GB large VMDK image with -512 MB RAM, an IDE controller and a bridged network interface is shown +`image="oem"` in :file:`config.xml`, where the `oem-resize` option is +disabled. An example configuration for a 42-GB large VMDK image with +512 MB of RAM, an IDE controller, and a bridged network interface is shown below: .. code:: xml @@ -45,25 +45,25 @@ below: -The following attributes of the `type` element are deserve attention +The following attributes of the `type` element deserve attention when building simple disk images: -- `format`: Specifies the format of the virtual disk, possible values are: - `gce`, `ova`, `qcow2`, `vagrant`, `vmdk`, `vdi`, `vhd`, `vhdx` and +- `format`: Specifies the format of the virtual disk. Possible values are + `gce`, `ova`, `qcow2`, `vagrant`, `vmdk`, `vdi`, `vhd`, `vhdx`, and `vhd-fixed`. - `formatoptions`: Specifies additional format options passed to - :command:`qemu-img`. `formatoptions` is a comma-separated list of format - specific options in a ``name=value`` format as expected by + :command:`qemu-img`. `formatoptions` is a comma-separated list of format- + specific options in a `name=value` format, as expected by :command:`qemu-img`. {kiwi} forwards the settings from the attribute as a parameter to the `-o` option in the :command:`qemu-img` call. -The `bootloader`, `size` and `machine` child-elements of `type` can be +The `bootloader`, `size`, and `machine` child elements of `type` can be used to customize the virtual machine image. These elements are described in -the following sections: :ref:`disk-bootloader`, :ref:`disk-the-size-element` -and :ref:`disk-the-machine-element` +the following sections: :ref:`disk-bootloader`, :ref:`disk-the-size-element`, +and :ref:`disk-the-machine-element`. -Once your image description is finished , you can build the image using the +Once your image description is finished, you can build the image using the following {kiwi} command: .. code:: bash @@ -84,13 +84,13 @@ You can test the image using QEMU: -m 4096 For further information on how to configure the image to work within a cloud -framework see: +framework, see: * :ref:`setup_for_ec2` * :ref:`setup_for_azure` * :ref:`setup_for_gce` -For information on how to setup a Vagrant system, see: :ref:`setup_vagrant`. +For information on how to set up a Vagrant system, see :ref:`setup_vagrant`. .. _disk-bootloader: @@ -108,7 +108,7 @@ Setting up the Bootloader in the Image The `bootloader` element defines which bootloader to use in the image, and the element offers several options for customizing its configuration. -For details, see: :ref:`preferences-type-bootloader` +For details, see :ref:`preferences-type-bootloader`. .. _disk-the-size-element: @@ -116,7 +116,7 @@ Modifying the Size of the Image ------------------------------- The `size` child element of `type` specifies the size of the resulting -disk image. The following example shows an image description, where 20 GB are +disk image. The following example shows an image description where 20 GB are added to the virtual machine image, of which 5 GB are left unpartitioned: .. code:: xml @@ -130,13 +130,13 @@ added to the virtual machine image, of which 5 GB are left unpartitioned: -The following optional attributes can be used to futher customize the image size: +The following optional attributes can be used to further customize the image size: -- `unit`: Defines the unit used for the provided numerical value, possible +- `unit`: Defines the unit used for the provided numerical value. Possible values are `M` for megabytes and `G` for gigabytes. The default unit is megabytes. -- `additive`: Boolean value that determines whether the provided value is added +- `additive`: A boolean value that determines whether the provided value is added to the current image size (`additive="true"`) or whether it is the total size (`additive="false"`). The default value is `false`. @@ -157,27 +157,27 @@ interfaces. The following attributes are supported by the `machine` element: - `ovftype`: The OVF configuration type. The Open Virtualization Format is a - standard for describing virtual appliances and distribute them in an archive - called Open Virtual Appliance (OVA). The standard describes the major + standard for describing virtual appliances and distributing them in an archive + called an Open Virtual Appliance (OVA). The standard describes the major components associated with a disk image. The exact specification depends on - the product using the format. Supported values are `zvm`, `powervm`, `xen` and + the product using the format. Supported values are `zvm`, `powervm`, `xen`, and `vmware`. - `HWversion`: The virtual machine's hardware version (`vmdk` and `ova` - formats only), refer to VMware documentation for further + formats only); refer to VMware documentation for further information on the supported values. - `arch`: the VM architecture (`vmdk` format only). Valid values are `ix86` (= `i585` and `i686`) and `x86_64`. -- `xen_loader`: the Xen target loader which is expected to load the guest. - Valid values are: `hvmloader`, `pygrub` and `pvgrub`. +- `xen_loader`: the Xen target loader that is expected to load the guest. + Valid values are `hvmloader`, `pygrub`, and `pvgrub`. - `guestOS`: The virtual guest OS' identification string for the VM (only applicable for `vmdk` and `ova` formats. Note that the name designation is different for the two formats). - Note: For vmware ovftools, guestOS is a VMX GuestOS, but not VIM GuestOS. - For instance, correct value for Ubuntu 64 bit is "ubuntu-64", but not + Note: For vmware ovftools, guestOS is a VMX GuestOS, but not a VIM GuestOS. + For instance, the correct value for Ubuntu 64-bit is "ubuntu-64", but not "ubuntu64Guest". See GUEST_OS_KEY_MAP in guest_os_tables.h at https://github.com/vmware/open-vm-tools for another guestOS values. @@ -204,7 +204,7 @@ Modifying the VM Configuration Directly The `vmconfig-entry` element is used to add entries directly into the virtual machine's configuration file. This is currently only supported for -the `vmdk` format where the provided strings are directly pasted into the +the `vmdk` format, where the provided strings are directly pasted into the :file:`.vmx` file. The `vmconfig-entry` element has no attributes and can appear multiple @@ -229,8 +229,8 @@ Adding Network Interfaces to the VM ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Network interfaces can be explicitly specified for the VM when required via -the `vmnic` element. This makes is possible to add another bridged interface or -to specify the driver wto be used. +the `vmnic` element. This makes it possible to add another bridged interface or +to specify the driver to be used. Note that this element is used for the `vmdk` image format only. @@ -257,8 +257,8 @@ The `vmnic` element supports the following attributes: - `mode`: The mode of the interface. -Note that {kiwi} doesn **not** verify the values of the -attributes, it only inserts them into the appropriate configuration +Note that {kiwi} does **not** verify the values of the +attributes; it only inserts them into the appropriate configuration files. @@ -287,14 +287,14 @@ Each `vmdisk` element can be further customized using optional attributes: - `controller`: The disk controller used for the VM guest (`vmdk` format - only). Supported values are: `ide`, `buslogic`, `lsilogic`, `lsisas1068`, - `legacyESX` and `pvscsi`. + only). Supported values are `ide`, `buslogic`, `lsilogic`, `lsisas1068`, + `legacyESX`, and `pvscsi`. - `device`: The disk device to appear in the guest (`xen` format only). - `diskmode`: The disk mode (`vmdk` format only). Valid values are `monolithicSparse`, `monolithicFlat`, `twoGbMaxExtentSparse`, - `twoGbMaxExtentFlat` and `streamOptimized` (see also + `twoGbMaxExtentFlat`, and `streamOptimized` (see also https://vdc-download.vmware.com/vmwb-repository/dcr-public/6335f27c-c6e9-4804-95b0-ea9449958403/c7798a8b-4c73-41d9-84e8-db5453de7b17/doc/vddkDataStruct.5.3.html). - `disktype`: The type of the disk handled internally by the VM @@ -307,7 +307,7 @@ Adding CD/DVD Drives {kiwi} supports adding IDE and SCSCI CD/DVD drives to the virtual machine using the `vmdvd` element for the `vmdk` image format. The -following example adds two drives: one with a SCSCI and another with a +following example adds two drives: one with a SCSCI and another with an IDE controller: .. code:: xml diff --git a/doc/source/building_images/build_wsl_container.rst b/doc/source/building_images/build_wsl_container.rst index 044136c9..4a0f8a56 100644 --- a/doc/source/building_images/build_wsl_container.rst +++ b/doc/source/building_images/build_wsl_container.rst @@ -6,7 +6,7 @@ Build a WSL Container Image .. sidebar:: Abstract This page explains how to build a WSL/Appx container image. WSL stands for - Windows Subsystem Linux, and it is a zip-based container format consumable by + Windows Subsystem for Linux, and it is a zip-based container format consumable by Windows 10 with WSL enabled. @@ -14,8 +14,8 @@ Build a WSL Container Image utility. Make sure you have installed the package that provides the command on your build host. -Once the build host has the :command:`appx` installed, the -following image type setup is required in the XML description +Once the build host has the `appx` command installed, the +following image type setup is required in the XML description, :file:`config.xml`: .. code:: xml @@ -23,19 +23,19 @@ following image type setup is required in the XML description The :file:`/meta/data` path specifies a path that provides -additional information required for the :command:`WSL-DistroLauncher`. -This component consists out of a Windows(`exe`) executable file and +additional information required for the `WSL-DistroLauncher`. +This component consists of a Windows (`exe`) executable file and an :file:`AppxManifest.xml` file that references other files, like icons and resource configurations for the startup of the container under Windows. .. note:: **/meta/data** - Except for the root filesystem tarball {kiwi} is not - responsible for providing the meta data required for - the :command:`WSL-DistroLauncher`. It is expected that + Except for the root filesystem tarball, {kiwi} is not + responsible for providing the metadata required for + the `WSL-DistroLauncher`. It is expected that the given metadata path contains all the needed information. - Typically this information is delivered in a package + Typically, this information is delivered in a package provided by the distribution, and it is installed on the build host. @@ -43,7 +43,7 @@ container under Windows. Setup of the WSL-DistroLauncher ------------------------------- -The contents of the :file:`AppxManifest.xml` is changed by {kiwi} +The contents of the :file:`AppxManifest.xml` are changed by {kiwi} if the :file:`containerconfig` section is provided in the XML description. In the context of a WSL image, the following container configuration parameters are taken into account: @@ -65,10 +65,10 @@ information is not specified, the existing :file:`AppxManifest.xml` is left untouched. created_by - Specifies the name of a publisher organization. An appx container - must to be signed off with a digital signature. If the image is - build in the Open Build Service (OBS), this is done automatically. - Outside of OBS, you must o make sure that the given publisher organization + Specifies the name of a publisher organization. An `appx` container + must be signed off with a digital signature. If the image is + built in the Open Build Service (OBS), this is done automatically. + Outside of OBS, you must make sure that the given publisher organization name matches the certificate used for signing. author @@ -76,9 +76,9 @@ author application_id Specifies an ID name for the container. The name must start with - a letter, and only alphanumeric characters are allowed. {kiwi} doesn not - validate the specified name string, because there is no common criteria - for various the container architectures. + a letter, and only alphanumeric characters are allowed. {kiwi} does not + validate the specified name string because there are no common criteria + for the various container architectures. package_version Specifies the version identification for the container. {kiwi} @@ -91,23 +91,23 @@ launcher .. warning:: {kiwi} does not check the configuration in :file:`AppxManifest.xml` - ifor validity or completeness. + for validity or completeness. The following example shows how to build a WSL image based on openSUSE Tumbleweed: -1. Check the example image descriptions, +1. Check the example image descriptions; see :ref:`example-descriptions`. -#. Include the ``Virtualization/WSL`` repository to the list ((replace `` - with the desired distribution)): +#. Include the `Virtualization/WSL` repository in the list (replace `` + with the desired distribution): .. code:: bash $ zypper addrepo http://download.opensuse.org/repositories/Virtualization:/WSL/ WSL -#. Install :command:`fb-util-for-appx` utility and the package that - provides the :command:`WSL-DistroLauncher` metadata. See the +#. Install the `fb-util-for-appx` utility and the package that + provides the `WSL-DistroLauncher` metadata. See the previous note on :file:`/meta/data`. .. code:: bash @@ -116,10 +116,10 @@ openSUSE Tumbleweed: .. note:: - When building images with the Open Build Servic,e make sure - to add the packages from the zypper command above to the - project configuration via :command:`osc meta -e prjconf` along with - the line :file:`support: PACKAGE_NAME` for + When building images with the Open Build Service, make sure + to add the packages from the `zypper` command above to the + project configuration via `osc meta -e prjconf` along with + the line `support: PACKAGE_NAME` for each package that needs to be installed on the Open Build Service worker that runs the {kiwi} build process. @@ -146,7 +146,7 @@ openSUSE Tumbleweed: If the configured metadata path does not exist, the build will fail. Furthermore, {kiwi} does not check whether the metadata is complete or is - valid according to the requirements of the :command:`WSL-DistroLauncher` + valid according to the requirements of the `WSL-DistroLauncher`. #. Build the image with {kiwi}: @@ -162,5 +162,5 @@ Testing the WSL image For testing the image, you need a Windows 10 system. Before you proceed, enable the optional feature named :file:`Microsoft-Windows-Subsystem-Linux`. For -further details on how to setup the Windows machine, see: `Windows Subsystem for Linux -`__ +further details on how to set up the Windows machine, see `Windows Subsystem for Linux +`__. diff --git a/doc/source/commands/image_info.rst b/doc/source/commands/image_info.rst index 1939aa8c..80c9ed09 100644 --- a/doc/source/commands/image_info.rst +++ b/doc/source/commands/image_info.rst @@ -28,8 +28,8 @@ DESCRIPTION Provides information about the specified image description. If no specific info option is provided, the command lists basic information about the image. This information is also available in the image XML description file. Specifying an -extension option like `resolve-package-list` makes a dependency resolver to -run through the list of packages, providing more detailed information about +extension option like `resolve-package-list` makes a dependency resolver run +through the list of packages, providing more detailed information about the image description. .. _db_image_info_opts: @@ -39,7 +39,7 @@ OPTIONS --add-repo= - Add repository with given source, type, alias and priority. + Adds a repository with the given source, type, alias, and priority. --description= @@ -48,15 +48,15 @@ OPTIONS --ignore-repos - Ignore all repository configurations from the XML description. - This option is usually used together with the --add-repo - option. Otherwise there are no repositories available for the + Ignores all repository configurations from the XML description. + This option is usually used together with the `--add-repo` + option. Otherwise, there are no repositories available for processing the requested image information, which could lead to an error. --list-profiles - list profiles available for the selected/default type. + Lists profiles available for the selected/default type. NOTE: If the image description is designed in a way that there @@ -67,39 +67,39 @@ OPTIONS --print-kiwi-env - print kiwi profile environment variables. The listed variables + Prints kiwi profile environment variables. The listed variables are available in the shell environment of the kiwi hook scripts. NOTE: The kiwi profile environment grows during the build process. - When used in early stages e.g. in a post_bootstrap.sh script + When used in early stages, e.g., in a `post_bootstrap.sh` script, it can happen that not all variables have a value. The setup of the kiwi profile environment in the image info output can therefore also only list the static configuration values - which are known at the beginning of a build process. + that are known at the beginning of a build process. --resolve-package-list - Solve package dependencies and return a list of all - packages including their attributes, for example size, + Solves package dependencies and returns a list of all + packages, including their attributes, for example, size, shasum, and more. --print-xml - Print image description in the XML format. The specified image description is + Prints the image description in the XML format. The specified image description is converted to XML and sent to the XSLT stylesheet processor. The result is then validated using the RelaxNG schema and the schematron rules. The command is normally used to convert an old image description to the latest schema. --print-yaml - Behaves similar to `--print-xml`, but after validation, the result is + Behaves similarly to `--print-xml`, but after validation, the result is converted to the YAML format. The command can be used for different operations: * Conversion of the specified image description from or into different formats. This requires the `anymarkup` Python module to be installed. The - module is not a hard requirement and loaded on demand. If the module is - missing, requests to convert to other format than XML fail. + module is not a hard requirement and is loaded on demand. If the module is + missing, requests to convert to a format other than XML will fail. - * Update of an old image description to the latest schema + * Updates an old image description to the latest schema. diff --git a/doc/source/commands/image_resize.rst b/doc/source/commands/image_resize.rst index aba9e05d..362b98ff 100644 --- a/doc/source/commands/image_resize.rst +++ b/doc/source/commands/image_resize.rst @@ -22,7 +22,7 @@ SYNOPSIS DESCRIPTION ----------- -For disk based images, allow to resize the image to a new disk geometry. The +For disk-based images, this allows you to resize the image to a new disk geometry. The additional space is free and not in use by the image. The OEM boot code in {kiwi} offers a resizing procedure that can be used to make use of the additional free space. For OEM image builds, it is advisable to run the resizing @@ -36,14 +36,14 @@ OPTIONS --root= The path to the root directory. If not specified, kiwi - searches the root directory in build/image-root under + searches for the root directory in `build/image-root` under the specified target directory. --size= - New size of the image. The value is either a size in bytes, + The new size of the image. The value is either a size in bytes, or it can be specified with m (MB) or g (GB). Example: 20g --target-dir= - Directory containing the kiwi build results. + The directory containing the kiwi build results. diff --git a/doc/source/commands/kiwi.rst b/doc/source/commands/kiwi.rst index 68f2578f..1bf5a3c5 100644 --- a/doc/source/commands/kiwi.rst +++ b/doc/source/commands/kiwi.rst @@ -61,8 +61,8 @@ may also include additional files, such as scripts or configuration data. A collection of example image descriptions can be found in the following GitHub repository: https://github.com/OSInside/kiwi-descriptions. Most of the -descriptions provide a so-called appliance image. Appliance is a -small, text-based image including a predefined remote source setup to allow +descriptions provide a so-called appliance image. An appliance is a +small, text-based image, including a predefined remote source setup to allow the installation of missing software components. Although {kiwi} operates in two steps, the system build command combines both @@ -75,9 +75,9 @@ the prepared contents of the new image root tree to create an output image. {kiwi} supports the creation of the following image types: - ISO Live Systems -- virtual disk for e.g cloud frameworks +- virtual disk for, e.g., cloud frameworks - OEM expandable disk for system deployment from ISO or the network -- file system images for deployment in a PXE boot environment +- filesystem images for deployment in a PXE boot environment Depending on the image type, different disk formats and architectures are supported. @@ -89,41 +89,41 @@ GLOBAL OPTIONS --color-output - Use escape sequences to print different types of information in colored + Uses escape sequences to print different types of information in colored output. for this option to work, the underlying terminal must support those escape characters. Error messages appear in red, warning messages in yellow, and debugging information is printed in light grey. --config= - Use specified runtime configuration file. If not specified, the + Use the specified runtime configuration file. If not specified, the runtime configuration is expected to be in the :file:`~/.config/kiwi/config.yml` or :file:`/etc/kiwi.yml` files. --debug - Print debug information on the command line. Same as: `--loglevel 10`. + Prints debug information on the command line. Same as: `--loglevel 10`. --debug-run-scripts-in-screen - Run scripts called by {kiwi} in a screen session. + Runs scripts called by {kiwi} in a screen session. --logfile= - Specify log file. The logfile contains detailed information about - the process. The special call: `--logfile stdout` sends all + Specifies the log file. The logfile contains detailed information about + the process. The special call `--logfile stdout` sends all information to standard out instead of writing to a file. --logsocket= - Send log data to the specified Unix Domain socket in the same + Sends log data to the specified Unix Domain socket in the same format as with `--logfile`. --loglevel= - Specify logging level as a number. Further info about the + Specifies the logging level as a number. Further info about the available log levels can be found at: - https://docs.python.org/3/library/logging.html#logging-levels + https://docs.python.org/3/library/logging.html#logging-levels. Setting a log level displays all messages above the specified level. .. code:: bash @@ -141,51 +141,51 @@ GLOBAL OPTIONS --profile= - Select profile to use. The specified profile must be part of the + Selects a profile to use. The specified profile must be part of the XML description. The option can be specified multiple times to allow a combination of profiles. --setenv= - export environment variable and its value into the caller - environment. This option can be specified multiple times + exports an environment variable and its value into the caller's + environment. This option can be specified multiple times. --shared-cache-dir= - Specify an alternative shared cache directory. The directory + Specifies an alternative shared cache directory. The directory is shared via bind mount between the build host and image root system, and it contains information about package repositories - and their cache and meta data. The default location is `/var/cache/kiwi`. + and their cache and metadata. The default location is `/var/cache/kiwi`. --temp-dir= - Specify an alternative base temporary directory. The - provided path is used as base directory to store temporary - files and directories. Default is `/var/tmp`. + Specifies an alternative base temporary directory. The + provided path is used as a base directory to store temporary + files and directories. The default is `/var/tmp`. --target-arch= - Specify an image architecture. By default, the host architecture is used as + Specifies an image architecture. By default, the host architecture is used as the image architecture. If the specified architecture name does not match the - host architecture (thus requesting a cross architecture image build), you must + host architecture (thus requesting a cross-architecture image build), you must configure the support for the image architecture and binary format on the building host. This must be done during the preparation stage, and it is beyond the scope of {kiwi}. --type= - Select an image build type. The specified build type must be configured + Selects an image build type. The specified build type must be configured as part of the XML description. --kiwi-file= - Basename of kiwi file that contains the main image + The basename of the kiwi file that contains the main image configuration elements. If not specified, kiwi uses - a file named `config.xml` or a file matching `*.kiwi` + a file named `config.xml` or a file matching `*.kiwi`. --version - Show program version + Show the program version. .. _db_commands_kiwi_example: diff --git a/doc/source/commands/result_bundle.rst b/doc/source/commands/result_bundle.rst index d7cc500e..5a9dbb9d 100644 --- a/doc/source/commands/result_bundle.rst +++ b/doc/source/commands/result_bundle.rst @@ -23,7 +23,7 @@ SYNOPSIS DESCRIPTION ----------- -Create a result bundle from the image build in the specified target directory. +Creates a result bundle from the image build in the specified target directory. Each resulting image contains the specified bundle identifier as part of its filename. Uncompressed image files are also compressed as an XZ archive. An SHA checksum is generated for each resulting image. @@ -35,12 +35,12 @@ OPTIONS --bundle-dir= - Directory containing the bundle results, compressed versions of + The directory containing the bundle results, compressed versions of image results, and SHA checksum files. --bundle-format= - Specify the bundle format to create the bundle. If provided, + Specifies the bundle format to create the bundle. If provided, this setting will overwrite an eventually provided `bundle_format` attribute from the main image description. The format string can contain placeholders for the following elements: @@ -58,15 +58,15 @@ OPTIONS --id= Bundle ID. It is a free-form text appended to the image - version information as part of the result image filename. + version information as part of the resulting image filename. --target-dir= - Directory containing the {kiwi} build results. + The directory containing the {kiwi} build results. --zsync_source= - Download location of the bundle file or files. Only relevant if `zsync` is + The download location of the bundle file or files. Only relevant if `zsync` is used to sync the bundle. * The zsync control file is created for the bundle files marked for compression. @@ -80,4 +80,4 @@ OPTIONS --no-compress Do not compress the result image file(s). Note: Image files that - were already produced as compressed variants stays compressed. + were already produced as compressed variants stay compressed. diff --git a/doc/source/commands/result_list.rst b/doc/source/commands/result_list.rst index 6c0be92e..462ea7da 100644 --- a/doc/source/commands/result_list.rst +++ b/doc/source/commands/result_list.rst @@ -19,7 +19,7 @@ SYNOPSIS DESCRIPTION ----------- -List build results from a previous build or create command. During multiple +Lists build results from a previous build or create command. During multiple image builds with the same target directory, the build result information is overwritten every time you build an image. This means that the build result list is valid for the last build only. diff --git a/doc/source/commands/system_build.rst b/doc/source/commands/system_build.rst index c39a66ba..ea0e8f6b 100644 --- a/doc/source/commands/system_build.rst +++ b/doc/source/commands/system_build.rst @@ -43,8 +43,8 @@ DESCRIPTION Build an image in one step. The build command combines preparation and building steps, which makes it possible to create an image with a single command. The build command creates the root directory of the image under -`/build/image-root` and writes a log file -`/build/image-root.log`. The result image files are created in the +`/build/image-root` and writes a log file, +`/build/image-root.log`. The resulting image files are created in the specified target directory. .. _db_kiwi_system_build_opts: @@ -54,25 +54,25 @@ OPTIONS --add-bootstrap-package= - Specify package to install as part of the early {kiwi} bootstrap phase. + Specifies a package to install as part of the early {kiwi} bootstrap phase. The option can be specified multiple times. --add-container-label= - Add a container label in the container configuration metadata. It + Adds a container label in the container configuration metadata. It overwrites the label with the provided key-value pair if it is already defined in the XML description. --add-package= - Specify package to add (install). The option can be specified + Specifies a package to add (install). The option can be specified multiple times. --add-repo= - Add a new repository to the existing repository setup in the XML + Adds a new repository to the existing repository setup in the XML description. This option can be specified multiple times. - For details about the possible option values see the **--set-repo** + For details about the possible option values, see the **--set-repo** information below. --add-repo-credentials= @@ -84,65 +84,65 @@ OPTIONS --allow-existing-root - Use an existing root directory from a previous + Uses an existing root directory from a previous build attempt. Use with caution, because this can cause an inconsistent - root tree if the existing contents does not fit to the + root tree if the existing contents do not fit the previous image type setup. --clear-cache - Delete repository cache for each of the used repositories + Deletes the repository cache for each of the used repositories before installing any package. This is useful when an image build validates the signature of the package from the original repository source for any build. Some package managers unconditionally trust the contents of the cache, which works for - cache data dedicated to one build. In case of {kiwi}, the cache + cache data dedicated to one build. In the case of {kiwi}, the cache is shared between multiple image builds on that host for performance reasons. --ca-cert= - Add a cert-file to the directory storing additional local CA certificates. + Adds a cert file to the directory storing additional local CA certificates. The import will occur immediately after the bootstrap process, where the required CA update tooling is expected to be installed. This option is useful for situations where certificates are not packaged, - or the certificates are required during the build process, e.g. due + or the certificates are required during the build process, e.g., due to proxy servers in the build environment that need certificates in chroot. The option can be specified multiple times. --ca-target-distribution= - Specify target distribution for the import of certificates - via the --ca-cert options(s) and/or the provided + Specifies the target distribution for the import of certificates + via the `--ca-cert` options(s) and/or the provided `` from the image description. The selected distribution is used - in KIWI to map the distribution specific CA storage path and + in KIWI to map the distribution-specific CA storage path and update tool for the import process. --delete-package= - Specify package to delete. The option can be specified + Specifies a package to delete. The option can be specified multiple times. --description= - Path to an XML description. This is a directory containing at least - one _config.xml_ or _*.kiwi_ XML file. + The path to an XML description. This is a directory containing at least + one `_config.xml_` or `_*.kiwi_` XML file. --ignore-repos - Ignore all repository configurations from the XML description. - This option is used in combination with the `--add-repo`` + Ignores all repository configurations from the XML description. + This option is used in combination with the `--add-repo` option. Otherwise, there are no repositories available for an image build, which leads to an error. --ignore-repos-used-for-build Works the same way as `--ignore-repos`, except that repository configuration - with the imageonly attribute set to **true** is not ignored. + with the `imageonly` attribute set to **true** is not ignored. --set-repo= - Overwrite the first repository entry in the XML description with the + Overwrites the first repository entry in the XML description with the provided information: - **source** @@ -158,7 +158,7 @@ OPTIONS - **alias** An alias name for the repository. If not specified, {kiwi} generates - an alias name as result of hex representation from uuid4. While the hex + an alias name as a result of a hex representation from uuid4. While the hex is used to uniquely identify the repository, it is not descriptive. We recommend using descriptive aliases. @@ -172,7 +172,7 @@ OPTIONS - **imageinclude** Set to either **true** or **false** to indicate if the repository - is be part of the system image repository setup or not. + is part of the system image repository setup or not. - **package_gpgcheck** @@ -181,17 +181,17 @@ OPTIONS - **{signing_keys}** - List of signing_keys enclosed in curly brackets and delimited by - the semicolon. The reference to a signing key must be provided in the URI + A list of `signing_keys` enclosed in curly brackets and delimited by + a semicolon. The reference to a signing key must be provided in the URI format. - **components** - Component list for Debian-based repos as space-delimited string. + A component list for Debian-based repos as a space-delimited string. - **distribution** - Main distribution name for Debian-based repos. + The main distribution name for Debian-based repos. - **repo_gpgcheck** @@ -200,53 +200,53 @@ OPTIONS - **repo_sourcetype** - Specify the source type of the repository path. Supported values - are baseurl, metalink or mirrorlist. With baseurl the source - path is interpreted as simple URI. If metalink is set the source - path is resolved as metalink URI and if mirrorlist is set the + Specifies the source type of the repository path. Supported values + are `baseurl`, `metalink`, or `mirrorlist`. With `baseurl`, the source + path is interpreted as a simple URI. If `metalink` is set, the source + path is resolved as a metalink URI, and if `mirrorlist` is set, the source path is resolved as a mirrorlist file. If not specified, - baseurl is the default + `baseurl` is the default. --set-repo-credentials= - For **uri://user:pass@location** type repositories, set the user and + For **uri://user:pass@location**-type repositories, set the user and password connected to the set-repo specification. If the provided value describes a filename in the filesystem, the first line of that file is used as credentials. --set-container-derived-from= - Overwrite the source location of the base container for the selected + Overwrites the source location of the base container for the selected image type. The setting applies only if the configured image type - is setup with an initial derived_from reference. + is set up with an initial `derived_from` reference. --set-container-tag= - Overwrite the container tag in the container configuration. + Overwrites the container tag in the container configuration. The setting is only effective if the container configuration provides the initial tag value. --set-type-attr= - Overwrite/set the attribute with the provided value in the selected - build type section. Example: `--set-type-attr volid=some` + Overwrites/sets the attribute with the provided value in the selected + build type section. Example: `--set-type-attr volid=some`. --set-release-version= - Overwrite/set the release-version element in the selected - build type preferences section + Overwrites/sets the release-version element in the selected + build type preferences section. --signing-key= - Set the key file to be trusted and imported into the package - manager database before performing any operation. This is useful + Sets the key file to be trusted and imported into the package + manager's database before performing any operation. This is useful when an image build validates repository and package signatures during build time. This option can be specified multiple times. --target-dir= - Path to store the build results. + The path to store the build results. .. _db_kiwi_system_build_uri: @@ -255,18 +255,18 @@ URI_TYPES - **http://** | **https://** | **ftp://** - Remote repository delivered via the HTTP or FTP protocol. + A remote repository delivered via the HTTP or FTP protocol. - **obs://** - Open Buildservice repository. The source data is translated into + An Open Buildservice repository. The source data is translated into an HTTP URL pointing to http://download.opensuse.org. - **ibs://** - Internal Open Buildservice repository. The source data is translated into + An internal Open Buildservice repository. The source data is translated into an HTTP URL pointing to download.suse.de. - **dir://** - Local directory. + A local directory. diff --git a/doc/source/commands/system_create.rst b/doc/source/commands/system_create.rst index ac7a71a9..5bdbc3fe 100644 --- a/doc/source/commands/system_create.rst +++ b/doc/source/commands/system_create.rst @@ -23,7 +23,7 @@ DESCRIPTION ----------- Create an image from the previously prepared image root directory. The `kiwi -create` command is normally issued after the `kiwi prepare` command, and it and +create` command is normally issued after the `kiwi prepare` command, and it builds the requested image type in the specified target directory. .. _db_kiwi_system_create_opts: @@ -33,19 +33,19 @@ OPTIONS --root= - Path to the image root directory. This directory is normally created by the + The path to the image root directory. This directory is normally created by the `kiwi prepare` command. Keep in mind that if the specified directory is not created using the `kiwi prepare` command, {kiwi} stores image build metadata - in the image/ directory. This directory must exist for the `kiwi create` + in the `image/` directory. This directory must exist for the `kiwi create` command to work correctly. --target-dir= - Path to store the build results. + The path to store the build results. --signing-key= - Trusted key file to be imported into the package manager database before + A trusted key file to be imported into the package manager's database before performing any operation. This is useful if an image build validates repository and package signatures during build time. In the create step, this option only affects the boot image. This option can be specified multiple diff --git a/doc/source/commands/system_prepare.rst b/doc/source/commands/system_prepare.rst index cb2d093d..8f50d253 100644 --- a/doc/source/commands/system_prepare.rst +++ b/doc/source/commands/system_prepare.rst @@ -40,7 +40,7 @@ DESCRIPTION Create a new image root directory. The prepare step sets up a new image root directory from the specified XML description. The specified -directory acts as a root directory of the new image root system. +directory acts as the root directory of the new image root system. You can enter the system as root via chroot using the following command: .. code:: bash @@ -70,49 +70,49 @@ OPTIONS --add-repo= - Add a new repository to the existing repository setup in the XML + Adds a new repository to the existing repository setup in the XML description. This option can be specified multiple times. For details about the supported option values, see the **--set-repo** - information below + information below. --add-repo-credentials= - For **uri://user:pass@location** type repositories, set the user and password + For **uri://user:pass@location**-type repositories, set the user and password connected with an add-repo specification. If the provided value is a filename in the filesystem, the first line of the file is used as credentials. --allow-existing-root - Allow to re-use an existing image root directory. + Allows you to re-use an existing image root directory. --clear-cache - Delete repository cache for each of the used repositories + Deletes the repository cache for each of the used repositories before installing any package. This is useful if an image build validates the signature of the package from the original repository source for any build. Some package managers unconditionally trust the contents of the cache, which works for - cache data dedicated to one build. In case of {kiwi}, the cache + cache data dedicated to one build. In the case of {kiwi}, the cache is shared between multiple image builds on the host for performance reasons. --ca-cert= - Add a cert-file to the directory storing additional local CA certificates. + Adds a cert file to the directory storing additional local CA certificates. The import will occur immediately after the bootstrap process, where the required CA update tooling is expected to be installed. This option is useful for situations where certificates are not packaged, - or the certificates are required during the build process, e.g. due + or the certificates are required during the build process, e.g., due to proxy servers in the build environment that need certificates in chroot. The option can be specified multiple times. --ca-target-distribution= - Specify target distribution for the import of certificates - via the --ca-cert options(s) and/or the provided + Specifies the target distribution for the import of certificates + via the `--ca-cert` option(s) and/or the provided `` from the image description. The selected distribution is used - in KIWI to map the distribution specific CA storage path and + in KIWI to map the distribution-specific CA storage path and update tool for the import process. --delete-package= @@ -122,28 +122,28 @@ OPTIONS --description= - Path to the {kiwi} XML description. The directory must contain at least a - config.xml of \*.kiwi XML description. + The path to the {kiwi} XML description. The directory must contain at least a + `config.xml` or `*.kiwi` XML description. --ignore-repos - Ignore all repository configurations in the XML description. - This option is normally used in combination with the `--add-repo`` + Ignores all repository configurations in the XML description. + This option is normally used in combination with the `--add-repo` option. Otherwise, an image build operation results in an error. --ignore-repos-used-for-build - Works the same way as `--ignore-repos`,` but the repository - configurations that have the imageonly attribute set to **true** + Works the same way as `--ignore-repos`, but the repository + configurations that have the `imageonly` attribute set to **true** are not ignored. --root= - Path to the new root system. + The path to the new root system. --set-repo= - Overwrite the first repository entry in the XML description with the + Overwrites the first repository entry in the XML description with the provided information: - **source** @@ -159,9 +159,9 @@ OPTIONS - **alias** An alias name for the repository. If not specified, {kiwi} generates - an alias name based hex representation of uuid4. While the hex + an alias name based on a hex representation of uuid4. While the hex is used to uniquely identify the repository, it is not descriptive. - We recommend to use a descriptive and unique alias name. + We recommend using a descriptive and unique alias name. - **priority** @@ -182,17 +182,17 @@ OPTIONS - **{signing_keys}** - List of signing_keys enclosed in curly brackets and delimited by - the semicolon. The reference to a signing key must be provided in the URI + A list of signing_keys enclosed in curly brackets and delimited by + a semicolon. The reference to a signing key must be provided in the URI format. - **components** - Component list for Debian-based repos as a space-delimited string. + A component list for Debian-based repos as a space-delimited string. - **distribution** - Main distribution name for Debian-based repos. + The main distribution name for Debian-based repos. - **repo_gpgcheck** @@ -201,45 +201,45 @@ OPTIONS - **repo_sourcetype** - Specify the source type of the repository path. Supported values - are baseurl, metalink or mirrorlist. With baseurl the source - path is interpreted as simple URI. If metalink is set the source - path is resolved as metalink URI and if mirrorlist is set the + Specifies the source type of the repository path. Supported values + are `baseurl`, `metalink`, or `mirrorlist`. With `baseurl`, the source + path is interpreted as a simple URI. If `metalink` is set, the source + path is resolved as a metalink URI, and if `mirrorlist` is set, the source path is resolved as a mirrorlist file. If not specified, - baseurl is the default + `baseurl` is the default. --set-repo-credentials= - For **uri://user:pass@location** type repositories, set the user and + For **uri://user:pass@location**-type repositories, sets the user and password connected to the set-repo specification. If the provided value is a filename in the filesystem, the first line of that file is used as credentials. --set-container-derived-from= - Overwrite the source location of the base container for the selected + Overwrites the source location of the base container for the selected image type. The setting is only effective if the configured image type - is setup with an initial derived_from reference + is set up with an initial derived_from reference. --set-container-tag= - Overwrite the container tag in the container configuration. + Overwrites the container tag in the container configuration. The setting applies only if the container configuration provides an initial tag value. --set-type-attr= - Overwrite/set the attribute with the provided value in the selected - build type section. Example: `--set-type-attr volid=some` + Overwrites/sets the attribute with the provided value in the selected + build type section. Example: `--set-type-attr volid=some`. --set-release-version= - Overwrite/set the release-version element in the selected - build type preferences section + Overwrites/sets the release-version element in the selected + build type preferences section. --signing-key= - Set the key file to be trusted and imported into the package + Sets the key file to be trusted and imported into the package manager database before performing any operation. This is useful if an image build validates repository and package signatures during build time. This option can be specified multiple diff --git a/doc/source/commands/system_update.rst b/doc/source/commands/system_update.rst index 558ac8b2..b8d077f8 100644 --- a/doc/source/commands/system_update.rst +++ b/doc/source/commands/system_update.rst @@ -21,7 +21,7 @@ SYNOPSIS DESCRIPTION ----------- -Update a previously prepare image root tree. The update command refreshes the +Update a previously prepared image root tree. The update command refreshes the contents of the root directory according to the repository setup of the image XML description. The update command can also be used to add or remove packages from the image root tree. diff --git a/doc/source/concept_and_workflow.rst b/doc/source/concept_and_workflow.rst index 93a42b59..897fb034 100644 --- a/doc/source/concept_and_workflow.rst +++ b/doc/source/concept_and_workflow.rst @@ -27,11 +27,11 @@ configured system in a single file) of a Linux distribution in two steps (for further details, see :ref:`working-with-kiwi-image-building-process`): 1. *Prepare operation*: generate an *unpacked image tree* of your - image. The unpacked tree is a directory containing the future file - system of your image, generated from your image description. + image. The unpacked tree is a directory containing the future filesystem + of your image, generated from your image description. 2. *Create operation*: the unpacked tree generated in step 1 is packaged - into the format required for the final usage (e.g. a ``qcow2`` disk + into the format required for the final usage (e.g., a `qcow2` disk image to launch the image with QEMU). {kiwi} executes these steps using the following components, which it expects @@ -39,19 +39,19 @@ to find in the *description directory*: :ref:`image-description`: The :file:`config.xml` file contains the image description, which is a - collection of general settings of the final image, like the image layout + collection of general settings of the final image, like the image layout, installed packages, present users, etc. .. note:: - The filename :file:`config.xml` is not mandatory, the image description + The filename :file:`config.xml` is not mandatory; the image description file can also have an arbitrary name plus the :file:`*.kiwi` extension. {kiwi} first looks for a :file:`config.xml` file. If it cannot be found, it picks the first :file:`*.kiwi` file. :ref:`working-with-kiwi-user-defined-scripts`: If present, custom configuration shell scripts run at different - stages of the build process. They can be used to fine tune + stages of the build process. They can be used to fine-tune the image in ways that are not possible via the settings provided in :file:`config.xml`. @@ -65,7 +65,7 @@ Overlay tree directory: overwritten. CD root user data: - For live ISO images and install ISO images an optional archive + For live ISO images and install ISO images, an optional archive is supported. This is a tar archive matching the name :file:`config-cdroot.tar[.compression_postfix]`. @@ -79,10 +79,10 @@ CD root user data: Image Building Process ---------------------- -{kiwi} creates images in a two step process: The first step, the *prepare* +{kiwi} creates images in a two-step process: The first step, the *prepare* operation, generates a so-called *unpacked image tree* (directory) using the information provided in the :file:`config.xml` configuration file -(see :ref:`image-description`) +(see :ref:`image-description`). The second step, the *create* operation, creates the *packed image* or *image* in the specified format based on the unpacked image tree and the @@ -100,61 +100,61 @@ information provided in the :file:`config.xml` configuration file. The Prepare Step ^^^^^^^^^^^^^^^^ -As the first step, {kiwi} creates an *unpackaged image tree*, also called "root tree". This +As the first step, {kiwi} creates an *unpackaged image tree*, also called a "root tree". This directory will be the installation target for software packages to be installed during the image creation process. For the package installation, {kiwi} relies on the package manager specified -in the ``packagemanager`` element in :file:`config.xml`. {kiwi} supports the -following package managers: ``dnf``, ``zypper`` (default) and ``apt``. +in the `packagemanager` element in :file:`config.xml`. {kiwi} supports the +following package managers: `dnf`, `zypper` (default), and `apt`. The prepare step consists of the following substeps: #. **Create Target Root Directory** - By default {kiwi} aborts with an error if the target root tree + By default, {kiwi} aborts with an error if the target root tree already exists to avoid accidental deletion of an existing unpacked image. The option `--allow-existing-root` can be used - to work based on an existing root tree + to work based on an existing root tree. #. **Bootstrap Target Root Directory** First, {kiwi} configures the package manager to use the repositories specified in the configuration file, via the command line, or both. After the repository setup, the packages specified in the - ``bootstrap`` section of the image description are installed in a + `bootstrap` section of the image description are installed in a temporary directory external to the target root tree. This establishes the initial environment to support the completion of the process in a - chroot setting. At the end of the ``bootstrap`` phase the script + chroot setting. At the end of the `bootstrap` phase, the script :file:`post_bootstrap.sh` is executed, if present. .. note:: - The essential bootstrap packages are usually ``filesystem`` and - ``glibc-locale`` to specify as part of the bootstrap. The dependency + The essential bootstrap packages are usually `filesystem` and + `glibc-locale` to specify as part of the bootstrap. The dependency chain of these two packages is usually sufficient to populate the bootstrap environment with all required software to support the installation of packages into the new root tree. #. **Install Packages** - After the ``bootstrap`` phase all other `` sections are - used to complete the installation as chroot operation. {kiwi} uses - the package manager as installed in the ``bootstrap`` phase and + After the `bootstrap` phase, all other `` sections are + used to complete the installation as a chroot operation. {kiwi} uses + the package manager as installed in the `bootstrap` phase and installs all other packages as configured. .. note:: The installation of software packages through the selected package manager may install unwanted packages. Removing these packages can be - accomplished by marking them for deletion in the image description, see + accomplished by marking them for deletion in the image description; see :ref:`uninstall-system-packages`. #. **Apply the Overlay Tree** Next, {kiwi} applies all files and directories present in the overlay - directory named :file:`root` or in the compressed overlay - :file:`root.tar.gz` to the target root tree. Files already present in + directory named :file:`root` or in the compressed overlay, + :file:`root.tar.gz`, to the target root tree. Files already present in the target root directory are overwritten. This allows you to overwrite any file that was installed by one of the packages during the installation phase. @@ -169,30 +169,30 @@ The prepare step consists of the following substeps: overlay tree, it is possible to overwrite files already existing in the target root tree. -#. **Execute the user-defined script** :file:`config.sh` +#. **Execute the user-defined script** :file:`config.sh`. - At the end of the preparation stage the script :file:`config.sh` is - executed (if present). It is run in the top level directory of the + At the end of the preparation stage, the script :file:`config.sh` is + executed (if present). It is run in the top-level directory of the target root tree. The script's primary function is to complete the - system configuration. For more details about custom scripts - see :ref:`working-with-kiwi-user-defined-scripts` + system configuration. For more details about custom scripts, + see :ref:`working-with-kiwi-user-defined-scripts`. #. **Modify the Root Tree** - The unpacked image tree is now finished to be converted into the final + The unpacked image tree is now finished and can be converted into the final image in the *create step*. It is possible to make manual modifications to the unpacked tree before it is converted into the final image. Since the unpacked image tree is just a directory, it can be modified - using the standard tools. Optionally, it is also possible to "change - root (:command:`chroot`)" into it, for instance to invoke the package - manager. Beside the standard file system layout, the unpacked image tree + using the standard tools. Optionally, it is also possible to 'change + root (`chroot`)' into it, for instance, to invoke the package + manager. Besides the standard filesystem layout, the unpacked image tree contains an additional directory named :file:`/image` that is not present in a regular system. It contains information {kiwi} requires during the create step, including a copy of the :file:`config.xml` file. By default, {kiwi} will not stop after the *prepare step* and will - directly proceed with the *create step*. Therfore to perform manual + proceed directly with the *create step*. Therefore, to perform manual modifications, proceed as follows: .. code:: shell-session @@ -204,11 +204,11 @@ The prepare step consists of the following substeps: .. warning:: Modifications of the unpacked root tree Do not make any changes to the system, since they are lost when - re-running the ``prepare`` step again. Additionally, you may - introduce errors that occur during the ``create`` step which are + re-running the `prepare` step again. Additionally, you may + introduce errors that occur during the `create` step, which are difficult to track. The recommended way to apply changes to the unpacked image directory is to change the configuration and re-run - the ``prepare`` step. + the `prepare` step. .. _create-step: @@ -221,17 +221,17 @@ unpacked root tree into one or multiple output files appropriate for the respective build type. It is possible to create multiple images from the same unpacked -root tree, for example, a self installing OEM +root tree, for example, a self-installing OEM image and a virtual machine image from the same image description. The only prerequisite is that both image types are specified in :file:`config.xml`. -During the *create step* the following operations are performed by {kiwi}: +During the *create step*, the following operations are performed by {kiwi}: -#. **Execute the User-defined Script** :file:`images.sh` +#. **Execute the User-defined Script** :file:`images.sh`. - At the beginning of the image creation process the script named + At the beginning of the image creation process, the script named :file:`images.sh` is executed (if present). For more details about - custom scripts see :ref:`working-with-kiwi-user-defined-scripts` + custom scripts, see :ref:`working-with-kiwi-user-defined-scripts`. #. **Create the Requested Image Type** diff --git a/doc/source/concept_and_workflow/customize_the_boot_process.rst b/doc/source/concept_and_workflow/customize_the_boot_process.rst index 849b90f5..8cdc1fc9 100644 --- a/doc/source/concept_and_workflow/customize_the_boot_process.rst +++ b/doc/source/concept_and_workflow/customize_the_boot_process.rst @@ -10,16 +10,16 @@ This boot image is a compressed cpio initial RAM disk, and it's called the executes :command:`init` or, if present, :command:`linuxrc`. Depending on the image type, {kiwi} creates the boot image automatically during -the ``create`` step. To create the :file:`initrd`, {kiwi} uses a tool called +the `create` step. To create the :file:`initrd`, {kiwi} uses a tool called `dracut`. dracut-generated initrd archives can be extended with custom modules to -add functionality which is not natively provided by dracut itself. In the scope +add functionality that is not natively provided by dracut itself. In the scope of {kiwi}, the following dracut modules are used: ``kiwi-dump`` Serves as an image installer. It provides the required implementation to install a {kiwi} image on a selectable target. This module is required if one - of the attributes in the image type definition `installiso`, `installstick` or - `installpxe` is set to `true`. + of the attributes in the image type definition, `installiso`, `installstick`, or + `installpxe`, is set to `true`. ``kiwi-dump-reboot`` Serves to boot the system into the installed image after installation is @@ -30,8 +30,8 @@ of {kiwi}, the following dracut modules are used: if the `iso` image type is selected. ``kiwi-overlay`` - Allows to boot disk images with the attribute `overlayroot` set to `true`. A - disk like that has its root partition compressed and readonly. The disk boots up + Allows you to boot disk images with the attribute `overlayroot` set to `true`. A + disk like that has its root partition compressed and read-only. The disk boots up using overlayfs for the root filesystem with a separate partition on the same disk for persistent data. @@ -39,7 +39,7 @@ of {kiwi}, the following dracut modules are used: Resizes an OEM disk image after installation on the target disk to meet the size limits configured in the `oemconfig` section of the image description. The module takes over the tasks of - repartitioning the disk, resizing RAID, LVM, LUKS and other layers as well as + repartitioning the disk, resizing RAID, LVM, LUKS, and other layers, as well as resizing the system filesystems. ``kiwi-lib`` @@ -48,8 +48,8 @@ of {kiwi}, the following dracut modules are used: .. note:: Using Custom Boot Image Support In addition to the standard dracut-based creation of the boot image, {kiwi} - supports the use of custom boot images for the image types ``oem`` - and ``pxe``. The use of a custom boot image is enabled by setting the + supports the use of custom boot images for the image types `oem` + and `pxe`. The use of a custom boot image is enabled by setting the following attribute in the image description: .. code:: none @@ -57,21 +57,21 @@ of {kiwi}, the following dracut modules are used: Along with this setting, you must provide a reference to - a boot image description in the ``boot`` attribute as follows: + a boot image description in the `boot` attribute as follows: .. code:: none - While {kiwi} supports this approach, it is recommended using dracut instead. - Keep also in mind that although {kiwi} supports creation of custom boot + While {kiwi} supports this approach, it is recommended to use dracut instead. + Keep also in mind that although {kiwi} supports the creation of custom boot images, {kiwi} does not include any official boot image descriptions. You can find an OEM boot description example at https://build.opensuse.org/package/show/Virtualization:Appliances:Images:Testing_x86:tumbleweed/custom-oem-boot-description - and an PXE boot description example at - https://build.opensuse.org/package/show/Virtualization:Appliances:Images:Testing_x86:tumbleweed/custom-pxe-boot-description + and a PXE boot description example at + https://build.opensuse.org/package/show/Virtualization:Appliances:Images:Testing_x86:tumbleweed/custom-pxe-boot-description. - The custom boot image descriptions makes it possible to completely customize + The custom boot image descriptions make it possible to completely customize the behavior of the initrd. This concept is mostly used in PXE environments that are usually heavily customized and require a specific boot and deployment workflow. @@ -80,7 +80,7 @@ of {kiwi}, the following dracut modules are used: Boot Image Hook-Scripts ....................... -The dracut initrd system uses ``systemd`` to implement a predefined workflow +The dracut initrd system uses `systemd` to implement a predefined workflow of services documented in the bootup man page: http://man7.org/linux/man-pages/man7/dracut.bootup.7.html @@ -155,13 +155,13 @@ before the system rootfs is mounted. and libraries required by the hook script. * Each file must be included in the {kiwi} description either in a - package, archive, or in the root tree of the image description + package, an archive, or in the root tree of the image description directory. - * The parameters of the `inst_multiple` command are space separated. + * The parameters of the `inst_multiple` command are space-separated. - * Each parameter can be a single executable name if it exists in `/bin`, - `/sbin`, `/usr/bin`, or `/usr/sbin`` directories. + * Each parameter can be a single executable name if it exists in the `/bin`, + `/sbin`, `/usr/bin`, or `/usr/sbin` directories. * Otherwise, a full path to the file is required. This normally applies for libraries and other special files. @@ -178,17 +178,17 @@ the `dracut project page `_. Boot Image Parameters ..................... -A dracut generated initrd in a {kiwi} image build process includes one or -more of the {kiwi} provided dracut modules. The following list documents +A dracut-generated initrd in a {kiwi} image build process includes one or +more of the {kiwi}-provided dracut modules. The following list documents the available kernel boot parameters for these modules: ``rd.kiwi.term`` - Exports the TERM variable into the initrd environment. If + Exports the `TERM` variable into the initrd environment. If the default value for the terminal emulation is not correct, `rd.kiwi.term` can be used to overwrite the default. The environment is also passed to the systemd unit that calls - dialog based programs in {kiwi} dracut code, which means that the - TERM setting applies there too. + dialog-based programs in {kiwi} dracut code, which means that the + `TERM` setting applies there too. ``rd.kiwi.debug`` Activates the debug log file for the {kiwi} part of @@ -196,81 +196,81 @@ the available kernel boot parameters for these modules: ``rd.kiwi.dialog.timeout=seconds|off`` Sets a timeout value for dialogs invoked by kiwi dracut - modules. By default the timeout is set to 60 seconds. + modules. By default, the timeout is set to 60 seconds. If set to the special value `off`, the dialog will never - timeout. + time out. ``rd.kiwi.install.devicepersistency=by-*`` Instructs an OEM installation image to present the list of available disk devices using the device names as provided - by the specified `by-*` representation. For example + by the specified `by-*` representation. For example, `rd.kiwi.install.devicepersistency=by-path` would show the by-path device names in the list of available disks. ``rd.kiwi.install.pxe`` - Instructs an OEM installation image to lookup the system + Instructs an OEM installation image to look up the system image on a remote location specified in `rd.kiwi.install.image`. ``rd.kiwi.install.image=URI`` Specifies the remote location of the system image in - a PXE based OEM installation. + a PXE-based OEM installation. ``rd.kiwi.install.pass.bootparam`` - Instructs an OEM installation image to pass an additional + Instructs an OEM installation image to pass additional boot parameters to the kernel used to boot the installed image. This - can be used, for example, to pass on first boot configuration for a PXE image. + can be used, for example, to pass on first-boot configuration for a PXE image. Note that options starting with `rd.kiwi` are not passed to avoid side effects. ``rd.kiwi.install.retain_last`` Instructs an OEM installation to retain the contents of the last partition on the target disk. This setting is only useful - if the last partition does not belong to the main OS e.g. an + if the last partition does not belong to the main OS, e.g., an extra data partition added via the `spare_part` attribute in the type setup of the image description. The implementation also checks if the start address of the last partition on the - target disk matches with the start adress of the image to be - deployed. Only if they match the data on the last partition - can be retained. + target disk matches the start address of the image to be + deployed. Only if they match can the data on the last partition + be retained. ``rd.kiwi.oem.luks.reencrypt`` - For OEM LUKS2 encrypted disk images. If set, reencrypts the disk - prior an eventual resize and therefore creates a new key pool and - master key. The reencryption is advisable if the image binary is - not protected. With access to the image binary it's possible to - extract the luks header which then allows to decrypt the data - unless it was reencrypted. The reencryption process only runs if - the checksum of the luks header still matches the one from the - original disk image. Be aware that the reencryption will ask + For OEM LUKS2-encrypted disk images. If set, it re-encrypts the disk + prior to an eventual resize and therefore creates a new key pool and + master key. The re-encryption is advisable if the image binary is + not protected. With access to the image binary, it's possible to + extract the LUKS header, which then allows you to decrypt the data + unless it was re-encrypted. The re-encryption process only runs if + the checksum of the LUKS header still matches the one from the + original disk image. Be aware that the re-encryption will ask for the passphrase if the image has been built with an initial - luks passphrase. + LUKS passphrase. ``rd.kiwi.oem.luks.reencrypt_randompass`` - For OEM LUKS2 encrypted disk images in combination - with `rd.kiwi.oem.luks.reencrypt`. Reset insecure built time + For OEM LUKS2-encrypted disk images in combination + with `rd.kiwi.oem.luks.reencrypt`. Resets the insecure built-time passphrase, set via the `luks=` attribute, with a random - onetime passphrase that will be stored in memory at + one-time passphrase that will be stored in memory at `/run/.kiwi_reencrypt.keyfile`. .. warning:: The passphrase will only persist as long as the system does not reboot. Using this option usually requires that - the boot process implements code to set a retrievable keyfile - information for subsequent boot processes of this system, e.g + the boot process implements code to set retrievable keyfile + information for subsequent boot processes of this system, e.g., TPM setup or similar. ``rd.kiwi.oem.disk.consistency`` For OEM disk images providing an installation image. If set, the installation image will check against all disks that are - not the selected target disk if there is any disk in the system + not the selected target disk to see if there is any disk in the system that has the same PTUUID compared to the image that is about - to be installed. If such a disk is found this indicates that + to be installed. If such a disk is found, this indicates that the same image was already installed to another storage disk - on the same system which will cause device id inconsistencies - for the entire system. In such a case an error message is - displayed providing information about the conflicting device - and the installation will be cancelled. + on the same system, which will cause device ID inconsistencies + for the entire system. In such a case, an error message is + displayed, providing information about the conflicting device, + and the installation will be canceled. ``rd.kiwi.oem.maxdisk=size[KMGT]`` Specifies the maximum disk size an unattended OEM installation uses for image @@ -282,25 +282,25 @@ the available kernel boot parameters for these modules: ``rd.kiwi.oem.force_resize`` Forces the disk resize process on an OEM disk image. If set, no sanity - check for unpartitioned/free space is performed and also an eventually + check for unpartitioned/free space is performed, and also an eventually configured `` configuration from the image description - will not be taken into account. The disk resize will be started which - includes re-partition as well as all steps to resize the block layers + will not be taken into account. The disk resize will be started, which + includes re-partitioning as well as all steps to resize the block layers up to the filesystem holding the data. As `rd.kiwi.oem.force_resize` bypasses all sanity checks to detect if such a resize process is needed or not, it can happen that all program calls of the resize - process ends without any effect if the disk is already properly + process end without any effect if the disk is already properly resized. It's also important to understand that the partition UUIDs - will change on every resize which might be an unwanted side effect + will change on every resize, which might be an unwanted side effect of a forced resize. ``rd.kiwi.oem.installdevice`` Configures the disk device to use in an OEM installation. This overwrites or resets any other OEM device-specific settings, such as `oem-device-filter`, - `oem-unattended-id` or `rd.kiwi.oem.maxdisk`, and continues the installation on + `oem-unattended-id`, or `rd.kiwi.oem.maxdisk`, and continues the installation on the given device. The device must exist and must be a block special. -.. note:: Non interactive mode activated by rd.kiwi.oem.installdevice +.. note:: Non-interactive mode activated by rd.kiwi.oem.installdevice When setting `rd.kiwi.oem.installdevice` explicitly through the kernel command line, {kiwi} uses the device without prompting for confirmation. @@ -308,7 +308,7 @@ the available kernel boot parameters for these modules: ``rd.live.overlay.size`` Specifies the size for the `tmpfs` filesystem of a live ISO image that is used for the `overlayfs` mount process. If the write area of the overlayfs mount - uses this tmpfs, any new data written during the runtime of the system is + uses this `tmpfs`, any new data written during the runtime of the system is written in this space. The default value is `50%`, meaning half of the available RAM space can be used for writing new data. @@ -317,7 +317,7 @@ the available kernel boot parameters for these modules: ``rd.live.encrypt`` Instructs a live ISO image to encrypt the persistent write partition. - The boot process becomes interactive in this case and the user has + The boot process becomes interactive in this case, and the user has to specify a passphrase at boot time. ``rd.live.overlay.cowfs`` @@ -329,38 +329,38 @@ the available kernel boot parameters for these modules: `live-grub-stick`, the live ISO image is copied as a file on the target device, and a GRUB loopback setup is created there to boot the live system from the file. In this case, the persistent write setup that normally creates an extra - write partition on the target will fail in most situations, because the target + write partition on the target will fail in most situations because the target has no free and unpartitioned space available. To prevent this from happening, a COW file (live_system.cow) of a partition is created alongside the live ISO image file. The default size of the COW file is 500MB. ``rd.live.cowfile.path`` - Effectively used in isoscan loop mounted live systems. For details on this - type of live system refer to :ref:`iso_as_file_to_usb_stick`. + Effectively used in isoscan loop-mounted live systems. For details on this + type of live system, refer to :ref:`iso_as_file_to_usb_stick`. Specifies the path of the COW file below the `/run/initramfs/isoscan` loop - mount point. If not specified the cowfile is placed at + mount point. If not specified, the cowfile is placed at `/run/initramfs/isoscan/live_system.cow`. ``rd.live.dir`` - Specifies a directory that contains the live OS root directory. Default is + Specifies a directory that contains the live OS root directory. The default is `LiveOS`. ``rd.live.squashimg`` - Specifies the name of the squashfs image file which contains the OS root. - Default is `squashfs.img`. + Specifies the name of the squashfs image file that contains the OS root. + The default is `squashfs.img`. ``rd.kiwi.allow_plymouth`` - By default kiwi stops plymouth if present and active in the - initrd. Setting rd.kiwi.allow_plymouth will keep plymouth - active in the initrd including all effects that might have - to the available consoles. + By default, kiwi stops plymouth if it is present and active in the + initrd. Setting `rd.kiwi.allow_plymouth` will keep plymouth + active in the initrd, including all effects that might have + on the available consoles. Boot Debugging '''''''''''''' If the boot process encounters a fatal error, the default behavior is to stop the boot process without any possibility to interact with the system. -To prevent this, activate dracut's builtin debug mode in combination +To prevent this, activate dracut's built-in debug mode in combination with the {kiwi} debug mode as follows: .. code:: bash diff --git a/doc/source/concept_and_workflow/packages.rst b/doc/source/concept_and_workflow/packages.rst index 71853259..896e7465 100644 --- a/doc/source/concept_and_workflow/packages.rst +++ b/doc/source/concept_and_workflow/packages.rst @@ -24,32 +24,32 @@ of packages via the `packages` element. The `packages` element provides a collection of different child elements that instruct {kiwi} when and how to perform package installation or -removal. Each `packages` element acts as a group, whose behavior can be +removal. Each `packages` element acts as a group whose behavior can be configured via the following attributes: - `type`: either `bootstrap`, `image`, `delete`, `uninstall` or one of the following build types: `docker`, `iso`, `oem`, `kis`, `oci`. - Packages for `type="bootstrap"` are pre-installed to populate the images' - root file system before chrooting into it. + Packages for `type="bootstrap"` are pre-installed to populate the image's + root filesystem before chrooting into it. Packages in `type="image"` are installed immediately after the initial - chroot into the new root file system. + chroot into the new root filesystem. Packages in `type="delete"` and `type="uninstall"` are removed from the - image, for details see :ref:`uninstall-system-packages`. + image. For details, see :ref:`uninstall-system-packages`. - And packages which belong to a build type are only installed when that + And packages that belong to a build type are only installed when that specific build type is currently processed by {kiwi}. - `profiles`: a list of profiles to which this package selection applies (see :ref:`image-profiles`). -- `patternType`: selection type for patterns, supported values are: - `onlyRequired`, `plusRecommended`, see: +- `patternType`: selection type for patterns; supported values are: + `onlyRequired`, `plusRecommended`; see: :ref:`product-and-namedCollection-element`. -The following sections describes the different child elements of +The following sections describe the different child elements of a `packages` group. .. _package-element: @@ -70,10 +70,10 @@ removed), whose name is specified via the mandatory `name` attribute: This adds the package `udev` to the list of packages to be added to the -initial filesystem. Note, that the value that you pass via the `name` +initial filesystem. Note that the value that you pass via the `name` attribute is passed directly to the used package manager. Thus, if the -package manager supports other means how packages can be specified, you may -pass them in this context too. For example, RPM based package managers +package manager supports other means of how packages can be specified, you may +pass them in this context too. For example, RPM-based package managers (like :command:`dnf` or :command:`zypper`) can install packages via their `Provides:`. This can be used to add a package that provides a certain capability (for example, `Provides: /usr/bin/my-binary`) via: @@ -88,12 +88,12 @@ capability (for example, `Provides: /usr/bin/my-binary`) via: Whether this works depends on the package manager and on the environment -that is being used. In the Open Build Service, certain `Provides` either -are not visible or cannot be properly extracted from the {kiwi} +that is being used. In the Open Build Service, certain `Provides` are either +not visible or cannot be properly extracted from the {kiwi} description. Therefore, relying on `Provides` is not recommended. Packages can also be included only on specific host architectures via the -`arch` attribute. {kiwi} compares the `arch` attributes value with the host +`arch` attribute. {kiwi} compares the `arch` attribute's value with the host architecture that builds the image according to the output of `uname -m`. .. code:: xml @@ -108,7 +108,7 @@ architecture that builds the image according to the output of `uname -m`. This results in `grub2-x86_64-efi` and `shim` being only installed if the -build host is a 64bit x86 machine, but `grub2` will be installed independent +build host is a 64-bit x86 machine, but `grub2` will be installed independent of the architecture. @@ -133,7 +133,7 @@ archive in the image description folder). {kiwi} extracts the archive into the root directory of the image using `GNU tar `_. This means that only archives supported by it can be included. When multiple `archive` elements are -specified then they are applied in a top to bottom order. If a file is +specified, then they are applied in a top-to-bottom order. If a file is already present in the image, then the file from the archive overwrites it (same as with the image overlay). @@ -146,7 +146,7 @@ Uninstall System Packages appliance: 1. Packages present as a child element of `` - are gracefully uninstalled by the package manager together with + are gracefully uninstalled by the package manager, together with dependent packages and orphaned dependencies. 2. Packages present as a child element of `` are removed @@ -165,16 +165,16 @@ Both types of removals take place after :file:`config.sh` is run in the * the packages dependent on the listed ones * any orphaned dependency of the listed packages - Use this feature with caution as it can cause removal of + Use this feature with caution, as it can cause the removal of required tools, leading to failures in later build stages. Removing packages via `type="uninstall"` can be used to completely remove a -build time tool (for example, a compiler), without having to specify all +build-time tool (for example, a compiler) without having to specify all dependencies of that tool (as opposed to when using `type="delete"`). Consider the following example, where we want to compile a custom program in :file:`config.sh`. We ship its source code via an -`archive` element and add the build tools (`ninja`, `meson` and `clang`) to +`archive` element and add the build tools (`ninja`, `meson`, and `clang`) to `` and ``: .. code:: xml @@ -197,11 +197,11 @@ custom program in :file:`config.sh`. We ship its source code via an -The tools `meson`, `clang` and `ninja` are then available during the +The tools `meson`, `clang`, and `ninja` are then available during the :ref:`prepare step `, and they can be used in :file:`config.sh` (for further details, see -:ref:`working-with-kiwi-user-defined-scripts`), for example to build -``foo_app``: +:ref:`working-with-kiwi-user-defined-scripts`), for example, to build +`foo_app`: .. code:: bash @@ -213,12 +213,12 @@ The tools `meson`, `clang` and `ninja` are then available during the popd The `` element ensures that the final -appliance no longer contains the tools required to build ``foo_app``, +appliance no longer contains the tools required to build `foo_app`, thus making the image smaller. There are also other use cases for `type="uninstall"`, especially for specialized appliances. For containers, you can remove the package -`shadow` (it is required to setup new user accounts) or any remaining +`shadow` (it is required to set up new user accounts) or any remaining partitioning tools (`parted` or `fdisk`). All networking tools can be safely uninstalled in images for embedded devices without a network connection. @@ -228,18 +228,18 @@ connection. The `product` and `namedCollection` element ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -{kiwi} supports the inclusion of openSUSE products or of namedCollections -(*patterns* in SUSE based distributions or *groups* for RedHat based +{kiwi} supports the inclusion of openSUSE products or of named collections +(*patterns* in SUSE-based distributions or *groups* for RedHat-based distributions). These can be added via the `product` and `namedCollection` child elements, which both take the mandatory `name` attribute and the optional `arch` attribute. `product` and `namedCollection` can be used to shorten the list of packages that need to be added to the image description. A -named pattern, specified with the namedCollection element is a +named pattern, specified with the `namedCollection` element, is a representation of a predefined list of packages. Specifying a pattern installs all packages listed in the named pattern. Support for patterns is -distribution-specific and available in SLES, openSUSE, CentOS, RHEL and +distribution-specific and available in SLES, openSUSE, CentOS, RHEL, and Fedora. The optional `patternType` attribute on the packages element allows you to control the installation of dependent packages. You may assign one of the following values to the `patternType` attribute: @@ -257,7 +257,7 @@ The `ignore` element Packages can be explicitly marked to be ignored for installation inside a `packages` collection. This can be used to exclude certain packages from being -installed when using patterns with `patternType="plusRecommended"` as shown +installed when using patterns with `patternType="plusRecommended"`, as shown in the following example: .. code:: xml @@ -273,7 +273,7 @@ in the following example: -Packages can be marked as ignored during the installation by adding a +Packages can be marked as ignored during the installation by adding an `ignore` child element with the mandatory `name` attribute set to the name of the package. Optionally, you can specify the architecture via `arch`, similarly to :ref:`package-element`. diff --git a/doc/source/concept_and_workflow/profiles.rst b/doc/source/concept_and_workflow/profiles.rst index 61034f49..eaa26fb0 100644 --- a/doc/source/concept_and_workflow/profiles.rst +++ b/doc/source/concept_and_workflow/profiles.rst @@ -34,7 +34,7 @@ machine images of the `oem` type are configured: one for QEMU (using the Each profile is declared via the element `profile` that must be a child of `profiles`, and it must contain the `name` and `description` -attributes. The `description` is only present for documentation purposes, +attributes. The `description` is only present for documentation purposes; `name`, on the other hand, is used to instruct {kiwi} which profile to build via the command line. Additionally, you can provide the boolean attribute `import`, which defines whether this profile should be used by default when @@ -57,7 +57,7 @@ Profiles can furthermore inherit settings from another profile via the -In the above example, the profile `QEMU` inherit the settings from `VM`. +In the above example, the profile `QEMU` inherits the settings from `VM`. For further details on the usage of *profiles*, see -:ref:`building-build-with-profiles` +:ref:`building-build-with-profiles`. diff --git a/doc/source/concept_and_workflow/repository_setup.rst b/doc/source/concept_and_workflow/repository_setup.rst index e3cefe52..a406640b 100644 --- a/doc/source/concept_and_workflow/repository_setup.rst +++ b/doc/source/concept_and_workflow/repository_setup.rst @@ -14,7 +14,7 @@ Adding repositories the image description. This means that at least one repository **must** be defined. Otherwise, {kiwi} cannot fetch any packages. -A repository is added to the description via the `repository` element +A repository is added to the description via the `repository` element, which is a child of the top-level `image` element: .. code:: xml @@ -35,18 +35,18 @@ The above example specifies two repositories: *{exc_kiwi_repo}* at the Open Build Service (OBS). 2. The RPM repository belonging to the OS project: - *{exc_repo}*, at the Open Build Service (OBS). The translated - http URL is also included in the final appliance. + *{exc_repo}* at the Open Build Service (OBS). The translated + HTTP URL is also included in the final appliance. The `repository` element accepts one `source` child element that -contains the URL of the repository in an correct format along with the +contains the URL of the repository in a correct format, along with the following optional attributes: - `imageinclude`: Specifies whether the repository should be added to the - resulting image. Default is false. + resulting image. The default is false. - `imageonly`: A repository with `imageonly="true"` is not available - during image build, but is present in the resulting appliance. Default is + during the image build but is present in the resulting appliance. The default is false. - `priority`: An integer value for all packages in this repository. If @@ -54,34 +54,34 @@ following optional attributes: with the highest priority is used. - `alias`: Name to use for the repository. It appears as the repository's name - in the image visible via ``zypper repos`` or ``dnf repolist``. If `alias`` is - not specified, {kiwi} generates an alias name using hex representation from + in the image, visible via `zypper repos` or `dnf repolist`. If `alias` is + not specified, {kiwi} generates an alias name using a hex representation from uuid4. -- `repository_gpgcheck`: Specify whether or not this specific repository +- `repository_gpgcheck`: Specifies whether or not this specific repository values the result of the repository signature validation. The default value is `false`. -- `package_gpgcheck`: Specify whether or not this specific repository +- `package_gpgcheck`: Specifies whether or not this specific repository values the result of the package signature validation for each package taken from this repository. The default value is `false`. -- `components`: Distribution components used for `deb` repositories. Default is `main`. +- `components`: Distribution components used for `deb` repositories. The default is `main`. -- `distribution`: Distribution name information, used for deb repositories. +- `distribution`: Distribution name information, used for `deb` repositories. - `profiles`: List of profiles to which this repository applies. -- `customize`: Script to run custom modifications to the repo file or files. +- `customize`: A script to run custom modifications to the repo file or files. Repo files allow for several customization options, but not all of them are supported to be set by kiwi through the current repository schema. As the used options do not follow any standard, and they are not compatible between package managers and distributions, the only way to handle - this is through a script hook which is invoked with the repo file as + this is through a script hook that is invoked with the repo file as a parameter for each file created by {kiwi}. An example for a script call to add the `module_hotfixes` option - for a `dnf` compatible repository configuration could look as follows: + for a `dnf`-compatible repository configuration could look as follows: .. code:: bash @@ -91,7 +91,7 @@ following optional attributes: .. note:: If the script is provided as a relative path, it is expected to be found - in the image description directory: + in the image description directory. .. _supported-repository-paths: @@ -99,14 +99,14 @@ Supported repository paths ^^^^^^^^^^^^^^^^^^^^^^^^^^ The actual location of a repository is specified in the `source` child -element of `repository` via its only attribute `path`. {kiwi} supports the -following paths types: +element of `repository` via its only attribute, `path`. {kiwi} supports the +following path types: - `http://URL` or `https://URL` or `ftp://URL`: a URL to the repository - available via HTTP(s) or FTP. + available via HTTP(S) or FTP. - `obs://$PROJECT/$REPOSITORY`: checks whether the repository `$REPOSITORY` - of the project `$PROJECT` available on the Open Build Service (OBS). By + of the project `$PROJECT` is available on the Open Build Service (OBS). By default, {kiwi} looks for projects on `build.opensuse.org `_, but this can be overridden using the runtime configuration file (see :ref:`runtime_config`). @@ -114,7 +114,7 @@ following paths types: from **different** OBS instances (use direct URLs to the :file:`.repo` file instead in this case). -- `obsrepositories:/`: special path only available for builds using the Open +- `obsrepositories:/`: a special path only available for builds using the Open Build Service. The repositories configured for the OBS project where the {kiwi} image resides are made available inside the appliance. This allows you to configure the repositories of your image from OBS itself, without modifying diff --git a/doc/source/concept_and_workflow/runtime_configuration.rst b/doc/source/concept_and_workflow/runtime_configuration.rst index 40e320cf..ed70e885 100644 --- a/doc/source/concept_and_workflow/runtime_configuration.rst +++ b/doc/source/concept_and_workflow/runtime_configuration.rst @@ -3,8 +3,8 @@ The Runtime Configuration File ------------------------------ -{kiwi} supports an additional configuration file for runtime specific -settings which do not belong in the image description but which are +{kiwi} supports an additional configuration file for runtime-specific +settings that do not belong in the image description but which are persistent and are unsuitable for command-line parameters. The runtime configuration file must adhere to the `YAML `_ @@ -17,5 +17,5 @@ configuration file in the following locations: 2. :file:`/etc/kiwi.yml` A default runtime config file in :file:`/etc/kiwi.yml` is provided with -the python3-kiwi package. The file contains all settings as comments +the `python3-kiwi` package. The file contains all settings as comments, including a short description of each setting. diff --git a/doc/source/concept_and_workflow/shell_scripts.rst b/doc/source/concept_and_workflow/shell_scripts.rst index 42ee1f6e..53201db6 100644 --- a/doc/source/concept_and_workflow/shell_scripts.rst +++ b/doc/source/concept_and_workflow/shell_scripts.rst @@ -6,7 +6,7 @@ User-Defined Scripts .. note:: **Abstract** This chapter describes the purpose of the user-defined scripts - :file:`config.sh`, :file:`image.sh`, :file:`pre_disk_sync.sh` and + :file:`config.sh`, :file:`image.sh`, :file:`pre_disk_sync.sh`, and :file:`disk.sh`. These scripts can be used to further customize an image in ways that are not possible via the image description alone. @@ -16,7 +16,7 @@ root environment (chroot) containing an appliance: post_bootstrap.sh Runs at the end of the `bootstrap` phase as part of the :ref:`prepare step `. The script can be used to configure the package manager with - additional settings that apply in the following chroot-based installation step + additional settings that apply in the following chroot-based installation step, which completes the installation. The script can also be used for other tasks. config.sh @@ -28,13 +28,13 @@ config.sh config-overlay.sh Available only if `delta_root="true"` is set. In this case, the script runs at - the end of the :ref:`prepare step ` prior the umount of the + the end of the :ref:`prepare step ` prior to the `umount` of the overlay root tree. It runs after `config.sh` (if specified), and it is the last entry point to change the delta root tree. config-host-overlay.sh Available only if `delta_root="true"` is set. In this case, the script runs at - the end of the :ref:`prepare step ` prior the umount of the + the end of the :ref:`prepare step ` prior to the `umount` of the overlay root tree. The script is called **NOT CHROOTED** from the host with the image root directory as its working directory. It runs after `config.sh` and `config-overlay.sh` (if any or both are specified), and it is the last @@ -44,30 +44,30 @@ images.sh Executed at the beginning of the :ref:`image creation process `. It runs in the same image root tree created by the prepare step, but it is invoked whenever an image needs to be created from that root tree. - It is normally used to apply image type specific changes to the root tree, such + It is normally used to apply image-type-specific changes to the root tree, such as a modification to a config file that must be done when building a live - iso, but not when building a virtual disk image. + ISO but not when building a virtual disk image. pre_disk_sync.sh Executed for the disk image type `oem` only, and it runs right before the synchronization of the root tree into the disk image - loop file. The :file:`pre_disk_sync.sh` can be used to change + loop file. The :file:`pre_disk_sync.sh` can be used to change the content of the root tree as a last action before the sync to the disk image is performed. This is useful, for example, for deleting - components from the system which were needed earlier or cannot - be modified afterwards when syncing into a read-only filesystem. + components from the system that were needed earlier or cannot + be modified afterward when syncing into a read-only filesystem. disk.sh Executed for the disk image type `oem` only, and it runs after the - synchronization of the root tree to the disk image loop file. The chroot + synchronization of the root tree to the disk image loop file. The `chroot` environment for this script call is the virtual disk itself and not the root - tree. The script :file:`disk.sh` is normally used to apply changes at parts of + tree. The script :file:`disk.sh` is normally used to apply changes to parts of the system that are not an element of the file-based root tree, such as the partition table, the contents of the final initrd, the bootloader, filesystem attributes, etc. {kiwi} executes scripts via the operating system if their executable -bit is set (in that case, a shebang is mandatory); otherwise they are +bit is set (in that case, a shebang is mandatory); otherwise, they are invoked via the Bash shell. If a script exits with a non-zero exit code, {kiwi} reports the failure and aborts the image creation. @@ -88,12 +88,12 @@ In this mode, a script can be started using the following template: echo "break" /bin/bash -Calling the script executes a `screen` session executes, which gives you access -to the break in shell. You can then implement the desired script code in this -environment.. Once the shell is closed the {kiwi} process continues. +Calling the script executes a `screen` session, which gives you access +to the break-in shell. You can then implement the desired script code in this +environment. Once the shell is closed, the {kiwi} process continues. In addition to providing a fully featured terminal throughout the execution of -the script code, you also have have control of the session during the process of +the script code, you also have control of the session during the process of the image creation. Listing the active sessions for script execution can be done as follows: @@ -107,7 +107,7 @@ as follows: .. note:: - As shown above the screen session for executing the script code provides + As shown above, the screen session for executing the script code provides extended control, which can be considered a security risk. Because of that, {kiwi} only runs scripts through `screen` when explicitly enabled via the `--debug` switch. In production, all scripts must run natively and @@ -153,8 +153,8 @@ Functions ^^^^^^^^^ The :file:`.kconfig` file provides a common set of functions. Functions -specific to SUSE Linux Enterprise and openSUSE start with ``suse``, functions -applicable to all Linux distributions start with ``base``. +specific to SUSE Linux Enterprise and openSUSE start with `suse`; functions +applicable to all Linux distributions start with `base`. The following list describes all functions provided by :file:`.kconfig`: @@ -162,14 +162,14 @@ baseSetRunlevel {value} Set the default run level. baseStripAndKeep {list of info-files to keep} - Helper function for the ``baseStrip*`` functions that reads a list of files to - check from stdin for removing params: files which should be kept. + A helper function for the `baseStrip*` functions that reads a list of files to + check from stdin for removing params: files that should be kept. baseStripLocales {list of locales} - Removes all locales, except for the ones given as the parameter. + Removes all locales except for the ones given as the parameter. baseStripTranslations {list of translations} - Removes all translations, except those given as the parameter. + Removes all translations except those given as the parameter. baseStripUnusedLibs Removes libraries that are not directly linked against applications @@ -179,12 +179,12 @@ baseUpdateSysConfig {filename} {variable} {value} Updates the contents of a sysconfig variable. baseSystemdServiceInstalled {service} - Prints the path of the first found systemd unit or mount with name passed + Prints the path of the first found systemd unit or mount with the name passed as the first parameter. baseSysVServiceInstalled {service} Prints the name `${service}` if a SysV init service with the same name is - found; otherwise it prints nothing. + found; otherwise, it prints nothing. baseSystemdCall {service_name} {args} Calls `systemctl ${args} ${service_name}` if a systemd unit, a systemd @@ -198,7 +198,7 @@ baseRemoveService {servicename} baseService {servicename} {on|off} Activates or deactivates a service via :command:`systemctl`. - The function requires the service name and the value ``on`` or ``off`` as + The function requires the service name and the value `on` or `off` as parameters. The following example enables the sshd service on boot: @@ -208,42 +208,42 @@ baseService {servicename} {on|off} baseService sshd on suseInsertService {servicename} - Calls baseInsertService. It exists only for + Calls `baseInsertService`. It exists only for compatibility reasons. suseRemoveService {servicename} - Calls baseRemoveService. It exists only for + Calls `baseRemoveService`. It exists only for compatibility reasons. suseService {servicename} {on|off} - Calls baseService. It exists only for compatibility + Calls `baseService`. It exists only for compatibility reasons. suseSetupProduct Creates the :file:`/etc/products.d/baseproduct` link pointing to the product referenced either by :file:`/etc/SuSE-brand` or :file:`/etc/os-release` or the latest `.prod` file available in - :file:`/etc/products.d` + :file:`/etc/products.d`. baseVagrantSetup Configures the image to work as a vagrant box by performing the following changes: - - add the ``vagrant`` user to :file:`/etc/sudoers` - or :file:`/etc/sudoers.d/vagrant` + - add the `vagrant` user to :file:`/etc/sudoers` + or :file:`/etc/sudoers.d/vagrant`. - insert the insecure vagrant ssh key, apply recommended - ssh settings and start the ssh daemon - - create the default shared folder :file:`/vagrant` + ssh settings, and start the ssh daemon. + - create the default shared folder :file:`/vagrant`. Debug {message} - Helper function to print the supplied message if the variable DEBUG is + A helper function to print the supplied message if the variable DEBUG is set to 1 (disabled by default). Echo {echo commandline} - Helper function to print a message to the controlling terminal. + A helper function to print a message to the controlling terminal. Rm {list of files} - Helper function to delete files and log the deletion. + A helper function to delete files and log the deletion. Profile Environment Variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -287,7 +287,7 @@ $kiwi_type .. note:: **.profile.extra** - If there is the file :file:`/.profile.extra` available in the initrd, {kiwi} + If the file :file:`/.profile.extra` is available in the initrd, {kiwi} imports the file importing :file:`/.profile`. Configuration Tips @@ -295,40 +295,40 @@ Configuration Tips #. **Locale configuration:** - To set locale, {kiwi} relies on :command:`systemd-firstboot` that writes the - locale configuration file :file:`/etc/locale.conf`. The values for the locale + To set the locale, {kiwi} relies on `systemd-firstboot`, which writes the + locale configuration file, :file:`/etc/locale.conf`. The values for the locale settings are taken from the description XML file in the `` element under ``. - Keep im mind that if the build distribution does not use `/etc/locale.conf`, - the :command:`systemd-firstboot` does not have any effect on the locale + Keep in mind that if the build distribution does not use `/etc/locale.conf`, + `systemd-firstboot` does not have any effect on the locale settings. For example, in the SLE12 distribution, - :command:`systemd-firstboot` is only effective when locales in - :file:`/etc/sysconfig/language` are not set, or when the file does not exist + `systemd-firstboot` is only effective when locales in + :file:`/etc/sysconfig/language` are not set or when the file does not exist at all. For compatibility reasons, the file :file:`/etc/sysconfig/language` in SLE12 has precedence over :file:`/etc/locale.conf`, and management tools can still use `sysconfig` files for locale settings. In any case, it is possible to configure the locale setting inside the - :file:`config.sh` script in {kiwi} using in distribution-specific way, or by - adding any additional configuration file as part of the overlay root-tree. + :file:`config.sh` script in {kiwi} in a distribution-specific way or by + adding any additional configuration file as part of the overlay root tree. #. **Stateless systemd UUIDs:** Machine ID files (:file:`/etc/machine-id`, :file:`/var/lib/dbus/machine-id`) - may be created and set during the image package installation depending on + may be created and set during the image package installation, depending on the distribution. Those UUIDs must be unique and must be set only once in each deployment. If :file:`/etc/machine-id` does not exist or contains the string - `uninitialized` (systemd v249 and later), this triggers firstboot action + `uninitialized` (systemd v249 and later), this triggers a firstboot action in systemd, and the services are run with `ConditionFirstBoot=yes`. Unless the file already contains a valid machine ID, systemd generates a machine ID and - write it into the file, creating it if necessary. See the `machine-id man + writes it into the file, creating it if necessary. See the `machine-id man page `_ for more details. - Depending on whether firstboot action should be triggered or not, + Depending on whether the firstboot action should be triggered or not, :file:`/etc/machine-id` can be created, removed, or set to `uninitialized` by :file:`config.sh`. @@ -344,15 +344,15 @@ Configuration Tips By default, the root filesystem is mounted read-only by dracut/systemd, so a missing :file:`/etc/machine-id` will lead to an error on boot. - To force the initial mount to be read-write, add the `rw` option to the kernel commandline. + To force the initial mount to be read-write, add the `rw` option to the kernel command line. - .. note:: Avoid inconsistent :file:`/var/lib/dbus/machine-id` + .. note:: Avoid inconsistent :file:`/var/lib/dbus/machine-id`. :file:`/etc/machine-id` and :file:`/var/lib/dbus/machine-id` - **must** contain the same unique ID. On modern systems - :file:`/var/lib/dbus/machine-id`, there is already a symlink to - :file:`/etc/machine-id`. However, on older systems there might be two - different files. This is the case for SLE-12 based images. If you are + **must** contain the same unique ID. On modern systems, + :file:`/var/lib/dbus/machine-id` is already a symlink to + :file:`/etc/machine-id`. However, on older systems, there might be two + different files. This is the case for SLE-12-based images. If you are targeting older operating systems, it is recommended to add the symlink creation into :file:`config.sh`: diff --git a/doc/source/concept_and_workflow/systemdeps.rst b/doc/source/concept_and_workflow/systemdeps.rst index 93a2c591..12fa3932 100644 --- a/doc/source/concept_and_workflow/systemdeps.rst +++ b/doc/source/concept_and_workflow/systemdeps.rst @@ -3,9 +3,9 @@ Host Requirements To Build Images --------------------------------- -Building OS images requires several tools and sub-systems to be present on the -host {kiwi} host. For example, to build a virtual disk image, tools for -partition table setup or tools to create filesystems must to be available on the +Building OS images requires several tools and subsystems to be present on the +{kiwi} host. For example, to build a virtual disk image, tools for +partition table setup or tools to create filesystems must be available on the host that builds the image. The number of required components depends on the selected image type and the @@ -13,51 +13,51 @@ features used with the image. It's unreasonable to expect {kiwi} users to know which exact components are needed to build the image. A mechanism called `kiwi-systemdeps` is designed to handle the host requirements. -`kiwi-systemdeps` consists out of a collection of sub-packages provided with the +`kiwi-systemdeps` consists of a collection of sub-packages provided with the `python-kiwi` main package. Each individual package requires a number of tools -and subsystem packages that belongs to the package category. There are the +and subsystem packages that belong to the package category. There are the following systemdeps packages: `kiwi-systemdeps-core`: * Supports building the simple root archive `tbz` image type. - * Installs the package managers which are supported by the target distribution + * Installs the package managers that are supported by the target distribution, as well as the `tar` archiving tool. `kiwi-systemdeps-containers`: - * Supports building `OCI` image types used with `docker`, `podman`. - * Installs the distribution specific tool chain to build OCI + * Supports building `OCI` image types used with `docker` and `podman`. + * Installs the distribution-specific toolchain to build OCI- compliant container images. `kiwi-systemdeps-containers-wsl`: * Supports building `appx` and `wsl` image types. The `wsl` type - is the successor for the former `appx` type - * Installs the distribution specific tool chain to build - WSL compliant container images on Windows systems. + is the successor to the former `appx` type. + * Installs the distribution-specific toolchain to build + WSL-compliant container images on Windows systems. `kiwi-systemdeps-iso-media`: * Supports building `iso` image types and `oem` install media. * Installs all tools required to build ISO filesystems. - * Depends on the `-core`, `-filesystems` and `-bootloaders` + * Depends on the `-core`, `-filesystems`, and `-bootloaders` kiwi-systemdeps packages. `kiwi-systemdeps-bootloaders`: * Supports building bootable `oem` and `iso` image types. * Installs all bootloader tools depending on the host architecture - to allow setup and install of the bootloader. The pulled in + to allow setup and install of the bootloader. The pulled-in components are required for any image that is able to boot through some BIOS or firmware. * Depends on the `-core` kiwi-systemdeps packages. `kiwi-systemdeps-filesystems`: * Supports building `fs-type`, `oem`, `pxe`, - `kis` and live `iso` image types. + `kis`, and live `iso` image types. * Installs all tools to create filesystems supported by {kiwi}. - The pulled in components are needed for any image type that + The pulled-in components are needed for any image type that needs to create a filesystem. This excludes the archive-based - image types like `docker`, `appx` or `tbz`. The package also + image types like `docker`, `appx`, or `tbz`. The package also installs tools one level below the actual filesystem creation - toolkit. These are components to manage loop devices as well - as partition table setup and subsystem support like LVM and LUKS. + toolkit. These are components to manage loop devices, as well + as partition table setup and subsystem support, like LVM and LUKS. * Depends on the `-core` kiwi-systemdeps packages. `kiwi-systemdeps-disk-images`: @@ -71,18 +71,18 @@ following systemdeps packages: * Installs the `jing` tool to validate the image description. This is useful for detailed error reports from {kiwi} if an image description validation error occurs. In addition, the `anymarkup` Python - module is installed if the the option to install recommended packages + module is installed if the option to install recommended packages is set. With `anymarkup` available, {kiwi} can also handle image - descriptions in another format than the XML markup (for example,YAML). + descriptions in a format other than the XML markup (for example, YAML). -Depending on the image type the `kiwi-systemdeps`` packages can help -to quickly setup the host system for building images. +Depending on the image type, the `kiwi-systemdeps` packages can help +to quickly set up the host system for building images. In case the host must support everything, there is also the main `kiwi-systemdeps` package that has all other -existing systemdeps packages as its dependency. +existing `systemdeps` packages as its dependency. .. note:: - Pulling in all `kiwi-systemdeps` packages can result in a large number - packages installed on the host., because the required packages themselves + Pulling in all `kiwi-systemdeps` packages can result in a large number of + packages installed on the host because the required packages themselves have other dependencies (for example, java for jing). diff --git a/doc/source/concept_and_workflow/users.rst b/doc/source/concept_and_workflow/users.rst index 96f874ac..b637aade 100644 --- a/doc/source/concept_and_workflow/users.rst +++ b/doc/source/concept_and_workflow/users.rst @@ -22,10 +22,10 @@ supports a list of multiple `user` child elements: -Each `user` element represents a specific added or modified user. +Each `user` element represents a specific user to be added or modified. The following attributes are mandatory: -- `name`: the UNIX username +- `name`: the UNIX username. - `password`: The password for the user account. It can be provided either in clear-text form (`pwdformat="plain"`) or in encrypted form @@ -40,12 +40,12 @@ The following attributes are mandatory: Additionally, the following optional attributes can be specified: -- `home`: the path to the user's home directory +- `home`: The path to the user's home directory. - `groups`: A comma-separated list of UNIX groups. The first element of the list is used as the user's primary group. The remaining elements are appended to the user's supplementary groups. When no groups are assigned, - the system's default primary group is be used. + the system's default primary group will be used. - `id`: The numeric user ID of the account. diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 9c79416c..5817dc80 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -18,17 +18,17 @@ Contributing The Basics ---------- -The core appliance builder is developed in Python and follows the test +The core appliance builder is developed in Python and follows the test- driven development rules. If you want to implement a bigger feature, consider opening an issue on -GitHub first to discuss the changes. Or join the discussion in the -``#kiwi`` channel on `Riot.im `_. +GitHub first to discuss the changes. Or, join the discussion in the +`#kiwi` channel on `Riot.im `_. Fork the upstream repository ---------------------------- -1. On GitHub, navigate to: https://github.com/OSInside/kiwi +1. On GitHub, navigate to: https://github.com/OSInside/kiwi. 2. In the top-right corner of the page, click :command:`Fork`. @@ -44,8 +44,8 @@ Create a local clone of the forked repository Install Required Operating System Packages ------------------------------------------ -{kiwi} requires additional packages at runtime which are not -provided by :command:`pip`. Those will be pulled in by installing +{kiwi} requires additional packages at runtime that are not +provided by `pip`. Those will be pulled in by installing the following package: * kiwi-systemdeps @@ -54,14 +54,14 @@ The package is provided on the Open Build Service in the `Virtualization:Appliances:Builder `__ project. For manual inspection of the packages -that are pulled in from the above kiwi-systemdeps package, please refer -to the `package/python-kiwi-spec-template` spec file from the checked +that are pulled in from the above `kiwi-systemdeps` package, please refer +to the `package/python-kiwi-spec-template` spec file from the checked- out Git repository. Create a Python Virtual Development Environment ----------------------------------------------- -The following commands initializes and activates a development +The following commands initialize and activate a development environment for Python 3: .. code:: shell-session @@ -94,7 +94,7 @@ Create a Branch for each Feature or Bugfix Code changes should be done in an extra Git branch. This allows for creating GitHub pull requests in a clean way. See also: `Collaborating with issues and pull requests -`_ +`_. .. code:: shell-session @@ -104,14 +104,14 @@ Make and commit your changes. .. note:: - You can make multiple commits which is generally useful to + You can make multiple commits, which is generally useful to give your changes a clear structure and to allow us to better review your work. .. note:: Your work is important and must be signed to ensure the integrity of - the repository and the code. Thus we recommend to setup a signing key + the repository and the code. Thus, we recommend setting up a signing key as documented in :ref:`Signing_Git_Patches`. .. code:: shell-session @@ -125,7 +125,7 @@ create a pull request into the upstream repository. $ git push origin my-topic-branch -Thank you much for contributing to {kiwi}. Your time and work effort is very +Thank you much for contributing to {kiwi}. Your time and work effort are very much appreciated! @@ -135,10 +135,10 @@ Coding Style {kiwi} follows the general PEP8 guidelines with the following exceptions: - We do not use free functions at all. Even utility functions must be part - of a class, but should be either prefixed with the `@classmethod` or + of a class but should be either prefixed with the `@classmethod` or `@staticmethod` decorators (whichever is more appropriate). -- Do not set module and class level variables, put these into the classes' +- Do not set module and class-level variables; put these into the class's `__init__` method. - The names of constants are not written in all capital letters. @@ -147,16 +147,16 @@ Documentation ~~~~~~~~~~~~~ {kiwi} uses `Sphinx `_ for the API, -user documentation and manual pages +user documentation, and man pages. .. code:: shell-session $ make docs -Document all your classes, methods, their parameters and their types using +Document all your classes, methods, their parameters, and their types using the standard `reStructuredText `_ -syntax as supported by Sphinx, an example class is documented as follows: +syntax as supported by Sphinx. An example class is documented as follows: .. code:: python @@ -165,7 +165,7 @@ syntax as supported by Sphinx, an example class is documented as follows: **Example class** :param str param: A parameter - :param bool : Source file name to compress + :param bool: Source file name to compress :param list supported_zipper: List of supported compression tools :attr Optional[str] attr: A class attribute """ @@ -188,36 +188,36 @@ Try to stick to the following guidelines when documenting source code: - Classes should be documented directly in their main docstring and not in `__init__`. -- Document **every** function parameter and every public attribute +- Document **every** function parameter and every public attribute, including their types. -- Only public methods should be documented, private methods don't have to, +- Only public methods should be documented; private methods don't have to be, unless they are complex and it is not easy to grasp what they do (which should be avoided anyway). -Please also document any user-facing changes that you implementing -(e.g. adding a new build type) in the user documentation, which can be +Please also document any user-facing changes that you are implementing +(e.g., adding a new build type) in the user documentation, which can be found in `doc/source`. General documentation should be put into the `working_with_kiwi/` subfolder, whereas documentation about more -specialized topics would belong into the `building/` subfolder. +specialized topics would belong in the `building/` subfolder. -Adhere to a line limit of 75 characters when writing the user facing +Adhere to a line limit of 75 characters when writing the user-facing documentation [#f1]_. Additional Information ---------------------- -The following sections provides further information about the repository -integrity, version, package and documentation management. +The following sections provide further information about the repository +integrity, version, package, and documentation management. .. _Signing_Git_Patches: Signing Git Patches ~~~~~~~~~~~~~~~~~~~ -To ensure the integrity of the repository and the code base, patches sent +To ensure the integrity of the repository and the codebase, patches sent for inclusion should be signed with a GPG key. To prepare Git to sign commits, follow these instructions: @@ -229,14 +229,14 @@ To prepare Git to sign commits, follow these instructions: $ gpg2 --expert --full-gen-key -#. Either choose a RSA key for signing (option `(4)`) or an ECC key for - signing (option `(10)`). For a RSA key choose a key size of 4096 bits - and for a ECC key choose Curve 25519 (option `(1)`). Enter a reasonable +#. Either choose an RSA key for signing (option `(4)`) or an ECC key for + signing (option `(10)`). For an RSA key, choose a key size of 4096 bits, + and for an ECC key, choose Curve 25519 (option `(1)`). Enter a reasonable validity period (we recommend 2 to 5 years). Complete the key generation by entering your name and email address. -#. Add the key ID to your git configuration, by running the following +#. Add the key ID to your git configuration by running the following :command:`git config` commands: .. code:: shell-session @@ -244,7 +244,7 @@ To prepare Git to sign commits, follow these instructions: $ git config --local user.signingkey $YOUR_SIGN_KEY_ID $ git config --local commit.gpgSign true - Omitting the flag `--local` will make these settings global for all + Omitting the `--local` flag will make these settings global for all repositories (they will be added to :file:`~/.gitconfig`). You can find your signkey's ID via: @@ -256,7 +256,7 @@ To prepare Git to sign commits, follow these instructions: uid [ultimate] YOU <$YOUR_EMAIL> The key's ID in this case would be `AABBCCDDEEFF0011`. Note that your - signkey will have only a `[S]` after the creation date, not a `[SC]` + sign key will have only a `[S]` after the creation date, not a `[SC]` (then you are looking at your ordinary GPG key that can also encrypt). @@ -267,16 +267,16 @@ The {kiwi} project follows the `Semantic Versioning `_ scheme. We use the :command:`bumpversion` tool for consistent versioning. Follow these instructions to bump the major, minor, or patch part of the -{kiwi} version. Ensure that your repository is clean (i.e. no modified and -unknown files exist) beforehand running :command:`bumpversion`. +{kiwi} version. Ensure that your repository is clean (i.e., no modified and +unknown files exist) before running :command:`bumpversion`. -* For backwards-compatible bug fixes: +* For backward-compatible bug fixes: .. code:: shell-session $ bumpversion patch -* For additional functionality in a backwards-compatible manner. When +* For additional functionality in a backward-compatible manner. When changed, the patch level is reset to zero: .. code:: shell-session @@ -290,31 +290,31 @@ unknown files exist) beforehand running :command:`bumpversion`. $ bumpversion major -Creating a RPM Package -~~~~~~~~~~~~~~~~~~~~~~ +Creating an RPM Package +~~~~~~~~~~~~~~~~~~~~~~~ -We provide a template for a RPM spec file in -:file:`package/python-kiwi-spec-template` alongside with a rpmlint +We provide a template for an RPM spec file in +:file:`package/python-kiwi-spec-template` alongside a `rpmlint` configuration file and an automatically updated :file:`python-kiwi.changes`. -To create the necessary files to build a RPM package via `rpmbuild`, run: +To create the necessary files to build an RPM package via `rpmbuild`, run: .. code:: shell-session $ make build The sources are collected in the :file:`dist/` directory. These can be -directly build it with :command:`rpmbuild`, :command:`fedpkg`, or submitted +directly built with :command:`rpmbuild`, :command:`fedpkg`, or submitted to the Open Build Service using :command:`osc`. .. [#f1] Configure your editor to automatically break lines and/or reformat - paragraphs. For Emacs you can use `M-x set-fill-column RET 75` and + paragraphs. For Emacs, you can use `M-x set-fill-column RET 75` and `M-x auto-fill-mode RET` for automatic filling of paragraphs in conjunction with `M-x fill-paragraph` (usually bound to `M-q`) to reformat a paragraph to adhere to the current column width. For - editing reStructuredText we recommend `rst-mode` (built-in to + editing reStructuredText, we recommend `rst-mode` (built into Emacs since version `23.1`). Vim users can set the text width via `:tw 75` and then use the commands `gwip` or `gq`. diff --git a/doc/source/contributing/kiwi_from_python.rst b/doc/source/contributing/kiwi_from_python.rst index 823a3ef1..f500e83b 100644 --- a/doc/source/contributing/kiwi_from_python.rst +++ b/doc/source/contributing/kiwi_from_python.rst @@ -5,12 +5,12 @@ Using {kiwi} in a Python Project {kiwi} is provided as a Python module under the **kiwi** namespace. It is available for the Python 3 version. The following - description applies for {kiwi} version |version|. + description applies to {kiwi} version |version|. {kiwi} can also function as a module for other Python projects. The following example demonstrates how to read an existing image description, add a new repository definition, and export the -modified description on stdout. +modified description on stdout: .. code:: python @@ -39,15 +39,15 @@ modified description on stdout. outfile=sys.stdout, level=0 ) -Each class in the example is responsible for a single tasks, so they can be -reused in other user cases. Therefore it is possible to use {kiwi} beyond the -main image building scope, for example to manage setup of loop devices, +Each class in the example is responsible for a single task, so they can be +reused in other use cases. Therefore, it is possible to use {kiwi} beyond the +main image building scope, for example, to manage the setup of loop devices, filesystems, partitions, etc. This means {kiwi} offers a way to describe a system, but you can choose whether you want to use the {kiwi} description format or not. The following example -shows how to use {kiwi} to create a simple filesystem image which contains your -host `tmp` directory. +shows how to use {kiwi} to create a simple filesystem image that contains your +host's `tmp` directory. .. code:: python diff --git a/doc/source/contributing/kiwi_plugin_architecture.rst b/doc/source/contributing/kiwi_plugin_architecture.rst index fbe0c487..32295441 100644 --- a/doc/source/contributing/kiwi_plugin_architecture.rst +++ b/doc/source/contributing/kiwi_plugin_architecture.rst @@ -11,21 +11,21 @@ Naming conventions Task plugin file name The file name of a task plugin must follow the pattern :file:`_.py`. This allows you to invoke the task - with :command:`kiwi-ng service command ...` + with :command:`kiwi-ng service command ...`. Task plugin option handling - {kiwi} uses the docopt module to handle options. Each task plugin - must use docopt to allow option handling. + {kiwi} uses the `docopt` module to handle options. Each task plugin + must use `docopt` to allow option handling. Task plugin class The implementation of the plugin must be a class that matches the naming - convention :class:`Task`. The class must inherit from the - :class:`CliTask` base class. On the plugin startup, {kiwi} expects an - implementation of the :file:`process` method. + convention `Task`. The class must inherit from the + :class:`CliTask` base class. On plugin startup, {kiwi} expects an + implementation of the `process` method. Task plugin entry point Registration of the plugin must be done in :file:`pyproject.toml` - using the ``tool.poetry.plugins`` concept. + using the `tool.poetry.plugins` concept. .. code:: python @@ -49,7 +49,7 @@ Example plugin which was set up using poetry and pyproject.toml. 1. Assuming the project namespace is **kiwi_relax_plugin**, create the task - plugin directory :file:`kiwi_relax_plugin/tasks` + plugin directory :file:`kiwi_relax_plugin/tasks`. 2. Create the entry point in :command:`pyproject.toml`. @@ -86,12 +86,12 @@ Example plugin options: --now - right now. For more details about docopt + right now. For more details about docopt, see: http://docopt.org """ - # These imports requires kiwi to be part of your environment + # These imports require kiwi to be part of your environment. # It can be either installed from pip into a virtual development - # environment or from the distribution package manager + # environment or from the distribution package manager. from kiwi.tasks.base import CliTask from kiwi.help import Help @@ -100,16 +100,16 @@ Example plugin self.manual = Help() if self.command_args.get('help') is True: # The following will invoke man to show the man page - # for the requested command. Thus for the call to - # succeed a manual page needs to be written and - # installed by the plugin + # for the requested command. Thus, for the call to + # succeed, a man page needs to be written and + # installed by the plugin. return self.manual.show('kiwi::relax::justdoit') print( 'https://genius.com/Frankie-goes-to-hollywood-relax-lyrics' ) -4. Test the plugin +4. Test the plugin. .. code:: bash diff --git a/doc/source/contributing/schema_extensions.rst b/doc/source/contributing/schema_extensions.rst index d10a904d..aa754c59 100644 --- a/doc/source/contributing/schema_extensions.rst +++ b/doc/source/contributing/schema_extensions.rst @@ -14,10 +14,10 @@ Extending {kiwi} with Custom Operations is no other plugin interface except for providing additional {kiwi} commands. Depending on the demand for custom plugins, the interface - to hook in code into other parts of the {kiwi} processing + to hook into code in other parts of the {kiwi} processing needs to be extended. - This description applies for version |version|. + This description applies to version |version|. The Section ----------------------- @@ -25,7 +25,7 @@ The Section The main {kiwi} schema supports an extension section that allows you to specify any XML structure and attributes, as long as they are attached to a namespace. This means that any custom XML -structure can be implemented similar to the the example below: +structure can be implemented similar to the example below: .. code:: bash @@ -38,20 +38,20 @@ structure can be implemented similar to the the example below: -* Any toplevel namespace must be unique -* Multiple different toplevel namespaces are allowed, - for example: my_plugin_a, my_plugin_b +* Any top-level namespace must be unique. +* Multiple different top-level namespaces are allowed, + for example, `my_plugin_a`, `my_plugin_b`. RELAX NG Schema for the Extension --------------------------------- If an extension section is found, {kiwi} looks up its namespace and uses the main XML catalog for the schema file to validate the extension data. -The schema file must be a RELAX NG schema in the .rng format. We recommend -to save the schema as :file:`/usr/share/xml/kiwi/my_plugin.rng` +The schema file must be a RELAX NG schema in the `.rng` format. We recommend +saving the schema as :file:`/usr/share/xml/kiwi/my_plugin.rng`. -For the example above, the RELAX NG Schema in the compressed format -:file:`my_plugin.rnc` looks as follows: +For the example above, the RELAX NG Schema in the compressed format, +:file:`my_plugin.rnc`, looks as follows: .. there is no rnc syntax highlighting, try cpp .. code:: cpp @@ -80,7 +80,7 @@ For the example above, the RELAX NG Schema in the compressed format } } -In order to convert this schema to the .rng format just call: +To convert this schema to the `.rng` format, just call: .. code:: bash @@ -90,7 +90,7 @@ Extension schema in XML catalog ------------------------------- As mentioned above, the mapping from the extension namespace to the -correct RELAX NG schema file is handled by a XML catalog file. The +correct RELAX NG schema file is handled by an XML catalog file. The XML catalog for the example is as follows: .. code:: bash @@ -102,8 +102,8 @@ XML catalog for the example is as follows: uri="file:////usr/share/xml/kiwi/my_plugin.rng"/> -For resolving the catalog, {kiwi} uses the :command:`xmlcatalog` command -and the main XML catalog from the system :file:`/etc/xml/catalog`. +For resolving the catalog, {kiwi} uses the `xmlcatalog` command +and the main XML catalog from the system, :file:`/etc/xml/catalog`. .. note:: @@ -111,7 +111,7 @@ and the main XML catalog from the system :file:`/etc/xml/catalog`. catalog file depends on the distribution and its version. Refer to the distribution documentation for information on adding XML catalogs. -If the following command provides the information to the correct +If the following command provides the information for the correct RELAX NG schema file, you are ready for a first test: .. code:: bash @@ -121,11 +121,11 @@ RELAX NG schema file, you are ready for a first test: Using the extension ------------------- -In order to test the extension, insert the example extension into one of your +To test the extension, insert the example extension into one of your image description's :file:`config.xml` file. The following example reads the name attribute from the title -section of the my_feature root element and prints it: +section of the `my_feature` root element and prints it: .. code:: python diff --git a/doc/source/contributing/scripts_testing.rst b/doc/source/contributing/scripts_testing.rst index 7a81c658..0b20457d 100644 --- a/doc/source/contributing/scripts_testing.rst +++ b/doc/source/contributing/scripts_testing.rst @@ -6,10 +6,10 @@ also: :ref:`working-with-kiwi-user-defined-scripts`). These functions utilize co to run the individual tasks and verify the final result. Ensure that you have either :command:`podman` or :command:`docker` installed and -configured on your system. With Podman, the integration tests use :command:`podman` in +configured on your system. With Podman, the integration tests use `podman` in **rootless mode** by default. You can select :command:`docker` instead by setting the environment variable -``CONTAINER_RUNTIME`` to ``docker``. Then you can run the integration tests via +``CONTAINER_RUNTIME`` to ``docker``. Then, you can run the integration tests via the `test_scripts` Makefile target: .. code:: shell-session @@ -20,7 +20,7 @@ the `test_scripts` Makefile target: The tests are written using the `pytest-container `__ plugin. If applicable, use the utility functions and fixtures of the plugin. For example, the -``auto_container`` and ``auto_container_per_test`` fixtures in conjunction with +`auto_container` and `auto_container_per_test` fixtures in conjunction with `testinfra `__. @@ -28,15 +28,15 @@ Test setup ~~~~~~~~~~ The script tests can be run inside different containers specified in -:file:`test/scripts/conftest.py`. This file contains the ``CONTAINERS`` list +:file:`test/scripts/conftest.py`. This file contains the `CONTAINERS` list with all currently present images. These images are pulled and built as needed, -and the :file:`functions.sh` is copied into :file:`/bin/`, so it is -available in ``PATH``. +and the :file:`functions.sh` is copied into `/bin/`, so it is +available in `PATH`. To use any of these containers, you can either define the global variable -``CONTAINER_IMAGES`` in a test module and use the ``auto_container`` fixture, or +`CONTAINER_IMAGES` in a test module and use the `auto_container` fixture, or `parametrize `__ the -``container`` fixture indirectly: +`container` fixture indirectly: .. code:: python @@ -53,12 +53,12 @@ To use any of these containers, you can either define the global variable assert not container_per_test.connection.file("/root/foobar").exists -The example above uses the ``_per_test`` variant of the ``container`` fixture. +The example above uses the `_per_test` variant of the `container` fixture. It ensures that the container is used only in a single test function. Use this -variant for tests that mutate the system under test, because otherwise it may -lead race conditions that are difficult to debug. For tests that only perform -reads, you can omit the ``_per_test`` suffix, so that the container environment can -shared with other tests. This improves execution speed, but comes at the +variant for tests that mutate the system under test because otherwise, it may +lead to race conditions that are difficult to debug. For tests that only perform +reads, you can omit the `_per_test` suffix so that the container environment can be +shared with other tests. This improves execution speed but comes at the expense of safety in case of mutation. For further information, refer to `pytest-container diff --git a/doc/source/image_description.rst b/doc/source/image_description.rst index febaeb38..db998971 100644 --- a/doc/source/image_description.rst +++ b/doc/source/image_description.rst @@ -5,8 +5,8 @@ Image Description .. note:: - This document explains the toplevel structure of the - {kiwi} image description document for version |version| + This document explains the top-level structure of the + {kiwi} image description document for version |version|. .. toctree:: :maxdepth: 1 @@ -33,9 +33,9 @@ Image Identity The mandatory :ref:`sec.description` element contains information about the author, -contact, license and the specification about the use case of this +contact, license, and the specification about the use case of this image. All data together forms the identity card of the image. -There can be only one `description` element +There can be only one `description` element. Image Preferences ----------------- @@ -46,8 +46,8 @@ Image Preferences The mandatory :ref:`sec.preferences` element contains information to classify the image and to describe the layout. All data about the image type, its -version, the partition layout and much more is specified here. There can be -multiple `preferences` elements +version, the partition layout, and much more is specified here. There can be +multiple `preferences` elements. Image Software Sources ---------------------- @@ -56,9 +56,9 @@ Image Software Sources -The mandatory :ref:`sec.repository` element contains information where to find the +The mandatory :ref:`sec.repository` element contains information on where to find the software packages that are used to build the image. There can be -multiple `repository` elements +multiple `repository` elements. Image Content Setup ------------------- @@ -70,8 +70,8 @@ Image Content Setup The mandatory :ref:`sec.packages` element contains information to list which software should be installed from the configured repositories into the image. Software can be defined as names for packages, -collections, archives or products. There can be multiple -`packages` elements +collections, archives, or products. There can be multiple +`packages` elements. Image Users ----------- @@ -81,8 +81,8 @@ Image Users The optional :ref:`sec.users` element contains information about system users -to be created inside of the image. There can be multiple `users` -elements +to be created inside the image. There can be multiple `users` +elements. Image Namespace --------------- @@ -92,9 +92,9 @@ Image Namespace The optional :ref:`sec.profiles` element contains information to create one -or more namespaces to an image description. The namespace can be +or more namespaces for an image description. The namespace can be used with any of the above elements and therefore tie them into -a namespace which can be selected at call time of {kiwi} +a namespace that can be selected at call time of {kiwi}. Image Includes -------------- @@ -103,8 +103,8 @@ Image Includes -The optional :ref:`sec.include` element allows to drop in the contents -of the specified :file:`filename.xml` file at the place were the `include` +The optional :ref:`sec.include` element allows you to drop in the contents +of the specified :file:`filename.xml` file at the place where the `include` statement was specified in the document. The `include` statement is -only allowed as descendant of the root (top-level element) of the +only allowed as a descendant of the root (top-level element) of the image description. diff --git a/doc/source/image_description/elements.rst b/doc/source/image_description/elements.rst index 135c9ab9..78c7883f 100644 --- a/doc/source/image_description/elements.rst +++ b/doc/source/image_description/elements.rst @@ -6,14 +6,14 @@ Image Description Elements .. note:: This document provides a reference for the elements - and attributes of the {kiwi} XML document in version |version| + and attributes of the {kiwi} XML document in version |version|. .. _sec.image: ------- -The toplevel of any {kiwi} image description +The top level of any {kiwi} image description. .. code:: xml @@ -23,22 +23,22 @@ The toplevel of any {kiwi} image description The image definition starts with an image tag and requires the schema format at version {schema_version}. The attribute name specifies the name -of the image which is also used for the filenames created by KIWI. Because -we don’t want spaces in filenames the name attribute must not have any +of the image, which is also used for the filenames created by KIWI. Because +we don’t want spaces in filenames, the name attribute must not have any spaces in its name. The following optional attributes can be inserted in the image tag: displayname - Allows setup of the boot menu title for the selected boot loader. So + Allows setting up the boot menu title for the selected boot loader. So you can have *suse-SLED-foo* as the image name but a different name as the boot display name. Spaces are not allowed in the display name - because it causes problems for some boot loaders and kiwi did not - take the effort to separate the ones which can display them correctly - from the ones which can't + because it causes problems for some boot loaders, and kiwi did not + take the effort to separate the ones that can display them correctly + from the ones that can't. id - sets an identification number which appears as file ``/etc/ImageID`` + sets an identification number that appears as file ``/etc/ImageID`` within the image. .. _sec.include: @@ -46,7 +46,7 @@ id --------- -Optional include of XML file content from file +Optional include of XML file content from a file. .. code:: xml @@ -69,9 +69,9 @@ with file :file:`description.xml` as follows: This will replace the `include` statement with the contents of :file:`description.xml`. The validation of the result happens after the inclusion of all `include` references. The value for -the `from` attribute is interpreted as an URI, as of now only -local URI types are supported as well as the `this://` resource -locator which translates into the path to the KIWI image +the `from` attribute is interpreted as a URI. As of now, only +local URI types are supported, as well as the `this://` resource +locator, which translates into the path to the KIWI image description. .. note:: @@ -79,7 +79,7 @@ description. The include information must be embedded into an `` root node. Only the inner elements of the root node will be included. The processing of XML data via XSLT always - requires a root node which is the reason why this is + requires a root node, which is the reason why this is required to be specified for include files as well. .. note:: @@ -91,9 +91,9 @@ description. .. note:: - The include is implemented via a XSLT stylesheet and therefore + The include is implemented via an XSLT stylesheet and therefore expects an XML document. Other markup formats are not supported - as include reference. + as an include reference. .. _sec.description: @@ -111,14 +111,14 @@ Provide an image identity. The mandatory description section contains information about the creator -of this image description. The attribute type could be either of the -value `system` which indicates this is a system image description or at -value `boot` for custom kiwi boot image descriptions. +of this image description. The attribute `type` could be either of the +value `system`, which indicates this is a system image description, or a value +`boot` for custom kiwi boot image descriptions. -The following optional sub sections can be inserted below the description tag: +The following optional subsections can be inserted below the description tag: license - Specifies the license name which applies to this image description. + Specifies the license name that applies to this image description. .. _sec.certificates: @@ -129,11 +129,11 @@ Add a cert-file to the directory storing additional local CA certificates. The import will occur immediately after the bootstrap process, where the required CA update tooling is expected to be installed. This setting is useful for situations where certificates are not packaged, -or the certificates are required during the build process, e.g. due +or the certificates are required during the build process, e.g., due to proxy servers in the build environment that need certificates in chroot. The required `target_distribution` attribute must be set to allow kiwi a correct matching for the CA store path and the update -tool with regards to the image target distribution. The following +tool with regard to the image's target distribution. The following settings apply: +--------------+-------------------------------------------+------------------------+ @@ -160,7 +160,7 @@ settings apply: ------------- -Setup image type and layout. +Set up image type and layout. .. code:: xml @@ -174,29 +174,29 @@ The mandatory preferences section contains information about the supported image type(s), the used package manager, the version of this image, and further optional elements. The preferences section can be configured to apply only for a certain architecture. In this -case specify the `arch` attribute with a value as it is reported -by :command:`uname -m` +case, specify the `arch` attribute with a value as it is reported +by :command:`uname -m`. ~~~~~~~~~~~~~~~~~~~~~~ The mandatory image version must be a three-part version number of the format: **Major**.\ **Minor**.\ **Release**. In case of changes to -the image description the following rules should apply: +the image description, the following rules should apply: * For smaller image modifications that do not add or remove any new packages, only the release number is incremented. The XML description file(``config.xml``) remains unchanged. -* For image changes that involve the addition or removal of packages - the minor number is incremented and the release number is reset. +* For image changes that involve the addition or removal of packages, + the minor number is incremented, and the release number is reset. -* For image changes that changes the behavior or geometry of the - image file the major number is incremented. +* For image changes that change the behavior or geometry of the + image file, the major number is incremented. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The mandatory packagemanager element specifies which package manager -should be used to handle software packages. The packagemanager setup +The mandatory `packagemanager` element specifies which package manager +should be used to handle software packages. The `packagemanager` setup is connected to the distribution used to build the image. The following table shows which package manager is connected to which distributor: @@ -214,19 +214,19 @@ table shows which package manager is connected to which distributor: | Alpine Linux | apk | +--------------+-----------------+ -In general the specification of one preferences section is sufficient. +In general, the specification of one preferences section is sufficient. However, it’s possible to specify multiple preferences sections and -distinguish between the sections via the profiles attribute. +distinguish between the sections via the `profiles` attribute. -In combination with the above the preferences element supports the +In combination with the above, the preferences element supports the following optional elements: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -locale-filtering can be set to "true" or "false". If set to "true" it -sets the install_lang macro for RPM based installations to the RPM -configured locale list. This results in language specific files to -become filtered out by `rpm` if they don't match the configured list. +locale-filtering can be set to "true" or "false". If set to "true", it +sets the `install_lang` macro for RPM-based installations to the RPM- +configured locale list. This results in language-specific files +being filtered out by `rpm` if they don't match the configured list. .. code:: xml @@ -236,12 +236,12 @@ become filtered out by `rpm` if they don't match the configured list. .. note:: - It depends on the individual package design if the install_lang + It depends on the individual package design if the `install_lang` macro contents apply to the package or not. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Specifies whether package signatures should be checked or not +Specifies whether package signatures should be checked or not. .. code:: xml @@ -252,7 +252,7 @@ Specifies whether package signatures should be checked or not ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Specifies whether files marked as documentation should be skipped -during installation +during installation. .. code:: xml @@ -263,7 +263,7 @@ during installation ~~~~~~~~~~~~~~~~~~~~~~~ Specifies the name of the console keymap to use. The value -corresponds to a map file in ``/usr/share/kbd/keymaps/xkb``. +corresponds to a map file in `/usr/share/kbd/keymaps/xkb`. .. code:: xml @@ -274,9 +274,9 @@ corresponds to a map file in ``/usr/share/kbd/keymaps/xkb``. ~~~~~~~~~~~~~~~~~~~~~~~ Specifies the time zone. Available time zones are located in the -``/usr/share/zoneinfo`` directory. Specify the attribute value -relative to ``/usr/share/zoneinfo``. For example, specify -Europe/Berlin for ``/usr/share/zoneinfo/Europe/Berlin``. +`/usr/share/zoneinfo` directory. Specify the attribute value +relative to `/usr/share/zoneinfo`. For example, specify +`Europe/Berlin` for `/usr/share/zoneinfo/Europe/Berlin`. .. code:: xml @@ -287,13 +287,13 @@ Europe/Berlin for ``/usr/share/zoneinfo/Europe/Berlin``. ~~~~~~~~~~~~~~~~~~~~~ Specifies the name of the UTF-8 locale to use, which defines the -contents of the RC_LANG system environment variable used in the +contents of the `RC_LANG` system environment variable used in the image and to run the custom scripts specified as part of the -{kiwi} image description. Please note only UTF-8 locales are -supported here which also means that the encoding must *not* be part +{kiwi} image description. Please note, only UTF-8 locales are +supported here, which also means that the encoding must *not* be part of the locale information. This means you need to specify the -locale using the 4-digit name like the following example: en_US or -en_US,de_DE +locale using the 4-digit name, like the following example: `en_US` or +`en_US,de_DE`. .. code:: xml @@ -303,7 +303,7 @@ en_US,de_DE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Specifies the name of the plymouth bootsplash theme to use +Specifies the name of the plymouth bootsplash theme to use. .. code:: xml @@ -323,14 +323,14 @@ bootloader has theme support. -Along with the version and the packagemanager at least one image type -element must be specified to indicate which image type should be build. +Along with the version and the packagemanager, at least one image type +element must be specified to indicate which image type should be built. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Specifies the distribution global release version as consumed -by package managers. Currently the release version is not set or -set to `0` for package managers which requires a value to operate. +Specifies the distribution's global release version as consumed +by package managers. Currently, the release version is not set or +set to `0` for package managers that require a value to operate. With the optional `release-version` section, users have an opportunity to specify a custom value which is passed along the package manager to define the distribution release. @@ -340,14 +340,14 @@ manager to define the distribution release. The release version information is currently used in dnf/dnf5 and microdnf package managers only. It might happen that it gets applied to the other package manager - backends as well. This will happen on demand though. + backends as well. This will happen on demand, though. ~~~~~~~~~~~~~~~~~~~ At least one type element must be configured. It is possible to specify multiple type elements in a preferences block. To set a given -type description as the default image use the boolean attribute primary -and set its value to true: +type description as the default image, use the boolean attribute `primary` +and set its value to `true`: .. code:: xml @@ -360,51 +360,51 @@ attribute. The following list describes the supported types and possible values of the image attribute: image="tbz" - A simple tar archive image. The tbz type packs the contents of - the image root tree into a xz compressed tarball. + A simple tar archive image. The `tbz` type packs the contents of + the image root tree into an xz-compressed tarball. image="btrfs|ext2|ext3|ext4|squashfs|xfs" A filesystem image. The image root tree data is packed into a filesystem image of the given type. An image of that type can - be loop mounted and accessed according to the capabiities of + be loop-mounted and accessed according to the capabilities of the selected filesystem. image="iso" - An iso image which can be dumped on a CD/DVD or USB stick - and boots off from this media without interfering with other - system storage components. A useful pocket system for testing - and demo and debugging purposes. + An ISO image that can be dumped on a CD/DVD or USB stick + and boots from this media without interfering with other + system storage components. A useful pocket system for testing, + demo, and debugging purposes. image="oem" An image representing an expandable system disk. This means after - deployment the system can resize itself to the new disk geometry. - The resize operation is configurable as part of the image description - and an installation image for CD/DVD, USB stick and Network deployment + deployment, the system can resize itself to the new disk geometry. + The resize operation is configurable as part of the image description, + and an installation image for CD/DVD, USB stick, and network deployment can be created in addition. For use in cloud frameworks like - Amazon EC2, Google Compute Engine or Microsoft Azure this disk + Amazon EC2, Google Compute Engine, or Microsoft Azure, this disk type also supports the common virtual disk formats. image="docker" - An archive image suitable for the docker container engine. + An archive image suitable for the Docker container engine. The image can be loaded via the `docker load` command and - works within the scope of the container engine + works within the scope of the container engine. image="oci" An archive image that builds a container matching the OCI (Open Container Interface) standard. The container should be - able to run with any oci compliant container engine. + able to run with any OCI-compliant container engine. image="appx" - An archive image suitable for the Windows Subsystem For Linux - container engine. The image can be loaded From a Windows System + An archive image suitable for the Windows Subsystem for Linux + container engine. The image can be loaded from a Windows System that has support for WSL activated. image="wsl" - An archive image suitable for the Windows Subsystem For Linux - container engine >= v2.4.4. The image represents a gzip compressed + An archive image suitable for the Windows Subsystem for Linux + container engine >= v2.4.4. The image represents a gzip-compressed tar file as described in https://learn.microsoft.com/en-us/windows/wsl/build-custom-distro - and can be loaded From a Windows System + and can be loaded from a Windows System that has support for WSL in that version activated. image="kis" @@ -414,74 +414,74 @@ image="kis" For completion of a type description, there could be several other optional attributes and child elements. The `type` element supports a -plethora of optional attributes, some of these are only relevant for -certain build types and will be covered in extra chapters that describes -the individual image types more detailed. Certain attributes are however +plethora of optional attributes; some of these are only relevant for +certain build types and will be covered in extra chapters that describe +the individual image types in more detail. Certain attributes are, however, useful for nearly all build types and will be covered next: bootpartition="true|false": - Boolean parameter notifying {kiwi} whether an extra boot + A boolean parameter notifying {kiwi} whether an extra boot partition should be used or not (the default depends on the current layout). This will override {kiwi}'s default layout. bootpartsize="nonNegativeInteger": - For images with a separate boot partition this attribute - specifies the size in MB. If not set the boot partition - size is set to 200 MB + For images with a separate boot partition, this attribute + specifies the size in MB. If not set, the boot partition + size is set to 200 MB. eficsm="true|false": For images with an EFI layout, specify if the legacy - CSM (BIOS) mode should be supported or not. By default + CSM (BIOS) mode should be supported or not. By default, CSM mode is enabled. efipartsize="nonNegativeInteger": - For images with an EFI fat partition this attribute - specifies the size in MB. If not set the EFI partition - size is set to 20 MB + For images with an EFI fat partition, this attribute + specifies the size in MB. If not set, the EFI partition + size is set to 20 MB. efifatimagesize="nonNegativeInteger": - For ISO images (live and install) the EFI boot requires + For ISO images (live and install), the EFI boot requires an embedded FAT image. This attribute specifies the size - in MB. If not set the FAT image size is set to 20 MB + in MB. If not set, the FAT image size is set to 20 MB. efiparttable="msdos|gpt": - For images with an EFI firmware specifies the partition - table type to use. If not set defaults to the GPT partition - table type for disk images, MBR (msdos) for ISO images. + For images with an EFI firmware, specifies the partition + table type to use. If not set, it defaults to the GPT partition + table type for disk images and MBR (msdos) for ISO images. dosparttable_extended_layout="true|false": - For oem disk images, specifies to make use of logical partitions + For OEM disk images, specifies to make use of logical partitions inside of an extended one. If set to true and if the msdos table type is active, this will cause the fourth partition to be an - extended partition and all following partitions will be + extended partition, and all following partitions will be placed as logical partitions inside of that extended partition. This setting is useful if more than 4 primary - partitions needs to be created in an msdos table + partitions need to be created in an msdos table. btrfs_quota_groups="true|false": - Boolean parameter to activate filesystem quotas if - the filesystem is `btrfs`. By default quotas are inactive. + A boolean parameter to activate filesystem quotas if + the filesystem is `btrfs`. By default, quotas are inactive. btrfs_set_default_volume="true|false": - For oem disk images using the btrfs filesystem, requests to - set a default volume for the rootfs which is used when the + For OEM disk images using the btrfs filesystem, this requests to + set a default volume for the rootfs, which is used when the filesystem gets mounted. In case a `true` value is provided or the attribute is not specified at all, kiwi will make a volume the default volume. This can be either `/` or the configured - root subvolume or the configured root snapshot. Consequently the + root subvolume or the configured root snapshot. Consequently, the entry created for the rootfs in the `/etc/fstab` file will not contain any specific volume definition. In case a `false` value - is provided, kiwi will not set any default volume which also + is provided, kiwi will not set any default volume, which also means that the entry for the rootfs in the `/etc/fstab` file requires a volume definition which is placed by kiwi as a `subvol=` parameter in the respective fstab field entry. In - addition the parameter `rootflags=subvol=` is added to the + addition, the parameter `rootflags=subvol=` is added to the kernel commandline such that early initrd code has a chance to know about the rootfs volume. btrfs_root_is_subvolume="true|false": Tell kiwi to create a root volume to host (/) inside. - The name of this subvolume is by default set to: `@`. + The name of this subvolume is, by default, set to: `@`. The name of the subvolume can be changed via a volume entry of the form: @@ -491,101 +491,101 @@ btrfs_root_is_subvolume="true|false": - By default the creation of a toplevel volume is set to: `true` + By default, the creation of a top-level volume is set to `true`. btrfs_root_is_snapper_snapshot="true|false": - Boolean parameter that tells {kiwi} to install + A boolean parameter that tells {kiwi} to install the system into a btrfs snapshot. The snapshot layout is compatible with the snapper management toolkit and follows a concept by SUSE. - By default snapshots are turned off. + By default, snapshots are turned off. btrfs_root_is_readonly_snapshot="true|false": - Boolean parameter notifying {kiwi} that - the btrfs root filesystem snapshot has to made read-only. if this option - is set to true, the root filesystem snapshot it will be turned into - read-only mode, once all data has been placed to it. The option is only - effective if `btrfs_root_is_snapper_snapshot` is also set to true. By default the + A boolean parameter notifying {kiwi} that + the btrfs root filesystem snapshot has to be made read-only. If this option + is set to true, the root filesystem snapshot will be turned into + read-only mode once all data has been placed in it. The option is only + effective if `btrfs_root_is_snapper_snapshot` is also set to true. By default, the root filesystem snapshot is writable. bootstrap_package="package_name": - For use with the `apt` packagemanager only. Specifies the name - of a bootstrap package which provides a bootstrap tarball + For use with the `apt` package manager only. Specifies the name + of a bootstrap package that provides a bootstrap tarball in :file:`/var/lib/bootstrap/PACKAGE_NAME.ARCH.tar.xz`. The tarball will be unpacked and used as the bootstrap rootfs to begin with. This allows for an alternative bootstrap - method. For further details see :ref:`debianbootstrap_alternative`. + method. For further details, see :ref:`debianbootstrap_alternative`. compressed="true|false": Specifies whether the image output file should be - compressed or not. This option is only used for filesystem only images or + compressed or not. This option is only used for filesystem-only images or for the `pxe` or `cpio` types. editbootconfig="file_path": - Specifies the path to a script which is called right + Specifies the path to a script that is called right before the bootloader is installed. The script runs relative to the - directory which contains the image structure. + directory that contains the image structure. editbootinstall="file_path": - Specifies the path to a script which is called right + Specifies the path to a script that is called right after the bootloader is installed. The script runs relative to the - directory which contains the image structure. + directory that contains the image structure. filesystem="btrfs|ext2|ext3|ext4|squashfs|xfs": - The root filesystem + The root filesystem. firmware="efi|uefi|bios|ec2|ofw|opal": Specifies the boot firmware of the appliance. This attribute is used to differentiate the image according to the firmware which boots up the system. It mostly impacts the disk layout and the - partition table type. By default `bios` is used on x86, - `ofw` on PowerPC and `efi` on ARM. + partition table type. By default, `bios` is used on x86, + `ofw` on PowerPC, and `efi` on ARM. * `efi` - Standard EFI layout + Standard EFI layout. * `uefi` - Standard EFI layout for secure boot + Standard EFI layout for secure boot. * `bios` - Standard BIOS layout for x86 + Standard BIOS layout for x86. * `ec2` - Standard BIOS layout for x86 using Xen grub modules for old - style Xen boot in Amazon EC2 + Standard BIOS layout for x86 using Xen grub modules for old- + style Xen boot in Amazon EC2. * `ofw` - Standard PPC layout + Standard PPC layout. * `opal` - Standard openPOWER PPC64 layout. kexec based boot process + Standard openPOWER PPC64 layout. kexec-based boot process. force_mbr="true|false": - Boolean parameter to force the usage of a MBR partition + A boolean parameter to force the usage of an MBR partition table even if the system would default to GPT. This is occasionally - required on ARM systems that use a EFI partition layout but which must - not be stored in a GPT. Note that forcing a MBR partition table incurs + required on ARM systems that use an EFI partition layout but must + not be stored in a GPT. Note that forcing an MBR partition table incurs limitations with respect to the number of available partitions and their sizes. fsmountoptions="option_string": - Specifies the filesystem mount options which are passed + Specifies the filesystem mount options that are passed via the `-o` flag to :command:`mount` and are included in :file:`/etc/fstab`. fscreateoptions="option_string": Specifies the filesystem options used to create the - filesystem. In {kiwi} the filesystem utility to create a filesystem is - called without any custom options. The default options are filesystem + filesystem. In {kiwi}, the filesystem utility to create a filesystem is + called without any custom options. The default options are filesystem- specific and are provided along with the package that provides the filesystem utility. For the Linux `ext[234]` filesystem, the default options can be found in the :file:`/etc/mke2fs.conf` file. Other - filesystems provides this differently and documents information - about options and their defaults in the respective manual page, e.g - :command:`man mke2fs`. With the `fscreateoptions` attribute it's possible + filesystems provide this differently and document information + about options and their defaults in the respective manual page, e.g., + :command:`man mke2fs`. With the `fscreateoptions` attribute, it's possible to directly influence how the filesystem will be created. The options provided as a string are passed to the command that creates the filesystem without any further validation by {kiwi}. For example, to turn - off the journal on creation of an ext4 filesystem the following option + off the journal on the creation of an ext4 filesystem, the following option would be required: .. code:: xml @@ -599,60 +599,60 @@ kernelcmdline="string": bootloader. root_clone="number" - For oem disk images, this attribute allows to create `number` + For OEM disk images, this attribute allows you to create `number` clone(s) of the root partition, with `number` >= 1. A clone partition - is content wise an exact byte for byte copy of the origin root partition. - However, to avoid conflicts at boot time the UUID of any + is content-wise an exact byte-for-byte copy of the origin root partition. + However, to avoid conflicts at boot time, the UUID of any cloned partition will be made unique. In the sequence of partitions, - the clone(s) will always be created first followed by the + the clone(s) will always be created first, followed by the partition considered the origin. The origin partition is the one that will be referenced and used by the system. - Also see :ref:`clone_partitions` + Also, see :ref:`clone_partitions`. boot_clone="number" - Same as `root_clone` but applied to the boot partition if present + Same as `root_clone` but applied to the boot partition if present. luks="passphrase|file:///path/to/keyfile|random": Supplying a value will trigger the encryption of the partition serving the root filesystem using the LUKS extension. The supplied value represents either the passphrase string or the location of - a key file if specified as `file://...` resource or the reserved - name `random`. When using a passphrase the system will interactively + a key file if specified as a `file://...` resource or the reserved + name `random`. When using a passphrase, the system will interactively ask for that passphrase on first boot unless it is set empty. - In case of an empty passphrase the system cannot be considered secure. - When using a key file the information from the file is read and + In case of an empty passphrase, the system cannot be considered secure. + When using a key file, the information from the file is read and used as a passphrase. The given key file is **not automatically** - placed into the system or added to the `etc/crypttab` which means - the passphrase in the key file is by default requested from an + placed into the system or added to `/etc/crypttab`, which means + the passphrase in the key file is, by default, requested from an interactive dialog at boot time. When using the reserved word `random`, kiwi will create a key file with a random passphrase - and place this information into `etc/crypttab`. This allows + and place this information into `/etc/crypttab`. This allows the system to boot without user interaction but also requires the initrd to be protected in some way because it will contain - the keyfile. The use of `random` is therefore only secure if - the image adds additional security that encrypts the initrd - like it is e.g. done in the IBM secure execution process. + the key file. The use of `random` is therefore only secure if + the image adds additional security that encrypts the initrd, + as is, e.g., done in the IBM secure execution process. If the encryption of the system is combined with the attribute - `bootpartition="false"` it's important to understand that this + `bootpartition="false"`, it's important to understand that this will place `/boot` into the encrypted area of the system and - leaves reading boot data from it as a responsibility to the - bootloader. Not every bootloader can cope with that and those - that can e.g. grub will then open an interactive dialog at + leave reading boot data from it as a responsibility to the + bootloader. Not every bootloader can cope with that, and those + that can, e.g., grub, will then open an interactive dialog at the bootloader level asking for the credentials to decrypt the root filesystem. luks_version="luks|luks1|luks2": - Specify which `LUKS` version should be used. If not set and by - default `luks` is used. The interpretation of the default depends + Specify which `LUKS` version should be used. If not set, and by + default, `luks` is used. The interpretation of the default depends on the distribution and could result in either 'luks1' or 'luks2'. The specification of the `LUKS` version allows using a different set of `luksformat` options. To investigate the differences between - the two please consult the `cryptsetup` manual page. + the two, please consult the `cryptsetup` manual page. target_blocksize="number": - Specifies the image blocksize in bytes which has to - match the logical blocksize of the target storage device. By default 512 - Bytes is used, which works on many disks. You can obtain the blocksize + Specifies the image blocksize in bytes, which has to + match the logical blocksize of the target storage device. By default, 512 + bytes is used, which works on many disks. You can obtain the blocksize from the `SSZ` column in the output of the following command: .. code:: shell-session @@ -660,77 +660,77 @@ target_blocksize="number": blockdev --report $DEVICE target_removable="true|false": - Indicate if the target disk for oem images is deployed - to a removable device e.g a USB stick or not. This only - affects the EFI setup if requested and in the end avoids + Indicate if the target disk for OEM images is deployed + to a removable device, e.g., a USB stick or not. This only + affects the EFI setup if requested, and in the end, avoids the creation of a custom boot menu entry in the firmware - of the target machine. By default the target disk is - expected to be non-removable + of the target machine. By default, the target disk is + expected to be non-removable. selinux_policy.attribute="targeted|mls|minimum": The `selinux_policy` attribute sets the SELinux policy to use. - `targeted` policy is the default policy. Only change this option + The `targeted` policy is the default policy. Only change this option if you want to use the `mls` or `minimum` policy. spare_part="number": Request a spare partition right before the root partition of the requested size. The attribute takes a size value - and allows a unit in MB or GB, e.g 200M. If no unit is given + and allows a unit in MB or GB, e.g., 200M. If no unit is given, the value is considered to be mbytes. A spare partition - can only be configured for the disk image type oem + can only be configured for the disk image type oem. spare_part_mountpoint="dir_path": - Specify mount point for spare partition in the system. - Can only be configured for the disk image type oem + Specify a mount point for the spare partition in the system. + Can only be configured for the disk image type oem. spare_part_fs="btrfs|ext2|ext3|ext4|xfs": - Specify filesystem for spare partition in the system. - Can only be configured for the disk image type oem + Specify a filesystem for the spare partition in the system. + Can only be configured for the disk image type oem. spare_part_fs_attributes="attribute_list": Specify filesystem attributes for the spare partition. - Attributes can be specified as comma separated list. - Currently the attributes `no-copy-on-write` and `synchronous-updates` + Attributes can be specified as a comma-separated list. + Currently, the attributes `no-copy-on-write` and `synchronous-updates` are available. Can only be configured for the disk image - type oem + type oem. spare_part_is_last="true|false": Specify if the spare partition should be the last one in - the partition table. Can only be configured for the `oem` - type with oem-resize switched off. By default the root - partition is the last one and the spare partition lives - before it. With this attribute that setup can be toggled. - However, if the root partition is no longer the last one - the oem repart/resize code can no longer work because - the spare part would block it. Because of that moving + the partition table. It can only be configured for the `oem` + type with oem-resize switched off. By default, the root + partition is the last one, and the spare partition lives + before it. With this attribute, that setup can be toggled. + However, if the root partition is no longer the last one, + the OEM repart/resize code can no longer work because + the spare part would block it. Because of that, moving the spare part at the end of the disk is only applied if oem-resize is switched off. There is a runtime - check in the {kiwi} code to check this condition + check in the {kiwi} code to check this condition. devicepersistency="by-uuid|by-label": Specifies which method to use for persistent device names. - This will affect all files written by kiwi that includes - device references for example `etc/fstab` or the `root=` - parameter in the kernel commandline. By default by-uuid - is used + This will affect all files written by kiwi that include + device references, for example, `/etc/fstab` or the `root=` + parameter in the kernel command line. By default, by-uuid + is used. squashfscompression="uncompressed|gzip|lzo|lz4|xz|zstd": - Specifies the compression type for mksquashfs + Specifies the compression type for mksquashfs. erofscompression="text" Specifies the compression type and level for erofs. - The attribute is a free form text because erofs allows paramters + The attribute is a free-form text because erofs allows parameters for the different compression types. Please consult the erofs - man page for details how to specify a value for the `-z` option - on `mkfs.erofs` and pass a proper value as erofscompression + man page for details on how to specify a value for the `-z` option + on `mkfs.erofs` and pass a proper value as `erofscompression`. standalone_integrity="true|false": For the `oem` type only, specifies to create a standalone - `dm_integrity` layer on top of the root filesystem + `dm_integrity` layer on top of the root filesystem. integrity_legacy_hmac="true|false": For the `oem` type only and in combination with the `standalone_integrity` - attribute, Allow to use old flawed HMAC calculation (does not protect superblock). + attribute, this allows the use of old, flawed HMAC calculations (does not protect the superblock). .. warning:: @@ -738,16 +738,16 @@ integrity_legacy_hmac="true|false": a specific old kernel is required! integrity_keyfile="filepath": - For the `oem` type only and in combination with the `standalone_integrity` - attribute, protects access to the integrity map using the given keyfile. + For the `oem` type only, and in combination with the `standalone_integrity` + attribute, this protects access to the integrity map using the given keyfile. integrity_metadata_key_description="string": - For the `oem` type only and in combination with + For the `oem` type only, and in combination with the `embed_integrity_metadata` attribute, specifies a custom description of an integrity key as it is expected to be present in the kernel keyring. The information is placed in the integrity - metadata block. If not specified kiwi creates a key argument - string instead which is based on the given `integrity_keyfile` + metadata block. If not specified, kiwi creates a key argument + string instead, which is based on the given `integrity_keyfile` filename. The format of this key argument is: .. code:: bash @@ -766,28 +766,28 @@ embed_integrity_metadata="true|false": |header|0xFF|dm_integrity_meta|0xFF|0x0| header: - Is a string of the following information separated by spaces + Is a string of the following information separated by spaces: * **version**: currently set to `1` - * **fstype**: name of `filesystem` attribute - * **access**: either `ro` or `rw` depending on the filesystem capabilities + * **fstype**: name of the `filesystem` attribute + * **access**: either `ro` or `rw`, depending on the filesystem capabilities * `integrity`: fixed identifier value dm_integrity_meta: - Is a string of the following information separated by spaces + Is a string of the following information separated by spaces: * **provided_data_sectors**: number of data sectors - * **sector_size**: sector size in byte, defaults to 512 + * **sector_size**: sector size in bytes; defaults to 512 * **parameter_count**: number of parameters needed to construct the integrity device map. - After the `parameter_count` a list of space separated parameters - follows and the `parameter_count` specifies the quantity of these - parameters + After the `parameter_count`, a list of space-separated parameters + follows, and the `parameter_count` specifies the quantity of these + parameters. * **parameters**: The first element of the parameter list contains information about - the used hash algorithm which is not part of the superblock and - provided according to the parameters passed along when {kiwi} - calls `integritysetup`. As of now this defaults to: + the used hash algorithm, which is not part of the superblock and + is provided according to the parameters passed along when {kiwi} + calls `integritysetup`. As of now, this defaults to: - internal_hash:sha256 @@ -796,9 +796,9 @@ embed_integrity_metadata="true|false": web for possible flag values. verity_blocks="number|all": - For the `oem` type only, specifies to create a dm verity hash + For the `oem` type only, specifies to create a dm-verity hash from the number of given blocks (or all) placed at the end of the - root filesystem For later verification of the device, + root filesystem. For later verification of the device, the credentials information produced by `veritysetup` from the cryptsetup tools are needed. This data as of now is only printed as debugging information to the build log file. A concept to @@ -816,7 +816,7 @@ embed_verity_metadata="true|false": |header|0xFF|dm_verity_credentials|0xFF|0x0| header: - Is a string of the following information separated by spaces + Is a string of the following information separated by spaces: * **version**: currently set to `1` * **fstype**: name of `filesystem` attribute @@ -824,7 +824,7 @@ embed_verity_metadata="true|false": * `verity`: fixed identifier value dm_verity_credentials: - Is a string of the following information separated by spaces + Is a string of the following information separated by spaces: * **hash_type**: hash type name as returned by `veritysetup` * **data_blksize**: data blocksize as returned by `veritysetup` @@ -848,140 +848,140 @@ embed_verity_metadata="true|false": **Common Options:** - * `panic-on-corruption`: System panics on corruption detection - * `restart-on-corruption`: System restarts on corruption (often default) - * `ignore-corruption`: Ignore corruption (debugging only) - * `ignore-zero-blocks`: Skip verification of zero blocks - * `check-at-most-once`: Verify each block only once + * `panic-on-corruption`: System panics on corruption detection. + * `restart-on-corruption`: System restarts on corruption (often default). + * `ignore-corruption`: Ignore corruption (debugging only). + * `ignore-zero-blocks`: Skip verification of zero blocks. + * `check-at-most-once`: Verify each block only once. For complete options, see `veritysetup(8) `_. overlayroot="true|false": - For the `oem` type only, specifies to use an `overlayfs` based root - filesystem consisting out of a squashfs compressed read-only root - filesystem combined with an optional write-partition or tmpfs. + For the `oem` type only, specifies to use an `overlayfs`-based root + filesystem consisting of a squashfs-compressed read-only root + filesystem combined with an optional write partition or tmpfs. The optional kernel boot parameter `rd.root.overlay.temporary` can be used to point the write area into a `tmpfs` instead of - a persistent write-partition. In this mode all written data is - temporary until reboot of the system. The kernel boot parameter + a persistent write partition. In this mode, all written data is + temporary until the system is rebooted. The kernel boot parameter `rd.root.overlay.size` can be used to configure the size for the `tmpfs` that is used for the `overlayfs` mount process if `rd.root.overlay.temporary` is requested. That size configures the amount of space available for writing new data during the runtime - of the system. The default value is set to `50%` which means one + of the system. The default value is set to `50%`, which means one half of the available RAM space can be used for writing new data. - By default the persistent write-partition is used. The size of that + By default, the persistent write partition is used. The size of that partition can be influenced via the optional `` element in the `` section or via the optional `` element in the `` section of the XML description. Setting a fixed `` value will set the size of the image disk to that value and results in an image file of that size. The available - space for the write partition is that size reduced by the + space for the write partition is that size, reduced by the size the squashfs read-only system needs. If the `` - element is set to `true` an eventually given `` element + element is set to `true`, an eventually given `` element will not have any effect because the write partition will be resized on first boot to the available disk space. - To disable the use of any overlay the kernel boot parameter + To disable the use of any overlay, the kernel boot parameter `rd.root.overlay.readonly` can be used. It takes precedence over all other overlay kernel parameters because it leads to the - deactivation of any overlayfs based action and just boots up with - the squashfs root filesystem. In fact this mode is the same + deactivation of any overlayfs-based action and just boots up with + the squashfs root filesystem. In fact, this mode is the same as not installing the `kiwi-overlay` dracut module. overlayroot_readonly_filesystem="squashfs|erofs": For the `oem` type only, specifies the filesystem type to use - as read-only filesystem in an `overlayroot` setup. By default - `squashfs` is used + as a read-only filesystem in an `overlayroot` setup. By default, + `squashfs` is used. overlayroot_write_partition="true|false": - For the `oem` type only, allows to specify if the extra read-write + For the `oem` type only, this allows you to specify if the extra read-write partition in an `overlayroot` setup should be created or not. - By default the partition is created and the kiwi-overlay dracut - module also expect it to be present. However, the overlayroot - feature can also be used without dracut (`initrd_system="none"`) - and under certain circumstances it is handy to configure if the + By default, the partition is created, and the kiwi-overlay dracut + module also expects it to be present. However, the overlayroot + feature can also be used without dracut (`initrd_system="none"`), + and under certain circumstances, it is handy to configure whether the partition table should contain the read-write partition or not. overlayroot_readonly_partsize="mbsize": - Specifies the size in MB of the partition which stores the - squashfs compressed read-only root filesystem in an - overlayroot setup. If not specified kiwi calculates + Specifies the size in MB of the partition that stores the + squashfs-compressed read-only root filesystem in an + overlayroot setup. If not specified, kiwi calculates the needed size by a preliminary creation of the - squashfs compressed file. However this is only accurate - if no changes to the root filesystem data happens + squashfs compressed file. However, this is only accurate + if no changes to the root filesystem data happen after this calculation, which cannot be guaranteed as - there is at least one optional script hook which is - allowed and applied after the calculation. In addition the + there is at least one optional script hook that is + allowed and applied after the calculation. In addition, the pre-calculation requires some time in the build process. - If the value can be provided beforehand this also speeds - up the build process significantly + If the value can be provided beforehand, this also speeds + up the build process significantly. bootfilesystem="btrfs|ext2|ext3|ext4|xfs|fat32|fat16": - If an extra boot partition is required this attribute - specify which filesystem should be used for it. The + If an extra boot partition is required, this attribute + specifies which filesystem should be used for it. The type of the selected bootloader might overwrite this - setting if there is no alternative possible though. + setting if there is no alternative possible, though. flags="overlay|dmsquash": - For the iso image type specifies the live iso technology and - dracut module to use. If set to overlay the kiwi-live dracut - module will be used to support a live iso system based on - squashfs+overlayfs. If set to dmsquash the dracut standard - dmsquash-live module will be used to support a live iso + For the ISO image type, this specifies the live ISO technology and + dracut module to use. If set to `overlay`, the kiwi-live dracut + module will be used to support a live ISO system based on + squashfs+overlayfs. If set to `dmsquash`, the dracut standard + dmsquash-live module will be used to support a live ISO system based on the capabilities of the upstream dracut module. format="gce|ova|qcow2|vagrant|vmdk|vdi|vhd|vhdx|vhd-fixed": - For disk image type oem, specifies the format of - the virtual disk such that it can run on the desired target + For disk image type oem, this specifies the format of + the virtual disk so that it can run on the desired target virtualization platform. formatoptions="string": - Specifies additional format options passed on to qemu-img - formatoptions is a comma separated list of format specific - options in a name=value format like qemu-img expects it. - kiwi will take the information and pass it as parameter to - the -o option in the qemu-img call + Specifies additional format options passed on to `qemu-img`. + `formatoptions` is a comma-separated list of format-specific + options in a `name=value` format, as `qemu-img` expects it. + kiwi will take the information and pass it as a parameter to + the `-o` option in the `qemu-img` call. fsmountoptions="string": - Specifies the filesystem mount options which also ends up in fstab - The string given here is passed as value to the -o option of mount + Specifies the filesystem mount options, which also end up in `fstab`. + The string given here is passed as a value to the `-o` option of `mount`. fscreateoptions="string": - Specifies options to use at creation time of the filesystem + Specifies options to use at the creation time of the filesystem. force_mbr="true|false": - Force use of MBR (msdos table) partition table even if the - use of the GPT would be the natural choice. On e.g some - arm systems an EFI partition layout is required but must - not be stored in a GPT. For those rare cases this attribute - allows to force the use of the msdos table including all + Force the use of an MBR (msdos table) partition table even if the + use of the GPT would be the natural choice. On, e.g., some + ARM systems, an EFI partition layout is required but must + not be stored in a GPT. For those rare cases, this attribute + allows you to force the use of the msdos table, including all its restrictions in max partition size and amount of - partitions + partitions. gpt_hybrid_mbr="true|false": For disk types, create a hybrid GPT/MBR partition table with an - 'accurate' MBR table that will have no 'bootable' flagged partition + 'accurate' MBR table that will have no 'bootable' flagged partition. For ISO types, create a hybrid GPT/MBR partition table where the MBR partition table contains a whole-disk 'protective' partition and a second bootable-flagged partition (intended to make the image - bootable in both UEFI and BIOS modes on as much hardware as possible) - In both cases, only has any effect if the EFI partition table - type is GPT + bootable in both UEFI and BIOS modes on as much hardware as possible). + In both cases, it only has an effect if the EFI partition table + type is GPT. hybridpersistent="true|false": - For the live ISO type, triggers the creation of a partition for - a COW file to keep data persistent over a reboot + For the live ISO type, this triggers the creation of a partition for + a COW file to keep data persistent over a reboot. hybridpersistent_filesystem="ext4|xfs": For the live ISO type, set the filesystem to use for persistent - writing if a hybrid image is used as disk on e.g a USB Stick. - By default the ext4 filesystem is used. + writing if a hybrid image is used as a disk on, e.g., a USB Stick. + By default, the ext4 filesystem is used. initrd_system="kiwi|dracut|none": - Specify which initrd builder to use, default is set to `dracut`. - If set to `none` the image is build without an initrd. Depending - on the image type this can lead to a non bootable system as its + Specify which initrd builder to use; the default is set to `dracut`. + If set to `none`, the image is built without an initrd. Depending + on the image type, this can lead to a non-bootable system, as it's now a kernel responsibility if the given root device can be mounted or not. @@ -991,59 +991,59 @@ metadata_path="dir_path": .. note:: - Currently this is only effective for the appx container image type. + Currently, this is only effective for the appx container image type. installboot="failsafe-install|harddisk|install": - Specifies the bootloader default boot entry for the initial + Specifies the bootloader's default boot entry for the initial boot of a {kiwi} install image. .. note:: - This value is only evaluated for grub + This value is only evaluated for grub. install_continue_on_timeout="true|false": Specifies the boot timeout handling for the {kiwi} - install image. If set to "true" the configured timeout - or its default value applies. If set to "false" no + install image. If set to "true", the configured timeout + or its default value applies. If set to "false", no timeout applies in the boot menu of the install image. installprovidefailsafe="true|false": - Specifies if the bootloader menu should provide an - failsafe entry with special kernel parameters or not + Specifies if the bootloader menu should provide a + failsafe entry with special kernel parameters or not. installiso="true|false" - Specifies if an install iso image should be created. + Specifies if an install ISO image should be created. This attribute is only available for the `oem` type. - The generated ISO image is an hybrid ISO which can be - used as disk on e.g a USB stick or as ISO. + The generated ISO image is a hybrid ISO that can be + used as a disk on, e.g., a USB stick or as an ISO. installpxe="true|false": - Specifies if a tarball that contains all data for a pxe network + Specifies if a tarball that contains all data for a PXE network installation should be created. This attribute is only available for the `oem` type. mediacheck="true|false": - For ISO images, specifies if the bootloader menu should provide an - mediacheck entry to verify ISO integrity or not. Disabled by default + For ISO images, specifies whether the bootloader menu should provide a + mediacheck entry to verify ISO integrity or not. It is disabled by default and only available for the x86 arch family. mdraid="mirroring|striping": - Setup software raid in degraded mode with one disk - Thus only mirroring and striping is possible + Set up software RAID in degraded mode with one disk. + Thus, only mirroring and striping are possible. primary="true|false": Specifies this type to be the primary type. If no type option - is given on the commandline, {kiwi} will build this type + is given on the commandline, {kiwi} will build this type. ramonly="true|false": - For all images that are configured to use the overlay filesystem + For all images that are configured to use the overlay filesystem, this setting forces any COW(Copy-On-Write) action to happen in RAM. rootfs_label="string": - Label name to set for the root filesystem. By default `ROOT` is used + A label name to set for the root filesystem. By default, `ROOT` is used. volid="string": - For the ISO type only, specifies the volume ID (volume name or label) + For the ISO type only, this specifies the volume ID (volume name or label) to be written into the master block. There is space for 32 characters. application_id="string": @@ -1052,7 +1052,7 @@ application_id="string": 128 characters. vhdfixedtag="GUID_string": - For the VHD disk format, specifies the GUID + For the VHD disk format, this specifies the GUID. derived_from="string": For container images, specifies the image URI of the container image. @@ -1062,46 +1062,46 @@ derived_from="string": delta_root="true|false": For container images and in combination with the `derived_from` attribute. If `delta_root` is set to `true`, {kiwi-ng} creates - a container image which only contains the differences compared - to the given `derived_from` container. Such a container is on - its own no longer functional and requires a tool which is able + a container image that only contains the differences compared + to the given `derived_from` container. Such a container is, on + its own, no longer functional and requires a tool that is able to provision a container instance from the `derived_from` container combined with the `delta_root` application container. Such a tool exists with the `oci-pilot `_ - project and allows to manage applications as containers - that feels like native applications on the host system. + project and allows you to manage applications as containers + that feel like native applications on the host system. ensure_empty_tmpdirs="true|false": - For OCI container images, specifies whether to ensure /run and /tmp + For OCI container images, this specifies whether to ensure the `/run` and `/tmp` directories are empty in the container image created by Kiwi. - Default is true. + The default is true. publisher="string": - For ISO images, specifies the publisher name of the ISO. + For ISO images, this specifies the publisher name of the ISO. eficsmpart_id="number": - For OEM images, specifies the partition number for the EFI CSM + For OEM images, this specifies the partition number for the EFI CSM (legacy BIOS) partition. For details about the evaluation and impact - of custom partition ids please see: :ref:`custom_partitions` + of custom partition ids, please see: :ref:`custom_partitions`. efipart_id="number": For OEM images, specifies the partition number for the EFI partition. - For details about the evaluation and impact of custom partition ids - please see: :ref:`custom_partitions` + For details about the evaluation and impact of custom partition ids, + please see: :ref:`custom_partitions`. rootpart_id="number": - For OEM images, specifies the partition number for the ROOT partition. - For details about the evaluation and impact of custom partition ids - please see: :ref:`custom_partitions` + For OEM images, this specifies the partition number for the ROOT partition. + For details about the evaluation and impact of custom partition ids, + please see: :ref:`custom_partitions`. bootpart_id="number": For OEM images, specifies the partition number for the BOOT partition. - For details about the evaluation and impact of custom partition ids - please see: :ref:`custom_partitions` + For details about the evaluation and impact of custom partition ids, + please see: :ref:`custom_partitions`. -The following sections shows the supported child elements of the `type` -element including references to their usage in a detailed type setup: +The following sections show the supported child elements of the `type` +element, including references to their usage in a detailed type setup: .. _preferences-type-luksformat: @@ -1111,7 +1111,7 @@ The `luksformat` element is used to specify additional luks options passed on to the `cryptsetup luksFormat` call. The element requires the attribute `luks` to be set in the `` section referring to `luksformat`. Several custom settings related to the LUKS and LUKS2 -format features can be setup. For example the setup of +format features can be set up. For example, the setup of the `dm_integrity` feature: .. code:: xml @@ -1126,21 +1126,21 @@ the `dm_integrity` feature: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The `bootloader` element is used to select the bootloader. At the moment, -`grub2`, `systemd_boot` and the combination of zipl -plus userspace grub2 `grub2_s390x_emu` are supported. The special -`custom` entry allows to skip the bootloader configuration and installation +`grub2`, `systemd_boot`, and the combination of zipl +plus userspace grub2, `grub2_s390x_emu`, are supported. The special +`custom` entry allows you to skip the bootloader configuration and installation and leaves this up to the user, which can be done by using the `editbootinstall` and `editbootconfig` custom scripts. .. note:: - bootloaders provides a very different set of features and only + Bootloaders provide a very different set of features and only work within their individual implementation priorities. {kiwi} - provides an API for bootloaders but not all API methods can be + provides an API for bootloaders, but not all API methods can be implemented for all bootloaders due to the fact that some - features only exists in one but not in another bootloader. If + features only exist in one but not in another bootloader. If a bootloader setting is used that is not understood by the - selected bootloader the image build process will fail with + selected bootloader, the image build process will fail with an exception message. name="grub2|systemd_boot|grub2_s390x_emu|zipl": @@ -1150,19 +1150,19 @@ name="grub2|systemd_boot|grub2_s390x_emu|zipl": The implementation to support systemd-boot reads all data from the ESP (EFI Standard Partition). This also - includes the kernel and initrd which requires the size - of the ESP to be configured appropriately. By default - {kiwi} configures the ESP with 20MB. For systemd_boot + includes the kernel and initrd, which requires the size + of the ESP to be configured appropriately. By default, + {kiwi} configures the ESP with 20MB. For systemd_boot, this is usually too small and can be changed with the - `efipartsize` attribute. Reading boot relevant files - from another filesystem requires to provide alternative - EFI filesystem drivers e.g efifs and also needs - adaptions on the setup of `bootctl`. + `efipartsize` attribute. Reading boot-relevant files + from another filesystem requires providing alternative + EFI filesystem drivers, e.g., efifs, and also needs + adaptations on the setup of `bootctl`. .. note:: systemd_boot and shim - At the moment the EFI image provided along with systemd-boot - is not compatible with the shim signed loader provided in an + At the moment, the EFI image provided along with systemd-boot + is not compatible with the shim-signed loader provided in an extra effort by the distributions. In addition to the mandatory name attribute, the following optional @@ -1176,20 +1176,20 @@ bls="true|false": output_console="none|console|gfxterm|serial|vga_text|mda_text|morse|spkmodem": Specifies the bootloader output console. The attribute is available for the - `grub` bootloader type. Multiple console types can be provided separated - by a space + `grub` bootloader type. Multiple console types can be provided, separated + by a space. input_console="none|console|serial|at_keyboard|usb_keyboard": Specifies the bootloader input console. The attribute is available for the - `grub` bootloader type. Multiple console types can be provided separated - by a space. If no input_console is provided, the value for the - output_console is used if specified. + `grub` bootloader type. Multiple console types can be provided, separated + by a space. If no `input_console` is provided, the value for the + `output_console` is used if specified. grub_template="filename": - Specifies a custom grub bootloader template file which will be used + Specifies a custom grub bootloader template file that will be used instead of the one provided with Kiwi. A static bootloader template to create the grub config file is only used in Kiwi if the native method - via the grub mkconfig toolchain does not work properly. As of today, + via the grub `mkconfig` toolchain does not work properly. As of today, this is only the case for live and install ISO images. Thus, this setting only affects the oem and iso image types. @@ -1209,10 +1209,10 @@ grub_template="filename": +-----------------------+----------------------------------------------+ | initrd_file | the name of the initial ramdisk file | +-----------------------+----------------------------------------------+ - | boot_options | kernel command line options for booting | + | boot_options | kernel command-line options for booting | | | normally | +-----------------------+----------------------------------------------+ - | failsafe_boot_options | kernel command line options for booting in | + | failsafe_boot_options | kernel command-line options for booting in | | | failsafe mode | +-----------------------+----------------------------------------------+ | gfxmode | the resolution to use for the bootloader; | @@ -1253,12 +1253,12 @@ timeout="number": Specifies the boot timeout in seconds prior to launching the default boot option. By default, the timeout is set to 10 seconds. It makes sense to set this value to `0` for images intended to be started - non-interactively (e.g. virtual machines). + non-interactively (e.g., virtual machines). timeout_style="countdown|hidden": Specifies the boot timeout style to control the way in which the timeout interacts with displaying the menu. If set, the display of the - bootloader menu is delayed after the timeout expired. In countdown mode, + bootloader menu is delayed after the timeout has expired. In countdown mode, an indication of the remaining time is displayed. The attribute is available for the grub loader only. @@ -1270,13 +1270,13 @@ targettype="CDL|LDL|FBA|SCSI|GPT": ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Used to specify data required to setup secure linux execution. Secure -linux execution reads the kernel, initrd and boot parameters from an +Used to specify data required to set up secure Linux execution. Secure +Linux execution reads the kernel, initrd, and boot parameters from an encrypted data blob and couples the image to the machine it gets -executed on. Typically the private key is protected in hardware on +executed on. Typically, the private key is protected in hardware on the machine itself. {kiwi} supports secure execution for the IBM secure -linux target on the s390 platform along with the bootloaders -`zipl` and `grub2-s390x-emu` +Linux target on the s390 platform, along with the bootloaders +`zipl` and `grub2-s390x-emu`. .. code:: xml @@ -1290,12 +1290,12 @@ linux target on the s390 platform along with the bootloaders -Except for the `hkd_ca_cert` all other certificates can be specified +Except for the `hkd_ca_cert`, all other certificates can be specified multiple times. hkd_cert: - The file specified in hkd_cert defines the `Host Key Document` - and tightly couples the image to the host matching the document + The file specified in `hkd_cert` defines the `Host Key Document` + and tightly couples the image to the host matching the document. hkd_ca_cert: Required in combination with `hkd_cert`, providing the `Common Authority` @@ -1308,18 +1308,18 @@ hkd_sign_cert: verification of the `Host Key Document`. hkd_revocation_list: - Optional in combination with `hkd_cert`, providing the the - revocation list to check on use of expired certificates in + Optional in combination with `hkd_cert`, providing the + revocation list to check on the use of expired certificates in the chain of trust. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Used to specify custom arguments for the tools called to setup +Used to specify custom arguments for the tools called to set up the bootloader: -* secure boot via `` e.g `shiminstall` -* installation of the bootloader via `` e.g `grub-install` -* configuration of the bootloader via `` e.g `grub-mkconfig` -* setup of bootloader environment variables via `` e.g `grub2-editenv` +* secure boot via ``, e.g., `shiminstall` +* installation of the bootloader via ``, e.g., `grub-install` +* configuration of the bootloader via ``, e.g., `grub-mkconfig` +* setup of bootloader environment variables via ``, e.g., `grub2-editenv` .. code:: xml @@ -1335,32 +1335,32 @@ the bootloader: .. note:: - {kiwi-ng} does not judge on the given parameters and if the provided + {kiwi-ng} does not judge the given parameters, and if the provided data is effectively used depends on the individual bootloader implementation. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Used to describe the container configuration metadata in docker or wsl -image types. For details see: :ref:`building_container_build` and: -:ref:`building_wsl_build` +image types. For details, see: :ref:`building_container_build` and: +:ref:`building_wsl_build`. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Used to describe vagrant configuration metadata in a disk image -that is being used as a vagrant box. For details see: :ref:`setup_vagrant` +that is being used as a vagrant box. For details, see: :ref:`setup_vagrant`. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Used to describe the volumes of the disk area which +Used to describe the volumes of the disk area, which contains the root filesystem. Volumes are either a feature -of the used filesystem or LVM is used for this purpose. -For details see: :ref:`custom_volumes` +of the used filesystem, or LVM is used for this purpose. +For details, see: :ref:`custom_volumes`. .. note:: When both `` and `` are used, `` - are evaluated first and mount points defined in `` cannot + are evaluated first, and mount points defined in `` cannot be redefined as `` volumes. The two types define a complete disk setup, so there cannot be any overlapping volumes or mount points. As a result, whatever is written in `` @@ -1369,33 +1369,33 @@ For details see: :ref:`custom_volumes` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Used to describe the geometry of the disk on the level of the -partition table. For details see: :ref:`custom_partitions` +partition table. For details, see: :ref:`custom_partitions`. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Used to customize the deployment process in an oem disk image. -For details see: :ref:`oem_customize` +Used to customize the deployment process in an OEM disk image. +For details, see: :ref:`oem_customize`. ~~~~~~~~~~~~~~~~~~~~~~~~~ Used to customize the size of the resulting disk image in an -oem image. For details see: :ref:`disk-the-size-element` +OEM image. For details, see: :ref:`disk-the-size-element`. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Used to customize the virtual machine configuration which describes +Used to customize the virtual machine configuration, which describes the components of an emulated hardware. -For details see: :ref:`disk-the-machine-element` +For details, see: :ref:`disk-the-machine-element`. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Used to customize the installation media images created for oem images +Used to customize the installation media images created for OEM images deployment. -For details see: :ref:`installmedia_customize` +For details, see: :ref:`installmedia_customize`. ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Used to specify custom arguments for the initrd tooling e.g. dracut +Used to specify custom arguments for the initrd tooling, e.g., dracut. .. code:: xml @@ -1409,24 +1409,24 @@ Used to specify custom arguments for the initrd tooling e.g. dracut dracut.uefi.true: - As part of the `setup` action, enables creating a UKI EFI binary + As part of the `setup` action, this enables creating a UKI EFI binary. dracut.module.NAME: - As part of the `add` or `omit` action, adds or omits the given - module name. The element can be specified multiple times + As part of the `add` or `omit` action, this adds or omits the given + module name. The element can be specified multiple times. dracut.driver.NAME: - As part of the `add` or `omit` action, adds or omits the given + As part of the `add` or `omit` action, this adds or omits the given kernel driver. The element can be specified multiple times and - accepts kernel driver names without the .ko extension + accepts kernel driver names without the `.ko` extension. .. _sec.registry: ------------ -Setup containers to fetch from a registry assigned to one -of the supported container backends +Set up containers to fetch from a registry assigned to one +of the supported container backends. .. code:: xml @@ -1438,12 +1438,12 @@ of the supported container backends -The optional containers element specifies the location of one ore +The optional containers element specifies the location of one or more containers on a registry `source` server. {kiwi} will take this information and fetch the containers as OCI archives to -the image. On first boot those container archives will be loaded +the image. On first boot, these container archives will be loaded into the local container backend store for the selected -backend and the archive files get deleted. +backend, and the archive files will be deleted. Supported `backend` values are `docker`, `podman`, and `container-snap`. The `backend` attribute is mandatory and specifies @@ -1453,7 +1453,7 @@ attributes: arch="arch" The containers section can be configured to apply only for a certain - architecture. In this case specify the `arch` attribute with a + architecture. In this case, specify the `arch` attribute with a value as it is reported by :command:`uname -m`. profiles="name[,name]" @@ -1463,7 +1463,7 @@ profiles="name[,name]" ----------------------- -Details about the container +Details about the container. .. code:: xml @@ -1471,28 +1471,28 @@ Details about the container -The `name` attributes is mandatory and specifies +The `name` attributes are mandatory and specify the name of the container as it exists in the registry. The `container` element has the following optional attributes: path="some/path" - The path to the container in the registry. If not specified - the value defaults to `/` + The path to the container in the registry. If not specified, + the value defaults to `/`. fetch_only="true|false" - If set to `true` kiwi will only fetch the container but does not - setup the systemd unit for loading the container into - the local registry. In this mode the container archive file stays - in the system and can be handled in a custom way. By default + If set to `true`, kiwi will only fetch the container but will not + set up the systemd unit for loading the container into + the local registry. In this mode, the container archive file stays + in the system and can be handled in a custom way. By default, `fetch_only` is set to `false`. tag="tagname" - Specifies the container tag to fetch. If not set the tag name - defaults to `latest` + Specifies the container tag to fetch. If not set, the tag name + defaults to `latest`. arch="arch" The container section can be configured to apply only for a certain - architecture. In this case specify the `arch` attribute with a + architecture. In this case, specify the `arch` attribute with a value as it is reported by :command:`uname -m`. .. _sec.repository: @@ -1500,7 +1500,7 @@ arch="arch" ------------- -Setup software sources for the image. +Set up software sources for the image. .. code:: xml @@ -1510,20 +1510,20 @@ Setup software sources for the image. The mandatory repository element specifies the location and type of a repository to be used by the package manager as a package installation -source. {kiwi} supports apk, apt, dnf4, dnf5, pacman and zypper as +source. {kiwi} supports apk, apt, dnf4, dnf5, pacman, and zypper as package managers, specified with the packagemanager element. The repository element has the following optional attributes: alias="name" Specifies an alternative name for the configured repository. If the - attribute is not specified {kiwi} will generate a random alias name + attribute is not specified, {kiwi} will generate a random alias name for the repository. The specified name must match the pattern: - `[a-zA-Z0-9_\-\.]+` + `[a-zA-Z0-9_\-\.]+`. components="name" Used for Debian (apt) based repositories only. Specifies the - component name that should be used from the repository. By default - the `main` component is used + component name that should be used from the repository. By default, + the `main` component is used. distribution="name" Used for Debian (apt) based repositories only. Specifies the @@ -1531,13 +1531,13 @@ distribution="name" imageonly="true|false" Specifies whether or not this repository should be configured in - the resulting image without using it at build time. By default - the value is set to false + the resulting image without using it at build time. By default, + the value is set to false. repository_gpgcheck="true|false" Specifies whether or not this specific repository values the result of the repository signature validation. If not set, the default is - `false`. If set the relevant key information needs to be provided + `false`. If set, the relevant key information needs to be provided on the {kiwi} commandline using the `--signing-key` option or via the `` element as part of the `` setting in the image description. @@ -1545,18 +1545,18 @@ repository_gpgcheck="true|false" package_gpgcheck="true|false" Specify whether or not this specific repository values the result of the package signature validation for each package taken from - this repository. If not set, the default value is false. + this repository. If not set, the default value is `false`. If set, the same key information requirements as for the - `repository_gpgcheck` attribute applies. + `repository_gpgcheck` attribute apply. customize="/path/to/custom_script" - Custom script hook which is invoked with the repo file as parameter + A custom script hook that is invoked with the repo file as a parameter for each file created by {kiwi}. .. note:: - If the script is provided as relative path it will - be searched in the image description directory + If the script is provided as a relative path, it will + be searched in the image description directory. imageinclude="true|false" Specifies whether the given repository should be configured as a @@ -1568,23 +1568,23 @@ imageinclude="true|false" .. note:: Scope of repository uri's The repository is configured in the image according to the source - path as specified with the path attribute of the source element. + path as specified with the `path` attribute of the source element. Therefore, if the path is not a fully qualified URL, you may need to adjust the repository file in the image to accommodate the expected location. It is recommended that you use the alias - attribute in combination with the imageinclude attribute to + attribute in combination with the `imageinclude` attribute to avoid having unpredictable random names assigned to the repository you wish to include in the image. password="string" Specifies a password for the given repository. The password attribute must be used in combination with the username attribute. Dependent on - the repository location this information may not be used. + the repository location, this information may not be used. username="name" Specifies a user name for the given repository. The username attribute must be used in combination with the password attribute. - Dependent on the repository location this information may not be + Dependent on the repository location, this information may not be used. prefer-license="true|false" @@ -1592,7 +1592,7 @@ prefer-license="true|false" install the license tarball if found on that repository. If no repository with a preferred license attribute exists, the search happens over all repositories. It's not guaranteed in that case that - the search order follows the repository order like they are written + the search order follows the repository order as they are written into the XML description. priority="number" @@ -1600,23 +1600,23 @@ priority="number" values are treated differently by different package managers. Repository priorities allow the package management system to disambiguate packages that may be contained in more than one of the - configured repositories. The zypper package manager for example + configured repositories. The zypper package manager, for example, prefers packages from a repository with a *lower* priority over packages from a repository with higher priority values. - The value 99 means “no priority is set”. For other package managers + The value 99 means “no priority is set”. For other package managers, please refer to the individual documentation about repository priorities. sourcetype="baseurl|metalink|mirrorlist" - Specifies the source type of the repository path. Depending on if the - source path is a simple url or a pointer to a metadata file or mirror - list, the configured package manager needs to be setup appropriately. - By default the source is expected to be a simple repository baseurl. + Specifies the source type of the repository path. Depending on whether the + source path is a simple URL or a pointer to a metadata file or mirror + list, the configured package manager needs to be set up appropriately. + By default, the source is expected to be a simple repository baseurl. use_for_bootstrap="true|false" Used for Debian (apt) based repositories only. It specifies whether this repository should be the one used for bootstrapping or not. It is set to 'false' by default. Only a single repository is allowed - to be used for bootstrapping, if no repository is set for the bootstrap + to be used for bootstrapping. If no repository is set for the bootstrap, the last one in the description XML is used. @@ -1631,42 +1631,42 @@ mandatory source child element: The location specification may include -the `%arch` macro which will expand to the architecture of the image +the `%arch` macro, which will expand to the architecture of the image building host. The value for the path attribute may begin with any of the following location indicators: * ``file:///local/path/to/file`` - An absolute path to a file accessible through the local file system. + An absolute path to a file accessible through the local filesystem. * ``ftp://`` - A ftp protocol based network location. + A ftp-protocol-based network location. * ``http://`` - A http protocol based network location. + A http-protocol-based network location. * ``https://`` - A https protocol based network location. + A https-protocol-based network location. .. note:: https repositories - When specifying a https location for a repository it is generally + When specifying a https location for a repository, it is generally necessary to include the openssl certificates and a cracklib word dictionary as package entries in the bootstrap section of the image configuration. The names of the packages to include are - individual to the used distribution. On SUSE systems as one example - this would be `openssl-certs` and `cracklib-dict-full` + individual to the used distribution. On SUSE systems, as one example, + this would be `openssl-certs` and `cracklib-dict-full`. * ``obs://Open:Build:Service:Project:Name`` A reference to a project in the Open Build Service (OBS). {kiwi} - translates the given project path into a remote url at which + translates the given project path into a remote URL at which the given project hosts the packages. * ``obsrepositories:/`` A placeholder for the Open Build Service (OBS) to indicate that all repositories are taken from the project configuration in OBS. -A repository `` element can optionally contain one ore more -signing keys for the packages from this repository like shown in the +A repository `` element can optionally contain one or more +signing keys for the packages from this repository, as shown in the following example: .. code:: xml @@ -1687,7 +1687,7 @@ manager. ----------- -Setup software components to be installed in the image. +Set up software components to be installed in the image. .. code:: xml @@ -1695,27 +1695,27 @@ Setup software components to be installed in the image. The mandatory packages element specifies the setup of a packages group for the given type. The value of the type attribute specifies -at which state in the build process the packages group gets handled, -supported values are as follows: +at which state in the build process the packages group is handled. +Supported values are as follows: type="bootstrap" - Bootstrap packages, list of packages to be installed first into + Bootstrap packages, a list of packages to be installed first into a new (empty) root tree. The packages list the required components to support a chroot environment from which further software - components can be installed + components can be installed. type="image" - Image packages, list of packages to be installed as part of a chroot - operation inside of the new root tree. + Image packages, a list of packages to be installed as part of a chroot + operation inside the new root tree. type="uninstall|delete" - Packages to be uninstalled or deleted. For further details - see :ref:`uninstall-system-packages` + Packages to be uninstalled or deleted. For further details, + see :ref:`uninstall-system-packages`. type="*image_type_name*" - Packages to be installed for the given image type name. For example - if set to type="iso", the packages in this group will only be - installed if the iso image type is build. + Packages to be installed for the given image type name. For example, + if set to `type="iso"`, the packages in this group will only be + installed if the ISO image type is built. The packages element must contain at least one child element of the @@ -1743,35 +1743,35 @@ attribute is also available in all of the following elements. -The namedCollection element is used to install a number of packages +The `namedCollection` element is used to install a number of packages grouped together under a name. This is a feature of the individual -distribution and used in the implementation of the {kiwi} package -manager backend. At the moment collections are only supported for -SUSE and Red Hat based distributions. The optional `patternType` attribute +distribution and is used in the implementation of the {kiwi} package +manager backend. At the moment, collections are only supported for +SUSE- and Red Hat-based distributions. The optional `patternType` attribute is used to control the behavior of the dependency resolution of the package collection. `onlyRequired` installs only the collection and its required packages. `plusRecommended` installs the collection, -any of its required packages and any recommended packages. +any of its required packages, and any recommended packages. .. note:: Collections on SUSE - On SUSE based distributions collections are called `patterns` and are + On SUSE-based distributions, collections are called `patterns` and are just simple packages. To get the names of the patterns such that - they can be used in a namedCollection type the following command: + they can be used in a namedCollection type, use the following command: `$ zypper patterns`. If for some reason the collection name cannot - be used it is also possible to add the name of the package that + be used, it is also possible to add the name of the package that provides the collection as part of a `package` element. To get the - names of the pattern packages type the following command: - `$ zypper search patterns`. By convention all packages that starts - with the name "patterns-" are representing a pattern package. + names of the pattern packages, type the following command: + `$ zypper search patterns`. By convention, all packages that start + with the name "patterns-" represent a pattern package. .. note:: Collections on Red Hat - On Red Hat based distributions collections are called `groups` and are - extra metadata. To get the names of these groups type the following + On Red Hat-based distributions, collections are called `groups` and are + extra metadata. To get the names of these groups, type the following command: `$ dnf group list -v`. Please note that since {kiwi} v9.23.39, group IDs are allowed only, e.g.: - + ``. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1784,9 +1784,9 @@ any of its required packages and any recommended packages. In CentOS Stream >= 8 and Red Hat Enterprise Linux >= 8, there are Application Streams that are offered in the form of modules (using Fedora Modularity technology). To build images that use -this content {kiwi} offers to enable/disable modules when using -the `dnf` or `microdnf` package manager backend. Modules are setup -prior the bootstrap phase and its setup persists as part of the +this content, {kiwi} offers to enable/disable modules when using +the `dnf` or `microdnf` package manager backend. Modules are set up +prior to the bootstrap phase, and their setup persists as part of the image. There are the following constraints when adding `collectionModule` @@ -1797,9 +1797,9 @@ elements: modules must be done once and as early as possible in the process of installing the image root tree. -* Disabling a module can only be done as a whole and therefore the +* Disabling a module can only be done as a whole, and therefore, the `stream` attribute is not allowed for disabling modules. For - enabling modules the stream` attribute is optional + enabling modules, the `stream` attribute is optional. * The `enable` attribute is mandatory because it should be an explicit setting if a module is effectively used or not. @@ -1812,15 +1812,15 @@ elements: -The file element takes the `name` attribute and looks up the -given name as file on the system. If specified relative {kiwi} +The `file` element takes the `name` attribute and looks up the +given name as a file on the system. If specified as a relative path, {kiwi} looks up the name in the image description directory. The file is installed using the `rsync` program. The file element has the following optional attributes: owner="user:group" The `owner` attribute can be specified to make the file - belonging to the specified owner and group. The ownership of + belong to the specified owner and group. The ownership of the original file is meaningless in this case. The provided value is passed along to the `chown` program. @@ -1832,7 +1832,7 @@ permissions="perms" target="some/path" The `target` attribute can be used to specify a target path to - install the file to the specified directory and name. Eventually + install the file to the specified directory and name. Eventually, missing parent directories will be created. @@ -1843,12 +1843,12 @@ target="some/path" -The archive element takes the `name` attribute and looks up the -given name as file on the system. If specified relative {kiwi} +The `archive` element takes the `name` attribute and looks up the +given name as a file on the system. If specified as a relative path, {kiwi} looks up the name in the image description directory. The archive -is installed using the `tar` program. Thus the file name is +is installed using the `tar` program. Thus, the file name is expected to be a tar archive. The compression of the archive is -detected automatically by the tar program. The optional target_dir +detected automatically by the tar program. The optional `target_dir` attribute can be used to specify a target directory to unpack the archive inside the image root tree. @@ -1860,11 +1860,11 @@ archive inside the image root tree. -The ignore element instructs the used package manager to ignore the +The `ignore` element instructs the used package manager to ignore the given package name at installation time. Please note whether or not the package can be ignored is up to the package manager. Packages -that are hard required by other packages in the install procedure -cannot be ignored and the package manager will simply ignore the +that are hard-required by other packages in the install procedure +cannot be ignored, and the package manager will simply ignore the request. @@ -1875,17 +1875,17 @@ request. -The product element instructs the used package manager to install -the given product. What installation of a product means is up to -the package manager and also distribution specific. This feature -currently only works on SUSE based distributions +The `product` element instructs the used package manager to install +the given product. What the installation of a product means is up to +the package manager and is also distribution-specific. This feature +currently only works on SUSE-based distributions. .. _sec.users: -------- -Setup image users. +Set up image users. .. code:: xml @@ -1902,17 +1902,17 @@ Setup image users. /> -The optional users element contains the user setup {kiwi} should create +The optional `users` element contains the user setup {kiwi} should create in the system. The optional `arch` attribute can be used to limit the -users setup to the host architecture from which {kiwi} is called. -At least one user child element must be specified as part of the users +user's setup to the host architecture from which {kiwi} is called. +At least one user child element must be specified as part of the `users` element. Multiple user elements may be specified. Each `user` element represents a specific user that is added or modified. The following attributes are mandatory: name="name": - the UNIX username + the UNIX username. password="string" The password for this user account. It can be provided either @@ -1923,52 +1923,52 @@ password="string" $ openssl passwd -1 -salt xyz PASSWORD - It is also possible to specify the password as a non encrypted string - by using the pwdformat attribute and setting it’s value to `plain`. + It is also possible to specify the password as a non-encrypted string + by using the `pwdformat` attribute and setting its value to `plain`. {kiwi} will then encrypt the password prior to the user being added to the system. .. warning:: plain text passwords - We do not recommend plain passwords as they will be readable in - the image configuration in plain text + We do not recommend plain passwords, as they will be readable in + the image configuration in plain text. All specified users and groups will be created if they do not already exist. The defined users will be part of the group(s) specified - with the groups attribute or belong to the default group as configured - in the system. If specified the first entry in the groups list is used + with the `groups` attribute or belong to the default group as configured + in the system. If specified, the first entry in the groups list is used as the login group. Additionally, the following optional attributes can be specified: home="path": - The path to the user's home directory + The path to the user's home directory. groups="group_a,group_b,group_c:id": - A comma separated list of UNIX groups. The first element of the + A comma-separated list of UNIX groups. The first element of the list is used as the user's primary group. The remaining elements are - appended to the user's supplementary groups. When no groups are assigned + appended to the user's supplementary groups. When no groups are assigned, then the system's default primary group will be used. If a group should - be of a specific group id, it can be appended to the name separated by + be of a specific group ID, it can be appended to the name, separated by a colon. .. note:: - Group ID's can only be set for groups that does not yet exist at + Group IDs can only be set for groups that do not yet exist at the time when {kiwi} creates them. A check is made if the desired - group is already present and if it exists the user will become a - member of that group but any given group ID from the {kiwi} - configuration will **not** be taken into account. Usually all + group is already present, and if it exists, the user will become a + member of that group, but any given group ID from the {kiwi} + configuration will **not** be taken into account. Usually, all standard system groups are affected by this behavior because they - are provided by the OS itself. Thus it's by intention not possible + are provided by the OS itself. Thus, it's by intention not possible to overwrite the group ID of an existing group. id="number": - The numeric user id of this account. + The numeric user ID of this account. pwdformat="plain|encrypted": - The format in which `password` is provided. The default if not - specified is `encrypted`. + The format in which `password` is provided. The default, if not + specified, is `encrypted`. .. _sec.profiles: @@ -1987,11 +1987,11 @@ The optional profiles section lets you maintain one image description while allowing for variation of other sections that are included. A separate profile element must be specified for each variation. The profile child element, which has name and description attributes, -specifies an alias name used to mark sections as belonging to a profile, +specifies an alias name used to mark sections as belonging to a profile and a short description explaining what this profile does. -For example to mark a set of packages as belonging to a profile, simply -annotate them with the profiles attribute as shown below: +For example, to mark a set of packages as belonging to a profile, simply +annotate them with the profiles attribute, as shown below: .. code:: xml diff --git a/doc/source/image_types_and_results.rst b/doc/source/image_types_and_results.rst index 0e1d2dbe..3c072a19 100644 --- a/doc/source/image_types_and_results.rst +++ b/doc/source/image_types_and_results.rst @@ -5,116 +5,116 @@ Image Types .. note:: - Before building an image with {kiwi} it's important to understand + Before building an image with {kiwi}, it's important to understand the different image types and their meaning. This document provides - an overview about the supported {kiwi} image types, their results + an overview of the supported {kiwi} image types, their results, and some words about the environment to run the build. ISO Hybrid Live Image - An iso image which can be dumped on a CD/DVD or USB stick - and boots off from this media without interfering with other - system storage components. A useful pocket system for testing - and demo and debugging purposes. For further details refer - to :ref:`hybrid_iso` + An ISO image that can be dumped on a CD/DVD or USB stick + and boots from this media without interfering with other + system storage components. A useful pocket system for testing, + demo, and debugging purposes. For further details, refer + to :ref:`hybrid_iso`. Virtual Disk Image An image representing the system disk, useful for cloud frameworks - like Amazon EC2, Google Compute Engine or Microsoft Azure. - For further details refer to :ref:`simple_disk` + like Amazon EC2, Google Compute Engine, or Microsoft Azure. + For further details, refer to :ref:`simple_disk`. OEM Expandable Disk Image An image representing an expandable system disk. This means after - deployment the system can resize itself to the new disk geometry. - The resize operation is configurable as part of the image description - and an installation image for CD/DVD, USB stick and Network deployment - can be created in addition. For further details refer to: - :ref:`expandable_disk` + deployment, the system can resize itself to the new disk geometry. + The resize operation is configurable as part of the image description, + and an installation image for CD/DVD, USB stick, and network deployment + can be created in addition. For further details, refer to: + :ref:`expandable_disk`. Docker Container Image - An archive image suitable for the docker container engine. + An archive image suitable for the Docker container engine. The image can be loaded via the `docker load` command and works within the scope of the container engine. - For further details refer to: :ref:`building_container_build` + For further details, refer to: :ref:`building_container_build`. WSL Container Image - An archive image suitable for the Windows Subsystem For Linux - container engine. The image can be loaded From a Windows System - that has support for WSL activated. For further details refer - to: :ref:`building_wsl_build` + An archive image suitable for the Windows Subsystem for Linux + container engine. The image can be loaded from a Windows System + that has support for WSL activated. For further details, refer + to: :ref:`building_wsl_build`. -KIS Root File System Image +KIS Root Filesystem Image An optional root filesystem image associated with a kernel and initrd. The use case for this component image type is highly customizable. Many different deployment strategies are possible. - For further details refer to: :ref:`kis` + For further details, refer to: :ref:`kis`. AWS Nitro Enclave - An initrd based image using the `eif` binary format. The image is + An initrd-based image using the `eif` binary format. The image is expected to be used in the AWS Nitro Enclave system or for testing - in QEMU. For further details refer to: :ref:`eif` + in QEMU. For further details, refer to: :ref:`eif`. Image Results ------------- {kiwi} execution results in an appliance image after a successful run of -:ref:`kiwi_system_build` or :ref:`kiwi_system_create` command. +the :ref:`kiwi_system_build` or :ref:`kiwi_system_create` command. The result is the image binary plus some additional metadata files -which are needed for image deployment and/or exists for informative -reasons. By default the output files follow this naming convention: +that are needed for image deployment and/or exist for informative +reasons. By default, the output files follow this naming convention: `.\-\.\` where `` is the name stated in the :ref:`image-description` as an attribute of the :ref:`sec.image` element. The `` is the CPU architecture used for the build, `` is the image version defined in -:ref:`\` element of the image description +the :ref:`` element of the image description, and the `` is dependent on the image type and its definition. Any {kiwi} appliance build results in, at least, the following output files: 1. The image binary, `.\-\.\`: - This is the file containig the actual image binary, depending - on the image type and its definition it can be a virtual disk image + This is the file containing the actual image binary. Depending + on the image type and its definition, it can be a virtual disk image file, an ISO image, a tarball, etc. 2. The `.-.packages` file: This file includes a sorted list of the packages - that are included into the image. In fact this is normalized dump of the - package manager database. It follows the following cvs format where each + that are included in the image. In fact, this is a normalized dump of the + package manager database. It follows the following CSV format, where each line is represented by: `|\|\|\|\|\|\` - The values represented here are mainly based on RPM packages metadata. - Other package managers may not provide all of these values, in such cases - the format is the same and the fields that cannot be provided are set as - `None` value. This list can be used to track changes across multiple + The values represented here are mainly based on RPM packages' metadata. + Other package managers may not provide all of these values. In such cases, + the format is the same, and the fields that cannot be provided are set as + `None`. This list can be used to track changes across multiple builds of the same image description over time by diffing the packages installed. 3. The `.-.verified` file: This file is the output of a verification done by the package manager - against the package data base. More specific it is the output of - the :command:`rpm` verification process or :command:`dpkg` verification + against the package database. More specifically, it is the output of + the `rpm` verification process or `dpkg` verification, depending on the packaging technology selected for the image. - In both cases the output follows the RPM verification syntax. This - provides an overview of all packages status right before any boot of + In both cases, the output follows the RPM verification syntax. This + provides an overview of all package statuses right before any boot of the image. -Depending on the image type, the following output files exists: +Depending on the image type, the following output files exist: image="tbz" - For this image type the result is mainly a root tree packed in a tarball: + For this image type, the result is mainly a root tree packed in a tarball: - **root archive**: :file:`{exc_image_base_name}.x86_64-{exc_image_version}.tar.xz` image="btrfs|ext2|ext3|ext4|squashfs|xfs" The image root tree data is packed into a filesystem image of the given - type, hence the resutl for an `ext4` image would be: + type; hence, the result for an `ext4` image would be: - **filesystem image**: :file:`{exc_image_base_name}.x86_64-{exc_image_version}.ext4` @@ -128,9 +128,9 @@ image="iso" image="oem" An image representing an expandable disk image. {kiwi} can also produce an installation ISO for this disk image by setting `installiso="true"` in - the :ref:`\\`) section or a tarball - including the artifacts for a network deployment by setting `installpxe="true"`. - For further details see :ref:`expandable_disk`. The results for `oem` + the :ref:`\\`) section or a tarball, + including the artifacts for a network deployment, by setting `installpxe="true"`. + For further details, see :ref:`expandable_disk`. The results for `oem` can be: - **disk image**: @@ -141,9 +141,9 @@ image="oem" :file:`{exc_image_base_name}.x86_64-{exc_image_version}.install.tar` The disk image can also be provided in one of the various virtual disk - formats which can be specified in `format` attribute of the + formats, which can be specified in the `format` attribute of the :ref:`\\` section. For further - details see :ref:`simple_disk`. The result for e.g `format="qcow2"` + details, see :ref:`simple_disk`. The result for e.g., `format="qcow2"` would be: - **disk image**: @@ -152,8 +152,8 @@ image="oem" instead of the `.raw` default disk format. image="docker" - An archive image suitable for the docker container engine. The result is - a loadable (:command:`docker load -i `) tarball: + An archive image suitable for the Docker container engine. The result is + a loadable (`docker load -i `) tarball: - **container**: :file:`{exc_image_base_name}.x86_64-{exc_image_version}.docker.tar.xz` @@ -167,15 +167,15 @@ image="oci" :file:`{exc_image_base_name}.x86_64-{exc_image_version}.oci.tar.xz` image="appx" - An archive image suitable for the Windows Subsystem For Linux + An archive image suitable for the Windows Subsystem for Linux container engine. The result is an `appx` binary file: - **container**: :file:`{exc_image_base_name}.x86_64-{exc_image_version}.appx` image="wsl" - An archive image suitable for the Windows Subsystem For Linux - container engine >= v2.4.4. The result is a gzip compressed tar + An archive image suitable for the Windows Subsystem for Linux + container engine >= v2.4.4. The result is a gzip-compressed tar archive with the `.wsl` extension: - **container**: @@ -183,7 +183,7 @@ image="wsl" image="kis" An optional root filesystem image associated with a kernel and initrd. - All three binaries are packed in a tarball, see :ref:`kis` for further + All three binaries are packed in a tarball. See :ref:`kis` for further details about the kis archive: - **kis archive**: @@ -194,7 +194,7 @@ Image Bundle Format The result files as mentioned above are used in the {kiwi} result bundler. The `kiwi-ng result bundle` command can be used to copy or package the -mandatory image files to create a customer release. In this process it's +mandatory image files to create a customer release. In this process, it's possible to apply a specific name pattern suitable for the requirements of the release. A typical result bundle call can look like the following: @@ -204,19 +204,19 @@ of the release. A typical result bundle call can look like the following: --bundle-dir=/path/to/image/release_result \ --id=release_identifier -In this call and depending on the image type the required files as they +In this call, and depending on the image type, the required files as they exist in :file:`/path/to/image/build_result` are copied to -:file:`/path/to/image/release_result/`. The only modification on the file -names is the `--id` information which is appended with a `-` to at the +:file:`/path/to/image/release_result/`. The only modification to the file +names is the `--id` information, which is appended with a `-` at the end of the version substring. If we take -:file:`{exc_image_base_name}.x86_64-{exc_image_version}.iso` as example. +:file:`{exc_image_base_name}.x86_64-{exc_image_version}.iso` as an example. This file would be bundled as -:file:`{exc_image_base_name}.x86_64-{exc_image_version}-release_identifier.iso` +:file:`{exc_image_base_name}.x86_64-{exc_image_version}-release_identifier.iso`. -Depending on the use case and the customer requirements this naming -schema and the default way how the kiwi bundler processes the result files +Depending on the use case and the customer requirements, this naming +schema and the default way the kiwi bundler processes the result files is not appropriate. To allow for a more flexible naming schema when -bundling results, {kiwi} allows to specify a bundle_format per type like +bundling results, {kiwi} allows you to specify a bundle_format per type, like in the following example: .. code:: xml @@ -226,38 +226,38 @@ in the following example: The specified `name_pattern` is used as the base name for the image -files the bundler uses. As part of the `name_pattern` the following -placeholders which gets replaced by their real value can be used: +files the bundler uses. As part of the `name_pattern`, the following +placeholders, which are replaced by their real value, can be used: %N - Turns into the contents of the `name` attribute of the `` section + Turns into the contents of the `name` attribute of the `` section. %P Turns into the profile name used at build time of the image. - If multiple profiles were used to build the image the result - name consists out of the individual profile names concatenated + If multiple profiles were used to build the image, the result + name consists of the individual profile names concatenated by a `_` in the order of their specification in the image - description and/or the commandline. + description and/or the command line. %A Turns into the architecture name at build time of the image. Arch names are taken from Python's `platform.machine` information. %I - Turns into the identifier name given via the `--id` option at - call time of the bundler + Turns into the identifier name given via the `--id` option at the + call time of the bundler. %T - Turns into the contents of the `image` attribute of the `` section + Turns into the contents of the `image` attribute of the `` section. %M - Turns into the major number of the `` section + Turns into the major number of the `` section. %m - Turns into the minor number of the `` section + Turns into the minor number of the `` section. %p - Turns into the patch number of the `` section + Turns into the patch number of the `` section. %v - Turns into the version text of the `` section + Turns into the version text of the `` section. diff --git a/doc/source/index.rst b/doc/source/index.rst index 43cd8ca3..ea646ba5 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -4,7 +4,7 @@ Building Linux System Appliances ================================ .. note:: - This documentation covers {kiwi-product} |version|- the command line + This documentation covers {kiwi-product} |version| - the command-line utility to build Linux system appliances. If you are using a {kiwi} schema version older than v74, upgrade the kiwi file as follows: @@ -60,19 +60,19 @@ Building Linux System Appliances The Appliance Concept --------------------- -An appliance is a ready to use image of an operating system including +An appliance is a ready-to-use image of an operating system, including a pre-configured application for a specific use case. The appliance is -provided as an image file and needs to be deployed to, or activated in +provided as an image file and needs to be deployed to or activated in the target system or service. -{kiwi} can create appliances in various forms: beside classical installation -ISOs and images for virtual machines it can also build images that boot via +{kiwi} can create appliances in various forms: besides classical installation +ISOs and images for virtual machines, it can also build images that boot via PXE or Vagrant boxes. -In {kiwi}, the appliance is specified via a collection of human readable files -in a directory, also called the `image description`. At least one XML file -:file:`config.xml` or :file:`.kiwi` is required. In addition there may as -well be other files like scripts or configuration data. +In {kiwi}, the appliance is specified via a collection of human-readable files +in a directory, also called the `image description`. At least one XML file, +:file:`config.xml` or :file:`.kiwi`, is required. In addition, there may as +well be other files, like scripts or configuration data. Use Cases --------- @@ -89,30 +89,30 @@ Private and Public Clouds Custom Linux Distribution Linux distributors provide their distribution based on a collection - of packages and release them on an install media like a DVD or an USB - stick. Typically a lot more software components exists for the - distribution which are not part of the default installation media + of packages and release them on an install medium like a DVD or a USB + stick. Typically, a lot more software components exist for the + distribution that are not part of the default installation media, or the installation media comes with software and installation - routines that are not matching your target audience. With an - appliance made by {kiwi} you can create an installation - media that matches custom criteria as needed by the customer - and does not require extra post processing steps after the + routines that do not match your target audience. With an + appliance made by {kiwi}, you can create an installation + medium that matches custom criteria as needed by the customer + and does not require extra post-processing steps after the default installation method provided by the distributor. Live Systems The ability to have a Linux OS that runs from a small storage - device like a USB stick or a SD card is the swiss army knife of many - system administrators. The creation of such a live system includes + device like a USB stick or an SD card is the Swiss army knife of many + system administrators. The creation of such a live system includes the use of technologies that are not part of a standard installation process. An appliance builder is needed to create this sort of system. Embedded Systems - Embedded Systems like the Raspberry Pi come with limited hardware + Embedded systems like the Raspberry Pi come with limited hardware components. Their boot sequences often do not allow for classic - installation methods through USB or DVD devices. Instead they boot + installation methods through USB or DVD devices. Instead, they boot through SD card slots or via the network. SoC (System on Chip) devices - also tend to implement non standard boot methods which can only + also tend to implement non-standard boot methods that can only be implemented through custom OS appliances. And More @@ -125,7 +125,7 @@ Contact * `Mailing list `__ - The `kiwi-images` group is an open group and anyone can + The `kiwi-images` group is an open group, and anyone can `subscribe `__, even if you do not have a Google account. diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 0ea87fcc..81fdf673 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -7,9 +7,9 @@ Installation This document describes how to install {kiwi}. -Apart from the preferred method to install {kiwi} via a distribution +Apart from the preferred method of installing {kiwi} via a distribution package manager, it is also available on `pypi `__ -and can be installed using Python's package manager pip as follows: +and can be installed using Python's package manager, pip, as follows: .. code:: shell-session @@ -20,7 +20,7 @@ and can be installed using Python's package manager pip as follows: Installation from OBS --------------------- -The most up to date packages of {kiwi} can be found on the Open Build Service +The most up-to-date packages of {kiwi} can be found on the Open Build Service in the `Virtualization:Appliances:Builder `__ project. @@ -31,9 +31,9 @@ To install {kiwi}, follow these steps: in your browser. 2. Right-click on the link of your preferred operating system and - copy the URL. In Firefox it is the menu :menuselection:`Copy link address`. + copy the URL. In Firefox, it is the menu :menuselection:`Copy link address`. -3. Insert the copied URL from the last step into your shell. The ``DIST`` +3. Insert the copied URL from the last step into your shell. The `DIST` placeholder contains the respective distribution. Use :command:`zypper addrepo` to add it to the list of your repositories: @@ -52,8 +52,8 @@ To install {kiwi}, follow these steps: .. note:: Other Distributions - If your distribution is not using :command:`zypper`, please use your - package manager's appropriate command instead. For :command:`dnf`, + If your distribution is not using `zypper`, please use your + package manager's appropriate command instead. For `dnf`, as an example, that is: .. code:: shell-session @@ -68,19 +68,19 @@ Installation from Distribution Repositories ------------------------------------------- Some Linux distributions ship {kiwi} in their official repositories. These -include **openSUSE** and **Fedora** since version 28. Note, these packages tend to -not be as up to date as the packages from OBS, so some features described +include **openSUSE** and **Fedora** since version 28. Note that these packages tend +not to be as up-to-date as the packages from OBS, so some features described here might not exist yet. .. note:: - There are many packages that contain the name *kiwi* in their name, some - of these are not even python packages. Please double check the packages' - description whether it is actually the {kiwi} Appliance builder before - installing it. Please also note, depending on how the responsible + There are many packages that contain the name *kiwi* in their name; some + of these are not even Python packages. Please double-check the package's + description to see whether it is actually the {kiwi} Appliance builder before + installing it. Please also note that, depending on how the responsible packager has integrated {kiwi} into the distribution, the install name can be different from the instructions provided in: - :ref:`installation-from-obs` + :ref:`installation-from-obs`. To install {kiwi} for the desired distribution, run the following command: @@ -100,7 +100,7 @@ Installation for SUSE Linux Enterprise -------------------------------------- {kiwi} is available and supported for SUSE Linux Enterprise (SLE). -The recommended and supported way is to install {kiwi} by using zypper. +The recommended and supported way is to install {kiwi} by using `zypper`. However, if you rely on some plugins for {kiwi}, either the plugin itself or any dependencies might not be available for your service pack. @@ -108,8 +108,8 @@ itself or any dependencies might not be available for your service pack. If you want to proceed anyway, keep these things in mind: * Plugins that are not provided by SLE are not supported. -* You probably need to install dependencies via :command:`pip`. - The :command:`pip` command installs these dependencies from PyPI +* You will probably need to install dependencies via `pip`. + The `pip` command installs these dependencies from PyPI (the Python Package Index). However, this approach will not update the RPM database. * Depending on your security concerns, installing Python packages @@ -129,8 +129,8 @@ There are two places for example appliance descriptions: The {kiwi} build tests: The {kiwi} project itself hosts a collection of appliance descriptions - which are used for integration testing of the {kiwi} builder itself. - These descriptions are required to build prior any {kiwi} release + that are used for integration testing of the {kiwi} builder itself. + These descriptions are required to build prior to any {kiwi} release and are also used as the base for this documentation. Please check them out when working with this reference guide: @@ -142,8 +142,8 @@ The {kiwi} build tests: The {kiwi} community descriptions project: There is a GitHub project hosting example appliance descriptions to be used - with the next generation {kiwi}. Contributions from the community makes up - the contents of this repository and users who need an example for a specific + with the next-generation {kiwi}. Contributions from the community make up + the contents of this repository, and users who need an example for a specific use case and distribution can clone the project as follows: .. code:: shell-session diff --git a/doc/source/integration_testing.rst b/doc/source/integration_testing.rst index 4799af39..e3e25e13 100644 --- a/doc/source/integration_testing.rst +++ b/doc/source/integration_testing.rst @@ -3,7 +3,7 @@ Building Build Tests {kiwi} provides a collection of integration test images for different architectures and distributions. The test descriptions -covers a number of appliance features that can be build with {kiwi}. +cover a number of appliance features that can be built with {kiwi}. The test descriptions are stored in a directory structure of the following layout: `build-tests/ARCH/DISTRIBUTION/test-image-NAME`. To build integration test image(s), the script `build-tests.sh` @@ -11,19 +11,19 @@ exists. The implementation of `build-tests.sh` calls kiwi's `boxbuild` command in container mode, which allows calling the script on -actually any host system that allows to run container instances +any host system that allows you to run container instances via `podman`. .. warning:: **Architectures** - Cross architecture image building is possible and also supported - via boxbuild, but the performance impact is big even in containers - using qemu-binfmt and even bigger in full qemu arch emulation. - This would slow down building the integration tests a lot and - therefore `build-tests.sh` requires the host architecture to - match with the image target architecture. + Cross-architecture image building is possible and also supported + via boxbuild, but the performance impact is big, even in containers + using qemu-binfmt, and even bigger in full qemu arch emulation. + This would slow down building the integration tests a lot, and + therefore, `build-tests.sh` requires the host architecture to + match the image target architecture. -Prior calling `build-tests.sh` the following requirements must be met: +Prior to calling `build-tests.sh`, the following requirements must be met: ``Tools`` @@ -37,8 +37,8 @@ Prior calling `build-tests.sh` the following requirements must be met: ``Source Checkout`` - Checkout the kiwi git repo which provides the test descriptions - as well as the `build-tests.sh` script + Check out the kiwi git repo, which provides the test descriptions + as well as the `build-tests.sh` script. .. code:: bash @@ -46,8 +46,8 @@ Prior calling `build-tests.sh` the following requirements must be met: ``kiwi-boxed-plugin`` - Fetch the kiwi-boxed-plugin from pip. It provides the boxbuild - command used by build-tests.sh + Fetch the `kiwi-boxed-plugin` from pip. It provides the boxbuild + command used by `build-tests.sh`. .. code:: bash @@ -56,9 +56,9 @@ Prior calling `build-tests.sh` the following requirements must be met: .. warning:: Make sure to be able to execute `kiwi-ng`. In case there was no {kiwi} - installed on your host you will get notified by the kiwi-boxed-plugin + installed on your host, you will be notified by the kiwi-boxed-plugin installation to update your path to `export PATH:~/.local/bin/kiwi-ng:$PATH`. - If in doubt about all this just install kiwi from pip too. + If in doubt about all this, just install kiwi from pip too. `pip install --upgrade kiwi` Building a specific integration test can be done as follows: @@ -83,5 +83,5 @@ can be done as follows: Building all integration tests can take some time and depends on the number of tests provided as well as on the build power - of the host system. In general the tests can also run in - parallel or distributed to multiple hosts + of the host system. In general, the tests can also run in + parallel or be distributed to multiple hosts. diff --git a/doc/source/overview.rst b/doc/source/overview.rst index 3218c4af..eb4d17a5 100644 --- a/doc/source/overview.rst +++ b/doc/source/overview.rst @@ -5,7 +5,7 @@ Overview .. note:: **Abstract** - This document provides a conceptual overview about the steps + This document provides a conceptual overview of the steps of creating an image with {kiwi}. It also explains the terminology regarding the concept and process when building system images with {kiwi} |version|. @@ -18,11 +18,11 @@ Overview Conceptual Overview ------------------- -A system image (usually called "image"), is a *complete installation* of a Linux -system within a file. The image represents an operation system and, +A system image (usually called an "image") is a *complete installation* of a Linux +system within a file. The image represents an operating system and, optionally, contains the "final" configuration. -{kiwi} creates images in a two step process: +{kiwi} creates images in a two-step process: 1. The first step, the *prepare operation*, generates a so-called *unpacked image tree* (directory) using the information provided in @@ -41,48 +41,48 @@ Terminology ----------- Appliance - An appliance is a ready to use image of an operating system + An appliance is a ready-to-use image of an operating system, including a pre-configured application for a specific use case. The appliance is provided as an image file and needs to be - deployed to, or activated in the target system or service. + deployed to or activated in the target system or service. Image The result of a {kiwi} build process. Image Description - Specification to define an appliance. The image description is a - collection of human readable files in a directory. At least one XML - file :file:`config.xml` or :file:`.kiwi` is required. In addition - there may be other files like scripts or configuration data. - These can be used to customize certain parts either of the {kiwi} - build process or of the initial start-up behavior of the image. + A specification to define an appliance. The image description is a + collection of human-readable files in a directory. At least one XML + file, :file:`config.xml` or :file:`.kiwi`, is required. In addition, + there may be other files, like scripts or configuration data. + These can be used to customize certain parts of either the {kiwi} + build process or the initial startup behavior of the image. Overlay Files A directory structure with files and subdirectories stored as part of the Image Description. This directory structure is packaged as - a file :file:`root.tar.gz` or stored inside a directory named + a file, :file:`root.tar.gz`, or stored inside a directory named :file:`root`. Additional overlay directories for selected profiles - are supported too and are taken into account if the directory + are also supported and are taken into account if the directory name matches the name of the profile. The content of each of the - directory structures is copied on top of the existing file - system (overlayed) of the appliance root. This also includes + directory structures is copied on top of the existing filesystem + (overlayed) of the appliance root. This also includes permissions and attributes as a supplement. {kiwi} An OS appliance builder. Virtualization Technology - Software simulated computer hardware. A virtual machine acts like - a real computer, but is separated from the physical hardware. - Within this documentation the QEMU virtualization system is - used. Another popular alternative is Virtualbox. + Software-simulated computer hardware. A virtual machine acts like + a real computer but is separated from the physical hardware. + Within this documentation, the QEMU virtualization system is + used. Another popular alternative is VirtualBox. System Requirements ------------------- To use and run {kiwi}, you need: -* A recent Linux distribution, see :ref:`supported-distributions` for +* A recent Linux distribution; see :ref:`supported-distributions` for details. * Enough free disk space to build and store the image. We recommend a diff --git a/doc/source/overview/workflow.rst b/doc/source/overview/workflow.rst index 86a3a02f..64ff460a 100644 --- a/doc/source/overview/workflow.rst +++ b/doc/source/overview/workflow.rst @@ -3,7 +3,7 @@ Basic Workflow .. note:: **Abstract** - Installation of a Linux system generally occurs by booting the target + The installation of a Linux system generally occurs by booting the target system from an installation source such as an installation CD/DVD, a live CD/DVD, or a network boot environment (PXE). The installation process is often driven by an installer that interacts with the user to collect @@ -11,24 +11,24 @@ Basic Workflow *software to be installed*, the *timezone*, system *user* data, and other information. Once all the information is collected, the installer installs the software onto the target system using packages from the - software sources (repositories) available. After the installation is - complete the system usually reboots and enters a configuration procedure - upon start-up. The configuration may be fully automatic or it may include + available software sources (repositories). After the installation is + complete, the system usually reboots and enters a configuration procedure + upon startup. The configuration may be fully automatic, or it may include user interaction. This description applies for version |version|. -A system image (usually called "image"), is a *complete installation* of a Linux +A system image (usually called an "image") is a *complete installation* of a Linux system within a file. The image represents an operational system and, optionally, contains the "final" configuration. The behavior of the image upon deployment varies depending on the image type and the image configuration since {kiwi} allows you to completely customize -the initial start-up behavior of the image. Among others, this includes +the initial startup behavior of the image. Among others, this includes images that: * can be deployed inside an existing virtual environment without requiring - configuration at start-up. + configuration at startup. * automatically configure themselves in a known target environment. * prompt the user for an interactive system configuration. @@ -41,12 +41,12 @@ This file is validated against the schema documented in: In addition, the image can optionally be customized using the :file:`config.sh` and :file:`images.sh` scripts and by using an *overlay tree (directory)* called :file:`root`. -See :ref:`description_components` section for further details. +See the :ref:`description_components` section for further details. .. note:: Previous Knowledge This documentation assumes that you are familiar with the general - concepts of Linux, including the boot process, and distribution concepts + concepts of Linux, including the boot process and distribution concepts such as package management. .. _description_components: @@ -57,24 +57,24 @@ Components of an Image Description A {kiwi} image description can be composed of several parts. The main part is the {kiwi} description file itself (named :file:`config.xml` or an arbitrary name plus the :file:`*.kiwi` extension). The configuration XML is the -only required component, others are optional. +only required component; others are optional. These are the optional components of an image description: #. ``config.sh`` shell script - Is the configuration shell script that runs at the end of the + This is the configuration shell script that runs at the end of the :ref:`prepare step ` if present. It can be used to - fine tune the unpacked image. + fine-tune the unpacked image. Note that the script is directly invoked by the operating system if its - executable bit is set. Otherwise it is called by :file:`bash` instead. + executable bit is set. Otherwise, it is called by :file:`bash` instead. #. ``images.sh`` shell script - Is the configuration shell script that runs at the beginning of the - create step. So it is expected to be used to handle image type specific - tasks. It is called in a similar fashion as ``config.sh`` + This is the configuration shell script that runs at the beginning of the + create step. So, it is expected to be used to handle image-type-specific + tasks. It is called in a similar fashion as `config.sh`. #. Overlay tree directory @@ -87,11 +87,11 @@ These are the optional components of an image description: #. CD root user data - For live ISO images and install ISO images an optional cdroot archive + For live ISO images and install ISO images, an optional cdroot archive is supported. This is a tar archive matching the name - :file:`config-cdroot.tar[.compression_postfix]`. If present it will + :file:`config-cdroot.tar[.compression_postfix]`. If present, it will be unpacked as user data on the ISO image. This is mostly useful to - add e.g license files or user documentation on the CD/DVD which + add, e.g., license files or user documentation on the CD/DVD, which can be read directly without booting from the media. #. Archives included in the :file:`config.xml` file. diff --git a/doc/source/plugins.rst b/doc/source/plugins.rst index c62f86d4..262c50d5 100644 --- a/doc/source/plugins.rst +++ b/doc/source/plugins.rst @@ -4,7 +4,7 @@ KIWI Plugins .. note:: This document provides a list of the existing {kiwi-product} plugins - which provides extended functionality for version |version|. + that provides extended functionality for version |version|. .. toctree:: :maxdepth: 1 diff --git a/doc/source/plugins/self_contained.rst b/doc/source/plugins/self_contained.rst index be9b3801..c35b5c0e 100644 --- a/doc/source/plugins/self_contained.rst +++ b/doc/source/plugins/self_contained.rst @@ -8,32 +8,32 @@ Building in a Self-Contained Environment Users building images with {kiwi} face problems if they want to build an image matching one of the following criteria: - * build should happen as non root user. + * The build should happen as a non-root user. - * build should happen on a host system distribution for which - no {kiwi} packages exists. + * The build should happen on a host system distribution for which + no {kiwi} packages exist. - * build happens on an incompatible host system distribution - compared to the target image distribution. For example - building an apt/dpkg based system on an rpm based system. + * The build happens on an incompatible host system distribution + compared to the target image distribution. For example, + building an apt/dpkg-based system on an rpm-based system. - * run more than one build process at the same time on the + * Run more than one build process at the same time on the same host. - * run a build process for a different target architecture - compared to the host architecture (Cross Arch Image Build) + * Run a build process for a different target architecture + compared to the host architecture (Cross-Arch Image Build). This document describes how to perform the build process in - a self contained environment using fast booting virtual + a self-contained environment using fast-booting virtual machines to address the issues listed above. The changes on the machine to become a build host will - be reduced to the requirements of the {kiwi} `boxed plugin` + be reduced to the requirements of the {kiwi} `boxed plugin`. Requirements ------------ -Add the {kiwi} repo from the Open Build Service. For details see +Add the {kiwi} repo from the Open Build Service. For details, see :ref:`installation-from-obs`. The following {kiwi} plugin needs to be installed on the build system: @@ -45,24 +45,24 @@ Building with the boxbuild command ---------------------------------- The installation of the {kiwi} boxed plugin has registered a new kiwi -command named `boxbuild`. The command implementation uses KVM as -virtualization technology and runs the {kiwi} `build` command inside of -a KVM controlled virtual machine. For running the build process in a -virtual machine it's required to provide VM images that are suitable -to perform this job. We call the VM images `boxes` and they contain +command named `boxbuild`. The command implementation uses KVM as a +virtualization technology and runs the {kiwi} `build` command inside +a KVM-controlled virtual machine. For running the build process in a +virtual machine, it's required to provide VM images that are suitable +to perform this job. We call the VM images `boxes`, and they contain kiwi itself as well as all other components needed to build appliances. Those boxes are hosted in the Open Build Service and are publicly available at the `Subprojects` tab in the: `Virtualization:Appliances:SelfContained `__ project. -As a user you don't need to work with the boxes because this is all done +As a user, you don't need to work with the boxes because this is all done by the plugin and provided as a service by the {kiwi} team. The `boxbuild` command knows where to fetch the box and also cares for an update of the box when it has changed. Building an image with the `boxbuild` command is similar to building with the `build` command. The plugin validates the given command call with the -capabilities of the `build` command. Thus one part of the `boxbuild` command +capabilities of the `build` command. Thus, one part of the `boxbuild` command is exactly the same as with the `build` command. The separation between `boxbuild` and `build` options is done using the `--` separator. The following example shows how to build an example from the `kiwi-descriptions` repo: @@ -78,31 +78,31 @@ example shows how to build an example from the `kiwi-descriptions` repo: .. note:: The provided `--description` and `--target-dir` options are - setup as shared folders between the host and the box. No other + set up as shared folders between the host and the box. No other data will be shared with the host. Sharing Backends ---------------- As mentioned above, the `boxbuild` call shares the two host directories -provided in `--description` and `--target-dir` with the box. To do this +provided in `--description` and `--target-dir` with the box. To do this, the following sharing backends are supported: ``--9p-sharing`` - With QEMU's `9pfs` you can create virtual filesystem devices - (virtio-9p-device) and expose them to the box. For more information + With QEMU's `9pfs`, you can create virtual filesystem devices + (virtio-9p-device) and expose them to the box. For more information, see `9pfs `__. Using this sharing backend does not require any setup procedure from the - user and is also the default for `boxbuild` + user and is also the default for `boxbuild`. ``--sshfs-sharing`` SSHFS is a FUSE-based filesystem client for mounting remote - directories over a Secure Shell connection (SSH). In `boxbuild` + directories over a Secure Shell connection (SSH). In `boxbuild`, this is used to mount directories from the host into the box. - Because this runs through an SSH connection the host must allow - connections from the box. If you plan to use `sshfs` add the + Because this runs through an SSH connection, the host must allow + connections from the box. If you plan to use `sshfs`, add the following SSH public key to the :file:`~/.ssh/authorized_keys` - file of the user which is expected to call `boxbuild` + file of the user who is expected to call `boxbuild`: .. code:: bash @@ -115,30 +115,30 @@ the following sharing backends are supported: If the `sshfs` backend is used without the host trusting the box, the `boxbuild` call will become interactive at the time of the sshfs - mount. In this case the user might be asked for a passphrase or - depending on the host `sshd` setup the request will be declined and - the boxbuild fails. + mount. In this case, the user might be asked for a passphrase, or + depending on the host's `sshd` setup, the request will be declined and + the boxbuild will fail. ``--virtiofs-sharing`` - QEMU virtio-fs shared file system daemon. Share a host directory tree - with a box through a virtio-fs device. For more information + QEMU virtio-fs shared filesystem daemon. Share a host directory tree + with a box through a virtio-fs device. For more information, see `virtiofs `__. Using this sharing backend does not require any setup procedure from the - user + user. .. warning:: - virtiofs support was added but considered experimental and - not yet stable across the distributions. Feedback welcome. + virtiofs support was added but is considered experimental and + not yet stable across the distributions. Feedback is welcome. Building in Container --------------------- -By default and also as preferred method, boxbuild runs in a KVM +By default, and also as the preferred method, boxbuild runs in a KVM virtual machine. However, support for building in container -instances via `podman` is also implemented. The boxes built as +instances via `podman` is also implemented. The boxes are built as virtual machine images and also as OCI containers hosted on the -openSUSE registry. In container mode boxbuild pulls +openSUSE registry. In container mode, boxbuild pulls the requested box from the remote registry to the local registry and starts a container instance. The following example shows how to build the mentioned {kiwi} integration test image in a @@ -153,28 +153,28 @@ container: .. note:: The provided `--description` and `--target-dir` options are - setup as shared volumes between the host and the box container. - In addition containers also shares the kiwi cache from + set up as shared volumes between the host and the box container. + In addition, containers also share the kiwi cache from `/var/cache/kiwi` with the host for better performance. .. warning:: - For building in a container several runtime constraints - exists and the isolation model is not as strict as it is + For building in a container, several runtime constraints + exist, and the isolation model is not as strict as it is when building in a VM. Please read the following information to get clarity on the existing constraints. ``loop devices`` As kiwi requires loop devices and calls other operations - which requires root privileges, `podman` is started through `sudo`. + that require root privileges, `podman` is started through `sudo`. As podman runs daemonless, the calling user must have the - privileges to perform the needed kiwi actions. Non + privileges to perform the needed kiwi actions. Non- privileged builds are therefore not possible in container mode with kiwi. ``linux capabilities`` - Several linux capabilities as they can be found in - https://man7.org/linux/man-pages/man7/capabilities.7.html are + Several Linux capabilities, as they can be found in + https://man7.org/linux/man-pages/man7/capabilities.7.html, are set when `boxbuild` starts the container: * AUDIT_WRITE @@ -185,8 +185,8 @@ container: ``host device nodes`` The host device nodes from `/dev` are shared with the container instance. This is required to work with loop devices - inside of the container. Device isolation is therefore + inside the container. Device isolation is therefore not possible in container mode with kiwi. The loop device - handling for container based builds, restricts the number of + handling for container-based builds restricts the number of simultaneous kiwi build processes on this host to the number of available loop device nodes exposed from the host kernel. diff --git a/doc/source/plugins/stackbuild.rst b/doc/source/plugins/stackbuild.rst index 18f9d500..4f3c6cd7 100644 --- a/doc/source/plugins/stackbuild.rst +++ b/doc/source/plugins/stackbuild.rst @@ -5,8 +5,8 @@ Building based on Containers .. note:: **Abstract** - When building images exposes one of the following - requirements the stackbuild plugin provides an opportunity + When building images, one of the following + requirements of the stackbuild plugin provides an opportunity to address it: * Preserve the image rootfs for a later rebuild without @@ -16,12 +16,12 @@ Building based on Containers * Build an image based on a container stack. - * Transform a container into a {kiwi} image type + * Transform a container into a {kiwi} image type. Installation ------------ -Add the {kiwi} repo from the Open Build Service. For details see +Add the {kiwi} repo from the Open Build Service. For details, see :ref:`installation-from-obs`. The following {kiwi} plugin needs to be installed on the build system: @@ -32,29 +32,29 @@ installed on the build system: Concept ------- -The design of the stackbuild plugin is two fold: +The design of the stackbuild plugin is twofold: -First the plugin comes with a command called `stash` which allows -to store a kiwi built root tree as an OCI container. OCI stands for -*Open Container Interface* and is a defacto standard format in the -container world. Once the container got created it can be managed +First, the plugin comes with a command called `stash` that allows +you to store a kiwi-built root tree as an OCI container. OCI stands for +*Open Container Interface* and is a de facto standard format in the +container world. Once the container has been created, it can be managed using the preferred container toolchain. The plugin code itself uses `podman` to work with containers. -As a next step and with the root tree as a container the plugin offers -the opportunity to build images based on one ore more containers. -That's also the reason why the plugin is called *stackbuild* as it +As a next step, and with the root tree as a container, the plugin offers +the opportunity to build images based on one or more containers. +That's also the reason why the plugin is called *stackbuild*, as it allows you to stack different root containers together. -Consequently the other command provided is named `stackbuild`. +Consequently, the other command provided is named `stackbuild`. The `stash` and `stackbuild` commands can be used independently from each other. If there is already a registry with containers that should be used to build images from, `stackbuild` can directly consume them. -This concept leads to a number of use cases and a few of them were +This concept leads to a number of use cases, and a few of them were picked and put into the abstract of this article. For the purpose -of documenting the functionality of the plugin only a part of the +of documenting the functionality of the plugin, only a part of the possibilities are taken into account as follows: .. _stash: @@ -62,9 +62,9 @@ possibilities are taken into account as follows: Create a stash -------------- -The `stash` command creates an OCI compliant container from a given +The `stash` command creates an OCI-compliant container from a given {kiwi-product} image root tree and registers it in the local -container registry. From there a user can push it to any registry +container registry. From there, a user can push it to any registry of choice. The following example creates a stash of a Tumbleweed build @@ -91,16 +91,16 @@ registry: docker://docker.io/.../twmos-snapshot:2021-10-08 If the `stash` command is called multiple times with the same -container-name this leads to a new layer in the container for +container name, this leads to a new layer in the container for each call. To inspect the number of layers added to the -container the following command can be used: +container, the following command can be used: .. code:: bash $ podman inspect twmos-snapshot -To list all stashes created by the `stash` command the following -command can be used +To list all stashes created by the `stash` command, the following +command can be used: .. code:: bash @@ -112,21 +112,21 @@ Rebuild from a stash The `stackbuild` command takes the given container(s) from the local or remote registry and uses it/them to either rebuild an image from that data or build a new image on top of that data. If multiple containers -are given the `stackbuild` command stacks them together in the order -as they were provided. +are given, the `stackbuild` command stacks them together in the order +in which they were provided. .. note:: - When using multiple containers the result stack root tree is + When using multiple containers, the result stack root tree is created from a sequence of rsync commands into the same target directory. The stackbuild plugin does this with any container - content given and does not check, validate or guarantee that - the selection of containers are actually stackable or leads to - an usable root tree. This means it's in the responsibility of - the caller to make sure the provided containers can actually + content given and does not check, validate, or guarantee that + the selection of containers is actually stackable or leads to a + usable root tree. This means it's the caller's responsibility + to make sure the provided containers can actually be stacked together in the given order. -To simply rebuild the image from the stash created in :ref:`stash` +To simply rebuild the image from the stash created in :ref:`stash`, call `stackbuild` as follows: .. code:: bash @@ -151,16 +151,16 @@ of container images into another image type that is supported by {kiwi}. The following example demonstrates how an existing container image from the openSUSE registry can be turned into a virtual machine image. -When moving a container into a virtual machine image the following -aspects has to be taken into account: +When moving a container into a virtual machine image, the following +aspects have to be taken into account: 1. A container image usually has no kernel installed. 2. A container image usually has no bootloader installed. 3. A container image usually has no user configured. -For a VM image the mentioned aspects are mandatory. Therefore +For a VM image, the mentioned aspects are mandatory. Therefore, the following {kiwi} image description contains this additional -information which the container cannot provide: Create the +information that the container cannot provide: Create the {kiwi} description as follows: .. code:: bash diff --git a/doc/source/quickstart.rst b/doc/source/quickstart.rst index 33ebad63..ca5ef790 100644 --- a/doc/source/quickstart.rst +++ b/doc/source/quickstart.rst @@ -6,7 +6,7 @@ Quick Start .. note:: **Abstract** This document describes how to start working with {kiwi}, - an OS appliance builder. This description applies for + an OS appliance builder. This description applies to version |version|. Before you start @@ -28,7 +28,7 @@ Before you start .. note:: - In case the following procedure causes any trouble + If the following procedure causes any trouble please take a look at the :ref:`troubleshooting` chapter and/or reach out at: :ref:`contact` @@ -42,14 +42,14 @@ as follows: $ tree -L 3 kiwi/build-tests -Take a look which images are available in the example appliances repository -and select one that matches your desired image as close as possible. Or +Take a look at which images are available in the example appliances repository +and select one that matches your desired image as closely as possible. Or just use the one given in the examples below. Build your First Image ---------------------- -Your first image will be a simple system disk image which can run +Your first image will be a simple system disk image that can run in any full virtualization system like QEMU. Invoke the following {kiwi} command in order to build it: @@ -70,8 +70,8 @@ folder that contains the image description which you selected. Run your Image -------------- -Running an image actually means booting the operating system. In order to -do that attach the disk image to a virtual system. In this example we use +Running an image actually means booting the operating system. To +do that, attach the disk image to a virtual system. In this example, we use QEMU and boot it as follows: .. code:: bash diff --git a/doc/source/troubleshooting.rst b/doc/source/troubleshooting.rst index 543f1d48..558218f2 100644 --- a/doc/source/troubleshooting.rst +++ b/doc/source/troubleshooting.rst @@ -5,10 +5,10 @@ Troubleshooting .. note:: **Abstract** - This document describes situations which leads to issues - during build or boot time of the image build with {kiwi}. + This document describes situations that lead to issues + during build or boot time of the image built with {kiwi}. The suggested solutions are considered best practice but - are just one out of other possible solution candidates. + are just one of many possible solutions. .. toctree:: :maxdepth: 1 diff --git a/doc/source/troubleshooting/architectures.rst b/doc/source/troubleshooting/architectures.rst index 10324971..4839e716 100644 --- a/doc/source/troubleshooting/architectures.rst +++ b/doc/source/troubleshooting/architectures.rst @@ -1,24 +1,24 @@ Architectures ------------- -With regards to the information in :ref:`supported-distributions` -one requirement between the build host and the image when it comes to -architecture support is, that the image architecture should match the -build host architecture. Cross arch building would require any core -tool that is used to build an image to be cross arch capable. +With regards to the information in :ref:`supported-distributions`, +one requirement between the build host and the image, when it comes to +architecture support, is that the image architecture should match the +build host architecture. Cross-arch building would require any core +tool that is used to build an image to be cross-arch capable. -To patch e.g an x86_64 system such that it can build an +To patch, e.g., an x86_64 system such that it can build an aarch64 image would require some work on binutils and hacks as well as -performance tweaks which is all not worth the effort and still can lead -to broken results. Thus we recommend to provide native systems for the -target architecture and build there. One possible alternative is to -use the kiwi boxed plugin as mentioned above together with a box -created for the desired architecture. However keep in mind the +performance tweaks, which is all not worth the effort and can still lead +to broken results. Thus, we recommend providing native systems for the +target architecture and building there. One possible alternative is to +use the kiwi boxed plugin, as mentioned above, together with a box +created for the desired architecture. However, keep in mind the performance problematic when running a VM of a different architecture. The majority of the image builds are based on the x86 architecture. -As mentioned {kiwi} also supports other architectures, shown in the +As mentioned, {kiwi} also supports other architectures, as shown in the table below: .. table:: @@ -42,4 +42,4 @@ table below: The support status for an architecture depends on the distribution. If the distribution does not build its packages for the desired - architecture, {kiwi} will not be able to build an image for it + architecture, {kiwi} will not be able to build an image for it. diff --git a/doc/source/troubleshooting/boxbuild_tweaks.rst b/doc/source/troubleshooting/boxbuild_tweaks.rst index 8003f684..f689c29f 100644 --- a/doc/source/troubleshooting/boxbuild_tweaks.rst +++ b/doc/source/troubleshooting/boxbuild_tweaks.rst @@ -4,13 +4,13 @@ Boxbuild Tweaks .. note:: Abstract This document describes a few ways to modify - box build VMs for testing/debugging. + box-build VMs for testing and debugging. Increase Box Build Image Size ----------------------------- In particularly large builds, you may find that the -upstream build boxes aren't quite large enough, and +upstream build boxes are not quite large enough and fail to build during the final few steps. While it is a bit of a kludge, it is possible to increase the size of the build box. @@ -18,10 +18,10 @@ size of the build box. To do so, follow these steps: .. note:: For this example, we will assume the box increase - question is an Ubuntu box, located in ~/.kiwi_boxes/ubuntu + in question is an Ubuntu box, located in `~/.kiwi_boxes/ubuntu`. 1. While the VM is offline, locate the VM you want to modify - and resize with `qemu-img`. Here we will increase the size + and resize with `qemu-img`. Here, we will increase the size by 20G. The VM will have to be told to utilize this space in the following steps. @@ -29,7 +29,7 @@ To do so, follow these steps: $ qemu-img resize Ubuntu-Box.x86_64-1.22.04-System-BuildBox.qcow2 +20G -2. When relaunching your `kiwi-ng` box build, make sure you use `--no-snapshot` +2. When relaunching your `kiwi-ng` box build, make sure you use the `--no-snapshot` and `--box-debug` options within your build command/script. Example: .. code:: bash @@ -39,14 +39,14 @@ To do so, follow these steps: --description ./ubuntu-jammy --target-dir /build/kiwi/outputs/ 3. When the build fails and drops you into the VM console, you will - need to extend the partition of the VM rootfs, then resize with - `resize2fs`. In this example, `parted` was used and the partition - in question was /dev/vda3. + need to extend the partition of the VM's rootfs, then resize it with + `resize2fs`. In this example, `parted` was used, and the partition + in question was `/dev/vda3`. .. code:: bash $ parted - # Can run parted print to check for relevant partitions if needed. + # You can run parted print to check for relevant partitions if needed. (parted) $ print (parted) $ resizepart 3 100% # Exit from parted @@ -55,10 +55,10 @@ To do so, follow these steps: $ resize2fs /dev/vda3 4. From this point, depending on where your build failed, it may be - possible to continue your build from inside the box, using the + possible to continue your build from inside the box using the existing 9p mount points defined by your build command. Using the - command above as an example, `/result` within the box maps up to - `/build/kiwi/outputs` on the host, and it's possible to run + command above as an example, `/result` within the box maps to + `/build/kiwi/outputs` on the host, and it's possible to run: .. code:: bash @@ -66,6 +66,5 @@ To do so, follow these steps: --root=/result/build/image-root/ --target-dir=/result 5. If the rebuild from within was successful, you can copy the files - from `/result` to `/bundle`, from within the VM, where `/bundle` + from `/result` to `/bundle` from within the VM, where `/bundle` maps to your `target-dir` on the host. - diff --git a/doc/source/troubleshooting/buildhost_constraints.rst b/doc/source/troubleshooting/buildhost_constraints.rst index 1b32898d..45081e9e 100644 --- a/doc/source/troubleshooting/buildhost_constraints.rst +++ b/doc/source/troubleshooting/buildhost_constraints.rst @@ -3,58 +3,59 @@ Build Host Constraints ====================== -For building images a host system is required that runs the build process. -Tools to create the image are used from that host and this creates an -indirect dependency to the target image. For example; Building an +For building images, a host system is required that runs the build process. +Tools to create the image are used from that host, and this creates an +indirect dependency on the target image. For example, building an Ubuntu image requires the apt and dpkg tools and metadata to be available and functional on the host to build an Ubuntu image. There are many more -of those host vs. image dependencies and not all of them can be resolved +of those host vs. image dependencies, and not all of them can be resolved in a clear and clean way. The most compatible environment is provided if the build host is of the same -distribution than the target image. In other cases our recommendation is that -the build host is of the same distribution than the target and near to the +distribution as the target image. In other cases, our recommendation is that +the build host is of the same distribution as the target and near to the major version (+-1) compared to the target. Such an environment can be found in: * The Open Build Service `OBS `__. * The {kiwi} boxed plugin: :ref:`self_contained` -In general, our goal is to support any major distribution with {kiwi}. However -for building images we rely on core tools which are not under our control. -Also several design aspects of distributions like **secure boot** and working +In general, our goal is to support any major distribution with {kiwi}. However, +for building images, we rely on core tools that are not under our control. +Also, several design aspects of distributions like **secure boot** and working with **upstream projects** are different and not influenced by us. There -are many side effects that can be annoying especially if the build host -is not of the same distribution vendor than the image target. +are many side effects that can be annoying, especially if the build host +is not of the same distribution vendor as the image target. Package Manager Behavior ------------------------ One of the key requirements for {kiwi} is that the target distribution -consists out of a collection of software packages provided through -software repositories. As of today this applies to every Linux +consists of a collection of software packages provided through +software repositories. As of today, this applies to every Linux distribution in some shape or form. For the installation of this -software packages there are tools available called `package manager` +software packages, there are tools available called `package manager`, and {kiwi} implements an API for a variety of package managers to support the different Linux distributions. -In {kiwi} the package manager tools are called in a way that allows -for a non interactive installation of the packages specified in the -image description. However, {kiwi} does intentionally not configure +In {kiwi}, the package manager tools are called in a way that allows +for a non-interactive installation of the packages specified in the +image description. However, {kiwi} does not intentionally configure other features of the package manager to keep their distribution default behavior as much as possible. There are many options that can be set for a package manager to behave differently. This part of the troubleshooting exists to inform about the most common surprises or unexpected behavior of certain package managers and -solutions how to address them. +solutions on how to address them. .. note:: All of the following information applies to package manager - calls performed inside of the image root tree. Meaning `after` - the image bootstrap phase. During the image bootstrap phase - all package manager calls happens on the build host and their + calls performed inside of the image root tree. Meaning, `after` + the image bootstrap phase. During the image bootstrap phase, + all package manager calls happen on the build host, and their behavior can only be influenced by changing the setup of the + build host. An isolated build environment is required to address issues in this area. See :ref:`self_contained` for details. @@ -66,17 +67,17 @@ hardware was found by the kernel on this system. The package manager can use this information to match package(s) that holds a reference to the alias name and installs it automatically. For example: Automatically install a driver package if the -respective hardware is present. In zypper this behavior is by -default enabled. When building an image this feature can be +respective hardware is present. In zypper, this behavior is by +default enabled. When building an image, this feature can be unwanted and lead to interesting side effects. As it's required to build the image on some host, there is also some hardware -available during build. This must not necessarily be the same +available during the build. This must not necessarily be the same or compatible hardware the image is expected to run on later. -For example: The buildhost has a nvidia graphics card. An -image build process would install the nvidia driver package due +For example, the build host has a NVIDIA graphics card. An +image build process would install the NVIDIA driver package due to the modalias match. The image is expected to run on a system -without a nvidia card. The build process would install unneeded -software. To switch off modalias matching in zypper follow +without an NVIDIA card. The build process would install unneeded +software. To switch off modalias matching in zypper, follow these steps: 1. Add a `post_bootstrap.sh` hook script to your image description @@ -86,18 +87,19 @@ these steps: echo 'ZYPP_MODALIAS_SYSFS=""' > .kiwi.package_manager.env -2. Optionally add a `config.sh` hook script to your image description +2. Optionally, add a `config.sh` hook script to your image description with the following code: .. code:: bash rm .kiwi.package_manager.env - This will delete the custom environment file such that it does - not appear in the final image + This will delete the custom environment file so that it does + not appear in the final image. 3. Rebuild your image. The `.kiwi.package_manager.env` environment file is used by kiwi and added to the execution environment of the package manager. The `ZYPP_MODALIAS_SYSFS` variable can be used to switch off the modalias matching. For more - details on zypper setting please refer to: https://doc.opensuse.org/projects/libzypp/HEAD/zypp-envars.html + details on zypper settings, please refer to: https://doc.opensuse.org/projects/libzypp/HEAD/zypp-envars.html + diff --git a/doc/source/troubleshooting/filesystems.rst b/doc/source/troubleshooting/filesystems.rst index 59805ff2..3dbbb4f3 100644 --- a/doc/source/troubleshooting/filesystems.rst +++ b/doc/source/troubleshooting/filesystems.rst @@ -3,26 +3,26 @@ Incompatible Filesystem Settings on Host vs. Image .. note:: **Abstract** - This page provides further information how to solve - image boot problems if the filesystem tool chain on + This page provides further information on how to solve + image boot problems if the filesystem toolchain on the image build host is incompatible with the - image target distribution + image's target distribution. -When {kiwi} builds an image which requests the creation of a +When {kiwi} builds an image that requests the creation of a filesystem, the required filesystem creation tool, for -example `mkfs.xfs`, is called from the host on which {kiwi} -gets called. It is expected that the generated filesystem -is compatible with the image target distribution. This +example, `mkfs.xfs`, is called from the host on which {kiwi} +is running. It is expected that the generated filesystem +is compatible with the image's target distribution. This expectation is not always correct and depends on the compatibility of the filesystem default settings between build host and image target. We know about the following -settings that causes an incompatible filesystem which +settings that cause an incompatible filesystem, which will not be able to be used on boot: Ext[2,3,4] Check `/etc/mke2fs.conf` on the build host and make sure the configured `inode_size` is the same as the setting used - for the target image. To solve an issue of this type use + for the target image. To solve an issue of this type, use the following filesystem creation option in your {kiwi} image configuration: @@ -33,12 +33,12 @@ Ext[2,3,4] XFS Check the XFS metadata setup on the build host and make sure the settings are compatible with the target image. XFS has the - default settings compiled in, thus it might be needed to build + default settings compiled-in, thus it might be needed to build the image first and use the `xfs_info` tool in a `disk.sh` script - to fetch the settings at build time of the image. We know from + to fetch the settings at the build time of the image. We know from community reports that the setting `sparse=1` will cause issues on older versions of grub's xfs module, which does not know how - to handle this setting properly. To solve an issue of this type + to handle this setting properly. To solve an issue of this type, use the following filesystem creation option in your {kiwi} image configuration: @@ -47,15 +47,15 @@ XFS btrfs - btrfs and default page sizes (4k vs 64k). By default btrfs - autodetects the sectorsize according to the used kernel page - size. If the sectorsize differs from the page size, the - created filesystem can not be mounted by the image target + btrfs and default page sizes (4k vs 64k). By default, btrfs + autodetects the sector size according to the used kernel page + size. If the sector size differs from the page size, the + created filesystem cannot be mounted by the image's target kernel. If there is a different kernel page size between the - kernel on the system the image is build on and the later + kernel on the system the image is built on and the later kernel used for the image, it's required to specify the filesystem sector size to match with the kernel page size - of the kernel used for the image. This can be done like in + of the kernel used for the image. This can be done as in the following example: .. code:: xml @@ -65,9 +65,9 @@ btrfs .. note:: There can be more inconsistencies in the area of filesystems - which we haven't listed here. In general it's advisable to - build the image in a compatible environment. At best the + that we have not listed here. In general, it's advisable to + build the image in a compatible environment. At best, the build host distribution is of the same major Linux version - than the image target. For this purpose {kiwi} provides the - so called `boxed-plugin`. Further details can be found + as the image target. For this purpose, {kiwi} provides the + so-called `boxed-plugin`. Further details can be found in :ref:`self_contained` diff --git a/doc/source/troubleshooting/security.rst b/doc/source/troubleshooting/security.rst index 3f576aae..d0859378 100644 --- a/doc/source/troubleshooting/security.rst +++ b/doc/source/troubleshooting/security.rst @@ -3,46 +3,46 @@ Host Security Settings Conflicts with KIWI .. note:: **Abstract** - This page provides further information how to solve + This page provides further information on how to solve image build problems caused by `selinux` security policies. Linux systems are protected against write/read or other -operations depending on the application which wants to +operations depending on the application that wants to access or modify data. The rules for this protection are provided in security policies. There are several applications enforcing these security settings, e.g `apparmor` or `selinux`. -In this troubleshooting chapter the focus is set on `selinux` +In this troubleshooting chapter, the focus is on `selinux`. Protecting files, process groups, kernel filesystems, device -nodes and more from unauthorized access and restrict it to +nodes and more from unauthorized access and restricting it to a certain set of applications is a nice concept. However, if -taken serious no other application except the ones configured +taken seriously, no other application except the ones configured in the security policy will function properly. When building an appliance, the appliance builder has to have access to a wide range of services. It must be able to create a new package database elsewhere in the system. It must be able to create, read and write device nodes, create filesystems, -partitions, bootloader configurations etc etc. The list is very +partitions, bootloader configurations, etc. The list is very long and no security policy could cover this in a way that it -would not be open to everything which in the end leads to a +would not be open to everything, which in the end leads to a pointless exercise and no security at all. This means for users who would like to keep the security settings of the system enforced and unchanged, the only way to allow {kiwi} to do its job is to run it through `boxbuild` as explained in -:ref:`self_contained` +:ref:`self_contained`. For users who can afford to open the system security policy, -the following procedure will make {kiwi} to work: +the following procedure will allow {kiwi} to work: .. code:: bash sudo setenforce 0 -This action disables selinux temporary. To disable selinux -permanently perform the following steps: +This action disables selinux temporarily. To disable selinux +permanently, perform the following steps: 1. Open the SELinux configuration file: :file:`/etc/selinux/config` 2. Locate the following line: `SELINUX=enforcing` @@ -56,8 +56,8 @@ permanently perform the following steps: .. note:: - similar instructions applies to other application security + Similar instructions apply to other application security subsystems like `apparmor`. Due to the complexity of these - systems this article just mentions the most common issue + systems, this article only mentions the most common issue people run into when building images on systems protected - through `selinux`. + by `selinux`. diff --git a/doc/source/working_with_images.rst b/doc/source/working_with_images.rst index 25668b31..5a09b169 100644 --- a/doc/source/working_with_images.rst +++ b/doc/source/working_with_images.rst @@ -3,7 +3,7 @@ Working with Images .. note:: - This document provides a collection of worksheets which + This document provides a collection of worksheets that describes the creation and setup of appliances to work within a number of different target environments. diff --git a/doc/source/working_with_images/build_in_buildservice.rst b/doc/source/working_with_images/build_in_buildservice.rst index 990465ae..f55530ac 100644 --- a/doc/source/working_with_images/build_in_buildservice.rst +++ b/doc/source/working_with_images/build_in_buildservice.rst @@ -3,20 +3,20 @@ Building in the Open Build Service .. note:: **Abstract** - This document gives a brief overview how to build images with + This document gives a brief overview of how to build images with {kiwi} in version |version| inside of the Open Build Service. - A tutorial on the Open Buildservice itself can be found here: + A tutorial on the Open Build Service itself can be found here: https://en.opensuse.org/openSUSE:Build_Service_Tutorial -The next generation {kiwi} is fully integrated with the Open Build Service. -In order to start it's best to checkout one of the integration test +The next-generation {kiwi} is fully integrated with the Open Build Service. +To start, it's best to check out one of the integration test image build projects from the base Testing project `Virtualization:Appliances:Images:Testing_$ARCH:$DISTRO` at: https://build.opensuse.org -For example the test images for SUSE on x86 can be found `here +For example, the test images for SUSE on x86 can be found `here `__. @@ -26,24 +26,24 @@ Advantages of using the Open Build Service (OBS) The Open Build Service offers multiple advantages over running {kiwi} locally: -* OBS will host the latest successful build for you without having to setup +* OBS will host the latest successful build for you without you having to set up a server yourself. * As {kiwi} is fully integrated into OBS, OBS will automatically rebuild your - images if one of the included packages or one of its dependencies or {kiwi} - itself get updated. + images if one of the included packages, one of its dependencies, or {kiwi} + itself is updated. -* The builds will no longer have to be executed on your own machine, but +* The builds will no longer have to be executed on your own machine but will run on OBS, thereby saving you resources. Nevertheless, if a build - fails, you get a notification via email (if enabled in your user's + fails, you will get a notification via email (if enabled in your user's preferences). Differences Between Building Locally and on OBS ----------------------------------------------- -Note, there is a number of differences when building images with {kiwi} using -the Open Build Service. Your image that build locally just fine, might not +Note that there are a number of differences when building images with {kiwi} using +the Open Build Service. Your image that built locally just fine might not build without modifications. The notable differences to running {kiwi} locally include: @@ -51,14 +51,14 @@ The notable differences to running {kiwi} locally include: * OBS will pick the {kiwi} package from the repositories configured in your project, which will most likely not be the same version that you are running locally. - This is especially relevant when building images for older versions like + This is especially relevant when building images for older versions, like SUSE Linux Enterprise. Therefore, include the custom appliances repository as described in the following section: :ref:`obs-recommended-settings`. * When {kiwi} runs on OBS, OBS will extract the list of packages from :file:`config.xml` and use it to create a build root. In contrast to a - local build (where your distributions package manager will resolve the + local build (where your distribution's package manager will resolve the dependencies and install the packages), OBS will **not** build your image if there are multiple packages that could be chosen to satisfy the dependencies of your packages [#f1]_. This shows errors like this: @@ -81,7 +81,7 @@ The notable differences to running {kiwi} locally include: .. warning:: We strongly encourage you to remove your repositories from :file:`config.xml` and move them to the repository configuration in your project's settings. This usually prevents the issue of having the - choice for multiple package version and results in a much smoother + choice for multiple package versions and results in a much smoother experience when using OBS. * By default, OBS builds only a single build type and the default @@ -91,7 +91,7 @@ The notable differences to running {kiwi} locally include: There are two options to build multiple profiles on OBS: - 1. Use the `` element and add it bellow the XML + 1. Use the `` element and add it below the XML declaration (``): .. code:: xml @@ -106,10 +106,10 @@ The notable differences to running {kiwi} locally include: 2. Use the `multibuild `_ feature. - The first option is simpler to use, but has the disadvantage that your - appliances are built sequentially. The `multibuild` feature allows to + The first option is simpler to use but has the disadvantage that your + appliances are built sequentially. The `multibuild` feature allows you to build each profile as a single package, thereby enabling parallel execution, - but requires an additional :file:`_multibuild` file. For the above example + but it requires an additional :file:`_multibuild` file. For the above example, :file:`config.xml` would have to be adapted as follows: .. code:: xml @@ -133,11 +133,11 @@ The notable differences to running {kiwi} locally include: * Subfolders in OBS projects are ignored by default by :command:`osc` and - must be explicitly added via :command:`osc add $FOLDER` [#f2]_. Bear that + must be explicitly added via `osc add $FOLDER` [#f2]_. Bear that in mind when adding the overlay files inside the :file:`root/` directory to your project. -* OBS ignores file permissions. Therefore :file:`config.sh` and +* OBS ignores file permissions. Therefore, :file:`config.sh` and :file:`images.sh` will **always** be executed through BASH (see also: :ref:`working-with-kiwi-user-defined-scripts`). @@ -150,8 +150,8 @@ Working with OBS ^^^^^^^^^^^^^^^^ Although OBS is an online service, it is not necessary to test every change -by uploading it. OBS will use the same process as ``osc build`` does, so if -your image builds locally via ``osc build`` it should also build online on +by uploading it. OBS will use the same process as `osc build` does, so if +your image builds locally via `osc build`, it should also build online on OBS. @@ -161,8 +161,8 @@ Repository Configuration When setting up the project, enable the `images` repository: the `images` repository's checkbox can be found at the bottom of the selection screen that appears when clicking `Add from a Distribution` in the `Repositories` -tab. Or specify it manually in the project configuration (it can be -accessed via ``osc meta -e prj``): +tab. Or, specify it manually in the project configuration (it can be +accessed via `osc meta -e prj`): .. code:: xml @@ -186,9 +186,9 @@ your dependent packages. These repositories can be provided in two ways: This instructs OBS to inject the repositories from your project into your appliance. - Additional repositories can be added by invoking ``osc meta -e prj`` and - adding a line of the following form as a child of ````: + Additional repositories can be added by invoking `osc meta -e prj` and + adding a line of the following form as a child of ``: .. code:: xml @@ -233,15 +233,15 @@ your dependent packages. These repositories can be provided in two ways: - Now `Virtualization:Appliances:Builder` is the last repository, which' + Now, `Virtualization:Appliances:Builder` is the last repository whose repositories are included into the search path. As `openSUSE:Factory/snapshot` is among these, it can be omitted from the repository list. #. Keep the repositories in your :file:`config.xml` configuration file. If you have installed the latest stable {kiwi} as described in - :ref:`kiwi-installation` then you should add the following repository to - your projects configuration (accessible via :command:`osc meta -e + :ref:`kiwi-installation`, then you should add the following repository to + your project's configuration (accessible via :command:`osc meta -e prjconf`), so that OBS will pick the latest stable {kiwi} version too: .. code:: xml @@ -251,26 +251,26 @@ your dependent packages. These repositories can be provided in two ways: x86_64 - Replace ``$DISTRO`` with the appropriate name for the distribution that + Replace `$DISTRO` with the appropriate name for the distribution that you are currently building and optionally adjust the architecture. -We recommend to use the first method, as it integrates better into +We recommend using the first method, as it integrates better into OBS. Note that your image description will then no longer build outside of -OBS though. If building locally is required, use the second method. +OBS, though. If building locally is required, use the second method. .. warning:: - Adding the repositories to project's configuration makes it impossible + Adding the repositories to the project's configuration makes it impossible to build images for different distributions from the same project. Since the repositories are added for every package in your project, all your image builds will share the same repositories, thereby resulting in conflicts for different distributions. - We recommend to create a separate project for each distribution. If that + We recommend creating a separate project for each distribution. If that is impossible, you can keep all your repositories (including - `Virtualization:Appliances:Builder`) in :file:`config.xml`. That however + `Virtualization:Appliances:Builder`) in :file:`config.xml`. That, however, usually requires a large number of workarounds via `Prefer:` settings in the project configuration and is thus **not** recommended. @@ -278,8 +278,8 @@ OBS though. If building locally is required, use the second method. Project Configuration ^^^^^^^^^^^^^^^^^^^^^ -The Open Build Service will by default create the same output file as {kiwi} -when run locally, but with a custom filename ending (that is unfortunately +The Open Build Service will, by default, create the same output file as {kiwi} +when run locally but with a custom filename ending (that is, unfortunately, unpredictable). This has the consequence that the download URL of your image will change with every rebuild (and thus break automated scripts). OBS can create symbolic links with static names to the latest @@ -289,40 +289,40 @@ build by adding the following line to the project configuration: Repotype: staticlinks -If build Vagrant images (see :ref:`setup_vagrant`) add the repository-type +If you build Vagrant images (see :ref:`setup_vagrant`), add the repository-type `vagrant`. OBS creates a `boxes/` subdirectory in your download repositories, which contains JSON files for Vagrant [#f4]_. -If you have added your repositories to :file:`config.xml`, you probably see +If you have added your repositories to :file:`config.xml`, you will probably see errors of the following type: .. code:: bash unresolvable: have choice for SOMEPACKAGE: SOMEPAKAGE_1 SOMEPACKAGE_2 -Instead of starting from scratch and manually adding ``Prefer:`` statements -to the project configuration, we recommend to copy the current project +Instead of starting from scratch and manually adding `Prefer:` statements +to the project configuration, we recommend copying the current project configuration of the testing project `Virtualization:Appliances:Images:Testing_$ARCH:$DISTRO` into your own project. It provides a good starting point and can be adapted to your OBS project. -.. [#f1] This is a design decision made by OBS: as it's purpose is to build - packages in a reproducible fashion it cannot make a decision which - package to choose from multiple available ones. A package manager build - for end-users on the other hand **must** make an a choice, as it would +.. [#f1] This is a design decision made by OBS: as its purpose is to build + packages in a reproducible fashion, it cannot make a decision which + package to choose from multiple available ones. A package manager built + for end users, on the other hand, **must** make a choice, as it would be otherwise hardly usable. -.. [#f2] :file:`osc` compresses added folders into a `cpio +.. [#f2] `osc` compresses added folders into a `cpio `_ archive and decompresses it - before running your builds. The only downside of this is, that the - contents of your overlay is not conveniently visible via the web + before running your builds. The only downside of this is that the + contents of your overlay are not conveniently visible via the web interface. .. [#f3] Taken from the project `Virtualization:Appliances:Images:openSUSE-Tumbleweed - `_ + `_. .. [#f4] Vagrant uses these JSON files for automatic updates of your Vagrant boxes. diff --git a/doc/source/working_with_images/build_with_profiles.rst b/doc/source/working_with_images/build_with_profiles.rst index 5ee7bbbb..7e7655fb 100644 --- a/doc/source/working_with_images/build_with_profiles.rst +++ b/doc/source/working_with_images/build_with_profiles.rst @@ -28,7 +28,7 @@ Consult the manual page of :file:`kiwi` for further details: Building with the Open Build Service ------------------------------------ -The Open Build Service (OBS) support profiles via the `multibuild +The Open Build Service (OBS) supports profiles via the `multibuild `_ feature. @@ -65,10 +65,10 @@ To enable and use the profiles, follow these steps: you want OBS to build. -Note, by default, OBS excludes the build **without** any profile +Note that, by default, OBS excludes the build **without** any profile enabled. -Running a build of a multibuild enabled repository via :file:`osc` can be +Running a build of a multibuild-enabled repository via :file:`osc` can be achieved via the `-M $PROFILE` flag: .. code:: shell-session diff --git a/doc/source/working_with_images/build_without_debianbootstrap.rst b/doc/source/working_with_images/build_without_debianbootstrap.rst index 8cdb2a3b..a17c6bf2 100644 --- a/doc/source/working_with_images/build_without_debianbootstrap.rst +++ b/doc/source/working_with_images/build_without_debianbootstrap.rst @@ -5,23 +5,23 @@ Circumvent Debian Bootstrap .. sidebar:: Abstract - This page provides information how to build Debian based + This page provides information on how to build Debian-based images without an extra bootstrap process. -When building Debian based images {kiwi} uses `apt` in the +When building Debian-based images, {kiwi} uses `apt` in the bootstrap and the system phase to create the image root tree. However, `apt` does not support a native way to bootstrap -an empty root tree. Therefore the bootstrap phase uses +an empty root tree. Therefore, the bootstrap phase uses apt only to resolve the given bootstrap packages and to download these packages from the given repositories. The list of packages is then manually extracted into the -new root tree which is not exactly the same as if `apt` +new root tree, which is not exactly the same as if `apt` would have installed them natively. For the purpose of creating an initial tree to begin with, this procedure -is acceptable though. +is acceptable, though. -If, for some reasons, this bootstrap procedure is not -applicable, {kiwi} allows for an alternative process which is +If, for some reason, this bootstrap procedure is not +applicable, {kiwi} allows for an alternative process that is based on a prebuilt bootstrap-root archive provided as a package. To make use of a `bootstrap_package`, the name of that package @@ -34,36 +34,36 @@ needs to be referenced in the {kiwi} description as follows: -The boostrap process now changes in a way that the provided -bootstrap_package `bootstrap-root` will be installed on the build -host machine. Next {kiwi} searches for a tar archive file +The bootstrap process now changes in a way that the provided +`bootstrap_package`, `bootstrap-root`, will be installed on the build +host machine. Next, {kiwi} searches for a tar archive file, :file:`/var/lib/bootstrap/bootstrap-root.ARCH.tar.xz`, -where `ARCH` is the name of the host architecture e.g `x86_64`. -If found the archive gets unpacked and serves as the bootstrap +where `ARCH` is the name of the host architecture, e.g., `x86_64`. +If found, the archive is unpacked and serves as the bootstrap root tree to begin with. The optionally provided additional -bootstrap packages, `a` and `b` in this example will be installed -like system packages via `chroot` and `apt`. Usually no additional -bootstrap packages are needed as they could all be handled as +bootstrap packages, `a` and `b` in this example, will be installed +like system packages via `chroot` and `apt`. Usually, no additional +bootstrap packages are needed, as they could all be handled as system packages. How to Create a bootstrap_package --------------------------------- Changing the setup in {kiwi} to use a `bootstrap_package` rather -then using {kiwi}'s debian bootstrap method to do the job, comes with -the task to create that package providing the bootstrap root tree. There -are more than one way to do this. The following procedure is just one +than using {kiwi}'s Debian bootstrap method to do the job comes with +the task of creating that package, providing the bootstrap root tree. There +is more than one way to do this. The following procedure is just one example and requires some background knowledge about the Open Build Service -`OBS `__ and its {kiwi} integration. +(`OBS `__) and its {kiwi} integration. -1. Create an OBS project and repository setup that matches your image target -2. Create an image build package +1. Create an OBS project and repository setup that matches your image target. +2. Create an image build package. .. code:: bash osc mkpac bootstrap-root -3. Create the following :file:`appliance.kiwi` file +3. Create the following :file:`appliance.kiwi` file: .. code:: xml @@ -114,10 +114,10 @@ example and requires some background knowledge about the Open Build Service osc add appliance.kiwi osc ci -4. Package the image build results into a debian package +4. Package the image build results into a Debian package. - In step 3. the bootstrap root tarball was created but not yet - packaged. A debian package is needed such that it can be + In step 3, the bootstrap root tarball was created but not yet + packaged. A Debian package is needed so that it can be referenced with the `bootstrap_package` attribute and the repository providing it. The simplest way to package the `bootstrap-root` tarball is to create another package in OBS and use the tarball file as diff --git a/doc/source/working_with_images/clone_partitions.rst b/doc/source/working_with_images/clone_partitions.rst index 8feeebb0..85270a24 100644 --- a/doc/source/working_with_images/clone_partitions.rst +++ b/doc/source/working_with_images/clone_partitions.rst @@ -6,23 +6,23 @@ Partition Clones .. sidebar:: Abstract This page provides details about the partition clone feature - and its use cases + and its use cases. -{kiwi} allows to create block level clones of certain partitions -used in the image. Clones can be created from the `root`, `boot` +{kiwi} allows you to create block-level clones of certain partitions +used in the image. Clones can be created from the `root`, `boot`, and any other partition listed in the `` element. A partition clone is a simple byte dump from one block storage device to another. However, this would cause conflicts -during boot of the system because all unique identifiers like -the UUID of a filesystem will no longer be unique. The clone +during boot of the system because all unique identifiers, like +the UUID of a filesystem, will no longer be unique. The clone feature of {kiwi} takes care of this part and re-creates the relevant unique identifiers per cloned partition. {kiwi} allows -this also for complex partitions like LVM, LUKS or RAID. +this also for complex partitions like LVM, LUKS, or RAID. The partition clone(s) will always appear first in the partition table, followed by the origin partition. The origin partition is the one -whose identifier will be referenced and used by the system. By default +whose identifier will be referenced and used by the system. By default, no cloned partition will be mounted or used by the system at boot time. Let's take a look at the following example: @@ -40,7 +40,7 @@ Let's take a look at the following example: 100 -With the above setup {kiwi} will create a disk image that +With the above setup, {kiwi} will create a disk image that contains the following partition table: .. code:: @@ -56,64 +56,64 @@ contains the following partition table: 8 1337344 3864575 2 GiB 8300 p.lxrootclone1 9 3864576 6287326 2 GiB 8300 p.lxroot -When booting the system only the origin partitions `p.lxboot`, `p.lxroot` -and `p.lxhome` will be mounted and visible in e.g. :file:`/etc/fstab`, -the bootloader or the initrd. Thus partition clones are present as a data +When booting the system, only the origin partitions `p.lxboot`, `p.lxroot`, +and `p.lxhome` will be mounted and visible in, e.g., :file:`/etc/fstab`, +the bootloader, or the initrd. Thus, partition clones are present as a data source but are not relevant for the operating system from a functional perspective. -As shown in the above example there is one clone request for root and boot -and a two clone requests for the home partition. {kiwi} does not sanity- -check the provided number of clones (e.g. whether your partition table +As shown in the above example, there is one clone request for root and boot +and two clone requests for the home partition. {kiwi} does not sanity- +check the provided number of clones (e.g., whether your partition table can hold that many partitions). .. warning:: - There is a limit how many partitions a partition table can hold. + There is a limit to how many partitions a partition table can hold. This also limits how many clones can be created. It's important when using the `root_clone` attribute to specify a size for -the part of the system that represents the root partition. As of today {kiwi} +the part of the system that represents the root partition. As of today, {kiwi} does not automatically divide the root partition into two identical pieces. -In order to create a clone of the partition a size specification is required. -In the above example the size for root is provided via the `oem-systemsize` +To create a clone of the partition, a size specification is required. +In the above example, the size for root is provided via the `oem-systemsize` element. Using a root clone and fixed size values has the following consequences: -1. The resize capability must be disabled. This is done via `oem-resize` +1. The resize capability must be disabled. This is done via the `oem-resize` element. The reason is that only the last partition in the partition table can be resized without destroying data. If there is a clone of - the root partition it should never be resized because then the two - partitions will be different in size and no longer clones of each other + the root partition, it should never be resized because then the two + partitions will be different in size and no longer be clones of each other. -2. There can be unpartitioned space left. In the above example the overall +2. There can be unpartitioned space left. In the above example, the overall disk size is set to 100G. The sum of all partition sizes will be smaller - than this value and there is no resize available anymore. Depending - on the overall size setup for the disk this will leave unpartitioned + than this value, and there is no resize available anymore. Depending + on the overall size setup for the disk, this will leave unpartitioned space free on the disk. Use Case -------- Potential use cases for which a clone of one or more partitions -is useful include among others: +is useful include, among others: Factory Resets: - Creating an image with the option to rollback to the + Creating an image with the option to roll back to the state of the system at deployment time can be very helpful - for disaster recovery + for disaster recovery. System Updates with Rollbacks e.g A/B: - Creating an image which holds extra space allowing to rollback - modified data can make a system more robust. For example - in a simple A/B update concept, partition A would get updated + Creating an image that holds extra space allowing to roll back + modified data can make a system more robust. For example, + in a simple A/B update concept, partition A would be updated but would flip to B if A is considered broken after applying the update. .. note:: - Most probably any use case based on partition clones requires + Most probably, any use case based on partition clones requires additional software to manage them. {kiwi} provides the - option to create the clone layout but it does not provide + option to create the clone layout, but it does not provide the software to implement the actual use case for which the partition clones are needed. @@ -128,7 +128,7 @@ table. For partition clones, the following naming convention applies: kiwi_(name)PartClone(id)="(partition_number)" The `(name)` is either taken from the `name` attribute -of the `` element or it is a fixed name assigned by {kiwi}. +of the `` element, or it is a fixed name assigned by {kiwi}. There are the following reserved partition names for which cloning is supported: @@ -136,7 +136,7 @@ is supported: * readonly * boot -For the mentioned example this will result in the +For the mentioned example, this will result in the following :file:`/config.partids`: .. code:: diff --git a/doc/source/working_with_images/custom_partitions.rst b/doc/source/working_with_images/custom_partitions.rst index cf4a4abb..f7b9a5d6 100644 --- a/doc/source/working_with_images/custom_partitions.rst +++ b/doc/source/working_with_images/custom_partitions.rst @@ -6,22 +6,22 @@ Custom Disk Partitions .. sidebar:: Abstract This page provides details about the opportunities and limitations - to customize the partition table in addition to the volume management + of customizing the partition table in addition to the volume management settings from :ref:`custom_volumes`. -{kiwi} has its own partitioning schema which is defined according to several +{kiwi} has its own partitioning schema, which is defined according to several different user configurations: boot firmware, boot partition, expandable layouts, etc. Those supported features have an impact on the partitioning schema. -MBR or GUID partition tables are not flexible, carry limitations and are -tied to some specific disk geometry. Because of that the preferred alternative +MBR or GUID partition tables are not flexible, have limitations, and are +tied to some specific disk geometry. Because of that, the preferred alternative to disk layouts based on traditional partition tables is using flexible -approaches like logic volumes. +approaches like logical volumes. -However, on certain conditions additional entries to the low level -partition table are needed. For this purpose the `` section -exists and allows to add custom entries like shown in the following +However, under certain conditions, additional entries to the low-level +partition table are needed. For this purpose, the `` section +exists and allows you to add custom entries, as shown in the following example: .. code:: xml @@ -31,38 +31,38 @@ example: Each `` entry puts a partition of the configured size in the -low level partition table, creates a filesystem on it and includes -it to the system's fstab file. If parts of the root filesystem are -moved into its own partition like it's the case in the above example, +low-level partition table, creates a filesystem on it, and includes +it in the system's fstab file. If parts of the root filesystem are +moved into their own partition, as in the above example, this partition will also contain the data that gets installed during the image creation process to that area. -The following attributes must/can be set to configured a partition entry: +The following attributes must/can be set to configure a partition entry: name="identifier" Mandatory name of the partition as handled by {kiwi}. .. note:: - There are the following reserved names which cannot be used + The following reserved names cannot be used because they are already represented by existing attributes: - `root`, `readonly`, `boot`, `prep`, `spare`, `swap`, `efi_csm` + `root`, `readonly`, `boot`, `prep`, `spare`, `swap`, `efi_csm`, and `efi`. partition_name="name" Optional name of the partition as it appears when listing the - table contents with tools like `gdisk`. If no name is set - {kiwi} constructs a name of the form `p.lx(identifier_from_name_attr)` + table contents with tools like `gdisk`. If no name is set, + {kiwi} constructs a name of the form `p.lx(identifier_from_name_attr)`. partition_type="type_identifier" Optional partition type identifier as handled by {kiwi}. - Allowed values are `t.linux` and `t.raid`. If not specified + Allowed values are `t.linux` and `t.raid`. If not specified, `t.linux` is the default. size="size_string" Mandatory size of the partition. A size string can end with `M` or - `G` to indicate a mega-Byte or giga-Byte value. Without a unit - specification mega-Byte is used. + `G` to indicate a megabyte or gigabyte value. Without a unit + specification, megabyte is used. mountpoint="path" Optional mountpoint to mount the partition in the system. @@ -73,51 +73,52 @@ filesystem="btrfs|ext2|ext3|ext4|squashfs|xfs label="string" Optional filesystem label if a filesystem is provided. If no - label is specified the `name` identifier is set as filesystem - label + label is specified, the `name` identifier is set as the filesystem + label. clone="number" Optional setting to indicate that this partition should be - cloned `number` of times. A clone partition is content wise an - exact byte for byte copy of the origin. However, to avoid conflicts at boot - time the UUID of any cloned partition will be made unique. In the - sequence of partitions, the clone(s) will always be created first + cloned `number` of times. A clone partition is content-wise an + exact byte-for-byte copy of the origin. However, to avoid conflicts at boot + time, the UUID of any cloned partition will be made unique. In the + sequence of partitions, the clone(s) will always be created first, followed by the partition considered the origin. The origin partition is the one that will be referenced and used by the - system + system. part_id="number" Specify the partition number for this partition. This is the number used for the partition in the partition table. The value impacts the - name of the unix device node associated with the partition. This means - if the disk name is e.g. `/dev/sda` and `part_id="42"` is set the - unix node for this partition will be `/dev/sda42`. Please note that + name of the Unix device node associated with the partition. This means + if the disk name is, e.g., `/dev/sda` and `part_id="42"` is set, the + Unix node for this partition will be `/dev/sda42`. Please note that the number has no impact on the geometry or order of partitions as - they get created. The partitions in the `` section still - gets created in the order as they are listed. Please also note if - custom partition ids are used it is strongly recommended that they - are used across all partitions created by kiwi. The reason for this - is that kiwi uses an incremental counter which by default matches - with the number of the partition in the table. If custom partition - id's are not used for all partitions this results in a mix of - numbers, which works but is not obviously visible by reading the - image description. Because of that also see the information about - the `` attributes `eficsmpart_id`, `efipart_id`, - `rootpart_id` and `bootpart_id` + they are created. The partitions in the `` section are still + created in the order in which they are listed. Please also note, if + custom partition IDs are used, it is strongly recommended that they + be used across all partitions created by kiwi. The reason for this + is that kiwi uses an incremental counter that, by default, matches + the number of the partition in the table. If custom partition + IDs are not used for all partitions, this results in a mix of + numbers, which works but is not obviously visible when reading the + image description. Because of that, also see the information about -Despite the customization options of the partition table shown above + the `` attributes `eficsmpart_id`, `efipart_id`, + `rootpart_id`, and `bootpart_id`. + +Despite the customization options of the partition table shown above, there are the following limitations: -1. By default the root partition is always the last one +1. By default, the root partition is always the last one. - Disk imags build with {kiwi} are designed to be expandable. - For this feature to work the partition containing the system + Disk images built with {kiwi} are designed to be expandable. + For this feature to work, the partition containing the system's rootfs must always be the last one. If this is unwanted for - some reason {kiwi} offers an opportunity for one extra/spare - partition with the option to be also placed at the end of the - table. For details lookup `spare_part` in :ref:`image-description-elements` + some reason, {kiwi} offers an opportunity for one extra/spare + partition with the option to also be placed at the end of the + table. For details, look up `spare_part` in :ref:`image-description-elements`. -2. By default there are no gaps in the partition table +2. By default, there are no gaps in the partition table. The way partitions are configured is done such that there are no gaps in the table of the image. However, leaving some space @@ -126,27 +127,27 @@ there are the following limitations: * **Deploy with unpartitioned free space.** - To leave space unpartitioned on first boot of a disk image - it is possible to configure an `` which is + To leave space unpartitioned on the first boot of a disk image, + it is possible to configure an `` that is smaller than the disk the image gets deployed to. Details - about this setting can be found in :ref:`image-description-elements` + about this setting can be found in :ref:`image-description-elements`. * **Build with unpartitioned free space.** - To leave space unpartitioned at build time of the image it + To leave space unpartitioned at build time of the image, it is possible to disable `` and configure an - `` which is smaller than the kiwi calculated + `` which is smaller than the kiwi-calculated disk size or the fixed setting for the disk size via the `size>` element. * **Build with unpartitioned free space.** Setting some unpartitioned free space on the disk can be done using - the `unpartitioned` attribute of `size` element in type's section. - For details see :ref:`disk-the-size-element` + the `unpartitioned` attribute of the `size` element in the type's section. + For details, see :ref:`disk-the-size-element`. * **Resize built image adding unpartitioned free space.** A built image can be resized by using the `kiwi-ng image resize` command - and set a new extended size for the disk. See {kiwi} commands docs + and setting a new extended size for the disk. See {kiwi} commands docs :ref:`here `. diff --git a/doc/source/working_with_images/custom_volumes.rst b/doc/source/working_with_images/custom_volumes.rst index 82a23abe..7e606f1d 100644 --- a/doc/source/working_with_images/custom_volumes.rst +++ b/doc/source/working_with_images/custom_volumes.rst @@ -5,14 +5,14 @@ Custom Disk Volumes .. sidebar:: Abstract - This chapter provides high level explanations on how to handle volumes - or subvolumes definitions for disk images using {kiwi}. + This chapter provides high-level explanations on how to handle volume + or subvolume definitions for disk images using {kiwi}. {kiwi} supports defining custom volumes by using the logical volume manager -(LVM) for the Linux kernel or by setting volumes at filesystem level when -filesystem supports it (e.g. btrfs). +(LVM) for the Linux kernel or by setting volumes at the filesystem level when +the filesystem supports it (e.g., btrfs). -Volumes are defined in the {kiwi} description file :file:`config.xml`, +Volumes are defined in the {kiwi} description file, :file:`config.xml`, using `systemdisk`. This element is a child of the `type`. Volumes themselves are added via (multiple) `volume` child elements of the `systemdisk` element: @@ -46,7 +46,7 @@ attributes: .. note:: Special name for the root volume - One can use the `@root` name to refer to the volume mounted at `/`, in + You can use the `@root` name to refer to the volume mounted at `/` in case some specific size attributes for the root volume have to be defined. For instance: @@ -54,39 +54,39 @@ attributes: - In addition to the custom size of the root volume it's also possible - to setup the name of the root volume as follows: + In addition to the custom size of the root volume, it's also possible + to set up the name of the root volume as follows: .. code:: xml - If no name for the root volume is specified the - default name: **LVRoot** applies. + If no name for the root volume is specified, the + default name, **LVRoot**, applies. - `freespace`: Optional attribute defining the additional free space added to the volume. If no suffix (`M` or `G`) is used, the value is considered to be in megabytes. -- `label`: Optional attribute to set filesystem label of the volume. +- `label`: Optional attribute to set the filesystem label of the volume. - `copy_on_write`: Optional attribute to set the filesystem copy-on-write attribute for this volume. - `quota`: Optional attribute for the `btrfs` filesystem only. Allows - to specify a quota size for the generated volume. + you to specify a quota size for the generated volume. - `filesystem_check`: Optional attribute to indicate that this - filesystem should perform the validation to become filesystem checked. - The actual constraints if the check is performed or not depends on - systemd and filesystem specific components. If not set or set to - `false` no system component will be triggered to run an eventual - filesystem check, which results in this filesystem to be never checked. + filesystem should perform the validation to become filesystem-checked. + The actual constraints of whether the check is performed or not depends on + systemd and filesystem-specific components. If not set or set to + `false`, no system component will be triggered to run an eventual + filesystem check, which results in this filesystem never being checked. The latter is the default. - `arch`: Optional attribute to create the volume only if it matches the specified host architecture. Multiple architecture names can - be specified as comma separated list. + be specified as a comma-separated list. .. warning:: The size attributes for filesystem volumes, as for btrfs, are @@ -95,8 +95,8 @@ attributes: The `systemdisk` element additionally supports the following optional attributes: -- `name`: The volume group name, by default `kiwiVG` is used. This setting +- `name`: The volume group name, by default, `kiwiVG` is used. This setting is only relevant for LVM volumes. -- `preferlvm`: Boolean value instructing {kiwi} to prefer LVM even if the +- `preferlvm`: A boolean value instructing {kiwi} to prefer LVM even if the used filesystem has its own volume management system. diff --git a/doc/source/working_with_images/disk_ramdisk_deployment.rst b/doc/source/working_with_images/disk_ramdisk_deployment.rst index cac4ad1d..5e61ed91 100644 --- a/doc/source/working_with_images/disk_ramdisk_deployment.rst +++ b/doc/source/working_with_images/disk_ramdisk_deployment.rst @@ -1,7 +1,7 @@ .. _ramdisk_deployment: -Deploy and Run System in a RamDisk -================================== +Deploy and Run a System in a Ramdisk +==================================== .. sidebar:: Abstract @@ -27,7 +27,7 @@ the image into a ramdisk serves this purpose. echo 'add_drivers+=" brd "' > /etc/dracut.conf.d/10-brd.conf -{kiwi} allows to create a bootable ISO image which deploys the image +{kiwi} allows you to create a bootable ISO image that deploys the image into a ramdisk and activates that image with the following oem type definition: @@ -46,15 +46,15 @@ oem type definition: The type specification above builds an installation ISO image -which deploys the System Image into the specified ramdisk -device (/dev/ram1). The setup of the ISO image boots with a -short boot timeout of 1sec and just runs through the process -without asking any questions. In a ramdisk deployment the -optional target verification, swap space and multipath targets +that deploys the System Image into the specified ramdisk +device (`/dev/ram1`). The setup of the ISO image boots with a +short boot timeout of 1 second and just runs through the process +without asking any questions. In a ramdisk deployment, the +optional target verification, swap space, and multipath targets are out of scope and therefore disabled. The configured size of the ramdisk via `oem-ramdisk-size` specifies -the kB size of the OS disk and it must be at least of the size of the +the kB size of the OS disk, and it must be at least of the size of the System Image. The disk size can be configured dynamically with the following value in the kernelcmdline attribute: @@ -75,27 +75,27 @@ follows: or a real machine, must provide enough RAM to hold the image in the ramdisk as well as have enough RAM available to operate the OS and its applications. The {kiwi} build image with the - extension .raw provides the System Image which gets deployed - into the RAM space. Substract the size of the System Image + extension .raw provides the System Image that gets deployed + into the RAM space. Subtract the size of the System Image from the RAM space the machine offers and make sure the result is still big enough for the use case of the appliance. In - case of a virtual machine, attach enough main memory to fit - this calculation. In case of QEMU this can be done with - the `-m` option + the case of a virtual machine, attach enough main memory to fit + this calculation. In the case of QEMU, this can be done with + the `-m` option. -Like all other oem {kiwi} images, also the ramdisk setup supports -all the deployments methods as explained in :ref:`deployment_methods` +Like all other oem {kiwi} images, the ramdisk setup also supports +all the deployment methods as explained in :ref:`deployment_methods`. This means it's also possible to dump the ISO image on a USB -stick let the system boot from it and unplug the stick from -the machine because the system was deployed into RAM +stick, let the system boot from it, and unplug the stick from +the machine because the system was deployed into RAM. -.. note:: Limitations Of RamDisk Deployments +.. note:: Limitations Of Ramdisk Deployments - Only standard images which can be booted by a simple root mount - and root switch can be used. Usually {kiwi} calls kexec after deployment - such that the correct, for the image created dracut initrd, will boot - the image. In case of a RAM only system kexec does not work because - it would loose the ramdisk contents. Thus the dracut initrd driving + Only standard images that can be booted by a simple root mount + and root switch can be used. Usually, {kiwi} calls kexec after deployment + such that the correct dracut initrd created for the image will boot + the image. In the case of a RAM-only system, kexec does not work because + it would lose the ramdisk contents. Thus, the dracut initrd driving the deployment is also the environment to boot the system. There are cases where this environment is not suitable to boot the system. diff --git a/doc/source/working_with_images/disk_setup_for_azure.rst b/doc/source/working_with_images/disk_setup_for_azure.rst index 39bef037..ae9956ad 100644 --- a/doc/source/working_with_images/disk_setup_for_azure.rst +++ b/doc/source/working_with_images/disk_setup_for_azure.rst @@ -11,24 +11,24 @@ Image Description for Microsoft Azure * :ref:`simple_disk` -A virtual disk image which is able to boot in the Microsoft Azure -cloud framework has to comply the following constraints: +A virtual disk image that is able to boot in the Microsoft Azure +cloud framework has to comply with the following constraints: -* Hyper-V tools must be installed -* Microsoft Azure Agent must be installed -* Disk size must be set to 30G -* Kernel parameters must allow for serial console +* Hyper-V tools must be installed. +* The Microsoft Azure Agent must be installed. +* The disk size must be set to 30G. +* Kernel parameters must allow for a serial console. -To meet this requirements update the {kiwi} image +To meet these requirements, update the {kiwi} image description as follows: 1. Software packages - Make sure to add the following packages to the package list + Make sure to add the following packages to the package list: .. note:: - Package names used in the following list matches the + Package names used in the following list match the package names of the SUSE distribution and might be different on other distributions. @@ -39,7 +39,7 @@ description as follows: 2. Image Type definition - Update the oem image type setup as follows + Update the oem image type setup as follows: .. code:: xml @@ -59,6 +59,6 @@ description as follows: An image built with the above setup can be uploaded into the -Microsoft Azure cloud and registered as image. For further -information on how to upload to Azure see: -`azurectl `_ +Microsoft Azure cloud and registered as an image. For further +information on how to upload to Azure, see: +`azurectl `_. diff --git a/doc/source/working_with_images/disk_setup_for_ec2.rst b/doc/source/working_with_images/disk_setup_for_ec2.rst index 6eaec8f1..52170256 100644 --- a/doc/source/working_with_images/disk_setup_for_ec2.rst +++ b/doc/source/working_with_images/disk_setup_for_ec2.rst @@ -11,27 +11,27 @@ Image Description for Amazon EC2 * :ref:`simple_disk` -A virtual disk image which is able to boot in the Amazon EC2 -cloud framework has to comply the following constraints: +A virtual disk image that is able to boot in the Amazon EC2 +cloud framework has to comply with the following constraints: -* Xen tools and libraries must be installed -* cloud-init package must be installed -* cloud-init configuration for Amazon must be provided -* Grub bootloader modules for Xen must be installed -* AWS tools must be installed -* Disk size must be set to 10G -* Kernel parameters must allow for xen console +* Xen tools and libraries must be installed. +* The cloud-init package must be installed. +* A cloud-init configuration for Amazon must be provided. +* Grub bootloader modules for Xen must be installed. +* AWS tools must be installed. +* The disk size must be set to 10G. +* Kernel parameters must allow for a Xen console. -To meet this requirements add or update the {kiwi} image +To meet these requirements, add or update the {kiwi} image description as follows: 1. Software packages - Make sure to add the following packages to the package list + Make sure to add the following packages to the package list: .. note:: - Package names used in the following list matches the + Package names used in the following list match the package names of the SUSE distribution and might be different on other distributions. @@ -45,7 +45,7 @@ description as follows: 2. Image Type definition - Update the oem image type setup as follows + Update the oem image type setup as follows: .. code:: xml @@ -62,13 +62,13 @@ description as follows: -3. Cloud Init setup +3. Cloud-Init setup - Cloud init is a service which runs at boot time and allows - to customize the system by activating one ore more cloud init - modules. For Amazon EC2 the following configuration file - :file:`/etc/cloud/cloud.cfg` needs to be provided as part of the - overlay files in your {kiwi} image description + Cloud-init is a service that runs at boot time and allows + you to customize the system by activating one or more cloud-init + modules. For Amazon EC2, the following configuration file, + :file:`/etc/cloud/cloud.cfg`, needs to be provided as part of the + overlay files in your {kiwi} image description: .. code:: yaml @@ -127,5 +127,5 @@ description as follows: ssh_svcname: sshd An image built with the above setup can be uploaded into the -Amazon EC2 cloud and registered as image. For further information -on how to upload to EC2 see: `ec2uploadimg `_ +Amazon EC2 cloud and registered as an image. For further information +on how to upload to EC2, see: `ec2uploadimg `_. diff --git a/doc/source/working_with_images/disk_setup_for_google.rst b/doc/source/working_with_images/disk_setup_for_google.rst index e5a317c4..794ef990 100644 --- a/doc/source/working_with_images/disk_setup_for_google.rst +++ b/doc/source/working_with_images/disk_setup_for_google.rst @@ -11,24 +11,24 @@ Image Description for Google Compute Engine * :ref:`simple_disk` -A virtual disk image which is able to boot in the Google Compute Engine -cloud framework has to comply the following constraints: +A virtual disk image that is able to boot in the Google Compute Engine +cloud framework has to comply with the following constraints: -* {kiwi} type must be an expandable disk -* Google Compute Engine init must be installed -* Disk size must be set to 10G -* Kernel parameters must allow for serial console +* {kiwi} type must be an expandable disk. +* Google Compute Engine init must be installed. +* Disk size must be set to 10G. +* Kernel parameters must allow for a serial console. -To meet this requirements update the {kiwi} image +To meet these requirements, update the {kiwi} image description as follows: 1. Software packages - Make sure to add the following packages to the package list + Make sure to add the following packages to the package list: .. note:: - Package names used in the following list matches the + Package names used in the following list match the package names of the SUSE distribution and might be different on other distributions. @@ -39,13 +39,13 @@ description as follows: 2. Image Type definition To allow the image to be expanded to the configured disk - geometry of the instance started by Google Compute Engine it is + geometry of the instance started by Google Compute Engine, it is suggested to let {kiwi}'s OEM boot code take over that task. It would - also be possible to try cloud-init's resize module but we found - conflicts when two cloud init systems, `google-compute-engine-init` and - `cloud-init` were used together. Thus for now we stick with {kiwi}'s - boot code which can resize the disk from within the initrd before - the system gets activated through systemd. + also be possible to try cloud-init's resize module, but we found + conflicts when two cloud-init systems, `google-compute-engine-init` and + `cloud-init`, were used together. Thus, for now, we stick with {kiwi}'s + boot code, which can resize the disk from within the initrd before + the system is activated through systemd. Update the oem image type setup to be changed into an expandable type as follows: @@ -66,5 +66,5 @@ description as follows: An image built with the above setup can be uploaded into the -Google Compute Engine cloud and registered as image. For further information -on how to upload to Google see: `google-cloud-sdk` on software.opensuse.org +Google Compute Engine cloud and registered as an image. For further information +on how to upload to Google, see: `google-cloud-sdk` on software.opensuse.org. diff --git a/doc/source/working_with_images/disk_setup_for_luks.rst b/doc/source/working_with_images/disk_setup_for_luks.rst index cbe9f027..066b7622 100644 --- a/doc/source/working_with_images/disk_setup_for_luks.rst +++ b/doc/source/working_with_images/disk_setup_for_luks.rst @@ -1,33 +1,33 @@ .. _setup_for_luks: -Image Description Encrypted Disk -================================ +Image Description for an Encrypted Disk +======================================= .. sidebar:: Abstract This page provides further information for handling - disk images with an encrypted root filesystem setup. - The information here is based on top of the following + disk images with an encrypted root filesystem. + The information here is based on the following article: * :ref:`simple_disk` A virtual disk image can be partially or fully encrypted using the LUKS extension supported by {kiwi}. A fully encrypted -image also includes the data in :file:`/boot` to be encrypted. +image also includes the data in `/boot` to be encrypted. Such an image requests the passphrase for the master key -to be entered at the bootloader stage. A partialy encrypted -image keeps :file:`/boot` unencrypted and on an extra boot partition. +to be entered at the bootloader stage. A partially encrypted +image keeps `/boot` unencrypted and on an extra boot partition. Such an image requests the passphrase for the master key later -in the boot process when the root partition gets accessed by -the systemd mount service. In any case the master passphrase +in the boot process when the root partition is accessed by +the systemd mount service. In any case, the master passphrase is requested only once. Update the {kiwi} image description as follows: 1. Software packages - Make sure to add the following package to the package list + Make sure to add the following package to the package list: .. note:: @@ -41,9 +41,9 @@ Update the {kiwi} image description as follows: 2. Image Type definition - Update the oem image type setup as follows + Update the oem image type setup as follows: - Full disk encryption including :file:`/boot`: + Full disk encryption, including `/boot`: .. code:: xml @@ -52,7 +52,7 @@ Update the {kiwi} image description as follows: - Encrypted root partition with an unencrypted extra :file:`/boot` partition: + Encrypted root partition with an unencrypted extra `/boot` partition: .. code:: xml @@ -64,9 +64,9 @@ Update the {kiwi} image description as follows: .. note:: The value for the `luks` attribute sets the master passphrase - for the LUKS keyring. Therefore the XML description becomes - security critical and should only be readable by trustworthy - people. Alternatively the credentials information can be + for the LUKS keyring. Therefore, the XML description becomes + security-critical and should only be readable by trustworthy + people. Alternatively, the credentials information can be stored in a key file and referenced as: .. code:: xml diff --git a/doc/source/working_with_images/disk_setup_for_vagrant.rst b/doc/source/working_with_images/disk_setup_for_vagrant.rst index eef985cf..fcc59a4a 100644 --- a/doc/source/working_with_images/disk_setup_for_vagrant.rst +++ b/doc/source/working_with_images/disk_setup_for_vagrant.rst @@ -6,7 +6,7 @@ Image Description for Vagrant .. sidebar:: Abstract This page provides further information for handling - Vagrant controlled disk images built with {kiwi} and references + Vagrant-controlled disk images built with {kiwi} and references the following article: * :ref:`simple_disk` @@ -17,28 +17,28 @@ Virtualization technologies. To run a system, Vagrant needs so-called **boxes**. A box is a TAR archive containing a virtual disk image and some metadata. -To build Vagrant boxes, you can use `Packer `_ which +To build Vagrant boxes, you can use `Packer `_, which is provided by Hashicorp itself. Packer is based on the official installation media (DVDs) as shipped by the distribution vendor. -The {kiwi} way of building images might be helpful, if such a media does not +The {kiwi} way of building images might be helpful if such a media does not exist or does not suit your needs. For example, if the distribution is still under development or you want to use a collection of your own -repositories. Note, that in contrast to Packer {kiwi} only supports the +repositories. Note that in contrast to Packer, {kiwi} only supports the libvirt and VirtualBox providers. Other providers require a different box layout that is currently not supported by {kiwi}. -In addition, you can use the {kiwi} image description as source for the -`Open Build Service `_ which allows +In addition, you can use the {kiwi} image description as a source for the +`Open Build Service `_, which allows building and maintaining boxes. -Vagrant expects boxes to be setup in a specific way (for details refer to +Vagrant expects boxes to be set up in a specific way (for details refer to the `Vagrant box documentation -`_.), applied to the +`_.). applied to the referenced {kiwi} image description from :ref:`simple_disk`, the following steps are required: -1. Update the image type setup +1. Update the image type setup. .. code:: xml @@ -52,11 +52,11 @@ steps are required: This modifies the type to build a Vagrant box for the libvirt - provider including a pre-defined disk size. The disk size is - optional, but recommended to provide some free space on disk. + provider, including a pre-defined disk size. The disk size is + optional but recommended to provide some free space on disk. For the VirtualBox provider, the additional attribute - ``virtualbox_guest_additions_present`` can be set to ``true`` when the + `virtualbox_guest_additions_present` can be set to `true` when the VirtualBox guest additions are installed in the {kiwi} image: .. code:: xml @@ -74,20 +74,20 @@ steps are required: - The resulting Vagrant box then uses the ``vboxfs`` module for the - synchronized folder instead of ``rsync``, that is used by default. + The resulting Vagrant box then uses the `vboxfs` module for the + synchronized folder instead of `rsync`, which is used by default. -2. Add mandatory packages +2. Add mandatory packages. .. code:: xml -3. Add additional packages +3. Add additional packages. - If you have set the attribute ``virtualbox_guest_additions_present`` to - ``true``, add the VirtualBox guest additions. For openSUSE the following + If you have set the attribute `virtualbox_guest_additions_present` to + `true`, add the VirtualBox guest additions. For openSUSE, the following packages are required: .. code:: xml @@ -96,7 +96,7 @@ steps are required: - Otherwise, you must add ``rsync``: + Otherwise, you must add `rsync`: .. code:: xml @@ -105,7 +105,7 @@ steps are required: Note that {kiwi} cannot verify whether these packages are installed. If they are missing, the resulting Vagrant box will be broken. -4. Add Vagrant user +4. Add Vagrant user. .. code:: xml @@ -116,15 +116,15 @@ steps are required: This adds the **vagrant** user to the system and applies the name of the user as the password for login. -5. Configure SSH, the default shared folder and sudo permissions +5. Configure SSH, the default shared folder, and sudo permissions. - Vagrant expects that it can login as the user ``vagrant`` using an - insecure public key [#f1]_. Furthermore, vagrant also usually uses + Vagrant expects that it can log in as the user `vagrant` using an + insecure public key [#f1]_. Furthermore, Vagrant also usually uses :file:`/vagrant` as the default shared folder and assumes that the - ``vagrant`` user can invoke commands via :command:`sudo` without having + `vagrant` user can invoke commands via `sudo` without having to enter a password. - This can be achieved using the function ``baseVagrantSetup`` in + This can be achieved using the function `baseVagrantSetup` in :file:`config.sh`: .. code:: bash @@ -133,15 +133,15 @@ steps are required: 6. Additional customizations: - Additionally to ``baseVagrantSetup``, you might want to also ensure the + In addition to `baseVagrantSetup`, you might want to also ensure the following: - - If you have installed the Virtualbox guest additions into your box, - then also load the ``vboxsf`` kernel module. - - When building boxes for libvirt, then ensure that the default wired - networking interface is called ``eth0`` and uses DHCP. This is - necessary since libvirt uses ``dnsmasq`` to issue IPs to the VMs. This - step can be omitted for Virtualbox boxes. + - If you have installed the VirtualBox guest additions into your box, + then also load the `vboxsf` kernel module. + - When building boxes for libvirt, ensure that the default wired + networking interface is called `eth0` and uses DHCP. This is + necessary since libvirt uses `dnsmasq` to issue IPs to the VMs. This + step can be omitted for VirtualBox boxes. An image built with the above setup creates a Vagrant box file with the extension :file:`.vagrant.libvirt.box` or @@ -154,14 +154,14 @@ command: .. note:: - Using the box with the libvirt provider requires alongside a correct + Using the box with the libvirt provider requires, alongside a correct Vagrant installation: - - the plugin ``vagrant-libvirt`` to be installed + - the plugin `vagrant-libvirt` to be installed - a running libvirtd daemon Once added to Vagrant, boot the box and log in -with the following sequence of :command:`vagrant` commands: +with the following sequence of `vagrant` commands: .. code:: bash @@ -173,21 +173,21 @@ with the following sequence of :command:`vagrant` commands: Customizing the embedded Vagrantfile ------------------------------------ -.. warning:: This is an advanced topic and not required for most users +.. warning:: This is an advanced topic and not required for most users. -Vagrant ship with an embedded :file:`Vagrantfile` that carries settings -specific to this box, for instance the synchronization mechanism for the -shared folder. {kiwi} generates such a file automatically for you and it +Vagrant ships with an embedded :file:`Vagrantfile` that carries settings +specific to this box, for instance, the synchronization mechanism for the +shared folder. {kiwi} generates such a file automatically for you, and it should be sufficient for most use cases. If a box requires different settings in the embedded :file:`Vagrantfile`, then the user can provide {kiwi} with a path to an alternative via the -attribute `embebbed_vagrantfile` of the `vagrantconfig` element: it +attribute `embedded_vagrantfile` of the `vagrantconfig` element: it specifies a relative path to the :file:`Vagrantfile` that will be included in the finished box. -In the following example snippet from :file:`config.xml` we add a custom +In the following example snippet from :file:`config.xml`, we add a custom :file:`MyVagrantfile` into the box (the file should be in the image description directory next to :file:`config.sh`): @@ -210,7 +210,7 @@ description directory next to :file:`config.sh`): The option to provide a custom :file:`Vagrantfile` can be combined with the usage of *profiles* (see :ref:`image-profiles`), so that certain builds can use the automatically generated :file:`Vagrantfile` (in -the following example that is the Virtualbox build) and others get a +the following example, that is the VirtualBox build) and others get a customized one (the libvirt profile in the following example): .. code:: xml @@ -265,5 +265,5 @@ customized one (the libvirt profile in the following example): -.. [#f1] The insecure key is removed from the box when the it is first +.. [#f1] The insecure key is removed from the box when it is first booted via Vagrant. diff --git a/doc/source/working_with_images/iso_to_usb_stick_deployment.rst b/doc/source/working_with_images/iso_to_usb_stick_deployment.rst index e3e2f0d1..7b489d2a 100644 --- a/doc/source/working_with_images/iso_to_usb_stick_deployment.rst +++ b/doc/source/working_with_images/iso_to_usb_stick_deployment.rst @@ -1,6 +1,6 @@ .. _iso_to_usb_stick: -Deploy ISO Image on an USB Stick +Deploy ISO Image on a USB Stick ================================ .. sidebar:: Abstract @@ -11,18 +11,18 @@ Deploy ISO Image on an USB Stick * :ref:`hybrid_iso` -In {kiwi} all generated ISO images are created to be hybrid. This means, +In {kiwi}, all generated ISO images are created to be hybrid. This means, the image can be used as a CD/DVD or as a disk. This works because the ISO image also has a partition table embedded. With more and more -computers delivered without a CD/DVD drive this becomes important. +computers delivered without a CD/DVD drive, this becomes important. The very same ISO image can be copied onto a USB stick and used as a bootable disk. The following procedure shows how to do this: -1. Plug in a USB stick +1. Plug in a USB stick. Once plugged in, check which Unix device name the stick was assigned - to. The following command provides an overview about all linux + to. The following command provides an overview of all Linux storage devices: .. code:: bash @@ -34,15 +34,15 @@ bootable disk. The following procedure shows how to do this: .. warning:: Make sure the selected device really points to your stick because - the following operation can not be revoked and will destroy all - data on the selected device + the following operation cannot be revoked and will destroy all + data on the selected device. .. code:: bash $ dd if={exc_image_base_name}.x86_64-{exc_image_version}.iso of=/dev/ -3. Boot from your USB Stick +3. Boot from your USB Stick. - Activate booting from USB in your BIOS/UEFI. As many firmware has different + Activate booting from USB in your BIOS/UEFI. As many firmwares have different procedures on how to do it, look into your user manual. - Many firmware offers a boot menu which can be activated at boot time. + Many firmwares offer a boot menu that can be activated at boot time. diff --git a/doc/source/working_with_images/iso_to_usb_stick_file_based_deployment.rst b/doc/source/working_with_images/iso_to_usb_stick_file_based_deployment.rst index e9a614cf..ac4a1848 100644 --- a/doc/source/working_with_images/iso_to_usb_stick_file_based_deployment.rst +++ b/doc/source/working_with_images/iso_to_usb_stick_file_based_deployment.rst @@ -1,7 +1,7 @@ .. _iso_as_file_to_usb_stick: -Deploy ISO Image as File on a FAT32 Formated USB Stick -====================================================== +Deploy ISO Image as a File on a FAT32 Formatted USB Stick +========================================================= .. sidebar:: Abstract @@ -13,34 +13,34 @@ Deploy ISO Image as File on a FAT32 Formated USB Stick In {kiwi}, all generated ISO images are created to be hybrid. This means, the image can be used as a CD/DVD or as a disk. The deployment of such -an image onto a disk like an USB stick normally destroys all existing +an image onto a disk like a USB stick normally destroys all existing data on this device. Most USB sticks are pre-formatted with a FAT32 -Windows File System and to keep the existing data on the stick untouched +Windows filesystem, and to keep the existing data on the stick untouched, a different deployment needs to be used. The following deployment process copies the ISO image as an additional file to the USB stick and makes the USB stick bootable. The ability to boot from the stick is configured through a SYSLINUX -feature which allows to loopback mount an ISO file and boot the +feature that allows you to loopback mount an ISO file and boot the kernel and initrd directly from the ISO file. The initrd loaded in this process must also be able to loopback mount the ISO file to access the root filesystem and boot the live system. The dracut initrd system used by {kiwi} provides this -feature upstream called as "iso-scan". Therefore all {kiwi} generated -live ISO images supports this deployment mode. +feature upstream, called "iso-scan". Therefore, all {kiwi}-generated +live ISO images support this deployment mode. -For copying the ISO file on the USB stick and the setup of the -SYSLINUX bootloader to make use of the "iso-scan" feature an extra tool +For copying the ISO file to the USB stick and the setup of the +SYSLINUX bootloader to make use of the "iso-scan" feature, an extra tool named `live-grub-stick` exists. The following procedure shows how -to setup the USB stick with `live-grub-stick`: +to set up the USB stick with `live-grub-stick`: -1. Install the `live-grub-stick` package from software.opensuse.org: +1. Install the `live-grub-stick` package from software.opensuse.org. -2. Plug in a USB stick +2. Plug in a USB stick. Once plugged in, check which Unix device name the FAT32 partition - was assigned to. The following command provides an overview about all + was assigned to. The following command provides an overview of all storage devices and their filesystems: .. code:: bash @@ -56,12 +56,12 @@ to setup the USB stick with `live-grub-stick`: $ sudo live-grub-stick {exc_image_base_name}.x86_64-{exc_image_version}.iso /dev/sdz1 -4. Boot from your USB Stick +4. Boot from your USB Stick. - Activate booting from USB in your BIOS/UEFI. As many firmware has different + Activate booting from USB in your BIOS/UEFI. As many firmwares have different procedures on how to do it, look into your user manual. - EFI booting from iso image is not supported at the moment, for EFI booting - use --isohybrid option with live-grub-stick, however note that all the data + EFI booting from an ISO image is not supported at the moment. For EFI booting, + use the --isohybrid option with live-grub-stick; however, note that all the data on the stick will be lost. - Many firmware offers a boot menu which can be activated at boot time. - Usually this can be reached by pressing the :kbd:`Esc` or :kbd:`F12` keys. + Many firmwares offer a boot menu that can be activated at boot time. + Usually, this can be reached by pressing the :kbd:`Esc` or :kbd:`F12` keys. diff --git a/doc/source/working_with_images/iso_to_usb_stick_grub2_boot_from_iso.rst b/doc/source/working_with_images/iso_to_usb_stick_grub2_boot_from_iso.rst index c38a9b39..bf5ce45a 100644 --- a/doc/source/working_with_images/iso_to_usb_stick_grub2_boot_from_iso.rst +++ b/doc/source/working_with_images/iso_to_usb_stick_grub2_boot_from_iso.rst @@ -1,6 +1,6 @@ .. _grub_boot_from_iso: -Booting a Live ISO Images from Grub2 +Booting Live ISO Images from Grub2 ==================================== .. sidebar:: Abstract @@ -14,29 +14,28 @@ Booting a Live ISO Images from Grub2 In {kiwi}, all generated ISO images are created to be hybrid. This means, the image can be used as a CD/DVD or as a disk. This works because the ISO image also has a partition table embedded. With more and more -computers delivered without a CD/DVD drive this becomes important. +computers delivered without a CD/DVD drive, this becomes important. Writing this image to a USB stick will permanently erase all existing data on the device. Additionally, the stick will no longer be usable for general data storage. Most USB sticks are pre-formatted with a -FAT32 or exFAT Windows file system and to keep the existing data +FAT32 or exFAT Windows filesystem, and to keep the existing data. -Fortunately Grub2 supports booting directly from ISO files. It does not matter +Fortunately, Grub2 supports booting directly from ISO files. It does not matter whether it is installed on your computer's hard drive or on a USB stick. The following deployment process copies the ISO image as an additional file to the USB stick or hard drive. The ability to boot from the disk is configured -through a Grub2 feature which allows to loopback mount an ISO file and boot the +through a Grub2 feature that allows you to loopback mount an ISO file and boot the kernel and initrd directly from the ISO file. The initrd loaded in this process must also be able to loopback mount the ISO file to access the root filesystem and boot the live system. FAT32 is widely supported on USB sticks. -For hard drives any filesystem supported by grub is apropriate -too. +For hard drives, any filesystem supported by grub is also appropriate. The dracut initrd system used by {kiwi} provides this -feature upstream called as "iso-scan/filename". Therefore all {kiwi} generated -live ISO images supports this deployment mode. +feature upstream, called "iso-scan/filename". Therefore, all {kiwi}-generated +live ISO images support this deployment mode. The following procedure expects an existing Grub2 installation on your hard drive or USB stick. @@ -50,14 +49,14 @@ hard drive or USB stick. sudo mkdir /iso sudo cp some-kiwi-live.iso /iso/ -2. Lookup the root filesystem UUID of your current operating system. +2. Look up the root filesystem UUID of your current operating system. Get this information by running the command: .. code:: bash findmnt -n -o UUID / -2. Add the following submenu setup to the :file:`grub.cfg` file: +3. Add the following submenu setup to the :file:`grub.cfg` file: .. note:: @@ -91,7 +90,7 @@ hard drive or USB stick. initrd $initrd } -3. Restart your computer and select the added menuentry. +4. Restart your computer and select the added menu entry. .. note:: diff --git a/doc/source/working_with_images/legacy_netboot_root_filesystem.rst b/doc/source/working_with_images/legacy_netboot_root_filesystem.rst index e7862f9d..423c2589 100644 --- a/doc/source/working_with_images/legacy_netboot_root_filesystem.rst +++ b/doc/source/working_with_images/legacy_netboot_root_filesystem.rst @@ -1,6 +1,6 @@ .. _build_legacy_pxe: -Build PXE Root File System Image for the legacy netboot infrastructure +Build PXE Root Filesystem Image for the legacy netboot infrastructure ====================================================================== .. _PXE: https://en.wikipedia.org/wiki/Preboot_Execution_Environment @@ -11,38 +11,38 @@ Build PXE Root File System Image for the legacy netboot infrastructure .. sidebar:: Abstract - This page explains how to build a file system image for use with + This page explains how to build a filesystem image for use with {kiwi}'s PXE boot infrastructure. It contains: - * how to build a PXE file system image - * how to setup the PXE file system image on the PXE server + * how to build a PXE filesystem image + * how to set up the PXE filesystem image on the PXE server * how to run it with QEMU `PXE`_ is a network boot protocol that is shipped with most BIOS implementations. The protocol sends a DHCP request to get an IP address. When an IP address is assigned, it uses the `TFTP`_ protocol to download a Kernel and boot instructions. Contrary to other images -built with {kiwi}, a PXE image consists of separate boot, kernel and root -filesystem images, since those images need to be made available in +built with {kiwi}, a PXE image consists of separate boot, kernel, and root +filesystem images, since these images need to be made available in different locations on the PXE boot server. -A root filesystem image which can be deployed via {kiwi}'s PXE -netboot infrastructure represents the system rootfs in a linux +A root filesystem image that can be deployed via {kiwi}'s PXE +netboot infrastructure represents the system's rootfs in a Linux filesystem. A user could loop mount the image and access the contents of the root filesystem. The image does not contain -any information about the system disk its partitions or the -bootloader setup. All of these information is provided by a -client configuration file on the PXE server which controlls +any information about the system disk, its partitions, or the +bootloader setup. All of this information is provided by a +client configuration file on the PXE server, which controls how the root filesystem image should be deployed. -Many different deployment strategies are possible, e.g root over +Many different deployment strategies are possible, e.g., root over `NBD`_ (network block device), `AoE`_ (ATA over Ethernet), or -NFS for diskless and diskfull clients. This particular +NFS for diskless and diskful clients. This particular example shows how to build an overlayfs-based union system based -on openSUSE Leap for a diskless client which receives the squashfs -compressed root file system image in a ramdisk overlayed via +on openSUSE Leap for a diskless client that receives the squashfs- +compressed root filesystem image in a ramdisk overlayed via overlayfs and writes new data into another ramdisk on the same -system. As diskless client, a QEMU virtual machine is used. +system. As a diskless client, a QEMU virtual machine is used. .. compound:: **Things to know before** @@ -51,18 +51,18 @@ system. As diskless client, a QEMU virtual machine is used. :ref:`network-boot-server` for instructions. * The following example assumes you will create the PXE image - on the PXE boot server itself (if not, use :command:`scp` to copy the files - on the remote host). + on the PXE boot server itself (if not, use `scp` to copy the files + to the remote host). - * To let QEMU connect to the network, we recommend to - setup a network bridge on the host system and let QEMU connect + * To let QEMU connect to the network, we recommend setting up + a network bridge on the host system and letting QEMU connect to it via a custom :file:`/etc/qemu-ifup`. For details, see https://en.wikibooks.org/wiki/QEMU/Networking - * The PXE root filesystem image approach is considered to be a + * The PXE root filesystem image approach is considered a legacy setup. The required netboot initrd code will be maintained outside of the {kiwi} appliance builder code base. If possible, - we recommend to switch to the OEM disk image deployment via + we recommend switching to the OEM disk image deployment via PXE. 1. Make sure you have checked out the example image descriptions, @@ -102,7 +102,7 @@ system. As diskless client, a QEMU virtual machine is used. loaded and which kernel parameters are set. A template has been installed at :file:`/srv/tftpboot/pxelinux.cfg/default` from the ``kiwi-pxeboot`` package. The minimal configuration required to boot the example image - looks like to following: + looks like the following: .. code:: bash @@ -122,11 +122,11 @@ system. As diskless client, a QEMU virtual machine is used. IMAGE=/dev/ram1;{exc_image_base_name_pxe}.x86_64;{exc_image_version};192.168.100.2;4096 UNIONFS_CONFIG=/dev/ram2,/dev/ram1,overlay - All PXE boot based deployment methods are controlled by a client + All PXE boot-based deployment methods are controlled by a client configuration file. The above configuration tells the client where - to find the image and how to activate it. In this case the image - will be deployed into a ramdisk (ram1) and overlay mounted such - that all write operations will land in another ramdisk (ram2). + to find the image and how to activate it. In this case, the image + will be deployed into a ramdisk (`ram1`) and overlay mounted such + that all write operations will land in another ramdisk (`ram2`). {kiwi} supports a variety of different deployment strategies based on the rootfs image created beforehand. For details, refer to :ref:`pxe_legacy_client_config` @@ -143,20 +143,20 @@ system. As diskless client, a QEMU virtual machine is used. PXE Client Setup Configuration ------------------------------ -All PXE boot based deployment methods are controlled by configuration files +All PXE boot-based deployment methods are controlled by configuration files located in :file:`/srv/tftpboot/KIWI` on the PXE server. Such a configuration file can either be client-specific (config.MAC_ADDRESS, for example config.00.AB.F3.11.73.C8), or generic (config.default). In an environment -with heterogeneous clients, this allows to have a default configuration -suitable for the majority of clients, to have configurations suitable -for a group of clients (for example machines with similar or identical +with heterogeneous clients, this allows for a default configuration +suitable for the majority of clients, configurations suitable +for a group of clients (for example, machines with similar or identical hardware), and individual configurations for selected machines. The configuration file contains data about the image and about configuration, synchronization, and partition parameters. -The configuration file has got the following general format: +The configuration file has the following general format: .. code:: bash @@ -186,16 +186,16 @@ The configuration file has got the following general format: The configuration file is sourced by Bash, so the same quoting rules as for Bash apply. -Not all configuration options needs to be specified. It depends on the +Not all configuration options need to be specified. It depends on the setup of the client which configuration values are required. The -following is a collection of client setup examples which covers all +following is a collection of client setup examples that cover all supported PXE client configurations. Setup Client with Remote Root ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To serve the image from a remote location and redirect all -write operations on a tmpfs, the following setup is required: +write operations to a tmpfs, the following setup is required: .. code:: bash @@ -215,22 +215,22 @@ write operations on a tmpfs, the following setup is required: UNIONFS_CONFIG=tmpfs,nbd,overlay The above setup shows the most common use case where the image built -with {kiwi} is populated over the network using either AoE, NBD or NFS -in combination with overlayfs which redirects all write operations -to be local to the client. In any case a setup of either AoE, NBD or +with {kiwi} is populated over the network using either AoE, NBD, or NFS +in combination with overlayfs, which redirects all write operations +to be local to the client. In any case, a setup of either AoE, NBD, or NFS on the image server is required beforehand. Setup Client with System on Local Disk ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To deploy the image on a local disk the following setup +To deploy the image on a local disk, the following setup is required: .. note:: - In the referenced {exc_description_pxe} XML description the ``pxe`` - type must be changed as follows and the image needs to be - rebuild: + In the referenced `{exc_description_pxe}` XML description, the `pxe` + type must be changed as follows, and the image needs to be + rebuilt: .. code:: xml @@ -242,22 +242,22 @@ is required: DISK="/dev/sda" PART="5;S;X,X;L;/" -The setup above will create a partition table on sda with a 5MB swap -partition (no mountpoint) and the rest of the disk will be a Linux(L) -partition with :file:`/` as mountpoint. The (``X``) in the PART setup specifies -a place holder to indicate the default behaviour. +The setup above will create a partition table on `sda` with a 5MB swap +partition (no mountpoint), and the rest of the disk will be a Linux(L) +partition with `/` as its mountpoint. The (`X`) in the `PART` setup specifies +a placeholder to indicate the default behavior. Setup Client with System on Local MD RAID Disk ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To deploy the image on a local disk with prior software RAID +To deploy the image on a local disk with a prior software RAID configuration, the following setup is required: .. note:: - In the referenced {exc_description_pxe} XML description the ``pxe`` - type must be changed as follows and the image needs to be - rebuild: + In the referenced `{exc_description_pxe}` XML description, the `pxe` + type must be changed as follows, and the image needs to be + rebuilt: .. code:: xml @@ -269,30 +269,30 @@ configuration, the following setup is required: IMAGE="/dev/md1;{exc_image_base_name_pxe}.x86_64;{exc_image_version};192.168.100.2;4096" PART="5;S;x,x;L;/" -The first parameter of the RAID line is the RAID level. So far only raid1 -(mirroring) is supported. The second and third parameter specifies the -raid disk devices which make up the array. If a RAID line is present -all partitions in ``PART`` will be created as RAID partitions. The first -RAID is named ``md0``, the second one ``md1`` and so on. It is required to -specify the correct RAID partition in the ``IMAGE`` line according to the -``PART`` setup. In this case ``md0`` is reserved for the SWAP space and ``md1`` +The first parameter of the RAID line is the RAID level. So far, only raid1 +(mirroring) is supported. The second and third parameters specify the +raid disk devices that make up the array. If a `RAID` line is present, +all partitions in `PART` will be created as RAID partitions. The first +RAID is named `md0`, the second one `md1`, and so on. It is required to +specify the correct RAID partition in the `IMAGE` line according to the +`PART` setup. In this case, `md0` is reserved for the SWAP space, and `md1` is reserved for the system. Setup Loading of Custom Configuration File(s) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In order to load for example a custom :file:`/etc/hosts` file on the client, +To load, for example, a custom :file:`/etc/hosts` file on the client, the following setup is required: .. code:: bash CONF="hosts;/etc/hosts;192.168.1.2;4096;ffffffff" -On boot of the client {kiwi}'s boot code will fetch the :file:`hosts` file +On boot of the client, {kiwi}'s boot code will fetch the :file:`hosts` file from the root of the server (192.168.1.2) with 4k blocksize and deploy -it as :file:`/etc/hosts` on the client. The protocol is by default tftp -but can be changed via the ``kiwiservertype`` kernel commandline option. -For details, see :ref:`custom-download-server` +it as :file:`/etc/hosts` on the client. The protocol is tftp by default +but can be changed via the `kiwiservertype` kernel command-line option. +For details, see :ref:`custom-download-server`. Setup Client to Force Reload Image ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -304,7 +304,7 @@ the disk is up-to-date, the following setup is required: RELOAD_IMAGE=1 -The option only applies to configurations with a DISK/PART setup +The option only applies to configurations with a `DISK`/`PART` setup. Setup Client to Force Reload Configuration Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -316,16 +316,16 @@ CONF, the following setup is required: RELOAD_CONFIG=1 -By default only configuration files which has changed according to -their checksum value will be reloaded. With the above setup all files +By default, only configuration files that have changed according to +their checksum value will be reloaded. With the above setup, all files will be reloaded from the PXE server. The option only applies to -configurations with a DISK/PART setup +configurations with a `DISK`/`PART` setup. Setup Client for Reboot After Deployment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To reboot the system after the initial deployment process is -done the following setup is required: +done, the following setup is required: .. code:: bash @@ -334,8 +334,8 @@ done the following setup is required: Setup custom kernel boot options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To deactivate the kernel mode setting on local -boot of the client the following setup is required: +To deactivate the kernel mode setting on the local +boot of the client, the following setup is required: .. code:: bash @@ -344,13 +344,13 @@ boot of the client the following setup is required: .. note:: This does not influence the kernel options passed to the client - if it boots from the network. In order to setup those the PXE - configuration on the PXE server needs to be changed + if it boots from the network. To set up those, the PXE + configuration on the PXE server needs to be changed. Setup a Custom Boot Timeout ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To setup a 10sec custom timeout for the local boot of the client +To set up a 10-second custom timeout for the local boot of the client, the following setup is required. .. code:: bash @@ -359,35 +359,35 @@ the following setup is required. .. note:: - This does not influence the boot timeout if the client boots off - from the network. + This does not influence the boot timeout if the client boots from + the network. .. _custom-download-server: Setup a Different Download Protocol and Server ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -By default all downloads controlled by the {kiwi} linuxrc code are -performed by an atftp call using the TFTP protocol. With PXE the download -protocol is fixed and thus you cannot change the way how the kernel and -the boot image (:file:`initrd`) is downloaded. As soon as Linux takes over, the -download protocols http, https and ftp are supported too. {kiwi} uses -the curl program to support the additional protocols. +By default, all downloads controlled by the {kiwi} linuxrc code are +performed by an atftp call using the TFTP protocol. With PXE, the download +protocol is fixed, and thus you cannot change the way the kernel and +the boot image (:file:`initrd`) are downloaded. As soon as Linux takes over, the +download protocols http, https, and ftp are also supported. {kiwi} uses +the `curl` program to support the additional protocols. -To select one of the additional download protocols the following -kernel parameters need to be specified +To select one of the additional download protocols, the following +kernel parameters need to be specified: .. code:: bash kiwiserver=192.168.1.1 kiwiservertype=ftp -To set up this parameters edit the file +To set up these parameters, edit the file :file:`/srv/tftpboot/pxelinux.cfg/default` on your PXE boot server and change the append line accordingly. .. note:: - Once configured all downloads except for kernel and initrd are + Once configured, all downloads except for kernel and initrd are now controlled by the given server and protocol. You need to make sure that this server provides the same directory and file structure - as initially provided by the ``kiwi-pxeboot`` package + as initially provided by the `kiwi-pxeboot` package. diff --git a/doc/source/working_with_images/network_live_iso_boot.rst b/doc/source/working_with_images/network_live_iso_boot.rst index b7f22211..067b1e09 100644 --- a/doc/source/working_with_images/network_live_iso_boot.rst +++ b/doc/source/working_with_images/network_live_iso_boot.rst @@ -13,17 +13,17 @@ Booting a Live ISO Image from Network In {kiwi}, live ISO images can be configured to boot via the PXE boot protocol. This functionality requires a network boot -server setup on the system. Details how to setup such a server +server setup on the system. Details on how to set up such a server can be found in :ref:`network-boot-server`. -After the live ISO was built as shown in :ref:`hybrid_iso`, +After the live ISO is built as shown in :ref:`hybrid_iso`, the following configuration steps are required to boot from the network: -1. Extract initrd/kernel From Live ISO +1. Extract initrd/kernel from Live ISO The PXE boot process loads the configured kernel and initrd from - the PXE server. For this reason, those two files must be extracted + the PXE server. For this reason, these two files must be extracted from the live ISO image and copied to the PXE server as follows: .. code:: bash @@ -35,13 +35,13 @@ the network: .. note:: - This step must be repeated with any new build of the live ISO image + This step must be repeated with any new build of the live ISO image. -2. Export Live ISO To The Network +2. Export Live ISO to the Network Access to the live ISO file must be provided by either `ftp`, - `http`, `https` or `dolly`. The most simple method is to setup a FTP server - e.g. `vsftpd` and copy the live ISO file to the data directory: + `http`, `https`, or `dolly`. The simplest method is to set up a FTP server, + e.g., `vsftpd`, and copy the live ISO file to the data directory: .. code:: bash @@ -54,13 +54,13 @@ the network: `wget ftp://IP/image/{exc_image_base_name_live}.x86_64-{exc_image_version}.iso` before the next step. -3. Setup live ISO boot entry in PXE configuration +3. Set up live ISO boot entry in PXE configuration .. note:: - The following step assumes that the pxelinux.0 loader + The following step assumes that the `pxelinux.0` loader has been configured on the boot server to boot up network - clients + clients. Edit the file :file:`/srv/tftpboot/pxelinux.cfg/default` and create a boot entry of the form: @@ -72,19 +72,19 @@ the network: append initrd=boot/initrd ip=dhcp root=live:ftp://IP/image/{exc_image_base_name_live}.x86_64-{exc_image_version}.iso * The `ip=` parameter controls how the dracut network module sets up - the network. Several options exists to control how the network - interface should be setup. Please consult the dracut manual + the network. Several options exist to control how the network + interface should be set up. Please consult the dracut manual for further information. * The boot parameter `root=live:PROTOCOL://IP/PATH...` specifies the - remote endpoint and protocol to find the live ISO file. So far - `ftp`, `http`, `https` and `dolly` are supported. + remote endpoint and protocol to find the live ISO file. So far, + `ftp`, `http`, `https`, and `dolly` are supported. 4. Boot from the Network - Within the network which has access to the PXE server and the - IP in the root= option, any network client can now boot the - live system. A test based on QEMU is done as follows: + Within the network that has access to the PXE server and the + IP in the `root=` option, any network client can now boot the + live system. A test based on QEMU can be done as follows: .. code:: bash @@ -93,7 +93,7 @@ the network: Available Remote Boot Options ----------------------------- -There are the following kernel boot options available to control +The following kernel boot options are available to control the behavior of the remote boot process. rd.kiwi.live.curl_options= @@ -103,32 +103,32 @@ rd.kiwi.live.dolly_options= Options passed along to the dolly call rd.kiwi.live.system= - Block device to use for the system. By default this is set to `/dev/ram0` + Block device to use for the system. By default, this is set to `/dev/ram0`. ramdisk_size=bytes - Size of the ramdisk in bytes. By default this is set to 2097152 (2G) + Size of the ramdisk in bytes. By default, this is set to 2097152 (2G). rd.kiwi.live.reset Force reset of the live system. This option only makes sense if the live system device (rd.kiwi.live.system) points to a persistent - storage device. In this case {kiwi} loads the system only once + storage device. In this case, {kiwi} loads the system only once and does not overwrite it unless a reset is requested. Persistent Live System ---------------------- -The remote boot process of a live ISO image, places the ISO file +The remote boot process of a live ISO image places the ISO file into a ramdisk by default. This means all data lives in memory and -is not persistent. In order to boot up the live system from a remote -location and keep it on a persistent storage, it's required to +is not persistent. To boot the live system from a remote +location and keep it on persistent storage, it's required to pass the `rd.kiwi.live.system` boot option with the device name pointing to that persistent storage. .. warning:: - All data on the device given via `rd.kiwi.live.system` will be wiped + All data on the device given via `rd.kiwi.live.system` will be wiped. -A test based on QEMU is done as follows: +A test based on QEMU can be done as follows: Edit the file :file:`/srv/tftpboot/pxelinux.cfg/default` and create a boot entry of the form: @@ -142,9 +142,9 @@ a boot entry of the form: * The `rd.live.overlay.persistent` and `rd.live.overlay.cowfs=xfs` options are standard {kiwi} live ISO options to control if and how a persistent write partition should be created. The options only take - an effect when booting into a persistent storage device. + effect when booting into a persistent storage device. -Next create a persistent storage disk of 3G and attach it to the +Next, create a persistent storage disk of 3G and attach it to the QEMU instance. .. code:: bash @@ -153,7 +153,7 @@ QEMU instance. $ qemu -boot n -hda mydisk.raw The live system will be deployed once to the locally attached disk and -boots from it. Any subsequent boot process will not modify the local +will boot from it. Any subsequent boot process will not modify the local disk unless `rd.kiwi.live.reset` is passed on the kernel command line. -If deployed there is also no need for the network anymore and the +If deployed, there is no need for the network anymore, and the system could also boot standalone. diff --git a/doc/source/working_with_images/network_overlay_boot.rst b/doc/source/working_with_images/network_overlay_boot.rst index 406f0618..3decdcd2 100644 --- a/doc/source/working_with_images/network_overlay_boot.rst +++ b/doc/source/working_with_images/network_overlay_boot.rst @@ -13,11 +13,11 @@ Booting a Root Filesystem from Network In {kiwi}, the `kiwi-overlay` dracut module can be used to boot from a remote exported root filesystem. The exported device -is visible as block device on the network client. {kiwi} -supports the two export backends `NBD` (Network Block Device) -and `AoE` (ATA over Ethernet) for this purpose. A system that is +is visible as a block device on the network client. {kiwi} +supports the two export backends, `NBD` (Network Block Device) +and `AoE` (ATA over Ethernet), for this purpose. A system that is booted in this mode will read the contents of the root filesystem -from a remote location and targets any write action into RAM by +from a remote location and target any write action into RAM by default. The kernel cmdline option `rd.root.overlay.write` can be used to specify an alternative device to use for writing. The two layers (read and write) are combined using the `overlayfs` @@ -25,10 +25,10 @@ filesystem. For remote boot of a network client, the PXE boot protocol is used. This functionality requires a network boot server -setup on the system. Details how to setup such a server +setup on the system. Details on how to set up such a server can be found in :ref:`network-boot-server`. -Before the KIS image can be build, the following configuration step +Before the KIS image can be built, the following configuration step is required: * Create dracut configuration to include the `kiwi-overlay` module @@ -40,11 +40,11 @@ is required: $ cd root/etc/dracut.conf.d $ echo 'add_dracutmodules+=" kiwi-overlay "' > overlay.conf -Now the KIS image can be build as shown in :ref:`kis`. After the +Now, the KIS image can be built as shown in :ref:`kis`. After the build, the following configuration steps are required to boot from the network: -1. Copy initrd/kernel from the KIS build to the PXE server +1. Copy the initrd/kernel from the KIS build to the PXE server The PXE boot process loads the configured kernel and initrd from the PXE server. For this reason, the following files must be @@ -59,11 +59,11 @@ from the network: Access to the root filesystem is implemented using either the AoE or the NBD protocol. This requires the export of the - root filesystem image as remote block device: + root filesystem image as a remote block device: Export via AoE: - Install the `vblade` package on the system which is expected - to export the root filesystem + Install the `vblade` package on the system that is expected + to export the root filesystem. .. note:: @@ -79,21 +79,21 @@ from the network: $ vbladed 0 1 IFACE {exc_image_base_name}.x86_64-{exc_image_version} The above command exports the given filesystem image file as a block - storage device to the network of the given IFACE. On any machine except + storage device to the network of the given `IFACE`. On any machine except the one exporting the file, it will appear as :file:`/dev/etherd/e0.1` - once the :command:`aoe` kernel module was loaded. The two numbers, - 0 and 1 in the above example, classifies a major and minor number which - is used in the device node name on the reading side, in this - case :file:`e0.1`. + once the `aoe` kernel module has been loaded. The two numbers, + 0 and 1 in the above example, classify a major and minor number + that is used in the device node name on the reading side, in this + case, :file:`e0.1`. .. note:: - Only machines in the same network of the given INTERFACE + Only machines in the same network of the given `INTERFACE` can see the exported block device. Export via NBD: - Install the `nbd` package on the system which is expected - to export the root filesystem + Install the `nbd` package on the system that is expected + to export the root filesystem. Once done, export the filesystem from the KIS build above as follows: @@ -115,9 +115,9 @@ from the network: .. note:: - The following step assumes that the pxelinux.0 loader + The following step assumes that the `pxelinux.0` loader has been configured on the boot server to boot up network - clients + clients. Edit the file :file:`/srv/tftpboot/pxelinux.cfg/default` and create a boot entry of the form: @@ -130,8 +130,8 @@ from the network: append initrd=boot/initrd root=overlay:nbd=server-ip:export The boot parameter `root=overlay:nbd=server-ip:export` specifies - the NBD server IP address and the name of the export as used in - :file:`/etc/nbd-server/config` + the NBD server's IP address and the name of the export as used in + :file:`/etc/nbd-server/config`. Using AoE: .. code:: bash @@ -141,11 +141,11 @@ from the network: append initrd=boot/initrd root=overlay:aoe=AOEINTERFACE The boot parameter `root=overlay:aoe=AOEINTERFACE` specifies the - interface name as it was exported by the :command:`vbladed` command + interface name as it was exported by the `vbladed` command. 4. Boot from the Network - Within the network which has access to the PXE server and the + Within the network that has access to the PXE server and the exported root filesystem image, any network client can now boot the system. A test based on QEMU can be done as follows: diff --git a/doc/source/working_with_images/setup_network_bootserver.rst b/doc/source/working_with_images/setup_network_bootserver.rst index 9bde94e7..92585567 100644 --- a/doc/source/working_with_images/setup_network_bootserver.rst +++ b/doc/source/working_with_images/setup_network_bootserver.rst @@ -5,20 +5,20 @@ Setting Up a Network Boot Server .. sidebar:: Abstract - This page provides general information how to setup + This page provides general information on how to set up a network boot server that provides all services - needed for the PXE boot protocol + needed for the PXE boot protocol. To be able to deploy a system through the PXE boot protocol, you need -to set up a network boot server providing the services DHCP and tftp. -With `dnsmasq` an utility exists which allows to setup all needed +to set up a network boot server providing the services DHCP and TFTP. +With `dnsmasq`, a utility exists that allows you to set up all needed services at once: Installing and Configuring DHCP and TFTP with dnsmasq ----------------------------------------------------- The following instructions can only serve as an example. Depending on your -network structure, the IP addresses, ranges and domain settings needs to +network structure, the IP addresses, ranges, and domain settings need to be adapted to allow the DHCP server to work within your network. If you already have a DHCP server running in your network, make sure that the `filename` and `next-server` directives are correctly set on this server. @@ -28,17 +28,17 @@ DHCP and TFTP server. 1. Install the `dnsmasq` package. -2. Create the file :file:`/etc/dnsmasq.conf` and insert the following content +2. Create the file :file:`/etc/dnsmasq.conf` and insert the following content: .. code:: bash - # Don't function as a DNS server. + # Do not function as a DNS server. port=0 # Log information about DHCP transactions. log-dhcp - # Set the root directory for files available via FTP, + # Set the root directory for files available via TFTP, # usually "/srv/tftpboot": tftp-root=TFTP_ROOT_DIR @@ -46,9 +46,9 @@ DHCP and TFTP server. dhcp-range=BOOT_SERVER_IP,proxy - In the next step it's required to decide for the boot method. There - is the PXE loader provided via pxelinux.0 from the syslinux package - and there is the GRUB loader provided via the grub package. + In the next step, it's required to decide on the boot method. There + is the PXE loader provided via `pxelinux.0` from the `syslinux` package, + and there is the GRUB loader provided via the `grub` package. .. note:: Placeholders @@ -56,15 +56,15 @@ DHCP and TFTP server. your network setup. -2.1. insert the following content to use pxelinux.0: +2.1. insert the following content to use `pxelinux.0`: .. code:: bash - # The boot filename, Server name, Server Ip Address + # The boot filename, server name, and server IP address dhcp-boot=pxelinux.0,,BOOT_SERVER_IP # Disable re-use of the DHCP servername and filename fields as extra - # option space. That's to avoid confusing some old or broken + # option space. This is to avoid confusing some old or broken # DHCP clients. dhcp-no-override @@ -82,20 +82,20 @@ DHCP and TFTP server. .. note:: - On boot of a network client with that configuration the default - pxelinux.0 config file is expected at + On boot of a network client with that configuration, the default + `pxelinux.0` config file is expected at :file:`TFTP_ROOT_DIR/pxelinux.cfg/default` -2.2. insert the following content to use grub: +2.2. insert the following content to use GRUB: .. code:: bash - # The boot filename, Server name, Server Ip Address + # The boot filename, server name, and server IP address dhcp-boot=boot/grub2/i386-pc/core.0,,BOOT_SERVER_IP - When using grub the referenced dhcp-boot grub module must be genereated. - To do this change the directory to :file:`TFTP_ROOT_DIR` and create - the :file:`setvars.conf` with the following content: + When using GRUB, the referenced `dhcp-boot` GRUB module must be generated. + To do this, change the directory to :file:`TFTP_ROOT_DIR` and create + the :file:`setvars.conf` file with the following content: .. code:: bash @@ -103,7 +103,7 @@ DHCP and TFTP server. set net_default_server=BOOT_SERVER_IP set prefix=boot/grub2 - Now call the following commands to create the grub module + Now, call the following commands to create the GRUB module: .. code:: bash @@ -116,7 +116,7 @@ DHCP and TFTP server. .. note:: - On boot of a network client with that configuration the grub + On boot of a network client with that configuration, the GRUB config file is expected at :file:`TFTP_ROOT_DIR/boot/grub2/grub.cfg` 3. Run the dnsmasq server by calling: diff --git a/doc/source/working_with_images/use_suse_media.rst b/doc/source/working_with_images/use_suse_media.rst index f2c27942..15184cd6 100644 --- a/doc/source/working_with_images/use_suse_media.rst +++ b/doc/source/working_with_images/use_suse_media.rst @@ -5,21 +5,21 @@ Using SUSE Product ISO To Build .. sidebar:: Abstract - This page provides information how to use the SUSE - media ISO with {kiwi} + This page provides information on how to use the SUSE + media ISO with {kiwi}. When building an image with {kiwi}, the image description usually points to a number of public/private package source repositories -from which the new image root tree will be created. Alternatively -the vendor provided product ISO image(s) can be used. The contents -of the ISO (DVD) media also provides package source repositories -but organized in a vendor specific structure. As a user it's -important to know about this structure such that the {kiwi} +from which the new image root tree will be created. Alternatively, +the vendor-provided product ISO image(s) can be used. The contents +of the ISO (DVD) media also provide package source repositories +but are organized in a vendor-specific structure. As a user, it's +important to know about this structure so that the {kiwi} image description can consume it. -To use a SUSE product media the following steps are required: +To use a SUSE product media, the following steps are required: -1. Mount the ISO media from file or DVD drive: +1. Mount the ISO media from the file or DVD drive: .. code:: bash @@ -27,14 +27,14 @@ To use a SUSE product media the following steps are required: 2. Lookup all `Product` and `Module` directories: - Below `/media/suse` there is a directory structure which + Below `/media/suse`, there is a directory structure that provides package repositories in directories starting with `Product-XXX` and `Module-XXX`. It depends on the package list in the {kiwi} image description from which location a package or a dependency of the package is - taken. Therefore it is best practice to browse through + taken. Therefore, it is best practice to browse through all the directories and create a `` definition - for each of them in the {kiwi} image description like + for each of them in the {kiwi} image description, as the following example shows: .. code:: xml @@ -47,13 +47,13 @@ To use a SUSE product media the following steps are required: -Once all the individual product and module repos has been created +Once all the individual product and module repos have been created in the {kiwi} image description, the build process can be started as usual. .. note:: - Because of the manual mount process the `/media/suse` location + Because of the manual mount process, the `/media/suse` location stays busy after {kiwi} has created the image. The cleanup of - this resource is a responsibility of the user and not done - by {kiwi} + this resource is the responsibility of the user and not done + by {kiwi}.