Allows setup of the boot menu title for the selected boot loader. So you can have suse-SLED-foo as the image name but a different name as the boot display name. Spaces are not allowed in the display name because it causes problems for some boot loaders and kiwi did not take the effort to separate the ones which can display them correctly from the ones which can't

specifies a KIWI git revision number which is known to build a working image from this description. If the KIWI git revision doesn't match the specified value, the process will exit. The currently used git revision can be queried by calling kiwi --version.

sets an identification number which appears as file /etc/ImageID within the image.

Use the lxc or docker image type to build a linux container image. For additional information refer to the Chapter 9, Docker images chapter.

Use one of the following image types to build a plain filesystem image. This will create a file containing the data in the specified filesystem and you can loop mount the image to view the contents e.g image="ext3":

Use the tbz image type to just pack the unpacked image tree into a tarball.

Use the cpio image type to specify the generation of a boot image (initrd). When generating a boot image, it is possible to specify a specific boot profile and boot kernel using the optional bootprofile="default" and bootkernel="std" attributes.

A boot image should group the various supported kernels into profiles. If the user chooses not to use the profiles supplied by KIWI, it is required that one profile named std be created. This profile will be used if no other bootkernel is specified. Further it is required to create a profile named default. This profile is used when no bootprofile is specified.

It is recommended that special configurations that omit drivers, use special drivers and/or special packages be specified as profiles.

The bootprofile and bootkernel attribute are respected within the definition of a system image. Us the attribute and value type="system" of the description element to specify the creation of a system image. The values of the bootprofile and bootkernel attributes are used by KIWI when generating the boot image.

Specify the key-value pair image="iso" to generate a live system suitable for deployment on optical media (CD or DVD). Use the boot="isoboot/suse-*" attribute when generating this image type to select the appropriate boot image for optical media. In addition the optional flags attribute may be set to the following values with the effects described below:

If the flags attribute is not used the filesystem will be squashfs compressed for /bin /boot /lib /lib64 /opt /sbin and /usr. The rest of the filesystem is packed into a tmpfs and linked via symbolic links

Use this type to create a virtual disk system suitable in a preload setting. In addition specify the attributes filesystem, and boot="oemboot/suse-*" to control the filesystem used for the virtual and to specify the proper boot image. Using the optional format attribute and setting, the value to iso or usb will create self installing images suitable for optical media or a USB stick, respectively. Booting from the media will deploy the OEM preload image onto the selected storage device of the system. It is also possible to configure the system to use logical volumes. Use the optional lvm attribute and specify the logical volume configuration with the systemdisk child element. The default volume group name is kiwiVG. Further configuration of the image is performed using the appropriate *config child block.

Creating a network boot image is supported by KIWI with the image="pxe" type. When specifying the creation of a network boot image use the filesystem and boot="netboot/suse-*" attributes to specify the filesystem of the image and the proper boot image. To compress the image file set the compressed boolean attribute to true. This setting will compress the image file and has no influence on the filesystem used within the image. The compression is often use to support better transfer times when the pxe image is pushed to the boot server over a network connection. The pxe image layout is controlled by using the pxedeploy child element.

The split image support allows the creation of an image as split files. Using this technique one can assign different file systems and different read-write properties to the different sections of the image. The oem, pxe, usb, and vmx types can be created as a split system image. Use the boot="oem|netboot|usb|vmx/suse-*" attribute to select the underlying type of the split image. The attributes fsreadwrite, fsreadonly are used to control the read-write properties of the filesystem specified as the attributes value. Use the appropriate *config child block to specify the properties of the underlying image. For example when building a OEM based split image use the oemconfig child section.

