Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]

4 Working from the Command Line

Note
Note

This document provides a list of the existing KIWI Next Generation (KIWI NG) commands for version 9.23.55.

4.1 kiwi-ng

4.1.1 SYNOPSIS

kiwi-ng [global options] service <command> [<args>]

kiwi-ng -h | --help
kiwi-ng [--profile=<name>...]
        [--temp-dir=<directory>]
        [--type=<build_type>]
        [--logfile=<filename>]
        [--debug]
        [--color-output]
        [--config=<configfile>]
    image <command> [<args>...]
kiwi-ng [--debug]
        [--color-output]
        [--config=<configfile>]
    result <command> [<args>...]
kiwi-ng [--profile=<name>...]
        [--shared-cache-dir=<directory>]
        [--temp-dir=<directory>]
        [--target-arch=<name>]
        [--type=<build_type>]
        [--logfile=<filename>]
        [--debug]
        [--color-output]
        [--config=<configfile>]
    system <command> [<args>...]
kiwi-ng compat <legacy_args>...
kiwi-ng -v | --version
kiwi-ng help

4.1.2 DESCRIPTION

KIWI NG is an imaging solution that is based on an image XML description. Such a description is represented by a directory which includes at least one config.xml or .kiwi file and may as well include other files like scripts or configuration data.

A collection of example image descriptions can be found on the github repository here: https://github.com/OSInside/kiwi-descriptions. Most of the descriptions provide a so called appliance image. Appliance means that it’s a small, text only based image including a predefined remote source setup to allow installation of missing software components at a later point in time.

KIWI NG operates in two steps. The system build command combines both steps into one to make it easier to start with KIWI NG. The first step is the preparation step and if that step was successful, a creation step follows which is able to create different image output types.

In the preparation step, you prepare a directory including the contents of your new filesystem based on one or more software package source(s) The creation step is based on the result of the preparation step and uses the contents of the new image root tree to create the output image.

KIWI NG supports the creation of the following image types:

  • ISO Live Systems

  • 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

Depending on the image type a variety of different disk formats and architectures are supported.

4.1.3 GLOBAL OPTIONS

--color-output

Use Escape Sequences to print different types of information in colored output. The underlaying terminal has to understand those escape characters. Error messages appear red, warning messages yellow and debugging information will be printed light grey.

--config

Use specified runtime configuration file. If not specified the runtime configuration is looked up at ~/.config/kiwi/config.yml or /etc/kiwi.yml

--debug

Print debug information on the commandline.

--logfile

Specify log file. the logfile contains detailed information about the process.

--profile

Select profile to use. The specified profile must be part of the XML description. The option can be specified multiple times to allow using a combination of profiles.

--shared-cache-dir

Specify an alternative shared cache directory. The directory is shared via bind mount between the build host and image root system and contains information about package repositories and their cache and meta data. The default location is set to /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. By default /var/tmp is used.

--target-arch

Specify the image architecture. By default the host architecture is used as the image architecture. If the specified architecture name does not match the host architecture and is therefore requesting a cross architecture image build, it’s important to understand that for this process to work a preparatory step to support the image architecture and binary format on the building host is required and not a responsibility of KIWI NG.

--type

Select image build type. The specified build type must be configured as part of the XML description.

--version

Show program version

4.1.4 EXAMPLE

$ git clone https://github.com/OSInside/kiwi

$ sudo kiwi-ng system build \
    --description kiwi/build-tests/x86/leap/test-image-disk \
    --set-repo obs://openSUSE:Leap:15.3/standard \
    --target-dir /tmp/myimage

4.2 kiwi-ng result list

4.2.1 SYNOPSIS

kiwi-ng [global options] service <command> [<args>]

kiwi-ng result list -h | --help
kiwi-ng result list --target-dir=<directory>
kiwi-ng result list help

4.2.2 DESCRIPTION

List build results from a previous build or create command. Please note if you build an image several times with the same target directory the build result information will be overwritten each time you build the image. Therefore the build result list is valid for the last build

4.2.3 OPTIONS

--target-dir

directory containing the kiwi build results

4.3 kiwi-ng result bundle

4.3.1 SYNOPSIS

kiwi-ng [global options] service <command> [<args>]

