openSUSE-KIWI Image System

allows setup of the boot menu title for isolinux and grub. So you can have suse-SLED-foo as the image name but something like my cool Image as the boot display name.

inherits the packages information from another image description

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

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

Use the cpio image type to specify the generation os a boot image (intrd). 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 apropriate 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 not be compressed and no union filesystem is used. In this case it is recommended to specify a split section as a child of this type element. The specification of a split block is also recommended when flags="compressed" is used.

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 lvmvolumes 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 netwoork 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 filesystems 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 controll 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.

Use the usb value to create a USB stick image. Set the filesystem attribute to the desired supported filesystem for the image and use the boot="usbboot/suse-*" attribute to select the USB boot image for the system. For a USB image you may also select GRUB or Syslinux as a bootloader by setting the optional bootloader attribute to grub ot syslinux, respectively. The USB image may also be created with LVM support. The same rules as indicated for the OEM image apply.

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 booloader 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 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 have to specifiy the locale like the following example: en_US or en_US,de_DE

Specifies the name of the gfxboot and bootsplash 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

Used if the option --base-root is not specified when calling KIWI. It’s possible to prepare and create an image using a predefined non empty root directory as base information. This could speedup the build process a lot if the base root path already contains most of the image data.

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

The optional ec2config block is used to specify information relevant only to AWS EC2 images. The following information can be provided:

<ec2config>
  <ec2accountnr> Your AWS account number </ec2accountnr> 
  <ec2certfile> Path to the AWS cert-*.pem file </ec2certfile>
  <ec2privatekeyfile> Path to the AWS pk-*.pem file </ec2privatekeyfile>
</ec2config>

Using the optional lvmvolumes section it possible to create a LVM (Logical Volume Management) based storage layout. By default, the volume group is named kiwiVG. It is possible to change the name of the group by setting the lvmgroup 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.

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

With the optional freespace attribute it is possible to add space to the volume. If the freespace attribute is not set the created volume will be 80 % to 90 % full. Using the optional size attribute the absolute size of the given volume is specified. The size attribute takes precedence over the freespace attribute. Should the specified size be too small the value will be ignored and a volume with approximately 80 % to 90 % fill will be created.

By default, the oemboot process will create or modify a swap, /home and / partition. It is possible to influence the behavior by the oem-* elements explained below. KIWI uses this information to create the file /config.oempartition as part of the automatically created oemboot boot image. The format of the file is a simple key=value format and created by the KIWIConfig.sh function named baseSetupOEMPartition.

<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. In order 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 enviroment 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 refere 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 pexedeploy 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="aufs|clicfs|unionfs"/> 
   <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 with containing approxiamtely 30 % free space.

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

For images of type split or iso the information provided in the optional split section is is considered if the compressed attribute is 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 persentently 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 showb 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"/> 
   <vmnic driver="name" interface="number" mode="mode"/> 
   <vmdisk controller="ide|scsi" id="number"/> 
   <vmdvd  controller="ide|scsi" id="number"/> 
</machine> 

The following information can be provided to setup the virtual main storage device and CD/DVD drive connection:

The following information can be provided to setup the virtual network interface:

Each file is specified relative to the /lib/modules/Version/kernel directory.

Each file is specified relative to the /lib/modules/Version/kernel/drivers directory.

Each file is specified relative to the /lib/modules/Version/kernel/drivers

Each file is specified relative to the /lib/modules/Version/kernel/drivers directory.

This attribute makes only sense for boot image descriptions. It indicates that the repository is allowed to become replaced by the repositories defined in the system image descriptions. Because KIWI automatically builds the boot image if required it should create that image from the same repositories which are used to build the system image to make sure both fit together. Therefore it is required to allow the repository to become overwritten which is indicated by the status attribute.

Specifies an alternative name used to identify the source channel. 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

Specifies the repository priority assigned to all packages available in this repository. For smart the following applies: If the exact same package is available in more than one channel, the repository with the highest priority number is used. The value 0 means “no priority is set”. For zypper the following applies: If the exact same package is available in more than one channel, the repository with the lowest priority number is used. The value 99 means “no priority is set”.

A relative path name, which is relative to the image description directory being referenced.

A path to a local .iso file which is then loopback mounted and used as a local path based repository. Alternatively one can do the loop mount himself and point a standard local path to the mounted directory

