KIWI(1) KIWI Manualpage KIWI(1)NAMEkiwi - Creating Operating System Images
SYNOPSISkiwi {-l | --list}
kiwi {-o | --clone} image-path {-d} destination
kiwi {-b | --build} image-path {-d} destination
BASICS
KIWI is a complete imaging solution that is based on an image
description. Such a description is represented by a directory which
includes at least one config.xml file and may as well include other
files like scripts or configuration data. The kiwi-templates package
provides example descriptions based on a JeOS system. JeOS means Just
enough Operating System. KIWI provides image templates based on that
axiom which means 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.
Detailed description of the kiwi image system exists in the system
design document in file:///usr/share/doc/packages/kiwi/kiwi.pdf. KIWI
always operates in two steps. The KIWI --build option just 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. If you have started with an example and want to add you own
changes it might be a good idea to clone of from this example. This can
be done by simply copying the entire image description or you can let
KIWI do that for you by using the kiwi--clone command.
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. If the image type ISO was requested, the output image would be a
file with the suffix .iso representing a live system on CD or DVD.
Other than that KIWI is able to create images for virtual and
para-virtual (Xen) environments as well as for USB stick, PXE network
clients and OEM customized Linux systems.
IMAGE PREPARATION AND CREATIONkiwi {-p | --prepare} image-path
[-r | --rootimage-root | --cachedirectory]
kiwi {-c | --create} image-root
{-d | --destdirdestination} [--type image-type]
IMAGE UPGRADE
If the image root tree is stored and not removed, it can be used for
upgrading the image according to the changes made in the repositories
used for this image. If a distributor provides an update channel for
package updates and an image config.xml includes this update channel as
repository, it is useful to store the image root tree and upgrade the
tree according to changes on the update channel. Given that the root
tree exists it's also possible to add or remove software and recreate
the image of the desired type.
kiwi {-u | --upgrade} image-root [--add-packagename]
[--add-patternname]
SYSTEM ANALYSIS/MIGRATION
KIWI provides a module which allows you to analyse the running system
and create a report and an image description representing the current
state of the machine. Among others this allows you to clone your
currently running system into an image. The system requires the zypper
backend in order to work properly.
The process creates a cache file so that subsequent calls of the
analysis runs much faster. Please have in mind that if your system has
changed (files created/deleted, etc.) the cache file might not be worth
to become reused. In this case you should remove the cache first and
start from scratch. The option --nofiles will prevent the system from
searching for unpackaged and packaged but modified files The option
--notemplate will prevent the creation of the image description files
which are needed if you want to use KIWI to create a clone image from
the result of the analysis. With the options --exclude and --skip you
can tell the system to ignore specific directories and/or packages.
This makes sense if you know before that some data is not worth to
become handled or can be restored easily later inside the cloned image
like software repositories.
The process will always place it's result into the
/tmp/$OptionValueOf--describe directory. The reason for this is because
/tmp is always excluded from the analysis and therefore we can safely
place new files there without influencing the process itself. You
should have at least 50 MB free space for the cache file and the image
description all the rest are just hard links.
As one result a HTML based report file is created which contains
important information about the system. You are free to ignore that
information but with the risk that the image from that description does
not represent the same system which is running at the moment. The less
issues left in the report the better is the result. In most cases a
manual fine tuning is required. This includes the repository selection
and the unmanaged files along with the configuration details of your
currently running operating system. You should understand the module as
a helper to analyse running servers.
kiwi {--describe} name [--exclude directory...] [--skip package...]
[--nofiles] [--notemplate]
IMAGE POSTPROCESSING MODES
The KIWI post-processing modes are used for special image deployment
tasks, like installing the image on a USB stick. So to say they are the
third step after preparation and creation. KIWI calls the
postprocessing modules automatically according to the specified output
image type and attributes but it's also possible to call them manually.
kiwi--bootvm initrd --bootvm-system systemImage
[--bootvm-disksize size]
kiwi--bootcd initrd
kiwi--installcd initrd --installcd-system vmx-system-image
kiwi--installstick initrd --installstick-system vmx-system-image
IMAGE FORMAT CONVERSION
The KIWI format conversion is useful to perform the creation of another
image output format like vmdk for VMware or ovf the open virtual
machine format. Along with the conversion KIWI also creates the virtual
machine configuration according to the format if there is a machine
section specified in the XML description
kiwi--convert systemImage [--format vmdk|ovf|qcow2|vhd]
HELPER TOOLS
The helper tools provide optional functions like creating a crypted
password string for the users section of the config.xml file as well as
signing the image description with an md5sum hash and adding splash
data to the boot image used by the bootloader.
kiwi--createpassword
kiwi--createhash image-path
kiwi {-i | --info} ImagePath
{--select repo-patterns|patterns|types|sources|size|profiles|packages|version }
kiwi--setup-splash initrd
The following list describes the helper tools more detailed
[--createpassword]
Create a crypted password hash and prints it on the console. The
user can use the string as value for the pwd attribute in the XML
users section
[--createhash image-path ]
Sign your image description with a md5sum. The result is written to
a file named .checksum.md and is checked if KIWI creates an image
from this description.
[ -i | --info image-path --select selection ]
List general information about the image description. So far you
can get information about the available patterns in the configured
repositories with repo-patterns, a list of used patterns for this
image with patterns, a list of supported image types with types, a
list of source URLs with sources, an estimation about the install
size and the size of the packages marked as to be deleted with
size, a list of profiles with profiles, a list of solved packages
to become installed with packages, and the information about the
appliance name and version with version
[--setup-splash initrd ]
Create splash screen from the data inside the initrd and re-create
the initrd with the splash screen attached to the initrd cpio
archive. This enables the kernel to load the splash screen at boot
time. If splashy is used only a link to the original initrd will be
created
GLOBAL OPTIONS
[--add-profile profile-name]
Use the specified profile. A profile is a part of the XML image
description and therefore can enhance each section with additional
information. For example adding packages.
[--set-repo URL]
Set/Overwrite the repo URL for the first repo listed in the
configuration file that does not have a "fixed" status. The change
is temporary and will not be written to the XML file.
[--set-repotype type]
Set/Overwrite repo type for the first listed repo. The supported
repo types depends on the packagemanager. Commonly supported are
rpm-md, rpm-dir and yast2. The change is temporary and will not be
written to the XML file.
[--set-repoalias name]
Set/Overwrite alias name for the first listed repo. Alias names are
optional free form text. If not set the source attribute value is
used and builds the alias name by replacing each “/” with a “_”. An
alias name should be set if the source argument doesn't really
explain what this repository contains. The change is temporary and
will not be written to the XML file.
[--set-repoprio number]
Set/Overwrite priority for the first listed repo. Works with the
smart packagemanager only. The Channel priority assigned to all
packages available in this channel (0 if not set). If the exact
same package is available in more than one channel, the highest
priority is used.
[--add-repo URL, --add-repotype type --add-repoalias name
--add-repoprio number ]
Add the given repository and type for this run of an image prepare
or upgrade process. Multiple --add-repo/--add-repotype options are
possible. The change will not be written to the config.xml file
[--ignore-repos]
Ignore all repositories specified so far, in XML or elsewhere. This
option should be used in conjunction with subsequent calls to
--add-repo to specify repositories at the commandline that override
previous specifications.
[--logfile Filename | terminal]
Write to the log file Filename instead of the terminal.
[--gzip-cmd cmd]
Specify an alternate command to run when compressing boot and
system images. Command must accept gzip options.
[--log-port PortNumber]
Set the log server port. By default port 9000 is used. If multiple
KIWI processes runs on one system it's recommended to set the
logging port per process.
[--package-manager smart|zypper ]
Set the package manager to use for this image. If set it will
temporarily overwrite the value set in the xml description.
[-A | --target-arch i586|x86_64|armv5tel|ppc ]
Set a special target-architecture. This overrides the used
architecture for the image-packages in zypp.conf. When used with
smart this option doesn't have any effect.
[--debug]
Prints a stack trace in case of internal errors
[--verbose 1|2|3 ]
Controls the verbosity level for the instsource module
IMAGE PREPARATION OPTIONS
[-r | --root RootPath]
Set up the physical extend, chroot system below the given root-path
path. If no --root option is given, KIWI will search for the
attribute defaultroot in config.xml. If no root directory is known,
a mktemp directory will be created and used as root directory.
[--force-new-root]
Force creation of new root directory. If the directory already
exists, it is deleted.
IMAGE UPGRADE/PREPARATION OPTIONS
[--cache directory ]
When specifying a cache directory, KIWI will create a cache each
for patterns and packages and re-use them, if possible, for
subsequent root tree preparations of this and/or other images
[--add-package package ]
Add the given package name to the list of image packages multiple
--add-package options are possible. The change will not be written
to the XML description.
[--add-pattern name ]
Add the given pattern name to the list of image packages multiple
--add-pattern options are possible. The change will not be written
to the xml description. Patterns can be handled by SUSE based
repositories only.
[--del-package package ]
Removes the given package by adding it the list of packages to
become removed. The change will not be written to the xml
description.
IMAGE CREATION OPTIONS
[-d | --destdir DestinationPath]
Specify destination directory to store the image file(s) If not
specified, KIWI will try to find the attribute defaultdestination
which can be specified in the preferences section of the config.xml
file. If it exists its value is used as destination directory. If
no destination information can be found, an error occurs.
[-t | --type Imagetype]
Specify the output image type to use for this image. Each type is
described in a type section of the preferences section. At least
one type has to be specified in the config.xml description. By
default, the types specifying the primary attribute will be used.
If there is no primary attribute set, the first type section of the
preferences section is the primary type. The types are only
evaluated when KIWI runs the --create step. With the option --type
one can distinguish between the types stored in config.xml
[-s | --strip]
Strip shared objects and executables - only makes sense in
combination with --create
[--prebuiltbootimage Directory]
Search in Directory for pre-built boot images.
[--isocheck]
in case of an iso image the checkmedia program generates a md5sum
into the ISO header. If the --isocheck option is specified a new
boot menu entry will be generated which allows to check this media
[--lvm]
Use the logical volume manager to control the disk. The partition
table will include one lvm partition and one standard ext2 boot
partition. Use of this option makes sense for the create step only
and also only for the image types: vmx, oem, and usb
[--fs-blocksize number ]
When calling KIWI in creation mode this option will set the block
size in bytes. For ISO images with the old style ramdisk setup a
blocksize of 4096 bytes is required
[--fs-journalsize number ]
When calling KIWI in creation mode this option will set the journal
size in mega bytes for ext[23] based filesystems and in blocks if
the reiser filesystem is used
[--fs-inodesize number ]
When calling KIWI in creation mode this option will set the inode
size in bytes. This option has no effect if the reiser filesystem
is used
[--fs-inoderatio number ]
Set the bytes/inode ratio. This option has no effect if the reiser
filesystem is used
[--fs-max-mount-count number ]
When calling kiwi in creation mode this option will set the number
of mounts after which the filesystem will be checked. Set to 0 to
disable checks. This option applies only to ext[234] filesystems.
[--fs-check-interval number ]
When calling kiwi in creation mode this option will set the maximal
time between two filesystem checks. Set to 0 to disable
time-dependent checks. This option applies only to ext[234]
filesystems.
[--fat-storage size in MB ]
if the syslinux bootlaoder is used this option allows to specify
the size of the fat partition. This is useful if the fat space is
not only used for booting the system but also for custom data.
Therefore this option makes sense when building a USB stick image
(image type: usb or oem)
[--partitioner parted|fdasd ]
Select the tool to create partition tables. Supported are parted
and fdasd (s390). By default parted is used
[--check-kernel]
Activates check for matching kernels between boot and system image.
The kernel check also tries to fix the boot image if no matching
kernel was found.
[--mbrid number]
Specifies a custom mbrid. The number value is treated as decimal
number which is internally translated into a 4byte hex value. The
allowed range therefore is from 0x0 to max 0xffffffff. By default
kiwi creates a random value
[--edit-bootconfig script]
Specifies the location of a custom script which is called right
before the bootloader is installed. This allows to modify the
bootloader configuration file written by kiwi. The scripts working
directory is the one which represents the image structure including
the bootloader configuration files. Please have in mind that
according to the image type, architecture and bootloader type the
files/directory structure and also the name of the bootloader
configuration files might be different.
FOR MORE INFORMATION
More information about KIWI, its files can be found at:
http://en.opensuse.org/Portal:KIWI
KIWI wiki
config.xml
The configuration XML file that contains every aspect for the image
creation.
file:///usr/share/doc/packages/kiwi/kiwi.pdf
The system design document which describes some details about the
building process.
file:///usr/share/doc/packages/kiwi/schema/kiwi.xsd.html
The KIWI RELAX NG XML Schema documentation.
file:///usr/share/doc/packages/kiwi/schema/test.xsd.html
The KIWI RELAX NG XML Schema documentation.
AUTHOR
Marcus Schaefer <ms (AT) suse.de>
Developer
KIWI 5.05 Created: 10/10/2013 KIWI(1)