Creation of a virtual disk system is enabled with the vmx value of the image attribute. Set the filesystem of the virtual disk with the filesystem attribute and select the appropriate boot image by setting boot="vmxboot/suse-*" The optional format attribute is used to specify one of the virtualization formats supported by QEMU, such as vmdk (also the VMware format) or qcow2. For the virtual disk image the optional vga attribute may be used to configure the kernel framebuffer device. Acceptable values can be found in the Linux kernel documentation for the framebuffer device (see Documentation/fb/vesafb.txt). KIWI also supports the selection of the boot loader for the virtual disk according to the rules indicated for the USB system. Last but not least the virtual disk system may also be created with a LVM based layout by using the lvm attribute. The previously indicated rules apply. Use the machine child element to specify appropriate configuration of the virtual disk system.

Specifies additional kernel parameters. The following example disables kernel messages: kernelcmdline="quiet"

For disk based image types, aka oem and vmx, mdraid activates the creation of a software raid image. The raid inside the image is created in degraded mode because at creation time we only know about one disk. It's in the hand of the user to add devices to the raid after the image runs on the target machine. The value for mdraid can be either mirroring or striping, which means the raid level is set to RAID1 (mirroring) or RAID0 (striping).

Specifies the base name of a license file which is displayed in oem images before the installation happens. It's possible to add more showlicense sections to display more licenses one after the other. If no such element is specified the default 'license' and 'EULA' files are searched. The search algorithm will append the .txt or .locale.txt suffix to the license name to form the license file name. You should make sure that you license files contains this suffix.

Specifies whether RPM should check the package signature or not

Specifies whether RPM should skip installing package documentation

Specifies whether RPM should be called with --force

Specifies the name of the console keymap to use. The value corresponds to a map file in /usr/share/kbd/keymaps. The KEYTABLE variable in /etc/sysconfig/keyboard file is set according to the keyboard mapping.

Specifies the time zone. Available time zones are located in the /usr/share/zoneinfo directory. Specify the attribute value relative to /usr/share/zoneinfo. For example, specify Europe/Berlin for /usr/share/zoneinfo/Europe/Berlin. KIWI uses this value to configure the timezone in /etc/localtime for the image.

Specifies the name of the UTF-8 locale to use, which defines the contents of the RC_LANG system environment variable in /etc/sysconfig/language. Please note only UTF-8 locales are supported here which also means that the encoding must not be part of the locale information. The KIWI schema validates the locale string according to the following pattern:[a-z]{2}_[A-Z]{2}(,[a-z]{2}_[A-Z]{2})*. This means you need to specify the locale like the following example: en_US or en_US,de_DE

Specifies the name of the bootsplash theme to use

Specifies the name of the gfxboot theme to use

Used if the --destdir option is not specified when calling KIWI

Used if the option --root is not specified when calling KIWI

Using the optional systemdisk section it is possible to create a LVM (Logical Volume Management) based storage layout or a btrfs based layout using sub volumes. See chapter 17 for details.

By default, the volume group is named kiwiVG. It is possible to change the name of the group by setting the name attribute to the desired name. Individual volumes within the volume group are specified using the volume element.

The following example shows the creation of a volume named usr and a volume named var inside the volume group systemVG.

 <systemdisk name="systemVG">
  <volume name="usr" freespace="100M"/>
  <volume name="var" size="200M"/>
</systemdisk>

The optional attribute freespace controls the amount of unused space available after software has been installed in the given volume. By default the available space of a created volume is between 10% and 20%. Using the optional size attribute the absolute size of the given volume is specified. The size attribute takes precedence over the freespace attribute. If the specified size is insufficient, based on the estimated software install size for the given volume, the specified value will be ignored and a volume with default settings will be created. This implies that the volume will be 80% to 90% full.

2015-11-30 - fs: This whole section has also been copied to the OEM chapter By default, the oemboot process will create or modify a swap, and / partition. It is possible to influence the behavior by the oem-* elements explained below.

<oemconfig>
   <oem-systemsize>2000</oem-systemsize>
   <oem-... >
</oemconfig>

Information contained in the optional pxedeploy section is only considered if the image attribute of the type element is set to pxe. To use a PXE image it is necessary to create a network boot infrastructure. Creation of the network boot infrastructure is simplified by the KIWI provided package kiwi-pxeboot . This package configures the basic PXE boot environment as expected by KIWI pxe images. The kiwi-pxeboot package creates a directory structure in /srv/tftpboot. Files created by the KIWI create step need to be copied to the /srv/tftpboot directory structure. For additional details about the PXE image please refer to the PXE Image chapter later in this document.

