Working from the Command Line

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 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. Same as: ‘–loglevel 10’

--debug-run-scripts-in-screen

Run 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 information to standard out instead of writing to a file

--logsocket

send log data to the given Unix Domain socket in the same format as with –logfile

--loglevel

specify logging level as number. Details about the available log levels can be found at: https://docs.python.org/3/library/logging.html#logging-levels Setting a log level causes all message >= level to be displayed.

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

--kiwi-file

Basename of kiwi file which contains the main image configuration elements. If not specified kiwi searches for 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.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,{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>...]
    [--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

--add-repo-credentials

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

--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 usually 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 generate an alias name as result of hex representation from uuid4. The hex 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.
- {signing_keys}
List of signing_keys enclosed in curly brackets and delimited by semicolon. The reference to a signing key must be provided as URI format
components
Component list for debian based repos as string delimited by a space
distribution
Main distribution name for debian based repos
repo_gpgcheck
Set to either true or false to specify if this 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 read and used as credentials information.

--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 operation. 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,{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>...]
    [--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

--add-repo-credentials

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

--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 usually 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 generate an alias name as result of hex representation from uuid4. The hex 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.
{signing_keys}
List of signing_keys enclosed in curly brackets and delimited by semicolon. The reference to a signing key must be provided as URI format
components
Component list for debian based repos as string delimited by a space
distribution
Main distribution name for debian based repos
repo_gpgcheck
Set to either true or false to specify if this 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 read and used as credentials information.

--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 operation. 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 operation. 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 usually 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

Building Linux System Appliances with KIWI Next Generation (KIWI NG) 9.25.12

4 Working from the Command Line #

Note

4.1 kiwi-ng #

4.1.1 SYNOPSIS #

4.1.2 DESCRIPTION #

4.1.3 GLOBAL OPTIONS #

4.1.4 EXAMPLE #

4.2 kiwi-ng result list #

4.2.1 SYNOPSIS #

4.2.2 DESCRIPTION #

4.2.3 OPTIONS #

4.3 kiwi-ng result bundle #

4.3.1 SYNOPSIS #

4.3.2 DESCRIPTION #

4.3.3 OPTIONS #

4.4 kiwi-ng system prepare #

4.4.1 SYNOPSIS #

4.4.2 DESCRIPTION #

4.4.3 OPTIONS #

4.5 kiwi-ng system update #

4.5.1 SYNOPSIS #

4.5.2 DESCRIPTION #

4.5.3 OPTIONS #

4.6 kiwi-ng system build #

4.6.1 SYNOPSIS #

4.6.2 DESCRIPTION #

4.6.3 OPTIONS #

4.6.4 URI_TYPES #

4.7 kiwi-ng system create #

4.7.1 SYNOPSIS #

4.7.2 DESCRIPTION #

4.7.3 OPTIONS #

4.8 kiwi-ng image resize #

4.8.1 SYNOPSIS #

4.8.2 DESCRIPTION #

4.8.3 OPTIONS #

4.9 kiwi-ng image info #

4.9.1 SYNOPSIS #

4.9.2 DESCRIPTION #

4.9.3 OPTIONS #