SDB:KIWI Cookbook GNOME System

Jump to: navigation, search

Build an image that uses a minimal GNOME desktop environment. Customize the base example to enable auto login, automatically start Firefox, and customize GNOME right out of the gate.
This procedure was tested on at least Kiwi version 3.75 ( kiwi --version )

A Minimal GNOME Appliance - our fifth recipe

While our previous recipes focused on the various types of images we can create with Kiwi this recipe focuses more on the content of the appliance and some configuration questions. Starting out we will take a look at the suse-min-gnome example and then expand the example to enable autologin and show how to autostart a specific application.

The default image type used for this appliance is a VMware image as it provides maximum flexibility for testing. You can use qemu, VirtualBox, or VMware player or server to test the resulting image. The image description is also configured to create a Live CD/DVD but you will need to use the --type iso command line argument for the create step to generate the ISO image.

Without further ado lets begin.


Minimal GNOME appliance

Prep Time:

  • 30 min

Cook Time:

  • 10 - 12 min depending on bandwidth (see previous discussion) and hardware of host


  • a running openSUSE 11.1 system
  • a openSUSE 11.1 repository
  • installed recent release of the KIWI toolset (at least version 3.75)
  • installed kiwi-doc package
  • about 1 GB free disk space

The recipe is based on the suse-min-gnome example located in /usr/share/doc/packages/kiwi/examples/suse-11.x/suse-min-gnome installed with the kiwi-doc package.

Using A Graphical Login

In order to have a graphical login working we need to include the X Server in our image, therefore we have a

 <package name="xorg-x11-server"/>

entry within our <packages> section. In this example we want to use GNOME as the desktop environment and GDM as the graphical login manager. Therefore, we use

 <package name="gdm"/>

in our <packages> section. Note that specifying gdm in combination with the patternType="plusRecommended" and patternPackageType="plusRecommended" attributes of the <packages> element is sufficient to create a minimal GNOME interface.

For good measure the system also includes Perl, Python, and an editor (Vim)

 <package name="python"/>
 <package name="perl"/>
 <package name="vim"/>

One tricky thing in the past has always been the X server configuration. One way to deal with this would be to use a generic frame buffer based xorg.conf file as an overlay file in our root tree of the Kiwi configuration directory. However, as you examine the structure of our example you will see that the only overlay file used is etc/init.d/boot.local. Thanks to an auto configuration mode in sax2 we can simply configure the X server when booting without user interaction. The content of boot.local is quite short and simple as shown below.

 # Create the X-server configuration file if it does not yet exist
 if [ ! -f /etc/X11/xorg.conf ]; then
     /usr/sbin/sax2 -c 0 -a -i &>/dev/null
If you are packaging proprietary graphics drivers for ATI or NVIDIA cards do not use the -i option.

With the release of openSUSE 11.2 the X server will configure itself automatically such that even the boot.local overlay file is no longer required and therefore the openSUSE 11.2 example contains no overlay files.

With the X server configured we need to make sure that GDM is started and that the system starts in runlevel 5. This "magic" happens in using Kiwi provided functions. The function calls of interest are as follows:

 baseUpdateSysConfig /etc/sysconfig/windowmanager DEFAULT_WM gnome
 baseUpdateSysConfig /etc/sysconfig/displaymanager DISPLAYMANAGER gdm
 baseSetRunlevel 5

Functions available in are separated into two categories, SUSE specific and distribution independent functions. SUSE specific functions have a suse prefix as in suseConfig and distribution independent function have a base prefix as in baseSetRunlevel.

The baseUpdateSysConfig function takes 3 arguments, the fully qualified path of the file in the image that is to be modified, the variable that should be set in this file, and the value of the variable. Note, that the baseUpdateSysConfig function will not create a new variable, it will only operate on variables that already exist in the configuration file. Using our first call to baseUpdateSysConfig as an example this will result in the following entry in /etc/sysconfig/windowmanager in our image.


The baseSetRunlevel function set the default runlevel of the appliance, in this case we want a full multiuser graphical environment with network, thus we set the runlevel to be 5.

After the changes to the configuration files we call suseConfig to apply the changes to the system.

The predefined functions available in are documented in the KIWI Image System Cookbook or alternatively you can access the man page for as follows:

# man

That's all the configuration we have to do to get our minimal GNOME based image to work. Let's create the image and check it out.

