KIWI(2)

NAME
kiwi - Creating Operating System Images

SYNOPSIS

kiwi [global options] service <command> [<args>]
kiwi -h | --help
kiwi [--profile=<name>...]
     [--type=<build_type>]
     [--logfile=<filename>]
     [--debug]
     [--color-output]
    image <command> [<args>...]
kiwi [--debug]
     [--color-output]
    result <command> [<args>...]
kiwi [--profile=<name>...]
     [--shared-cache-dir=<directory>]
     [--type=<build_type>]
     [--logfile=<filename>]
     [--debug]
     [--color-output]
    system <command> [<args>...]
kiwi --compat <legacy_args>...
kiwi -v | --version
kiwi help

DESCRIPTION

KIWI 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/SUSE/kiwi-descriptions. Most of the descriptions provide a so called JeOS image. JeOS means Just enough Operating System. A JeOS is 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 operates in two steps. The system build command combines both steps into one to make it easier to start with KIWI. 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 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.

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.

--compat
    Support legacy kiwi commandline, see COMPATIBILITY section for details.

--debug
    Print debug information on the commandline.

--logfile=<filename>
    Specify log file. the logfile contains detailed information about the process.

--profile=<name>
    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=<directory>
    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

--type=<build_type>
    Select image build type. The specified build type must be configured as part of the XML description.

--version
    Show program version

EXAMPLE

$ git clone https://github.com/SUSE/kiwi-descriptions
$ kiwi --type vmx system build \
    --description kiwi-descriptions/suse/x86_64/suse-leap-42.1-JeOS \
    --target-dir /tmp/myimage

SERVICES AND COMMANDS

  kiwi image resize

  SYNOPSIS

kiwi [global options] service <command> [<args>]
kiwi image resize -h | --help
kiwi image resize --target-dir=<directory> --size=<size>
    [--root=<directory>]
kiwi image resize help

  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.

  OPTIONS

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

--size=<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>
    Directory containing the kiwi build results

  kiwi image info

  SYNOPSIS

kiwi [global options] service <command> [<args>]
kiwi image info -h | --help
kiwi image info --description=<directory>
    [--resolve-package-list]
    [--ignore-repos]
    [--add-repo=<source,type,alias,priority>...]
    [--obs-repo-internal]
kiwi image info help

  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.

  OPTIONS

--add-repo=<source,type,alias,priority>
    Add repository with given source, type, alias and priority.

--description=<directory>
    The description must be a directory containing a kiwi XML description and optional metadata files.

--ignore-repos
    Ignore all repos from the XML configuration.

--obs-repo-internal
    When using obs repos resolve them using the SUSE internal buildservice. This only works if access to SUSE's internal buildservice is granted.

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

  kiwi result list

  SYNOPSIS

kiwi [global options] service <command> [<args>]
kiwi result list -h | --help
kiwi result list --target-dir=<directory>
kiwi result list help

  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

  OPTIONS

--target-dir=<directory>
    directory containing the kiwi build results

  kiwi result bundle

  SYNOPSIS

kiwi [global options] service <command> [<args>]
kiwi result bundle -h | --help
kiwi result bundle --target-dir=<directory> --id=<bundle_id> --bundle-dir=<directory>
kiwi result bundle help

  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.

  OPTIONS

--bundle-dir=<directory>
    directory containing the bundle results, compressed versions of image results and their sha sums

--id=<bundle_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>
    directory containing the kiwi build results

  kiwi system prepare

  SYNOPSIS

kiwi [global options] service <command> [<args>]
kiwi system prepare -h | --help
kiwi system prepare --description=<directory> --root=<directory>
    [--allow-existing-root]
    [--ignore-repos]
    [--set-repo=<source,type,alias,priority>]
    [--add-repo=<source,type,alias,priority>...]
    [--obs-repo-internal]
    [--add-package=<name>...]
    [--delete-package=<name>...]
kiwi system prepare help

  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

  OPTIONS

--add-package=<name>
    specify package to add(install). The option can be specified multiple times

--add-repo=<source,type,alias,priority>
    See the kiwi::system::build manual page for further details

--allow-existing-root
    allow to re-use an existing image root directory

--delete-package=<name>
    specify package to delete. The option can be specified multiple times

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

--obs-repo-internal
    See the kiwi::system::build manual page for further details

--root=<directory>
    Path to create the new root system.

--set-repo=<source,type,alias,priority>
    See the kiwi::system::build manual page for further details

  kiwi system create

  SYNOPSIS

kiwi [global options] service <command> [<args>]
kiwi system create -h | --help
kiwi system create --root=<directory> --target-dir=<directory>
kiwi system create help

  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

  OPTIONS

--root=<directory>
    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=<directory>
    Path to store the build results.

  kiwi system update

  SYNOPSIS

kiwi [global options] service <command> [<args>]
kiwi system update -h | --help
kiwi system update --root=<directory>
    [--add-package=<name>...]
    [--delete-package=<name>...]
kiwi system update help

  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

  OPTIONS

--add-package=<name>
    specify package to add(install). The option can be specified multiple times

--delete-package=<name>
    specify package to delete. The option can be specified multiple times

--root=<directory>
    Path to the root directory of the image.

  kiwi system build

  SYNOPSIS

kiwi [global options] service <command> [<args>]
kiwi system build -h | --help
kiwi system build --description=<directory> --target-dir=<directory>
    [--ignore-repos]
    [--set-repo=<source,type,alias,priority>]
    [--add-repo=<source,type,alias,priority>...]
    [--obs-repo-internal]
    [--add-package=<name>...]
    [--delete-package=<name>...]
kiwi system build help

  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.

  OPTIONS

--add-package=<name>
    specify package to add(install). The option can be specified multiple times

--add-repo=<source,type,alias,priority>
    Add a new repository to the existing repository setup in the XML description. This option can be specified multiple times

--delete-package=<name>
    specify package to delete. The option can be specified multiple times

--description=<directory>
    Path to the XML description. This is a directory containing at least one _config.xml_ or _*.kiwi_ XML file.

--obs-repo-internal
    The repository source type obs:// by default points to the Open Build Service. With the --obs-repo-internal option the source type is changed to the ibs:// type, pointing to the Internal Build Service. This allows to build images with repositories pointing to the SUSE internal build service. Please note this requires access permissions to the SUSE internal build service on the machine building the image.

--set-repo=<source,type,alias,priority>
    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.

--target-dir=<directory>
    Path to store the build results.

  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

COMPATIBILITY

This version of KIWI uses a different caller syntax compared to former versions. However there is a compatibility mode which allows to use a legacy KIWI commandline as follows:

$ kiwi --compat -- \
    --build kiwi-descriptions/suse/x86_64/suse-leap-42.1-JeOS \
    --type vmx -d /tmp/myimage

AUTHOR
Marcus Schäfer

COPYRIGHT
2016, Marcus Schäfer