In addition to the image files it is necessary that information be provided about the client setup. This information, such as the image to be used or the partitioning, is contained in a file with the name config.MAC in the directory /srv/tftpboot/KIWI. The content of this file is created automatically by KIWI if the pxedeploy section is provided in the image description. A pxedeploy section is outlined below:

<pxedeploy server="IP" blocksize="4096">
   <timeout>seconds</timeout>
   <kernel>kernel-file</kernel>
   <initrd>initrd-file</initrd>
   <partitions device="/dev/sda">
     <partition type="swap" number="1" size="MB"/>
     <partition type="L" number="2" size="MB"
              mountpoint="/" target="true"/>
     <partition type="fd"  number="3"/>
   </partitions>
   <union ro="dev" rw="dev" type="clicfs"/>
   <configuration source="/KIWI/../file" dest="/../file" arch="..."/>
   <configuration .../>
</pxedeploy> 

Use the size element to specify the image size in Megabytes or Gigabytes. The unit attribute specifies whether the given value will be interpreted as Megabytes (unit="M") or Gigabytes (unit="G"). The optional boolean attribute additive specifies whether or not the given size should be added to the size of the generated image or not.

In the event of a size specification that is too small for the generated image, KIWI will expand the size automatically unless the image size exceeds the specified size by 100 MB or more. In this case KIWI will generate an error and exit.

Should the given size exceed the necessary size for the image KIWI will not alter the image size as the free space might be required for proper execution of components within the image.

If the size element is not used, KIWI will create an image containing approximately 30 % free space.

<size unit="M">1000</size>

For images of type split or iso the information provided in the optional split section is considered if the compressed attribute is set to true. With the configuration in this block it is possible to determine which files are writable and whether these files should be persistently writable or temporarily. Note that for ISO images only temporary write access is possible.

When processing the provided configuration KIWI distinguishes between directories and files. For example, providing /etc as the value of the name attribute indicates that the /etc directory should be writable. However, this does not include any of the files or sub-directories within /etc. The content of /etc is populated as symbolic links to the read-only files. The advantage of setting only a directory to read-write access is that any newly created files will be stored on the disk instead of in tmpfs. Creating read-write access to a directory and it’s files requires two specifications as shown below.

<split>
  <temporary>
    <!-- read/write access to -->
    <file name="/var"/>
    <file name="/var/*"/>
    <!-- but not on this file: -->
    <except name="/etc/shadow"/>
  </temporary>
  <persistent>
    <!-- persistent read/write access to: -->
    <file name="/etc"/>
    <file name="/etc/*"/>
    <!-- but not on this file: -->
    <except name="/etc/passwd"/>
  </persistent>
</split>

Use the except element to specify exceptions to previously configured rules.

The optional machine section serves to specify information about a VM guest machine. Using the data provided in this section, KIWI will create a guest configuration file required to run the image on the target machine.

If the target is a VMware virtual machine indicated by the format attribute set to vmdk, KIWI creates a VMware configuration file. If the target is a Xen virtual machine indicated by the domain attribute in the machine section KIWI will create a Xen guest config file.

The sample block below shows the general outline of the information that can be specified to generate the configuration file

<machine arch="arch" memory="MB"
  HWversion="number" guestOS="suse|sles"
  domain="dom0|domU"/>
   <vmconfig-entry>Entry_for_VM_config_file<\vmconfig-entry>
   <vmconfig-entry .../>
   <vmnic driver="name" interface="number" mode="mode"/>
   <vmnic ...>
   <vmdisk controller="ide|scsi" id="number"/>
   <vmdvd  controller="ide|scsi" id="number"/>
</machine> 