# kiwi --prepare /usr/share/doc/packages/kiwi/examples/suse-11.1/suse-min-gnome -root /tmp/mymingnome
# kiwi --create /tmp/mymingnome -d /tmp/mymingnome-result

This will take a while as there is lots of data to be downloaded from the openSUSE repository. To speed up the process you can make a copy of the example and modify the repository definition to point to a local installation source. This process was described in the Start Cooking section.

Once the image creation process is completed you can test your image using you favorite Virtualization environment.

# qemu /tmp/mymingnome-result/suse-11.1-gnome-demo.i686-1.0.1.vmdk
Caveats with respect to image name and building in 64 bit mode apply as noted previously.

Once your through the boot process you will be greeted with the familiar GDM login screen.

The password for root and tux is consistent with our previous examples and was set to linux in the config.xml file.

The following sections discuss configuration options that may be applied individually or in combination, as in this example. Each section shows the changes to the Kiwi configuration directory (/tmp/gnome-exa) followed by a prepare and create step. You may choose to skip the prepare step by applying the changes directly to the unpacked image tree (/tmp/mymingnome) followed by the create step. While this shortcut will save time for this example it is inherently risky when used for a real project. Changes applied directly to the unpacked image directory are easily forgotten and if not applied to the Kiwi configuration directory will get lost when the image is recreated.

Autologin Configuration

In this step we will modify the configuration of the example, therefore you want of make a copy of the base example to create a working tree.

# cp -r /usr/share/doc/packages/kiwi/examples/suse-11.1/suse-min-gnome /tmp/gnome-exa

Setting up auto login for the user (tux) in our example is very straight forward. Just add the following line to /tmp/gnome-exa/ (or to the file in the location you have chosen)

 baseUpdateSysConfig /etc/sysconfig/displaymanager DISPLAYMANAGER_AUTOLOGIN tux

Now rebuild the image and test it and you'll see that the user tux will be automatically logged into the system.

# kiwi --prepare /tmp/gnome-exa -root /tmp/mygnome-exa
# kiwi --create /tmp/mygnome-exa -d /tmp/mygnome-exa-result
# qemu /tmp/mygnome-exa-result/suse-11.1-gnome-demo.i686-1.0.1.vmdk
Caveats with respect to image name and building in 64 bit mode apply as noted previously.

Now that we have autologin configure it might also be useful to automatically run a program on login. The next section will show how to configure the environment to do just that.

Start A Program On Login

The mechanism to automatically run a program is independent of the autologin feature described in the previous section. Thus you may choose to omit the setup of the autologin feature and still get a program started automatically when a given user logs in.

For this section we will continue to work in our working directory setup previously, i.e. we will use /tmp/gnome-exa. The program that will be started automatically is Firefox but this can of course be any executable that you would like to start automatically.

First create the directory that GNOME uses for auto starting programs.

# mkdir -p /tmp/gnome-exa/root/home/tux/.config/autostart

Replace /tmp/gnome-exa if you chose a different location to follow along with this example and replace tux if you chose to configure a different user in config.xml.

Now use you favorite editor to create the file firefox.desktop in /tmp/gnome-exa/root/home/tux/.config/autostart. The filename is not important, but I find it useful to have the filename indicate what program it is related to. Add the following lines to this file and save it.

 [Desktop Entry]

Now we are ready to rebuild and test.

# rm -rf /tmp/mygnome-exa
# kiwi --prepare /tmp/gnome-exa -root /tmp/mygnome-exa
# kiwi --create /tmp/mygnome-exa -d /tmp/mygnome-exa-result
# qemu /tmp/mygnome-exa-result/suse-11.1-gnome-demo.i686-1.0.1.vmdk
Caveats with respect to image name and building in 64 bit mode apply as noted previously.

If you have a custom script that you include via the overlay mechanism you can just specify the fully qualified path in the *.desktop file for example

 [Desktop Entry]

Would execute the file /opt/mysetup/myscript (the file needs to have execute permission of course).

This wraps up the autostart section of the example. In the next section we will look at some more GNOME customization to wrap things up.

Some GNOME Customization

Desktop Icon Removal

If you like a clean desktop, i.e. no icons cluttering the view of your beautiful background you can remove the icons that are currently shown when you boot the image with the following steps.

