documentation.suse.com / Building Linux System Appliances / Working from the Command Line

4 Working from the Command Line

 
Note
Note

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

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>]
        [--logsocket=<socketfile>]
        [--loglevel=<number>]
        [--debug]
        [--debug-run-scripts-in-screen]
        [--color-output]
        [--config=<configfile>]
        [--kiwi-file=<kiwifile>]
    image <command> [<args>...]
kiwi-ng [--logfile=<filename>]
        [--logsocket=<socketfile>]
        [--loglevel=<number>]
        [--debug]
        [--debug-run-scripts-in-screen]
        [--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>]
        [--logsocket=<socketfile>]
        [--loglevel=<number>]
        [--debug]
        [--debug-run-scripts-in-screen]
        [--color-output]
        [--config=<configfile>]
        [--kiwi-file=<kiwifile>]
    system <command> [<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. A description can consist of a single config.xml or .kiwi file. It 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 installation of missing software components.

Although 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 to prepare a directory that includes the contents of a new filesystem based on one or more software package sources. The second step uses the prepared contents of the new image root tree to create an 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, 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. 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 runtime configuration is expected to be in the ~/.config/kiwi/config.yml or /etc/kiwi.yml files.

--debug

Print debug information on the command line. Same as: --loglevel 10.

--debug-run-scripts-in-screen

Run scripts called by KIWI NG in a screen session.

--logfile

Specify 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 format as with --logfile.

--loglevel

Specify 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 Setting a log level displays all messages above the specified level.

----------------------------
| Level    | Numeric value |
----------------------------
| CRITICAL | 50            |
| ERROR    | 40            |
| WARNING  | 30            |
| INFO     | 20            |
| DEBUG    | 10            |
| NOTSET   | 0             |
----------------------------
--profile

Select 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.

--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 it contains information about package repositories and their cache and meta data. 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.

--target-arch

Specify 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 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 NG.

--type

Select 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 configuration elements. If not specified, kiwi uses a file named config.xml or a file matching *.kiwi

--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.5/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. 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.

4.2.3 OPTIONS

 
--target-dir

Directory containing the KIWI NG 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>
    [--bundle-format=<format>]
    [--zsync_source=<download_location>]
    [--package-as-rpm]
kiwi-ng result bundle help

4.3.2 DESCRIPTION

 

Create 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.

4.3.3 OPTIONS

 
--bundle-dir

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, 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:

  • %N : Image name

  • %P : Concatenated profile name (_)

  • %A : Architecture name

  • %I : Bundle ID

  • %T : Image build type name

  • %M : Image Major version number

  • %m : Image Minor version number

  • %p : Image Patch version number

  • %v : Image Version string

--id

Bundle ID. It is a free-form text appended to the image version information as part of the result image filename.

--target-dir

Directory containing the KIWI NG build results.

--zsync_source

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.

  • All files in a bundle must be stored in the same download location.

--package-as-rpm

Create an RPM package containing the result files.

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,{signing_keys},components,distribution,repo_gpgcheck>]
    [--set-repo-credentials=<user:pass_or_filename>]
    [--add-repo=<source,type,alias,priority,imageinclude,package_gpgcheck,{signing_keys},components,distribution,repo_gpgcheck>...]
    [--add-repo-credentials=<user:pass_or_filename>...]
    [--add-package=<name>...]
    [--add-bootstrap-package=<name>...]
    [--delete-package=<name>...]
    [--set-container-derived-from=<uri>]
    [--set-container-tag=<name>]
    [--add-container-label=<label>...]
    [--set-type-attr=<attribute=value>...]
    [--set-release-version=<version>]
    [--signing-key=<key-file>...]
kiwi-ng system prepare help

4.4.2 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. You can enter the system as root via chroot using the following command:

$ chroot <directory> bash

4.4.3 OPTIONS

 
--add-bootstrap-package

Specify a package to install as part of the early KIWI NG bootstrap phase. The option can be specified multiple times.

--add-container-label

Add a container label to the container configuration metadata. It overwrites the label with the provided key-value pair if it was already defined in the XML description.

--add-package

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

--add-repo-credentials

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.

--clear-cache

Delete 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 NG, the cache is shared between multiple image builds on the host for performance reasons.

--delete-package

Specify a package to delete. The option can be specified multiple times.

--description

Path to the KIWI NG XML description. The directory must contain at least a config.xml of *.kiwi XML description.