Use the vmconfig-entry element to create entries in the virtual machine's configuration file; .vmx for VMware images and .xenconfig for Xen images. You may specify as many configuration options as desired. The value of the vmconfig-entry element is expected to be specified in the syntax required by the VM configuration file to be written. The value is free format text and is not validated by Kiwi in any way. The entry is written to the VM configuration file verbatim.

Use the vmdisk element to setup the virtual main storage device.

Use the vmdvd element to setup a virtual optical drive (CD/DVD) connection

Use the vmnic element to setup the virtual network interface. Multiple vmnic child elements may be specified to setup multiple virtual network interfaces.

Specifies an alternative name for the configured repository. If the attribute is not specified KIWI will generate an alias name by replacing any “/” in the given repository location with an “_”. It is helpful to set an alias name if the repository path is insufficient in expressing the purpose of the contained packages.

Specifies whether the given repository should be configured as a repository in the image or not. The default behavior is that repositories used to build an image are not configured as a repository inside the image. This feature allows you to change the behavior by setting the value to true. The repository is configured in the image according to the source path as specified with the path attribute of the source element. Therefore, if the path is not a fully qualified URL, you may need to adjust the repository file in the image to accommodate the expected location. It is recommended that you use the alias attribute in combination with the imageinclude attribute to avoid having unpredictable random names assigned to the repository you wish to include in the image. This also facilitates modification of the "baseurl" entry in the .repo file from the config.sh script if you need to make adjustments to the path.

Specifies a password for the given repository. The password attribute must be used in combination with the username attribute. Dependent on the repository location this information may not be used.

The repository providing this attribute will be used primarily to install the license tarball if found on that repository. If no repository with a preferred license attribute exists, the search happens over all repositories. It's not guaranteed in that case that the search order follows the repository order like they are written into the XML description.

Specifies the repository priority for this given repository. Priority values are treated differently by different package managers. Repository priorities allow the package management system to disambiguate packages that may be contained in more than one of the configured repositories. The smart package manager treats packages from repositories with the highest priority number as preferable to packages from a repository with a lower priority number. The value 0 means “no priority is set”. The zypper package manager prefers packages from a repository with a lower priority over packages from a repository with higher priority values. The value 99 means “no priority is set”.

This attribute should only be applied in the context of a boot image description. Setting the status to replaceable indicates that the specified repository my be replaced by the repositories specified in the image description. This is important as the KIWI generated boot image, if required, should be created based on packages from the same repositories used to build the system image.

Specifies a user name for the given repository. The username attribute must be used in combination with the password attribute. Dependent on the repository location this information may not be used.

An absolute path to a directory accessible through the local file system. The “dir://” prefix may be omitted.

A ftp protocol based network location.

A http protocol based network location.

A https protocol based network location. See the comment above about the handling of certificates and additional package requirements in the bootstrap section of the image configuration.

An absolute path to an .iso file accessible via the local file system. KIWI will loop mount the the .iso file to a KIWI created directory with a generated name. The generated path is provided to the specified package manager as a repository location.

Using multiple .iso files from the same SLE product, requires that all .iso files are located in the same directory. Only the first .iso file is to be specified as a repository in the config.xml. The first .iso file contains all information necessary for the package manager to locate packages that are contained in other .iso files of the same product. Attempting to use multiple .iso files in a series as standalone repositories will result in an error.

A special network location used with the http protocol. The values of $dir1 and $dir2 represent the project location in the openSUSE build service. The location is evaluated as this://repos/$dir1/$dir2 .

The “obs://” prefix is also valid as part of the value for the boot attribute of the type. If used with the boot attribute it is evaluated as this://images/$dir1/$dir2 .

A special network location used with the http protocol. The given PROJECTNAME specifies a project in the openSUSE Build Service. The repository is a repository of type rpm-md. For example: path= "opensuse://openSUSE:10.3/standard" .

A plain resource string. Everything following 'plain://' will be forwarded to the package manager without further modification. This type of location specification is useful when KIWI does not support a specific URI but the specified package manager does.