First we remove the default icons, Help and openSUSE, by inserting the following into /tmp/mygnome-exa/ after the call to suseConfig. The requirement is that the position of this section must be prior to the call to baseCleanMount.

 # Remove system default desktop icons
 rm -f /usr/share/dist/desktop-files/*

This takes care of 2 of the 4 icons. Note that this has a system wide effect, i.e. these icons are now gone from the Desktop of all users of the system.

If you would like to disable the Home folder and Trash icons you have two options, a system wide modification and a modification on a per user basis. Both approaches are shown below.

First lets take a look at the removal of the Desktop icons on a per user basis.

Removing Home And Trash Icons Per User

In GNOME the configuration for applications and the desktop are stored in the users home directory in the hidden .gconf directory. This is the directory that gets updated when you make modifications via the gconf-editor tool. To remove the desktop icons create a directory in our configuration tree as follows:

# mkdir -p /tmp/mygnome-exa/root/home/tux/.gconf/apps/nautilus/desktop

Now with your favorite editor create the file %gconf.xml in the previously created directory and add the following content.

 <?xml version="1.0"?>
       <entry name="trash_icon_visible" mtime="1108553948" type="bool" value="false">
       <entry name="home_icon_visible" mtime="1108553943" type="bool" value="false">

This turns the display of the desktop icons off. For details on the format please refer to the GNOME Documentation.

This is of course nice if you are configuring just one user on the system. However, if you have many users and would like to hide the icons by default it is easier to make the modification for the whole system. The next section describes how this works.

Removing Home And Trash Icons By Default

The system wide default settings are stored in the file /etc/gconf/gconf.xml.vendor/%gconf-tree.xml. This file is placed into our image by the gconf2-branding-openSUSE package. Re-creating the file from scratch just to make a couple of modifications is too much trouble. The easiest approach is to copy the file from your running system into your Kiwi configuration directory as follows:

# mkdir -p /tmp/mygnome-exa/root/etc/gconf/gconf.xml.vendor
# cp /etc/gconf/gconf.xml.vendor/%gconf-tree.xml /tmp/mygnome-exa/root/etc/gconf/gconf.xml.vendor

Now you have a basic configuration to work with. Edit this file with your favorite editor and search for <dir name="nautilus">. In this section you will find a <dir name="desktop"> sub section. Prior to the closing tag </desktop> add the following:

 <entry name="trash_icon_visible" mtime="1108553948" type="bool" value="false">
 <entry name="home_icon_visible" mtime="1108553943" type="bool" value="false">

Save the file and you are all set.

You can now rebuild the images as before and test it. Once the system is up and running the desktop icons will not be visible.

With this you can customize everything about GNOME either on a per user basis or system wide. The structure of the directories follows the layout of features in the gconf-editor tool. For user based customization create the appropriate directory and place a %gconf.xml file into the directory. For system wide configuration create a <dir> section in the %gconf-tree.xml file.

As another customization example the last section below will show the customization of the desktop background.

A Custom Desktop Background

In this section we will just concentrate on the per user desktop customization. Lets start by placing our desired background image into the Kiwi configuration tree.

# mkdir -p /tmp/gnome-exa/root/usr/share/backgrounds

Creates a directory to where we can store the background image we want to use. Next copy your image (called myImage.png in our example) into the newly create directory

 cp path_to_image/myImage.png /tmp/gnome-exa/root/usr/share/backgrounds

Now create the directory for the configuration file to set the background image.

# mkdir -p /tmp/gnome-exa/root/home/tux/.gconf/desktop/gnome/background

With your favorite editor create the %gconf.xml file in the just created directory with the following content.

 <?xml version="1.0"?>
       <entry name="primary_color" mtime="1237339199" type="string">
       <entry name="secondary_color" mtime="1237339199" type="string">
       <entry name="color_shading_type" mtime="1237339200" type="string">
       <entry name="picture_options" mtime="1237339199" type="string">
       <entry name="picture_filename" mtime="1237339199" type="string">


Rebuild and test and your image is now the desktop background.

Quick Summary

The first 2 sections in this example are equally applicable to KDE replacing gdm with kdm and gnome with kde respectively. The customization section of the example applies only to GNOME.

Using predefined functions in you can make a large number of configuration changes in the image without using overlay files. Using overlay files allows you to customize the appearance of GNOME to your liking in the image.


When applying a per user configuration of GNOME and using autologin the configuration may not consistently be picked up by gconfd. Thus when using autologin it is more robust to apply any configuration changes on a system wide basis.