kiwi-ng result bundle -h | --help
kiwi-ng result bundle --target-dir=<directory> --id=<bundle_id> --bundle-dir=<directory>
    [--zsync_source=<download_location>]
    [--package-as-rpm]
kiwi-ng result bundle help

4.3.2 DESCRIPTION

Create result bundle from the image build results in the specified target directory. Each result image will contain the specified bundle identifier as part of its filename. Uncompressed image files will also become xz compressed and a sha sum will be created from every result image.

4.3.3 OPTIONS

--bundle-dir

directory containing the bundle results, compressed versions of image results and their sha sums

--id

bundle id, could be a free form text and is appended to the image version information if present as part of the result image filename

--target-dir

directory containing the kiwi build results

--zsync_source

Specify the download location from which the bundle file(s) can be fetched from. The information is effective if zsync is used to sync the bundle.

  • The zsync control file is only created for those bundle files which are marked for compression because in a KIWI NG build only those are meaningful for a partial binary file download.

  • It is expected that all files from a bundle are placed to the same download location

--package-as-rpm

Take all result files and create an rpm package out of it

4.4 kiwi-ng system prepare

4.4.1 SYNOPSIS

kiwi-ng [global options] service <command> [<args>]

kiwi-ng system prepare -h | --help
kiwi-ng system prepare --description=<directory> --root=<directory>
    [--allow-existing-root]
    [--clear-cache]
    [--ignore-repos]
    [--ignore-repos-used-for-build]
    [--set-repo=<source,type,alias,priority,imageinclude,package_gpgcheck>]
    [--add-repo=<source,type,alias,priority,imageinclude,package_gpgcheck>...]
    [--add-package=<name>...]
    [--add-bootstrap-package=<name>...]
    [--delete-package=<name>...]
    [--set-container-derived-from=<uri>]
    [--set-container-tag=<name>]
    [--add-container-label=<label>...]
    [--signing-key=<key-file>...]
kiwi-ng system prepare help

4.4.2 DESCRIPTION

Create a new image root directory. The prepare step builds a new image root directory from the specified XML description. The specified root directory is the root directory of the new image root system. As the root user you can enter this system via chroot as follows:

$ chroot <directory> bash

4.4.3 OPTIONS

--add-bootstrap-package

specify 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 overwrites the label with the provided key-value pair in case it was already defined in the XML description

--add-package

specify 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 description. This option can be specified multiple times. For details about the provided option values see the –set-repo information below

--allow-existing-root

allow to re-use an existing image root directory

--clear-cache

delete repository cache for each of the used repositories before installing any package. This is useful if an image build should take and validate the signature of the package from the original repository source for any build. Some package managers unconditionally trust the contents of the cache, which is ok for cache data dedicated to one build but in case of kiwi the cache is shared between multiple image builds on that host for performance reasons.

--delete-package

specify package to delete. The option can be specified multiple times

--description

Path to the kiwi XML description. Inside of that directory there must be at least a config.xml of *.kiwi XML description.

--ignore-repos

Ignore all repository configurations from the XML description. Using that option is usally done with a sequence of –add-repo options otherwise there are no repositories available for the image build which would lead to an error.

--ignore-repos-used-for-build

Works the same way as –ignore-repos except that repository configurations which has the imageonly attribute set to true will not be ignored.

--root

Path to create the new root system.

--set-repo

Overwrite the first repository entry in the XML description with the provided information:

  • source

    source url, pointing to a package repository which must be in a format supported by the selected package manager. See the URI_TYPES section for details about the supported source locators.

  • type

    repository type, could be one of rpm-md, rpm-dir or yast2.

  • alias

    An alias name for the repository. If not specified kiwi calculates an alias name as result from a sha sum. The sha sum is used to uniquely identify the repository, but not very expressive. We recommend to set an expressive and uniq alias name.

  • priority

    A number indicating the repository priority. How the value is evaluated depends on the selected package manager. Please refer to the package manager documentation for details about the supported priority ranges and their meaning.

  • imageinclude

    Set to either true or false to specify if this repository should be part of the system image repository setup or not.

  • package_gpgcheck

    Set to either true or false to specify if this repository should validate the package signatures.

--set-container-derived-from

overwrite 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

