1KIWI(8) kiwi KIWI(8)
2
6 kiwi - Creating Operating System Images
7
9 kiwi [global options] service <command> [<args>]
10 kiwi -h | --help
12 kiwi [--profile=<name>...]
13 [--type=<build_type>]
14 [--logfile=<filename>]
15 [--debug]
16 [--color-output]
17 image <command> [<args>...]
18 kiwi [--debug]
19 [--color-output]
20 result <command> [<args>...]
21 kiwi [--profile=<name>...]
22 [--shared-cache-dir=<directory>]
23 [--type=<build_type>]
24 [--logfile=<filename>]
25 [--debug]
26 [--color-output]
27 system <command> [<args>...]
28 kiwi compat <legacy_args>...
29 kiwi -v | --version
30 kiwi help
31
33 KIWI is an imaging solution that is based on an image XML description.
34 Such a description is represented by a directory which includes at
35 least one config.xml or .kiwi file and may as well include other files
36 like scripts or configuration data.
37 A collection of example image descriptions can be found on the github
39 repository here: https://github.com/OSInside/kiwi-descriptions. Most of
40 the descriptions provide a so called JeOS image. JeOS means Just enough
41 Operating System. A JeOS is a small, text only based image including a
42 predefined remote source setup to allow installation of missing soft‐
43 ware components at a later point in time.
44 KIWI operates in two steps. The system build command combines both
46 steps into one to make it easier to start with KIWI. The first step is
47 the preparation step and if that step was successful, a creation step
48 follows which is able to create different image output types.
49 In the preparation step, you prepare a directory including the contents
51 of your new filesystem based on one or more software package source(s)
52 The creation step is based on the result of the preparation step and
53 uses the contents of the new image root tree to create the output
54 image.
55 KIWI supports the creation of the following image types:
57 · ISO Live Systems
59 · Virtual Disk for e.g cloud frameworks
61 · OEM Expandable Disk for system deployment from ISO or the network
63 · File system images for deployment in a pxe boot environment
65 Depending on the image type a variety of different disk formats and
67 architectures are supported.
68
70 --color-output
71 Use Escape Sequences to print different types of information in
72 colored output. The underlaying terminal has to understand those
73 escape characters. Error messages appear red, warning messages
74 yellow and debugging information will be printed light grey.
75 --debug
77 Print debug information on the commandline.
78 --logfile=<filename>
80 Specify log file. the logfile contains detailed information
81 about the process.
82 --profile=<name>
84 Select profile to use. The specified profile must be part of the
85 XML description. The option can be specified multiple times to
86 allow using a combination of profiles
87 --shared-cache-dir=<directory>
89 Specify an alternative shared cache directory. The directory is
90 shared via bind mount between the build host and image root sys‐
91 tem and contains information about package repositories and
92 their cache and meta data. The default location is set to
93 /var/cache/kiwi
94 --type=<build_type>
96 Select image build type. The specified build type must be con‐
97 figured as part of the XML description.
98 --version
100 Show program version
101
103 $ git clone https://github.com/OSInside/kiwi-descriptions
104 $ kiwi --type vmx system build \
106 --description kiwi-descriptions/suse/x86_64/suse-leap-15.1-JeOS \
107 --target-dir /tmp/myimage
108
110 KIWI supports an additional configuration file for runtime specific
111 settings that do not belong into the image description but which are
112 persistent and would be unsuitable for command line parameters.
113 The runtime configuration file must adhere to the YAML syntax. KIWI
115 searches for the runtime configuration file in the following locations:
116 1. ~/.config/kiwi/config.yml
118 2. /etc/kiwi.yml
120 The parameters that can be changed via the runtime configuration file
122 are illustrated in the following example:
123 xz:
125 # Additional command line flags for `xz`
126 # see `man xz` for details
127 - options: -9e
128 obs:
130 # Override the URL to the Open Build Service (i.e. how repository
131 # paths starting with `obs://` will be resolved).
132 # This setting is useful for building a KIWI appliance locally, which is
133 # hosted on a custom OBS instance.
134 # defaults to: http://download.opensuse.org/repositories
135 - download_url: https://build.my-domain.example/repositories
136 # Specifies whether the Open Build Service instance is public or
138 # private
139 # defaults to true
140 - public: true | false
141 bundle:
143 # Configure whether the image bundle should contain a XZ compressed
144 # image result or not.
145 - compress: true | false
146 container:
148 # Specify the compression algorithm for compressing container
149 # images. Invalid entries are skipped.
150 # Defaults to `xz`.
151 - compress: xz | none
152 iso:
154 # Configure which tool KIWI will use to build ISO images. Invalid
155 # entries are ignored.
156 # Defaults to `xorriso`
157 - tool_category: cdrtools | xorriso
158 oci:
160 # Specify the OCI archive tool that will be used to create container
161 # archives for OCI compliant images.
162 # Defaults to `umoci`.
163 - archive_tool: umoci | buildah
164 build_constraints:
166 # Configure the maximum image size. Either provide a number in bytes
167 # or specify it with the suffix `m`/`M` for megabytes or `g`/`G` for
168 # gigabytes.
169 # If the resulting image exceeds the specified value, then KIWI will
170 # abort with an error.
171 # The default is no size constraint.
172 - max_size: 700m
173 runtime_checks:
175 # Provide a list of runtime checks that should be disabled. Checks
176 # that do not exist but are present in this list are silently
177 # ignored.
178 - disable: check_image_include_repos_publicly_resolvable | \
179 check_target_directory_not_in_shared_cache | \
180 check_volume_label_used_with_lvm | \
181 check_volume_setup_defines_multiple_fullsize_volumes | \
182 check_volume_setup_has_no_root_definition | \
183 check_container_tool_chain_installed | \
184 check_boot_description_exists | \
185 check_consistent_kernel_in_boot_and_system_image | \
186 check_dracut_module_for_oem_install_in_package_list | \
187 check_dracut_module_for_disk_oem_in_package_list | \
188 check_dracut_module_for_live_iso_in_package_list | \
189 check_dracut_module_for_disk_overlay_in_package_list | \
190 check_efi_mode_for_disk_overlay_correctly_setup | \
191 check_xen_uniquely_setup_as_server_or_guest | \
192 check_mediacheck_only_for_x86_arch | \
193 check_minimal_required_preferences
194
196 This version of KIWI uses a different caller syntax compared to former
197 versions. However there is a compatibility mode which allows to use a
198 legacy KIWI commandline as follows:
199 $ kiwi compat \
201 --build kiwi-descriptions/suse/x86_64/suse-leap-15.1-JeOS \
202 --type vmx -d /tmp/myimage
203
205 Marcus Schäfer
206
208 2019, Marcus Schäfer
2099.19.5 Dec 02, 2019 KIWI(8)