When using multiple .iso files from the same product, such SLES all .iso files need to be located in the same directory, but only the first .iso file needs to be added as a repository to the configuration. The first .iso file contains sufficient information for the package management tool to find packages in the other .iso files as long as they are located in the same directory. Attempting to use a second or third .iso file in a series as a stand alone repository will result in an error.

A http protocol based network location

A https protocol based network location

A ftp protocol based network location

A special http based network location which is created from the given openSUSE buildservice project name. The result is pointing to an rpm-md repository on the openSUSE buildservice. For example: path="opensuse://openSUSE:10.3/standard"

A local path which should be an absolute path description. The file:// prefix is optional and could also be omitted.

A special buildservice path whereas $dir1 and $dir2 represents the buildservice project location. If this type is used as part of a boot attribute KIWI evaluates it to this://images/$dir1/$dir2 and if used as part of a repository source path attribute it evaluates to this://repos/$dir1/$dir2

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 a 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 opensusePattern 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 with the following code snippet:

rpm -e --nodeps --noscripts \
$(rpm -q ‘baseGetPackagesForDeletion‘ | grep -v "is not installed")

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 USB image.

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

Specifies which image (name) should be loaded with which version (version) and to which storage device (device) it should be linked, e. g., /dev/ram1 or /dev/hda2. The netboot client partition (device) hda2 defines the root file system / and hda1 is used for the swap partition. The numbering of the hard disk device should not be confused with the RAM disk device, where /dev/ram0 is used for the initial RAM disk and can not be used as storage device for the second stage system image. SUSE recommends to use the device /dev/ram1 for the RAM disk. If the hard drive is used, a corresponding partitioning must be performed.

Specifies a comma-separated list of source:target configuration files. The source (src) corresponds to the path on the TFTP server and is loaded via TFTP. The download is made to the file on the netboot client indicated by the target (dest).

Specifies the partitioning data. The comma-separated list must contain the size (size), the type number (id), and the mount point (Mount). The size is measured in MB by default. Additionally all size specifications supported by the sfdisk program are allowed as well. The type number specifies the ID of the partition. Valid ID’s are listed via the sfdisk --list-types command. The mount specifies the directory the partition is mounted to.

Specifies the hard disk. Used only with PART and defines the device via which the hard disk can be addressed, e.g., /dev/hda.

If set to a non-empty string, this forces the configured image to be loaded from the server even if the image on the disk is up-to-date. The primary purpose of this setting is to aid debugging. The option is sensible only for disk based systems.

If set to a non-empty string, this forces all config files to be loaded from the server. The primary purpose of this setting is to aid debugging. The option is sensible only for disk based systems.

If set to an non-empty string, indicates that the both image specified needs to be combined into one bootable image, whereas the first image defines the read-write part and the second image defines the read-only part.

Specifies the KIWI initrd to be used for local boot of the system. The variables value must be set to the name of the initrd file which is used via PXE network boot. If the standard tftp setup suggested with the kiwi-pxeboot package is used all initrd files resides in the boot/ directory below the tftp server path /var/lib/tftpboot. Because the tftp server do a chroot into the tftp server path you need to specify the initrd file as the following example shows:

KIWI_INITRD=/boot/name-of-initrd-file

For netboot and usbboot images there is the possibility to use unionfs or aufs as container filesystem in combination with a compressed system image. The recommended compressed filesystem type for the system image is squashfs. In case of a USB stick system the usbboot image will automatically setup the unionfs/aufs filesystem. In case of a PXE network image the netboot image requires a config.MAC setup like the following example shows:

UNIONFS_CONFIG=/dev/sda2,/dev/sda3,aufs

In this example the first device /dev/sda2 represents the read/write filesystem and the second device /dev/sda3 represents the compressed system image filesystem. The container filesystem aufs is then used to cover the read/write layer with the read-only device to one read/write filesystem. If a file on the read-only device is going to be written the changes inodes are part of the read/write filesystem. Please note the device specifications in UNIONFS_CONFIG must correspond with the IMAGE and PART information. The following example should explain the interconnections:

IMAGE=/dev/sda3;image/myImage;1.1.1;192.168.1.1;4096
PART=200;S;x,300;L;/,x;L;x
UNIONFS_CONFIG=/dev/sda2,/dev/sda3,aufs
DISK=/dev/sda

As the second element of the PART list must define the root partition it’s absolutely important that the first device in UNIONFS_CONFIG references this device as read/write device. The second device of UNIONFS_CONFIG has to reference the given IMAGE device name.