--set-container-tag

overwrite the container tag in the container configuration. The setting is only effective if the container configuraiton provides an initial tag value

--signing-key

set the key file to be trusted and imported into the package manager database before performing any opertaion. This is useful if an image build should take and validate repository and package signatures during build time. This option can be specified multiple times.

4.5 kiwi-ng system update

4.5.1 SYNOPSIS

kiwi-ng [global options] service <command> [<args>]

kiwi-ng system update -h | --help
kiwi-ng system update --root=<directory>
    [--add-package=<name>...]
    [--delete-package=<name>...]
kiwi-ng system update help

4.5.2 DESCRIPTION

Update a previously prepare image root tree. The update command refreshes the contents of the root directory with potentially new versions of the packages according to the repository setup of the image XML description. In addition the update command also allows to add or remove packages from the image root tree

4.5.3 OPTIONS

--add-package

specify package to add(install). The option can be specified multiple times

--delete-package

specify package to delete. The option can be specified multiple times

--root

Path to the root directory of the image.

4.6 kiwi-ng system build

4.6.1 SYNOPSIS

kiwi-ng [global options] service <command> [<args>]

kiwi-ng system build -h | --help
kiwi-ng system build --description=<directory> --target-dir=<directory>
    [--allow-existing-root]
    [--clear-cache]
    [--ignore-repos]
    [--ignore-repos-used-for-build]
    [--set-repo=<source,type,alias,priority,imageinclude,package_gpgcheck>]
    [--add-repo=<source,type,alias,priority,imageinclude,package_gpgcheck>...]
    [--add-package=<name>...]
    [--add-bootstrap-package=<name>...]
    [--delete-package=<name>...]
    [--set-container-derived-from=<uri>]
    [--set-container-tag=<name>]
    [--add-container-label=<label>...]
    [--signing-key=<key-file>...]
kiwi-ng system build help

4.6.2 DESCRIPTION

build an image in one step. The build command combines kiwi’s prepare and create steps in order to build an image with just one command call. The build command creates the root directory of the image below <target-dir>/build/image-root and if not specified differently writes a log file <target-dir>/build/image-root.log. The result image files are created in the specified target-dir.

4.6.3 OPTIONS

--add-bootstrap-package

specify 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 overwrites the label with the provided key-value pair in case it was already defined in the XML description

--add-package

specify 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 description. This option can be specified multiple times. For details about the provided option values see the –set-repo information below

--allow-existing-root

Allow to use an existing root directory from an earlier build attempt. Use with caution this could cause an inconsistent root tree if the existing contents does not fit to the former image type setup

--clear-cache

delete repository cache for each of the used repositories before installing any package. This is useful if an image build should take and validate the signature of the package from the original repository source for any build. Some package managers unconditionally trust the contents of the cache, which is ok for cache data dedicated to one build but in case of kiwi the cache is shared between multiple image builds on that host for performance reasons.

--delete-package

specify package to delete. The option can be specified multiple times

--description

Path to the 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. Using that option is usally done with a sequence of –add-repo options otherwise there are no repositories available for the image build which would lead to an error.

--ignore-repos-used-for-build

Works the same way as –ignore-repos except that repository configurations which has the imageonly attribute set to true will not be ignored.

--set-repo

Overwrite the first repository entry in the XML description with the provided information:

  • source

    source url, pointing to a package repository which must be in a format supported by the selected package manager. See the URI_TYPES section for details about the supported source locators.

  • type

    repository type, could be one of rpm-md, rpm-dir or yast2.

  • alias

    An alias name for the repository. If not specified kiwi calculates an alias name as result from a sha sum. The sha sum is used to uniquely identify the repository, but not very expressive. We recommend to set an expressive and uniq alias name.

  • priority

    A number indicating the repository priority. How the value is evaluated depends on the selected package manager. Please refer to the package manager documentation for details about the supported priority ranges and their meaning.

  • imageinclude

    Set to either true or false to specify if this repository should be part of the system image repository setup or not.

  • package_gpgcheck

    Set to either true or false to specify if this repository should validate the package signatures.

--set-container-derived-from

overwrite 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

--set-container-tag

overwrite the container tag in the container configuration. The setting is only effective if the container configuraiton provides an initial tag value