A path to a samba share using the cifs protocol. KIWI creates a mount point and mounts the share including username and password, if specified. Access to the smb share from within the new root tree is provided via a cifs mount. Therefore, the package providing the cifs tools must be included in the package list for the bootstrap section of the image configuration. At the time of this writing the package providing the cifs tools is called cifs-utils. If any packages provided by the Samba share are used as part of the boot image the cifs tools must also be included in the boot image. This is accomplished with the bootinclude attribute of the package element. This is shown in the example below:

<packages type="bootstrap">
  <package name="cifs-utils" bootinclude="true"/>
  </packages>

PATH is the relative location to the image description directory for the current image.

Bootstrap packages, list of packages for the new operating system root tree. The packages list the required components to support a chroot environment in the new system root tree, such as glibc.

Delete packages, list of packages to be deleted from the image being created.

When using the delete type only package elements are considered, all other specifications such as namedCollection are ignored. The given package names are stored in the $delete environment variable of the /.profile file created by KIWI. The list of package names is returned by the baseGetPackagesForDeletion function. This list can then be used to delete the packages ignoring requirements or dependencies. This can be accomplished in the config.sh or images.sh script by calling the following helper function:

suseRemovePackagesMarkedForDeletion

Note, that the delete value is indiscriminate of the image type being built.

Image packages, list of packages to be installed in the image.

Image packages, a list of additional packages to be installed when building an ISO image.

Image packages, a list of additional packages to be installed when building an OEM image.

Image packages, a list of additional packages to be installed when building an PXE image.

Image packages, a list of additional packages to be installed when building a vmx virtual image of any format.

A required attribute. The name of the volume. If mountpoint is not specified, a directory with the given name will be created by KIWI if it does not already exist inside the root tree. However, if the name contains the KIWI internal path field separator “_”, it is required to specify the path in an additional mount point attribute. The special value @root can be combined with the size or freespace attribute to control the size of the root volume.

An optional attribute. Absolute size of the volume. If the size value is too small to store all data kiwi will exit. If no suffix is used, the value will be considered as Megabytes, otherwise add M (Megabyte) or G (Gigabyte) as suffix.

An optional attribute. Free space to be added to this volume. If no suffix is used, the value will be considered as Megabytes, otherwise add M (Megabyte) or G (Gigabyte) as suffix.

An optional attribute. Specifies a path which needs to exist inside the root directory.

Name or IP address of the server who implements the protocol

Name of the download protocol which could be one of http, https or ftp

Contains a list of groups that should be defined. At least one group name needs to be specified. The names are separated by a comma and a space. Although there is no limit for the number of groups, it should be kept to a minimum for reasonable manageability.

Valid group names are made up of uppercase and lowercase letters, and may use numeric, and underscore characters. The same rules used to define Bash or sh variable names apply. The following example contains valid names:

KIWI_GROUP="group1, group2, group3"

This parameter is used to assign MAC addresses to the groups defined with KIWI_GROUP. The name of this parameter depends on the group it represents. In our example the groups group1, group2, group3 are defined, so the corresponding parameters are:

These parameters contain a comma-separated list of MAC addresses that should be assigned to the specified group. MAC addresses always need to be specified with uppercase letters, otherwise they will not match. If the list of addresses is very long (several thousand entries), the client's boot process my be slowed down.

This script is executed prior to the hardware scan on the target machine.

This script is executed after the hardware scan on the target machine.

This script is executed immediately prior to the OEM image dump onto the target storage device.

This script is executed directly after the OEM image dump onto the target storage device when the image checksum has been successfully verified.

By default, the string OEM> will be used as the boot manager menu entry when KIWI creates the GRUB configuration during deployment. The oem-boot-title element allows you to set a custom name for the GRUB menu entry. This value can also be set at the boot prompt by the parameter kiwi_oemtitle="TITLE".

Specify if the system should wait for user interaction prior to continuing the initial boot process after (default value is false). This value can also be set at the boot prompt by the parameter kiwi_oembootwait=TRUE_OR_FALSE.

Specify if the recovery archive is stored as part of the image or if the archive is to be created at the time the image is deployed to the target storage device. This value can also be set at the boot prompt by the parameter kiwi_oemrecoveryInPlace=TRUE_OR_FALSE.