--ignore-repos

Ignore 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 are not ignored.

--root

Path to 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 that 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: rpm-md, apt-deb.

  • alias

    An alias name for the repository. If not specified, KIWI NG generates an alias name based 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.

  • priority

    A number indicating the repository priority. How the value is evaluated depends on the selected package manager. 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 the repository is part of the system image repository setup or not.

  • package_gpgcheck

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

    • {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 format.

  • components

    Component list for Debian-based repos as a space-delimited string.

  • distribution

    Main distribution name for Debian-based repos.

  • repo_gpgcheck

    Set to either true or false to specify if the repository must validate the repository signature.

--set-repo-credentials

For uri://user:pass@location type repositories, set 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 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 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

--set-release-version

Overwrite/set 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 if an image build validates 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 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.

4.5.3 OPTIONS

 
--add-package

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

--delete-package

Specify a 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,{signing_keys},components,distribution,repo_gpgcheck>]
    [--set-repo-credentials=<user:pass_or_filename>]
    [--add-repo=<source,type,alias,priority,imageinclude,package_gpgcheck,{signing_keys},components,distribution,repo_gpgcheck>...]
    [--add-repo-credentials=<user:pass_or_filename>...]
    [--add-package=<name>...]
    [--add-bootstrap-package=<name>...]
    [--delete-package=<name>...]
    [--set-container-derived-from=<uri>]
    [--set-container-tag=<name>]
    [--add-container-label=<label>...]
    [--set-type-attr=<attribute=value>...]
    [--set-release-version=<version>]
    [--signing-key=<key-file>...]
kiwi-ng system build help

4.6.2 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 <target-dir>/build/image-root and writes a log file <target-dir>/build/image-root.log. The result image files are created in the specified target directory.

4.6.3 OPTIONS

 
--add-bootstrap-package

Specify package to install as part of the early KIWI NG 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 if it is 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 possible option values see the –set-repo information below.

--add-repo-credentials

For uri://user:pass@location repositories, set the user and password associated with an add-repo specification. If the provided value describes a filename in the filesystem, the first line of that file is used as credentials.

--allow-existing-root

Use 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 previous image type setup.

--clear-cache

Delete 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 NG, 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 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` 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.

--set-repo

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

  • source

    Source URL pointing to a package repository that 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: rpm-md, apt-deb.

  • alias

    An alias name for the repository. If not specified, KIWI NG generates an alias name as result of hex representation from uuid4. While the hex is used to uniquely identify the repository, it is not descriptive. We recommend using descriptive aliases.

  • priority

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

  • imageinclude

    Set to either true or false to indicate if the repository is be part of the system image repository setup or not.

  • package_gpgcheck

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

  • {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 format.

  • components

    Component list for Debian-based repos as space-delimited string.

  • distribution

    Main distribution name for Debian-based repos.

  • repo_gpgcheck

    Set to either true or false to indicate if the repository should validate the repository signature.

--set-repo-credentials

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 image type. The setting applies only 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 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

--set-release-version

Overwrite/set 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 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.

4.6.4 URI_TYPES

 

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

    Remote repository delivered via the 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 NG 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 the previously prepared image root directory. The kiwi create command is normally issued after the kiwi prepare command, and it 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 normally created by the kiwi prepare command. Keep in mind that if the specified directory is not created using the kiwi prepare command, KIWI NG stores image build metadata in the image/ directory. This directory must exist for the kiwi create command to work correctly.

--target-dir

Path to store the build results.

--signing-key

Trusted key file to be 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. In the 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. The OEM boot code in KIWI NG 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 operation.

4.8.3 OPTIONS

 
--root

The path to the root directory. If not specified, kiwi searches 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, or it 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]
    [--list-profiles]
    [--print-kiwi-env]
    [--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 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 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. This option is usually used together with the –add-repo option. Otherwise there are no repositories available for the processing the requested image information, which could lead to an error.

--list-profiles

list profiles available for the selected/default type.

NOTE: If the image description is designed in a way that there is no default build type configured and/or the main build type is also profiled, it’s required to provide this information to kiwi to list further profiles for this type. For example: kiwi-ng –profile top_level_entry_profile image info …

--print-kiwi-env

print 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 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.

--resolve-package-list

Solve package dependencies and return 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 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 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.

  • Update of an old image description to the latest schema