Skip to content
This repository
tree: afd1e38f9c
Fetching contributors…

Cannot retrieve contributors at this time

file 417 lines (417 sloc) 20.438 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417
'\" t
.\" Title: kiwi
.\" Author: Marcus Schaefer <ms (AT) suse.de>
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: Created: 07/16/2012
.\" Manual: KIWI Manualpage
.\" Source: KIWI 5.03
.\" Language: English
.\"
.TH "KIWI" "1" "Created: 07/16/2012" "KIWI 5\&.03" "KIWI Manualpage"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
kiwi \- Creating Operating System Images
.SH "SYNOPSIS"
.HP \w'\fBkiwi\fR\ 'u
\fBkiwi\fR {\-l | \-\-list}
.HP \w'\fBkiwi\fR\ 'u
\fBkiwi\fR {\-o | \-\-clone} \fIimage\-path\fR {\-d} \fIdestination\fR
.HP \w'\fBkiwi\fR\ 'u
\fBkiwi\fR {\-b | \-\-build} \fIimage\-path\fR {\-d} \fIdestination\fR
.SH "BASICS"
.PP
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
\fIJust enough Operating System\fR\&. 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\&.
.PP
Detailed description of the kiwi image system exists in the system design document in
\m[blue]\fB\%file:///usr/share/doc/packages/kiwi/kiwi.pdf\fR\m[]\&. KIWI always operates in two steps\&. The KIWI
\fB\-\-build\fR
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
\fBkiwi\fR
\fB\-\-clone\fR
command\&.
.PP
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\&.
.SH "IMAGE PREPARATION AND CREATION"
.HP \w'\fBkiwi\fR\ 'u
\fBkiwi\fR {\-p | \-\-prepare} \fIimage\-path\fR
.br
[\-r | \-\-root\fIimage\-root\fR | \-\-cache\fIdirectory\fR]
.HP \w'\fBkiwi\fR\ 'u
\fBkiwi\fR {\-c | \-\-create} \fIimage\-root\fR
.br
{\-d | \-\-destdir\fIdestination\fR} [\-\-type\ \fIimage\-type\fR]
.SH "IMAGE UPGRADE"
.PP
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\&.
.HP \w'\fBkiwi\fR\ 'u
\fBkiwi\fR {\-u | \-\-upgrade} \fIimage\-root\fR [\-\-add\-package\fIname\fR] [\-\-add\-pattern\fIname\fR]
.SH "SYSTEM TO IMAGE MIGRATION"
.PP
The migration module allows you to migrate your currently running system into an image description\&. The module will check for files not managed by a package manager and also inspects your system for package pattern and file consistency according to the currently active repositories\&. The system requires the zypper backend in order to work properly\&.
.PP
The migration process creates a cache file so that subsequent calls of the migration 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
\fB\-\-nofiles\fR
will prevent the system from searching for unpackaged and packaged but modified files The option
\fB\-\-notemplate\fR
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 migration\&. With the options
\fB\-\-exclude\fR
and
\fB\-\-skip\fR
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 migrated or can be restored easily later inside the cloned image like software repositories\&.
.PP
The migration process will always place it\'s result into the
/tmp/$OptionValueOf\-m
directory\&. The reason for this is because
/tmp
is always excluded from the migration operation and therefore we can safely place new files there without influencing the migration 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\&.
.PP
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 migrated image 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 migrate running servers into images\&. The implementation is still under construction so expect better migration results in future releases :)
.HP \w'\fBkiwi\fR\ 'u
\fBkiwi\fR {\-m | \-\-migrate} \fIname\fR [\-\-exclude\ \fIdirectory\fR...] [\-\-skip\ \fIpackage\fR...] [\-\-nofiles] [\-\-notemplate]
.SH "IMAGE POSTPROCESSING MODES"
.PP
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\&.
.HP \w'\fBkiwi\fR\ 'u
\fBkiwi\fR \-\-bootvm\ \fIinitrd\fR \-\-bootvm\-system\ \fIsystemImage\fR [\-\-bootvm\-disksize\ \fIsize\fR]
.HP \w'\fBkiwi\fR\ 'u
\fBkiwi\fR \-\-bootcd\ \fIinitrd\fR
.HP \w'\fBkiwi\fR\ 'u
\fBkiwi\fR \-\-installcd\ \fIinitrd\fR \-\-installcd\-system\ \fIvmx\-system\-image\fR
.HP \w'\fBkiwi\fR\ 'u
\fBkiwi\fR \-\-installstick\ \fIinitrd\fR \-\-installstick\-system\ \fIvmx\-system\-image\fR
.SH "IMAGE FORMAT CONVERSION"
.PP
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
.HP \w'\fBkiwi\fR\ 'u
\fBkiwi\fR \-\-convert\ \fIsystemImage\fR [\-\-format\ \fIvmdk|ovf|qcow2|vhd\fR]
.SH "HELPER TOOLS"
.PP
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\&.
.HP \w'\fBkiwi\fR\ 'u
\fBkiwi\fR \-\-createpassword
.HP \w'\fBkiwi\fR\ 'u
\fBkiwi\fR \-\-createhash\ \fIimage\-path\fR
.HP \w'\fBkiwi\fR\ 'u
\fBkiwi\fR {\-i | \-\-info} \fIImagePath\fR {\-\-select\ \fI\ repo\-patterns|patterns|types|sources|size|profiles|packages|version\ \fR}
.HP \w'\fBkiwi\fR\ 'u
\fBkiwi\fR \-\-setup\-splash\ \fIinitrd\fR
.PP
The following list describes the helper tools more detailed
.PP
[\fB\-\-createpassword\fR]
.RS 4
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
.RE
.PP
[\fB\-\-createhash \fR\fB\fIimage\-path\fR\fR ]
.RS 4
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\&.
.RE
.PP
[ \fB\-i\fR | \fB\-\-info \fR\fB\fIimage\-path\fR\fR \fB\-\-select \fR\fB\fIselection\fR\fR ]
.RS 4
List general information about the image description\&. So far you can get information about the available patterns in the configured repositories with
\fIrepo\-patterns\fR, a list of used patterns for this image with
\fIpatterns\fR, a list of supported image types with
\fItypes\fR, a list of source URLs with
\fIsources\fR, an estimation about the install size and the size of the packages marked as to be deleted with
\fIsize\fR, a list of profiles with
\fIprofiles\fR, a list of solved packages to become installed with
\fIpackages\fR, and the information about the appliance name and version with
\fIversion\fR
.RE
.PP
[\fB\-\-setup\-splash \fR\fB\fIinitrd\fR\fR ]
.RS 4
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
.RE
.SH "GLOBAL OPTIONS"
.PP
[\fB\-\-add\-profile\fR \fIprofile\-name\fR]
.RS 4
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\&.
.RE
.PP
[\fB\-\-set\-repo\fR \fIURL\fR]
.RS 4
Set/Overwrite repo URL for the first listed repo\&. The change is temporary and will not be written to the XML file\&.
.RE
.PP
[\fB\-\-set\-repotype\fR \fItype\fR]
.RS 4
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\&.
.RE
.PP
[\fB\-\-set\-repoalias\fR \fIname\fR]
.RS 4
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
\(lq/\(rq
with a
\(lq_\(rq\&. 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\&.
.RE
.PP
[\fB\-\-set\-repoprio\fR \fInumber\fR]
.RS 4
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\&.
.RE
.PP
[\fB\-\-add\-repo \fR\fB\fIURL\fR\fR, \fB\-\-add\-repotype \fR\fB\fItype\fR\fR \fB\-\-add\-repoalias \fR\fB\fIname\fR\fR \fB\-\-add\-repoprio \fR\fB\fInumber\fR\fR ]
.RS 4
Add the given repository and type for this run of an image prepare or upgrade process\&. Multiple
\fB\-\-add\-repo\fR/\fB\-\-add\-repotype\fR
options are possible\&. The change will not be written to the
config\&.xml
file
.RE
.PP
[\fB\-\-ignore\-repos\fR]
.RS 4
Ignore all repositories specified so far, in XML or elsewhere\&. This option should be used in conjunction with subsequent calls to
\fB\-\-add\-repo\fR
to specify repositories at the commandline that override previous specifications\&.
.RE
.PP
[\fB\-\-logfile \fR\fB\fIFilename\fR\fR | \fBterminal\fR]
.RS 4
Write to the log file
\fIFilename\fR
instead of the terminal\&.
.RE
.PP
[\fB\-\-gzip\-cmd \fR\fB\fIcmd\fR\fR]
.RS 4
Specify an alternate command to run when compressing boot and system images\&. Command must accept
\fBgzip\fR
options\&.
.RE
.PP
[\fB\-\-log\-port \fR\fB\fIPortNumber\fR\fR]
.RS 4
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\&.
.RE
.PP
[\fB\-\-package\-manager \fR\fB\fIsmart|zypper\fR\fR ]
.RS 4
Set the package manager to use for this image\&. If set it will temporarily overwrite the value set in the xml description\&.
.RE
.PP
[\fB\-A\fR | \fB\-\-target\-arch \fR\fB\fIi586|x86_64|armv5tel|ppc\fR\fR ]
.RS 4
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\&.
.RE
.PP
[\fB\-\-debug\fR]
.RS 4
Prints a stack trace in case of internal errors
.RE
.PP
[\fB\-\-verbose \fR\fB\fI1|2|3\fR\fR ]
.RS 4
Controls the verbosity level for the instsource module
.RE
.SH "IMAGE PREPARATION OPTIONS"
.PP
[\fB\-r\fR | \fB\-\-root \fR\fB\fIRootPath\fR\fR]
.RS 4
Set up the physical extend, chroot system below the given root\-path path\&. If no
\fB\-\-root\fR
option is given, KIWI will search for the attribute defaultroot in
config\&.xml\&. If no root directory is known, a
\fBmktemp\fR
directory will be created and used as root directory\&.
.RE
.PP
[\fB\-\-force\-new\-root\fR]
.RS 4
Force creation of new root directory\&. If the directory already exists, it is deleted\&.
.RE
.SH "IMAGE UPGRADE/PREPARATION OPTIONS"
.PP
[\fB\-\-cache\fR \fIdirectory\fR ]
.RS 4
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
.RE
.PP
[\fB\-\-add\-package\fR \fIpackage\fR ]
.RS 4
Add the given package name to the list of image packages multiple
\fB\-\-add\-package\fR
options are possible\&. The change will not be written to the XML description\&.
.RE
.PP
[\fB\-\-add\-pattern\fR \fIname\fR ]
.RS 4
Add the given pattern name to the list of image packages multiple
\fB\-\-add\-pattern\fR
options are possible\&. The change will not be written to the xml description\&. Patterns can be handled by SUSE based repositories only\&.
.RE
.PP
[\fB\-\-del\-package\fR \fIpackage\fR ]
.RS 4
Removes the given package by adding it the list of packages to become removed\&. The change will not be written to the xml description\&.
.RE
.SH "IMAGE CREATION OPTIONS"
.PP
[\fB\-d\fR | \fB\-\-destdir \fR\fB\fIDestinationPath\fR\fR]
.RS 4
Specify destination directory to store the image file(s) If not specified, KIWI will try to find the attribute
\fIdefaultdestination\fR
which can be specified in the
\fIpreferences\fR
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\&.
.RE
.PP
[\fB\-t\fR | \fB\-\-type \fR\fB\fIImagetype\fR\fR]
.RS 4
Specify the output image type to use for this image\&. Each type is described in a
\fItype\fR
section of the preferences section\&. At least one type has to be specified in the
config\&.xml
description\&. By default, the types specifying the
\fIprimary\fR
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
\fB\-\-create\fR
step\&. With the option
\fB\-\-type\fR
one can distinguish between the types stored in
config\&.xml
.RE
.PP
[\fB\-s\fR | \fB\-\-strip\fR]
.RS 4
Strip shared objects and executables \- only makes sense in combination with
\fB\-\-create\fR
.RE
.PP
[\fB\-\-prebuiltbootimage \fR\fB\fIDirectory\fR\fR]
.RS 4
Search in
\fIDirectory\fR
for pre\-built boot images\&.
.RE
.PP
[\fB\-\-isocheck\fR]
.RS 4
in case of an iso image the checkmedia program generates a md5sum into the ISO header\&. If the
\fB\-\-isocheck\fR
option is specified a new boot menu entry will be generated which allows to check this media
.RE
.PP
[\fB\-\-lvm\fR]
.RS 4
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
.RE
.PP
[\fB\-\-fs\-blocksize \fR\fB\fInumber\fR\fR ]
.RS 4
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
.RE
.PP
[\fB\-\-fs\-journalsize \fR\fB\fInumber\fR\fR ]
.RS 4
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
.RE
.PP
[\fB\-\-fs\-inodesize \fR\fB\fInumber\fR\fR ]
.RS 4
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
.RE
.PP
[\fB\-\-fs\-inoderatio \fR\fB\fInumber\fR\fR ]
.RS 4
Set the bytes/inode ratio\&. This option has no effect if the reiser filesystem is used
.RE
.PP
[\fB\-\-fs\-max\-mount\-count \fR\fB\fInumber\fR\fR ]
.RS 4
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\&.
.RE
.PP
[\fB\-\-fs\-check\-interval \fR\fB\fInumber\fR\fR ]
.RS 4
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\&.
.RE
.PP
[\fB\-\-fat\-storage \fR\fB\fIsize in MB\fR\fR ]
.RS 4
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)
.RE
.PP
[\fB\-\-partitioner \fR\fB\fIparted|fdasd\fR\fR ]
.RS 4
Select the tool to create partition tables\&. Supported are parted and fdasd (s390)\&. By default parted is used
.RE
.PP
[\fB\-\-check\-kernel\fR]
.RS 4
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\&.
.RE
.PP
[\fB\-\-mbrid \fR\fB\fInumber\fR\fR]
.RS 4
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
.RE
.PP
[\fB\-\-edit\-bootconfig \fR\fB\fIscript\fR\fR]
.RS 4
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\&.
.RE
.SH "FOR MORE INFORMATION"
.PP
More information about KIWI, its files can be found at:
.PP
\m[blue]\fB\%http://en.opensuse.org/Portal:KIWI\fR\m[]
.RS 4
KIWI wiki
.RE
.PP
config\&.xml
.RS 4
The configuration XML file that contains every aspect for the image creation\&.
.RE
.PP
\m[blue]\fB\%file:///usr/share/doc/packages/kiwi/kiwi.pdf\fR\m[]
.RS 4
The system design document which describes some details about the building process\&.
.RE
.PP
\m[blue]\fB\%file:///usr/share/doc/packages/kiwi/schema/kiwi.xsd.html\fR\m[]
.RS 4
The KIWI RELAX\ \&NG XML Schema documentation\&.
.RE
.PP
\m[blue]\fB\%file:///usr/share/doc/packages/kiwi/schema/test.xsd.html\fR\m[]
.RS 4
The KIWI RELAX\ \&NG XML Schema documentation\&.
.RE
.SH "AUTHOR"
.PP
\fBMarcus Schaefer\fR <\&ms (AT) suse\&.de\&>
.RS 4
Developer
.RE
Something went wrong with that request. Please try again.