If this element is set to true (default value is false) the oemboot boot image (initrd) will not be replaced by the initrd created by the system. This option is useful when the system is installed on a flash disk. When booting from such a drive it is usually necessary to detect the storage location on each boot. This detection process is part of the oemboot boot image. This value can also be set at the boot prompt by the parameter kiwi_oemkboot=TRUE_OR_FALSE.

By default (false), an OEM image is installed on the specified disk on the target system. During this process the disk is being overwritten and the original data is lost. Setting this parameter to true, installs the image into an empty partition (that is a partition without a file system). If the device already contains a swap partition, it will be used, otherwise a swap file will be created. The empty partition needs to exist prior to booting the KIWI image, otherwise the installation will fail. Setting this parameter to true also makes KIWI ignore any other partitioning-related setting (for example oem-swap). See Section 12.4.3, “Partition Based Installation” for more details. This value can also be set at the boot prompt by the parameter kiwi_oempartition_install=TRUE_OR_FALSE.

If set to true, the system reboots after the OEM image has been deployed. By default this parameter is set to false. This value can also be set at the boot prompt by the parameter kiwi_oemreboot=TRUE_OR_FALSE.

If set to true, the system reboots after the OEM image has been deployed. A message, which the user needs to confirm to start the reboot is displayed. By default this parameter is set to false. This value can also be set at the boot prompt by the parameter kiwi_oemrebootinteractive=TRUE_OR_FALSE.

If this element is set to true (default value is false), KIWI will create a recovery archive from the prepared root tree. The archive will appear as /recovery.tar.bz2 in the image file. During the first boot of the image a single recovery partition will be created and the recovery archive will be moved to that partition. A boot menu entry for recovery, that will restores the original root tree on the system, is created. User data stored in /home will not be affected by the recovery process. This value can also be set at the boot prompt by the parameter kiwi_oemrecovery=TRUE_OR_FALSE.

Specify the partition type for the recovery partition. The default is to create a Linux partition (id = 83). This value can also be set at the boot prompt by the parameter kiwi_oemrecoveryID=ID.

Specify if the system should show boot messages (false) on the very first boot after having deployed the OEM image, or whether all boot messages should be suppressed (true). This value can also be set at the boot prompt by the parameter kiwi_oemsilentboot=TRUE_OR_FALSE.

Specify if the system is to be powered down after the OEM image has been deployed (the default value is false). This value can also be set at the boot prompt by the parameter kiwi_oemshutdown=TRUE_OR_FALSE.

Specify if the system is to be powered down after the OEM image has been deployed. A message, which the user needs to confirm to start the shutdown process, is displayed. This value can also be set at the boot prompt by the parameter kiwi_oemshutdowninteractive=TRUE_OR_FALSE.

Specify if a swap partition should be created (the default is true). This value can also be set at the boot prompt by the parameter kiwi_oemswap=TRUE_OR_FALSE.

Set the size of the swap partition in megabytes. If a swap partition is to be created and the size of the swap partition is not specified with this optional element, KIWI will create a swap partition of a size equal to two times of the RAM size at initial boot time. This value can also be set at the boot prompt by the parameter kiwi_oemswapMB=SIZE_IN_MB.

Set the size the operating system is allowed to consume on the target disk. The size limit does not include any consideration for swap space or a recovery partition. In a setup without a systemdisk element this value specifies the size of the root partition. In a setup including a systemdisk element this value specifies the size of the LVM partition which contains all specified volumes. Thus, the sum of all specified volume sizes plus the sum of the specified free space for each volume must be smaller or equal than the size specified with the oem-systemsize. This value can also be set at the boot prompt by the parameter kiwi_oemrootMB=SIZE_IN_MB.

If set to true, the image deployment is done without requiring user interaction. If the target system contains multiple disks, the first device (/dev/sda, for example) is automatically selected. This value can also be set at the boot prompt by the parameter kiwi_oemunattended=TRUE_OR_FALSE.