--signing-key

set the key file to be trusted and imported into the package manager database before performing any opertaion. This is useful if an image build should take and validate repository and package signatures during build time. This option can be specified multiple times

--target-dir

Path to store the build results.

4.6.4 URI_TYPES

  • http:// | https:// | ftp://

    remote repository delivered via http or ftp protocol.

  • obs://

    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 http url pointing to download.suse.de.

  • iso://

    Local iso file. kiwi loop mounts the file and uses the mount point as temporary directory source type

  • dir://

    Local directory

4.7 kiwi-ng system create

4.7.1 SYNOPSIS

kiwi-ng [global options] service <command> [<args>]

kiwi-ng system create -h | --help
kiwi-ng system create --root=<directory> --target-dir=<directory>
    [--signing-key=<key-file>...]
kiwi-ng system create help

4.7.2 DESCRIPTION

Create an image from a previously prepared image root directory. The kiwi create call is usually issued after a kiwi prepare command and builds the requested image type in the specified target directory

4.7.3 OPTIONS

--root

Path to the image root directory. This directory is usually created by the kiwi prepare command. If a directory is used which was not created by kiwi’s prepare command, it’s important to know that kiwi stores image build metadata below the image/ directory which needs to be present in order to let the create command operate correctly.

--target-dir

Path to store the build results.

--signing-key

set the key file to be trusted and imported into the package manager database before performing any opertaion. This is useful if an image build should take and validate repository and package signatures during build time. In create step this option only affects the boot image. This option can be specified multiple times

4.8 kiwi-ng image resize

4.8.1 SYNOPSIS

kiwi-ng [global options] service <command> [<args>]

kiwi-ng image resize -h | --help
kiwi-ng image resize --target-dir=<directory> --size=<size>
    [--root=<directory>]
kiwi-ng image resize help

4.8.2 DESCRIPTION

For disk based images, allow to resize the image to a new disk geometry. The additional space is free and not in use by the image. In order to make use of the additional free space a repartition process is required like it is provided by kiwi’s oem boot code. Therefore the resize operation is useful for oem image builds most of the time.

4.8.3 OPTIONS

--root

The path to the root directory, if not specified kiwi searches the root directory in build/image-root below the specified target directory

--size

New size of the image. The value is either a size in bytes or can be specified with m=MB or g=GB. Example: 20g

--target-dir

Directory containing the kiwi build results

4.9 kiwi-ng image info

4.9.1 SYNOPSIS

kiwi-ng [global options] service <command> [<args>]

kiwi-ng image info -h | --help
kiwi-ng image info --description=<directory>
    [--resolve-package-list]
    [--ignore-repos]
    [--add-repo=<source,type,alias,priority>...]
    [--print-xml|--print-yaml]
kiwi-ng image info help

4.9.2 DESCRIPTION

Provides information about the specified image description. If no specific info option is provided the command just lists basic information about the image which could also be directly obtained by reading the image XML description file. Specifying an extension option like resolve-package-list will cause a dependency resolver to run over the list of packages and thus provides more detailed information about the image description.

4.9.3 OPTIONS

--add-repo

Add repository with given source, type, alias and priority.

--description

The description must be a directory containing a kiwi XML description and optional metadata files.

--ignore-repos

Ignore all repository configurations from the XML description. Using that option is usally done with a sequence of –add-repo options otherwise there are no repositories available for the processing the requested image information which could lead to an error.

--resolve-package-list

Solve package dependencies and return a list of all packages including their attributes e.g size, shasum, and more.

--print-xml

Print image description in XML format. The given image description is read in, transformed internally to XML and send to the XSLT stylesheet processor. From there the result gets validated using the RelaxNG schema and the schematron rules. This result data will then be displayed. The typical use case for this command is to turn an old image description to the latest schema.

--print-yaml

Behaves the same like --print-xml except that after validation the result data will be transformed into the YAML format and displayed. Due to this processing the command can be used for different operations:

  • Conversion of a given image description from or into different formats. It’s required to install the anymarkup python module for this to work. The module is not a hard requirement and loaded on demand. If not available and a request to convert into a format different from XML is made an exception will be thrown.

  • Update of an old image description to the latest schema

Print this page