We all love the openSUSE KIWI build system because it’s a powerful and flexible way to build thin client images (or images in general). That being said, there are a number of different moving parts and it’s easy to miss something. In this article I’ll give you some KIWI troubleshooting techniques.

Here are a list of the key KIWI related files. Make sure that you’ve configured all of them.

  • Your kiwi build directory. This directory can be placed anywhere on your system and includes the following files
    • config.xml (This file is very important. It lists the name of the image you’re about to create, whether or not to use compression, size of the image, package repository(s), local users and packages to be included in your image.)
    • build.sh (If either Jason, Atiq or I have built you an image there’s probably a script named build.sh that automates the whole process. The script will automate the running of kiwi -p, copy over the appropriate configuration files and run kiwi -c. This script is not mandatory, but we find that a script like this makes life easier. Guy contends that it is unnecessary and most of its function should be performed by config.sh)
    • config.sh (This is a script that is automatically called after you run kiwi -p. The purpose of this script is to activate services so that they turn on when you boot the system.)
    • VERSION (This file exists in older versions of KIWI. In newer versions of KIWI the image version number is included config.xml)
    • images.sh (This script is automatically called after you run kiwi -c. The purpose of this script is to clean up the image. It uninstalls unneeded rpms, including rpm itself, in order to shrink the image size. It also removes parts of GNOME that aren’t needed and other system files. You can utilize this script to set up groups, change permissions and ownership on files and other things)
  • PXE Booting stuff
    • /etc/dhcpd.conf (Make sure that you have filename “pxelinux.0”; and next-server ipaddress.of.pxe.server; are configured)
    • /etc/sysconfig/atftpd (you must use atftp not tftp)
  • tftpboot directory
    • The default location for your atftp directory is /tftpboot
    • Within /tftpboot you should have the following files/directories
      • KIWI (all uppercase)
        • config.MAC:ADDRESS (Make sure that you have one of these files for each client mac address. I’ve been told that in newer versions of KIWI you can create a file named “default” that will be the default if a config.MAC file is not there for the specific device. Make sure that the letters in the mac address are UPPERCASE. Make sure that the ipaddress inside the config.mac file points to the server hosting the image. Also make sure that the name of the image is spelled right. Also make sure that if you’re using a compressed image you note it here.)
      • image (This directory contains your image and the image.md5. Make sure you have both files. Also after you have run kiwi -c don’t mount the image and mess around with the image and try to regenerate a checksum… it won’t work.)
      • initrd and linux (I’ve blogged about creating these files in kiwi before. You MUST use kiwi to generate these. To learn how click here.
      • pxelinux.0 (You can copy this from /usr/share/syslinux/pxelinux.0)
      • pxelinux.cfg
        • default (Make sure to point to the appropriate kiwi generated initrd and kiwi. Also don’t forget to add kiwitftp=ipaddress.of.server

Here are some more troubleshooting methods for common problems.

The image won’t fit on the flash even though you know it’s small enough: On a small flash don’t use compression. There isn’t enough space to de-compress it.

You have a specific package listed in config.xml, but it’s not showing up in your build: Make sure images.sh isn’t removing it.

You’re having trouble adding a local user in the images.sh script. Don’t try and add users in images.sh, rather add them in config.xml

Kiwi says that that it’s looking for image-name.gz but the image file I generate doesn’t end in .gz. Make sure that your /tftpboot/KIWI/config.MAC:ADDRESS file isn’t marked for compression.

I’m really not sure why it’s not deploying… In /etc/sysconfig/atftpd enable verbose logging. The logs will be written out to /var/log/messages. To enable this make sure the ATFTPD_OPTIONS line looks like this: ATFTPD_OPTIONS=”–daemon –verbose=10″

Everything seems right but the image won’t deploy: I’ve seen some really fast servers (quad core) and some really slow servers (running in a vm on a slow old laptop) get messed up with multicast. Edit your ATFTPD_OPTIONS line so it looks like this: ATFTPD_OPTIONS=”–daemon –no-multicast”.

As I come across other issues I’ll add to this article. If you’ve got your own solutions feel free to post comments.