Specifies additional command line options to be passed to the kernel when booting from disk. For instance, to enable a splash screen, you might use vga=0x317 splash=silent.

Specifies the number of seconds to wait at the grub boot screen when doing a local boot. The default is 10.

Mount the system image root filesystem remotely via NBD (Network Block Device). This means there is a server which exports the root directory of the system image via a specified port. The kernel provides the block layer, together with a remote port that uses the nbd-server program. For more information on how to set up the server, see the nbd-server man pages. The kernel on the remote client can set up a special network block device named /dev/nb0 using the nbd-client command. After this device exists, the mount program is used to mount the root filesystem. To allow the KIWI boot image to use that, the following information must be provided:

NBDROOT=NBD.Server.IP.address;\
  NBD-Port-Number;/dev/NBD-Device;\
  NBD-Swap-Port-Number;/dev/NBD-Swap-Device;\
  NBD-Write-Port-Number;/dev/NBD-Write-Device

The NBD-Device, NBD-Swap-Port-Number, NBD-Swap-Device, NBD-Write-Port-Number and NBD-Write-Device variables are optional. If the nbd root device is not set, the default values (/dev/nb0, port 2000) applies and if the nbd swap device is not set the default values (/dev/nb1, port 9210) applies. The swap space over the network using a network block device is only established if the client has less than 48 MB of RAM. The optional NBD-Write-Port-Number and NBD-Write-Device specifies a write COW location for the root filesystem. aufs is used as overlay filesystem in this case.

Mount the system image root filesystem remotely via AoE (ATA over Ethernet). This means there is a server which exports a block device representing the the root directory of the system image via the AoE subsystem. The block device could be a partition of a real or a virtual disk. In order to use the AoE subsystem I recommend to install the aoetools and vblade packages from here first: http://download.opensuse.org/repositories/system:/aoetools. Once installed the following example shows how to export the local /dev/sdb1 partition via AoE:

vbladed 0 1 eth0 /dev/sdb1 

Some explanation about this command, each AoE device is identified by a couple Major/Minor, with major between 0-65535 and minor between 0-255. AoE is based just over Ethernet on the OSI models so we need to indicate which ethernet card we’ll use. In this example we export /dev/sdb1 with a major value of 0 and minor of 1 on the eth0 interface. We are ready to use our partition on the network! To be able to use the device KIWI needs the information which AoE device contains the root filesystem. In our example this is the device /dev/etherd/e0.1. According to this the AOEROOT variable must be set as follows:

AOEROOT=/dev/etherd/e0.1

KIWI is now able to mount and use the specified AoE device as the remote root filesystem. In case of a compressed read-only image with aufs or clicfs, the AOEROOT variable can also contain a device for the write actions:

AOEROOT=/dev/etherd/e0.1,/dev/ram1

Writing to RAM is the default but you also can set another device like another aoe location or a local device for writing the data

Mount the system image root filesystem remotely via NFS (Network File System). This means there is a server which exports the root filesystem of the network client in such a way that the client can mount it read/write. In order to do that, the boot image must know the server IP address and the path name where the root directory exists on this server. The information must be provided as in the following example:

NFSROOT=NFS.Server.IP.address;/path/to/root/tree

Optionally you can set a UNIONFS_CONFIG variable which defines an aufs based overlay NFS directory or device like:

UNIONFS_CONFIG=/tmp/kiwi-11.1-cow,nfs,aufs # write to NFS directory
UNIONFS_CONFIG=/dev/ram1,nfs,aufs # write to RAM

This way you can keep the original root tree clean from any modifications

Specifies the KIWI initrd to be used for a local boot of the system. The value must be set to the name of the initrd file which is used via PXE network boot. If the standard TFTP setup suggested with the kiwi-pxeboot package is used, all initrd files reside in the /srv/tftpboot/boot/ directory. Because the TFTP server does a chroot into the TFTP server path, you must specify the initrd file as follows:

KIWI_INITRD=/boot/name-of-initrd-file

Specifies the kernel to be used for a local boot of the system The same path rules as described for KIWI_INITRD applies for the kernel setup:

KIWI_KERNEL=/boot/name-of-kernel-file

Specifies a message which is displayed during first deployment. Along with the message a shell is provided. This functionality should be used to send the user a message if it’s clear the boot process will fail because the boot environment or something else influences the pxe boot process in a bad way.

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